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 ("switch windows", "context's getting full", "I'll head out", "压缩了", "切窗口") — 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 / 多线程项目 / 多任务并行 — enable Multi-workstream Mode (METHODOLOGY §3.5). 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" / "压缩了" / "切窗口" Handoff — see §3 User says "update the project brain" / "let's record this" / "更新项目脑" Update — see §4 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) Tiered trust on brain/ writes (v2.6, METHODOLOGY §4.1): STATUS / HANDOFF / mechanical MAP registrations — write directly after the work lands, then announce what was written in the same reply (git is the review surface; silent writes are forbidden at every tier). DECISIONS / PROJECT / structural MAP changes — always ask first. 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 — ask the user. §1 New project kick-off When the user wants to scaffold: 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. 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. 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 humans). Walk the user through brain/PROJECT.md on day one — fill the one-line definition + "what we explicitly DON'T do." Don't let this drift into the future. Scan placeholders : grep -rn "⚠️ TODO ⚠️" <user-project>/brain/ — go through with the user. Empty fields should be intentional. First DECISIONS entry : append "establishing project-brain" with rejected alternatives, so this file is used from day one. §2 Startup (entering a project that already has brain/ ) Single-workstream (only STATUS.md ): Read brain/MAP.md Read brain/STATUS.md If brain/HANDOFF.md exists, read it Brief report: project recognized + current progress + last blocker Multi-workstream (multiple STATUS_<workstream>.md ): Read shared files: brain/MAP.md + brain/PROJECT.md Don't guess — ask: "I see this is a multi-workstream project with [list workstreams]. Which one does this window work on?" After the user answers, read corresponding brain/STATUS_<workstream>.md + brain/HANDOFF_<workstream>.md Brief report Universal discipline : if cwd switches to another project mid-session, re-read the new project's files; if the user switches workstreams in the same window, re-read the new workstream's files. Don't carry over memory. §3 Handoff (user signaling window switch) When the user says they're switching windows / context is getting full / heading out: Archive the existing HANDOFF first (if one exists): git mv brain/HANDOFF.md brain/handoffs/$( date +%Y-%m-%d-%H%M).md (For multi-workstream: brain/HANDOFF_<current>.md → brain/handoffs/<current>/... .) Write a fresh brain/HANDOFF.md capturing: Why the window-switch (context limit / break / refocus) Current state at this exact moment Where the next session should pick up Things still in head not yet written down — the unique value of HANDOFF (hunches, half-tried approaches, weird debugging observations) Keep it short. If STATUS was just overwritten, HANDOFF can be near-empty. §4 Update workflow When the user says "update the project brain": Look back at what happened in this session Propose a list with reasons — for each candidate file, say what to write and why: - STATUS overwrite: now at [X], next [Y]. Reason: you said "that's it" - DECISIONS: about to append? Reason: that section felt like it landed — does this count as decided? - MAP §5 register: new file at brain/topics/systems/[X].md. Reason: doc we just wrote - HANDOFF: not needed — you didn't say switch windows Wait for user's approval per item — they may say "OK, all of them" / "skip DECISIONS, that's still discussion" / "today, just STATUS" Write only the approved updates Never reverse this : don't ask the user "which files do you want to update?" That hands the wrong layer of judgment to the wrong person. Reference Full methodology (the why, all 16 traps, evolution story): ${CLAUDE_PLUGIN_ROOT}/METHODOLOGY.md Templates (what scaffold.sh copies): ${CLAUDE_PLUGIN_ROOT}/templates/ Doctor (structural health check) : bash "${CLAUDE_PLUGIN_ROOT}/scripts/doctor.sh" <user-project-root> Public repo : https://github.com/Ethan-YS/project-brain