/project-brain

name: project-brain
description: |
  Triggers (all require explicit user request — do NOT activate just because a brain/ folder exists):
  (1) The user wants to set up project-level memory ("set up project brain", "scaffold project context", "init project brain", "建项目脑").
  (2) The user is in a directory containing brain/ AND explicitly asks to resume / continue / load the project / check status / "what's the state of this project" / "继续这个项目".
  (3) The user signals window switch / context compaction / a handoff ("switch windows", "context's getting full", "I'll head out", "hand off", "shift change", "压缩了", "切窗口", "交接", "换班", "接班", "交班") — write a HANDOFF before they leave.
  (4) The user says "update the project brain" / "let's record this" / "更新项目脑" — propose a list with reasons; user approves per item.
  (5) The user mentions multiple parallel workstreams / concurrent windows / 多线程项目 / 多任务并行 / 几个窗口同时做 — enable Multi-workstream Mode (METHODOLOGY §3.5; §3.6 when windows run concurrently).
  (6) In a multi-workstream project, the user asks to hand work to another workstream / "tell the X window" / 交给另一条线 / 告诉 X 窗口 — record a cross-workstream request (METHODOLOGY §3.6.3).
  (7) The user asks for a handoff / 交接 in a project that has **no brain/** — say so, offer the §1.4b decomposition, otherwise write the handoff in brain shape at the project root (METHODOLOGY §1.4c). A progress file is not a trigger; the user's handoff request is.
  Do NOT auto-activate from casual conversation — explicit user request required. See METHODOLOGY.md.
allowed-tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]

project-brain

A folder structure + collaboration protocol for persistent project context across AI sessions. Use it to scaffold a `brain/` folder in the user's project, resume work from an existing one, or update entries when work happens.

When to invoke this skill

| User signal | Workflow | |---|---| | "set up project brain" / "scaffold project" / "建项目脑" / "init project context" | **Kick-off** — see §1 | | User is in a directory containing `brain/` **AND** explicitly says "load" / "resume" / "what's the status" / "继续这个项目" | **Startup** — see §2 | | User says "switch windows" / "context's getting full" / "I'll head out" / "hand off" / "shift change" / "压缩了" / "切窗口" / "交接" / "换班" / "接班" / "交班" | **Handoff** — see §3 | | A handoff / window-switch request as above, but the project has **no `brain/`** | **Handoff first, brain later** — see §3b | | User says "update the project brain" / "let's record this" / "更新项目脑" | **Update** — see §4 | | Multi-workstream project, user says "hand this to the X workstream" / "tell the X window" / "交给 X 线" | **Cross-workstream request** — see §5 |

**Activation boundary** (important): Do **not** activate just because a `brain/` folder exists in the current directory. Casual conversation that happens to occur inside a project does not require this skill — only explicit user requests do. This is intentional: the methodology refuses to auto-monitor or auto-trigger; user judgment decides when to engage.

Core principles (always honored)

• **`brain/` is written for the next window, not for the user** (v2.9.1, METHODOLOGY §4.1): write `STATUS` / `HANDOFF` / `MAP` registrations / `RUNBOOK` appends when the work lands — don't ask, don't report; commit with a message that says what changed. Ask the user exactly one thing, and only when you can't tell: **is this decided?** `DECISIONS` / `PROJECT` follow the answer; what the user said plainly, write without asking.
• **HANDOFF is a shift report** (v2.9, METHODOLOGY §3.2): six sections, empty ones deleted; the test is "could the next window look this up?", not length. Archives are history — what's still valid moves to STATUS / RUNBOOK / DECISIONS *before* archiving (Trap 21). Project-level traps and procedures live in `brain/topics/operations/RUNBOOK.md`, numbered; handoffs cite the numbers.
• **Neighbour projects** (v2.9, METHODOLOGY §3.6.6): sibling repos are reached through *their* MAP §6 roster — never copy a session id or window name into this brain. Requests across the boundary use the same two STATUS ledgers, keyed by project name.
• **Judgment Division**: the user decides "should we record now"; the AI decides "what specifically to record"; the user reviews. Don't push specialized judgments back to the user ("which files do you want me to update?").
• **DECISIONS gentle inquiry**: when something feels decided, ask "does this count as decided?" — don't assert "we decided X."
• **Multi-workstream**: if `brain/` has multiple `STATUS_<workstream>.md` files, don't guess this window's workstream — use explicit signals only (the window is named for the workstream, e.g. `web-6`, or the user said so when opening it), otherwise ask.
• **Concurrent windows** (v2.8, METHODOLOGY §3.6): workstreams are durable, windows are disposable — name workstreams, never window names, outside the MAP §6 roster (Trap 18). One checkout means one shared staging area: stage by name, check `git diff --cached --stat` before every commit (Trap 19); edit shared brain files in place, never rewrite them whole (Trap 20).

§1 New project kick-off

When the user wants to scaffold:

1. **Confirm applicability**: multi-module / long-lived / cross-session work? If a one-off script — say "this might be over-engineering for this project" and let the user override. 2. **Confirm single or multi-workstream**: most projects are single-workstream (default). If the project has parallel independent workstreams (dev + ops + outreach kind of project), ask the user to list workstream names. 3. **Run scaffold**: `bash "${CLAUDE_PLUGIN_ROOT}/scripts/scaffold.sh" <user-project-root>` (defaults to all four AI adapters: Claude, Cursor, Copilot, AGENTS.md). Add `--lang zh` if the project will be documented in Chinese — gives Chinese `brain/` templates + Chinese `CLAUDE.md` (other adapters stay English regardless, since they're consumed by AI tools, not huma