init-brain

name	init-brain
description	Use when setting up a project for AFK for the first time — scaffolds the brain/ vault and authors a tight CLAUDE.md (with an AGENTS.md symlink) that points at the brain; triggers include "init brain", "set up the brain", "create the brain vault", or "generate a CLAUDE.md to onboard the agent to this repo".

Init Brain

One-time AFK setup for a project. Two outputs:

1. An empty brain/ vault (folder + index.md) — scaffolded by an idempotent script.
2. A carefully authored CLAUDE.md (with AGENTS.md symlinked to it) that onboards any agent to the repo and points at the brain.

Run this once before first use. The vault is also created lazily by afk:reflect and afk:brain, but the CLAUDE.md/AGENTS.md authoring only happens here.

CLAUDE.md is the highest-leverage file in the repo — it loads into every session. Author it deliberately following references/claude-md-guide.md; never dump-generate it like /init.

When to Use

Use this skill when:

• A project has no brain/ vault yet and the user wants to set it up up front.
• The user wants a good CLAUDE.md/AGENTS.md for the repo, or to "onboard the agent" to the codebase.

The brain scaffold is idempotent, so it is safe to re-run to add the CLAUDE.md/AGENTS.md to a project that already has a vault.

Process

1. Run the scaffold script — it is idempotent and never overwrites existing content:

   bash "${CLAUDE_PLUGIN_ROOT}/skills/init-brain/scripts/init-brain.sh"
   

   It creates the vault structure only if missing — see scripts/init-brain.sh for the exact set of files. The one part the next step acts on: when the project already has a doc site (VitePress, VuePress, Docusaurus, Astro Starlight, Nextra, MkDocs, Sphinx), the script seeds a brain/sources/<name>.md stub per detected site so the brain points at those docs rather than absorbing them — nothing in the repo moves.

2. Refine the seeded source stubs. If the script printed a "Detected doc sites" report, open each detected docs root (its landing page / sidebar config), and in that site's brain/sources/<name>.md replace the Scope: _TODO …_ line with a real one-line scope of what those docs cover (e.g. "Public SDK API reference and guides", "Deployment runbooks"). Keep the "authoritative — don't duplicate into the brain" line. Skip any stub whose docs you can't read; leave its TODO for next time.

3. Author or repair CLAUDE.md. Read references/claude-md-guide.md first, then:

   • If CLAUDE.md is missing: research the repo before writing — the stack and package manager, the directory map, and the real build/test/run commands (read package.json/manifests, the README, the project layout; use the Explore agent for large repos). Then author a tight CLAUDE.md following the guide (WHAT/WHY/HOW, progressive disclosure, under ~300 lines, no code-style rules). Include the ## Memory — brain/ pointer block from the guide so the agent reads the vault.
   • If CLAUDE.md already exists: do not overwrite it. Only ensure a ## Memory — brain/ pointer is present, adding it if missing. Suggest larger trims only if the user asks to tighten it.

4. Link AGENTS.md to CLAUDE.md so every harness reads one file:

   bash "${CLAUDE_PLUGIN_ROOT}/skills/init-brain/scripts/link-agents.sh"
   

   It is idempotent and refuses to clobber a real AGENTS.md. If it exits with "AGENTS.md already exists as a regular file", stop and ask the user how to reconcile the two files — do not delete their content.

5. Report what changed (see Output). The PostToolUse hook keeps brain/index.md in sync — including the ## Sources section — as files are added or removed from then on.

Stop and Ask

STOP and ask the user when:

• The project root is ambiguous (e.g. a monorepo where the vault and CLAUDE.md could belong to more than one package).
• link-agents.sh reports a real AGENTS.md file already exists — reconcile its content with the user before touching it.

Do not ask about facts discoverable by reading the repo (stack, layout, commands) — research them and write the CLAUDE.md.

Output

Report, one line each:

• The brain/ vault root and the paths created (or "already present").
• Any doc sites detected and registered under brain/sources/, plus which still need a Scope line.
• Whether CLAUDE.md was authored, augmented with a brain pointer, or left as-is, and that AGENTS.md is symlinked to it.

References

• scripts/init-brain.sh — the idempotent brain scaffold; run it, don't reimplement it.
• scripts/link-agents.sh — guarded AGENTS.md → CLAUDE.md symlink; run it, don't reimplement it.
• references/claude-md-guide.md — how to author the CLAUDE.md (read before writing) and the brain-pointer block.