|
| 1 | +--- |
| 2 | +name: init |
| 3 | +description: Scaffold a new shared-brain knowledge base folder (default ~/kb) — a plain-markdown, OKF v0.1-conformant memory store that any coding agent can read/write across sessions. Use when the user asks to set up, init, or bootstrap a kb / shared brain / persistent agent memory folder, or wants an OKF bundle with a graph viewer ready out of the box. |
| 4 | +--- |
| 5 | + |
| 6 | +# init — scaffold a shared-brain kb folder |
| 7 | + |
| 8 | +## What this creates |
| 9 | + |
| 10 | +A self-contained directory — plain markdown, no database, no server — that is: |
| 11 | + |
| 12 | +- **A memory protocol.** `AGENTS.md` (the full read/write/dream rules), `CLAUDE.md` |
| 13 | + (thin pointer for Claude Code), `DREAM.md` (the consolidation pass), `MEMORY.md` |
| 14 | + (the index every agent reads first). |
| 15 | +- **An OKF v0.1 bundle.** `memory/` is the bundle root; every note is one `.md` |
| 16 | + file with a `type` in frontmatter. Conforms to |
| 17 | + [OKF v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) |
| 18 | + — see the companion **okf** skill/plugin for deeper bundle authoring and |
| 19 | + validation. |
| 20 | +- **A capture inbox.** `raw/inbox/` for low-ceremony daily notes; `raw/` for |
| 21 | + immutable source docs. |
| 22 | +- **Its own CLI and tooling**, vendored into `scripts/`/`bin/` so the folder |
| 23 | + keeps working even if this Claude plugin is later removed: `bin/kb` |
| 24 | + (capture/lint/sync/gen/viz/wire), `scripts/render_okf_viewer.py` (regenerates |
| 25 | + `memory/**/index.md` + a self-contained `viz.html` graph viewer), `scripts/ |
| 26 | +lint.sh`, `scripts/sync.sh`, `scripts/wire.sh`. |
| 27 | + |
| 28 | +This is the generic, brand-neutral form of a personal "shared brain" pattern — |
| 29 | +it ships with no memory content, no assumed git remote, and no personal |
| 30 | +branding. Everything it writes is a template for the user to fill in. |
| 31 | + |
| 32 | +## When to use |
| 33 | + |
| 34 | +- "set up a kb / shared brain / persistent memory folder for me" |
| 35 | +- "init ~/kb" or "bootstrap my knowledge base" |
| 36 | +- The user wants cross-session, cross-agent memory but has none yet. |
| 37 | + |
| 38 | +If a kb already exists at the target (has `AGENTS.md` or `memory/`), this skill |
| 39 | +is still safe to run — see Idempotency below — but check first whether the user |
| 40 | +actually wants `dream` (consolidate existing notes) instead of `init`. |
| 41 | + |
| 42 | +## Steps |
| 43 | + |
| 44 | +1. **Resolve the target path.** Default `$HOME/kb`. Use `$KB_DIR` if set, or a |
| 45 | + path the user gave explicitly. Confirm the path with the user if ambiguous. |
| 46 | +2. **Scaffold.** Run the bundled script with an absolute path (it does not |
| 47 | + expand `~`): |
| 48 | + |
| 49 | + ```bash |
| 50 | + bash "${CLAUDE_PLUGIN_ROOT}/skills/init/scripts/scaffold.sh" "$HOME/kb" |
| 51 | + ``` |
| 52 | + |
| 53 | + It is idempotent — creates missing files, chmods scripts executable, seeds |
| 54 | + starter `memory/{user,feedback,reference,projects,topics}/` groups, and |
| 55 | + **never overwrites a file that already exists** in the target. It ends by |
| 56 | + running `render_okf_viewer.py` once so `memory/index.md` and `viz.html` |
| 57 | + exist immediately. |
| 58 | + |
| 59 | +3. **Report what happened**: how many files were created vs. skipped |
| 60 | + (pre-existing), and the target path. |
| 61 | +4. **Offer, but do not run automatically, three follow-ups** — each changes |
| 62 | + something outside the new folder or is otherwise consequential, so ask |
| 63 | + first: |
| 64 | + - **PATH.** Suggest adding `export PATH="<target>/bin:$PATH"` to the user's |
| 65 | + shell rc. Don't edit their `.zshrc`/`.bashrc` yourself unless they ask. |
| 66 | + - **Version control.** Offer `git init` (and `git remote add origin <url>` |
| 67 | + if they have one). Skip silently if they don't want git. |
| 68 | + - **Wiring.** `<target>/scripts/wire.sh on` adds a small marked block to |
| 69 | + `~/.claude/CLAUDE.md` (and `~/.codex/AGENTS.md` / `~/.config/opencode/ |
| 70 | +AGENTS.md` if those tools are present) so every future session |
| 71 | + auto-reads the kb. This edits files **outside** the scaffolded folder and |
| 72 | + affects every future session — explain what it does and get explicit |
| 73 | + confirmation before running it. `wire.sh off` cleanly reverses it. |
| 74 | +5. **If the user wants example notes**, don't invent personal facts — either |
| 75 | + leave `memory/` empty for them to fill in via `kb capture`, or ask what to |
| 76 | + record. |
| 77 | + |
| 78 | +## After scaffolding |
| 79 | + |
| 80 | +- Point to `memory/_TEMPLATE.md` for the note format and `AGENTS.md` for the |
| 81 | + full protocol — both are self-documenting inside the new folder. |
| 82 | +- For ongoing maintenance (merge duplicates, prune stale notes, rebuild the |
| 83 | + index), use this plugin's **dream** skill against the new kb. |
| 84 | +- For richer OKF authoring/validation beyond what `bin/kb gen` covers (custom |
| 85 | + concept types, `validate_okf.py` conformance checks), use the **okf** plugin. |
| 86 | +- `kb viz` (or `bin/kb viz` before `PATH` is set) opens the graph viewer any |
| 87 | + time after notes are added. |
| 88 | + |
| 89 | +## Idempotency & safety |
| 90 | + |
| 91 | +- `scaffold.sh` only ever creates files that don't already exist — re-running |
| 92 | + it against a partially-set-up or already-populated kb is safe and adds |
| 93 | + nothing to files it finds present. |
| 94 | +- It never touches anything outside `<target>` — no global config, no shell |
| 95 | + rc, no git remote. Those are the explicit, confirm-first follow-ups above. |
| 96 | +- It writes no personal data — the scaffolded files are generic templates. |
| 97 | + |
| 98 | +## Checklist |
| 99 | + |
| 100 | +- [ ] Resolved target path (arg, `$KB_DIR`, or confirmed default `~/kb`). |
| 101 | +- [ ] Ran `scaffold.sh` with an absolute path; reported created vs. skipped files. |
| 102 | +- [ ] `memory/index.md` and `viz.html` exist (scaffold.sh generates them). |
| 103 | +- [ ] Offered PATH / git init / wire as separate, confirm-first steps — did not |
| 104 | + edit anything outside the target folder without asking. |
| 105 | +- [ ] Did not invent personal facts to seed `memory/` with. |
0 commit comments