[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-76146":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":14,"stars30d":15,"stars90d":14,"forks30d":14,"starsTrendScore":14,"compositeScore":16,"rankGlobal":9,"rankLanguage":9,"license":17,"archived":18,"fork":18,"defaultBranch":19,"hasWiki":20,"hasPages":18,"topics":21,"createdAt":9,"pushedAt":9,"updatedAt":31,"readmeContent":32,"aiSummary":33,"trendingCount":14,"starSnapshotCount":14,"syncStatus":34,"lastSyncTime":35,"discoverSource":36},76146,"project-brain","Ethan-YS\u002Fproject-brain","Ethan-YS","One folder. Every session knows where you left off. — An open-source methodology for AI-assisted projects.",null,"Shell",164,11,8,0,32,46.44,"MIT License",false,"main",true,[22,23,24,25,26,27,28,29,30],"ai-assistant","ai-coding","ai-pair-programming","claude-code","context-management","cursor","developer-tools","methodology","project-template","2026-06-12 04:01:20","# project-brain\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fassets\u002Fhero.png\" alt=\"One folder. Every session knows where you left off.\" width=\"100%\" \u002F>\n\u003C\u002Fp>\n\n> **Different session. Same brain.**\n>\n> A folder structure + collaboration protocol that lets your AI assistant pick up a project after a context wipe — across new sessions, new windows, new collaborators.\n\n[中文版 →](.\u002FREADME.zh-CN.md)\n\n**Part of [Sprout Labs](https:\u002F\u002Fethanflow.com)** — Local-first AI memory & agent safety, built independently by Ethan (Independent Product Designer & AI Builder, since 2016).\n[ethanflow.com](https:\u002F\u002Fethanflow.com) · [LinkedIn](https:\u002F\u002Fwww.linkedin.com\u002Fin\u002Fethan-ys\u002F) · [@ethanflow_lab](https:\u002F\u002Fx.com\u002Fethanflow_lab) · [GitHub](https:\u002F\u002Fgithub.com\u002FEthan-YS)\n\n\u003Cp align=\"center\">\n    \u003Ca href=\"https:\u002F\u002Flinux.do\" alt=\"LINUX DO\">\n        \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLINUX-DO-FFB003.svg?logo=data:image\u002Fsvg%2bxml;base64,DQo8c3ZnIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgd2lkdGg9IjEwMCIgaGVpZ2h0PSIxMDAiPjxwYXRoIGQ9Ik00Ni44Mi0uMDU1aDYuMjVxMjMuOTY5IDIuMDYyIDM4IDIxLjQyNmM1LjI1OCA3LjY3NiA4LjIxNSAxNi4xNTYgOC44NzUgMjUuNDV2Ni4yNXEtMi4wNjQgMjMuOTY4LTIxLjQzIDM4LTExLjUxMiA3Ljg4NS0yNS40NDUgOC44NzRoLTYuMjVxLTIzLjk3LTIuMDY0LTM4LjAwNC0yMS40M1EuOTcxIDY3LjA1Ni0uMDU0IDUzLjE4di02LjQ3M0MxLjM2MiAzMC43ODEgOC41MDMgMTguMTQ4IDIxLjM3IDguODE3IDI5LjA0NyAzLjU2MiAzNy41MjcuNjA0IDQ2LjgyMS0uMDU2IiBzdHlsZT0ic3Ryb2tlOm5vbmU7ZmlsbC1ydWxlOmV2ZW5vZGQ7ZmlsbDojZWNlY2VjO2ZpbGwtb3BhY2l0eToxIi8+PHBhdGggZD0iTTQ3LjI2NiAyLjk1N3EyMi41My0uNjUgMzcuNzc3IDE1LjczOGE0OS43IDQ5LjcgMCAwIDEgNi44NjcgMTAuMTU3cS00MS45NjQuMjIyLTgzLjkzIDAgOS43NS0xOC42MTYgMzAuMDI0LTI0LjM4N2E2MSA2MSAwIDAgMSA5LjI2Mi0xLjUwOCIgc3R5bGU9InN0cm9rZTpub25lO2ZpbGwtcnVsZTpldmVub2RkO2ZpbGw6IzE5MTkxOTtmaWxsLW9wYWNpdHk6MSIvPjxwYXRoIGQ9Ik03Ljk4IDcwLjkyNmMyNy45NzctLjAzNSA1NS45NTQgMCA4My45My4xMTNRODMuNDI2IDg3LjQ3MyA2Ni4xMyA5NC4wODZxLTE4LjgxIDYuNTQ0LTM2LjgzMi0xLjg5OC0xNC4yMDMtNy4wOS0yMS4zMTctMjEuMjYyIiBzdHlsZT0ic3Ryb2tlOm5vbmU7ZmlsbC1ydWxlOmV2ZW5vZGQ7ZmlsbDojZjlhZjAwO2ZpbGwtb3BhY2l0eToxIi8+PC9zdmc+\" \u002F>\u003C\u002Fa>\n\u003C\u002Fp>\n\n---\n\n## The problem\n\nLong-running projects with AI coding assistants (Claude Code, Cursor, Copilot, etc.) hit a counter-intuitive wall:\n\n> **Larger context windows don't solve the problem. Better information structure does.**\n\nA wider window doesn't mean it gets read. Read doesn't mean located. Located doesn't mean prioritized. Without structure, every new session starts with \"wait, what's going on here?\" — and the AI either reads too much (wasting tokens) or misses the critical pieces.\n\nSymptoms you'll recognize:\n\n- One README mixing project pitch + current status + decision history + how-to-run\n- Sprawling docs where boundaries blur (one architecture file containing design + ops + history + bugs)\n- Decisions buried in commit messages, chat logs, and footnotes — never traceable when you need them\n- Cross-window handoff loses the \"fresh stuff in your head\" — the next session starts blind\n- Projects running **multiple parallel workstreams** (e.g., dev + ops + outreach as three parallel streams) lose track of which session is on which line — switching between them re-orients from scratch every time\n\n`project-brain` is a structural answer: a `brain\u002F` folder layout + a small set of protocols, designed so a fresh AI session can read 2-3 files and be productive.\n\n## Quick start\n\n### Option A — install as a Claude Code plugin (recommended for Claude Code users)\n\nIn Claude Code, run these two slash commands:\n\n```\n\u002Fplugin marketplace add Ethan-YS\u002Fproject-brain\n\u002Fplugin install project-brain@sprout-labs\n```\n\nIf `\u002Fplugin` isn't exposed in your Claude Code environment (some embedded \u002F SDK contexts strip it), the CLI form does the exact same thing — run from any terminal:\n\n```bash\nclaude plugin marketplace add Ethan-YS\u002Fproject-brain\nclaude plugin install project-brain@sprout-labs\n```\n\nThat's it. From any project after that, just say:\n\n- **\"set up project brain\"** — kick off a new brain\n- **\"resume this project\"** — load `MAP.md` + `STATUS.md` + (if exists) `HANDOFF.md`\n- **\"I'm switching windows\"** \u002F **\"context's getting full\"** — write a HANDOFF before context dies\n- **\"update the project brain\"** — propose updates with reasons, you approve per item\n\nThe skill handles four workflows: new-project kick-off, startup resume, window-switch handoff, and updates. Auto-trigger requires an explicit user request — it intentionally does **not** activate just because a `brain\u002F` folder exists.\n\n> **Already installed the old way?** If you previously cloned to `~\u002F.claude\u002Fskills\u002Fproject-brain`, remove it first: `rm -rf ~\u002F.claude\u002Fskills\u002Fproject-brain`. The plugin install is the supported path going forward.\n\n> **Update later**: `\u002Fplugin marketplace update sprout-labs` to fetch the latest version.\n\n### Option B — manual scaffold (works with any AI assistant)\n\nIf you don't use Claude Code, or you just want the scaffold script:\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FEthan-YS\u002Fproject-brain.git\n\n# Scaffold into your project (defaults to all four AI adapters, English)\n.\u002Fproject-brain\u002Fscripts\u002Fscaffold.sh \u002Fpath\u002Fto\u002Fyour\u002Fproject\n\n# Or pick specific adapters:\n.\u002Fproject-brain\u002Fscripts\u002Fscaffold.sh \u002Fpath\u002Fto\u002Fyour\u002Fproject --tools claude,cursor\n\n# For projects documented in Chinese — gives Chinese brain\u002F + CLAUDE.md\n# (other adapters stay English — they're consumed by AI tools, not humans):\n.\u002Fproject-brain\u002Fscripts\u002Fscaffold.sh \u002Fpath\u002Fto\u002Fyour\u002Fproject --lang zh\n\n# Fill in brain\u002FPROJECT.md on day one\n# Walk through ⚠️ TODO ⚠️ placeholders\n```\n\nWhat the scaffold gives you:\n\n| File | Tool |\n|---|---|\n| `brain\u002F` | The project brain (PROJECT\u002FMAP\u002FSTATUS\u002FDECISIONS\u002FHANDOFF + topics\u002F) |\n| `CLAUDE.md` | Claude Code instruction file |\n| `.cursorrules` | Cursor instruction file |\n| `.github\u002Fcopilot-instructions.md` | GitHub Copilot Chat |\n| `AGENTS.md` | Codex CLI \u002F Aider \u002F Continue (AGENTS.md convention) |\n\nWhen a new AI session opens your project, the auto-loaded instruction file directs it to read `brain\u002FMAP.md` + `brain\u002FSTATUS.md`. If `brain\u002FHANDOFF.md` exists, it picks up the previous session's \"still-warm-not-yet-written-down\" thoughts.\n\n### Health check (any time after scaffolding)\n\n```bash\n.\u002Fproject-brain\u002Fscripts\u002Fdoctor.sh \u002Fpath\u002Fto\u002Fyour\u002Fproject\n```\n\nRead-only structural checks: missing core files, STATUS over 80 lines, decisions without \"rejected alternatives,\" topics\u002F files not registered in MAP, stale `⚠️ TODO ⚠️` placeholders, etc. Reports issues but never fixes them — that's still your call. See [scripts\u002Fdoctor.sh](.\u002Fscripts\u002Fdoctor.sh).\n\n### See a fully-filled example\n\nIf the empty templates feel abstract, see [examples\u002Fsmall-saas\u002F](.\u002Fexamples\u002Fsmall-saas\u002F) — a fictional SaaS project (\"Quill,\" a local-first notes app at v0.3) with every file filled in. Reading it is the fastest way to understand what each `brain\u002F` file looks like in real use.\n\n## Structure\n\n```\nbrain\u002F\n├── PROJECT.md       What is this project? What do we explicitly NOT do?\n├── MAP.md           Module structure + document index (\"where do I find X?\")\n├── STATUS.md        Current state — overwritable, soft cap 80 lines\n├── DECISIONS.md     Decision log — append-only, requires \"rejected alternatives\"\n├── HANDOFF.md       Cross-window bridge — what's still in head but not yet written\n├── handoffs\u002F        Archive of past HANDOFFs (timestamped)\n└── topics\u002F          Per-problem-dimension docs\n    ├── systems\u002F      → \"How is this designed?\"\n    ├── operations\u002F   → \"How do I operate it \u002F what to do each release?\"\n    ├── planning\u002F     → \"What are we going to build \u002F how to plan it?\"\n    └── feedback\u002F     → \"What is reality \u002F users telling us?\"\n```\n\n## Core principles\n\n### 1. Time-scale separation\n\nThe five core files in `brain\u002F` are split **by how often they change**, not by topic:\n\n| File | Volatility | When to read |\n|---|---|---|\n| `PROJECT.md` | Almost never | First contact \u002F scope ambiguous |\n| `MAP.md` | Slowly | Every new session |\n| `STATUS.md` | Frequently (per session) | Every new session |\n| `DECISIONS.md` | Append-only, event-driven | Tracing why something is the way it is |\n| `HANDOFF.md` | Per window-switch | New session start (if exists) |\n\nWhy volatility-based? Because **mixing low-frequency content with high-frequency content forces the low-frequency content to be re-edited every session** — the most common mode of doc rot.\n\n### 2. Problem-dimension classification (not by module)\n\n`brain\u002Ftopics\u002F` is divided into 4 dimensions: `systems` \u002F `operations` \u002F `planning` \u002F `feedback`. A single business module (say, \"payment\") has its design in `systems\u002F`, deploy logs in `operations\u002F`, pricing strategy in `planning\u002F`, user feedback in `feedback\u002F`.\n\nWhy? Modules grow, shrink, get renamed, get merged. The four problem dimensions are far more stable.\n\n### 3. Decision logging requires \"rejected alternatives\"\n\nEvery entry in `DECISIONS.md` must include what was considered and rejected, and why. Without this, the file degrades into a worse version of `CHANGELOG.md` (which already records \"what was done\"). The unique value of decision logs is **the paths not taken** — that's where a project's judgment lives.\n\n### 4. Judgment Division\n\nWhen the user says \"update the project brain\":\n- **The user** decides \"should we record now\" (high-level pacing instinct)\n- **The AI** decides \"specifically what to record \u002F how to write each entry\" (specialized understanding of how each file works)\n- **The user** approves or rejects the AI's judgment\n\nThe AI should not push specialized judgments back (\"which files do you want me to update?\") — that hands the wrong layer of judgment to the wrong person.\n\n### 5. Multi-workstream mode (v2.1, optional)\n\nSome projects naturally have parallel independent workstreams (e.g., development + operations + outreach in one product). For these, `STATUS` and `HANDOFF` split per workstream:\n\n```\nbrain\u002F\n├── PROJECT.md           ← shared\n├── MAP.md               ← shared\n├── DECISIONS.md         ← shared\n├── STATUS_dev.md        ← split per workstream\n├── STATUS_ops.md\n├── HANDOFF_dev.md\n├── HANDOFF_ops.md\n├── handoffs\u002F\n│   ├── dev\u002F\n│   └── ops\u002F\n└── topics\u002F              ← shared\n```\n\nSingle-workstream projects ignore this — they keep the default `STATUS.md` \u002F `HANDOFF.md`.\n\n## Why this exists — the evolution story\n\nThis methodology didn't appear from a design session. It evolved through real use across multiple projects — each iteration triggered by friction we hit and couldn't ignore.\n\n**v1 (April 2026)**: After accumulating 15+ scattered docs and one 32KB monolithic file in a single project, every new AI session needed to re-read everything to figure out \"what's going on here?\" We refactored across 4 commits and established the basic structure: `meta\u002F` (continuity layer) + `docs\u002F` (problem-dimension classified). The core insight was **separating files by volatility** — stable \u002F slowly-changing \u002F per-session \u002F append-only — to prevent the most common doc-rot pattern: low-frequency content getting re-edited because it lives next to high-frequency content.\n\n**v2 (April 30, 2026)**: We surveyed community approaches (Prompt Shelf 2026's three-file architecture, softaworks\u002Fagent-toolkit's session-handoff skill, Anthropic's official skills repo). We found:\n- Community solutions were stronger at **runtime mechanics** (auto-handoff triggers, staleness detection, handoff chains)\n- Our v1 was structurally deeper in three places: the \"what we explicitly DON'T do\" forcing function in PROJECT.md, mandatory \"rejected alternatives\" in decision log, and classification by problem-dimension instead of by module\n\nThe plan was \"borrow the runtime layer, keep the structural layer.\" But across 8 rounds of refinement, **the user systematically rejected mechanism creep**. Every time the AI proposed \"let me design auto-detection \u002F triggering \u002F staleness checking,\" the user said \"no — that's a judgment I'll make myself.\"\n\nThis crystallized into the **Judgment Division Principle** (see Core principle 4): the user decides \"should we record now\"; the AI decides \"what specifically to record\"; the user reviews. Don't hide specialized judgment behind automation.\n\nCompanion design changes: merged `meta\u002F` + `docs\u002F` into a single `brain\u002F`, added `HANDOFF.md` for cross-window continuity, replaced \"hard keyword detection\" with **gentle inquiry** (\"does this count as decided?\" instead of asserting \"we decided X\"), made placeholders visually loud (`⚠️ TODO ⚠️`), and made the git prerequisite explicit.\n\n**v2.1 (same day, evening)**: A second project — non-development, running parallel workstreams (official ops + outreach) — broke v2's hidden assumption that \"one project = one workstream.\" The user had naturally evolved a workaround using `STATUS_\u003Cworkstream>.md` naming. We folded it into the methodology as **Multi-workstream Mode** (Core principle 5): project-level files stay shared, status and handoff split per workstream.\n\n### The meta-takeaway\n\nThe healthy evolution pattern wasn't \"design everything upfront.\" It was **\"build what works now, let real-world friction drive the next version.\"** Each version came from a specific, named problem. Each refinement was triggered by a real moment of pain.\n\nIf you take one thing from this repo: **resist the urge to design comprehensive automation up front**. Real friction tells you which mechanisms are worth building, and which would just hand specialized judgment to the wrong layer.\n\n## Documentation\n\n- **[METHODOLOGY.md](.\u002FMETHODOLOGY.md)** — full methodology including all 14 traps, judgment division mechanics, multi-workstream details, and migration paths\n- **[CHANGELOG.md](.\u002FCHANGELOG.md)** — version history\n- **[skills\u002Fproject-brain\u002FSKILL.md](.\u002Fskills\u002Fproject-brain\u002FSKILL.md)** — Claude Code skill manifest (loaded automatically once the plugin is installed)\n- **[.claude-plugin\u002F](.\u002F.claude-plugin\u002F)** — `plugin.json` (manifest) + `marketplace.json` (Sprout Labs marketplace entry)\n- **[templates\u002F](.\u002Ftemplates\u002F)** — drop-in templates for `brain\u002F` + 4 AI tool adapters\n- **[examples\u002Fsmall-saas\u002F](.\u002Fexamples\u002Fsmall-saas\u002F)** — a fully-filled example brain\u002F folder\n- **[scripts\u002Fscaffold.sh](.\u002Fscripts\u002Fscaffold.sh)** — one-command scaffold into any project\n- **[scripts\u002Fdoctor.sh](.\u002Fscripts\u002Fdoctor.sh)** — read-only health check (catches the most common 6 traps)\n\n## Compatibility\n\nThis methodology is AI-agnostic. The repo includes adapter templates for:\n- **Claude Code** — install as a plugin (Option A above) for the full skill experience, or just drop in `CLAUDE.md` for project-level instructions\n- **Cursor** — `.cursorrules`\n- **GitHub Copilot Chat** — `.github\u002Fcopilot-instructions.md`\n- **Codex CLI \u002F Aider \u002F Continue** — `AGENTS.md` (the [agents.md](https:\u002F\u002Fagents.md) convention)\n- Any other AI assistant that respects a project-level instruction file (write your own pointer to `brain\u002FMAP.md` + `brain\u002FSTATUS.md`)\n\n`.\u002Fscripts\u002Fscaffold.sh` copies all four by default; use `--tools claude,cursor` to pick specific ones.\n\nRequirements:\n- **Git** — several mechanisms (HANDOFF archival, decision traceability, file blame) assume git history\n- That's it.\n\n## Status\n\n🌱 v2.4 — methodology stable, 140+ stars, multiple projects in active use. v2.4 ships as a one-command Claude Code plugin (the Sprout Labs marketplace). v2.3 added `scripts\u002Fdoctor.sh` (structural health check) and a fully-filled example project (`examples\u002Fsmall-saas\u002F`). v2.2 introduced the Claude Code skill manifest and adapter templates for Cursor \u002F Copilot \u002F AGENTS.md. External effectiveness data still pending — battle-tested by the maintainers daily; field reports from other users still being collected.\n\n## Authors\n\nBuilt by [**Ethan**](https:\u002F\u002Fethanflow.com), the person behind [Sprout Labs](https:\u002F\u002Fethanflow.com). The methodology came out of a Jarvis-style AI collaboration workflow: eight rounds of iteration in a single working day, each triggered by a specific friction point — not a design session.\n\nThe methodology itself models the working approach: clear judgment division, refusal to automate away decisions that should be made by humans, and willingness to admit when v1 needs to become v2.\n\nReleased under [Sprout Labs](https:\u002F\u002Fethanflow.com).\n\n## License\n\n[MIT](.\u002FLICENSE) — use it, modify it, share it. If it helps your workflow, a star on the repo is appreciated.\n\n## Contributing\n\nIssues and PRs welcome. The methodology is intentionally minimalist — proposals to add mechanisms should clearly identify the specific friction they solve. New traps (mistakes you've hit using this) are especially welcome.\n","project-brain 是一个旨在通过结构化文件夹和协作协议帮助AI助手在项目中保持上下文连贯性的开源方法论。其核心功能包括提供一种即使在会话、窗口或协作者变更后也能让AI助手快速恢复工作状态的机制，从而避免了重复了解项目背景的时间浪费。该项目主要使用Shell语言编写，并采用MIT许可协议发布。适用于需要长期维护且涉及多个并行工作流（如开发与运维）的复杂项目，尤其是当团队成员频繁变动时，能够有效提升工作效率和信息管理能力。",2,"2026-06-11 03:54:39","CREATED_QUERY"]