@rashidee/co2 1.2.5

package/plugin/SKILLS.md

@@ -0,0 +1,350 @@
+# CO2 Skills Catalog — Agent Reference
+
+> **Audience:** AI agents. This document tells you WHICH skill to invoke WHEN in the
+> Compound Context (CO2) workflow. Every skill reads its inputs from the project's context
+> files (`CLAUDE.md`, `<app_folder>/context/PRD.md`, etc.) — invoke with the application
+> name and version; do not ask the user for information the context files already contain.
+
+## Workflow Order
+
+Skills belong to phases and generally must run in this order per application:
+
+```
+0. Bootstrap        util-projectinit → (user fills session) → /brainstorm-loop → util-projectsync
+1. PRD clean-up     util-usanalyzer → util-ustagger          (util-updprd for requirement changes)
+2. Artifacts        modelgen-* → mockgen-* → specgen-* → testgen-functional
+                    (or all four via conductor-feature-prepare)
+3. Infrastructure   util-preparek8senv                        (before development)
+4. Development      conductor-feature-develop → tracegen-matrix (auto) → depgen-k8s (auto)
+5. Bug fixing       conductor-defect → tracegen-matrix (auto)
+```
+
+## Artifact Map — who produces what
+
+```
+<project_root>/
+├── CLAUDE.md                          ← /brainstorm-loop (Phase A), annotated by util-projectsync
+├── DEVTOOL.md                         ← per-developer (manual)
+├── ENVIRONMENT.md                     ← util-preparek8senv
+├── <topic>.brainstorm.md              ← util-projectinit (session doc, iterated by /brainstorm-loop)
+├── brainstorm-protocol.md             ← util-projectinit (copied)
+├── co2-context-generation-guide.md    ← util-projectinit (copied)
+├── environment/                       ← util-preparek8senv (K8s manifests for 3rd party apps; gitignored)
+└── <app_folder>/
+    ├── CHANGELOG.md                   ← appended by every skill (version gate)
+    ├── Dockerfile                     ← depgen-k8s
+    ├── k8s/                           ← depgen-k8s (app manifests; gitignored)
+    ├── (source code)                  ← conductor-feature-develop / conductor-defect
+    └── context/
+        ├── PRD.md                     ← /brainstorm-loop (Phase B), scaffolded by util-projectsync,
+        │                                tagged by util-ustagger, annotated by util-usanalyzer
+        ├── BUG.md                     ← util-projectsync scaffold; user reports; tagged by conductor-defect
+        ├── TRACEABILITY.md            ← tracegen-matrix
+        ├── model/                     ← modelgen-relational / modelgen-nosql
+        ├── mockup/                    ← mockgen-tailwind / mockgen-shadcn (assets + manifest;
+        │                                served by the shared Mockup Hub at <root>/mockup)
+        ├── specification/             ← specgen-* (one variant)
+        ├── test/                      ← testgen-functional
+        ├── prepare/                   ← conductor-feature-prepare (PREPARE_MASTER.md tracking)
+        ├── develop/                   ← conductor-feature-develop (tracking files)
+        └── bug/                       ← conductor-defect (per-bug tracking files)
+```
+
+**Universal conventions (apply to almost every skill):**
+
+- **Invocation shape:** `/skill-name <application> <version> [module:<name>]`. The application
+  name resolves to a root-level app folder (leading `<number>_` prefix stripped,
+  case-insensitive, snake/kebab/title case all match).
+- **Version gate:** skills refuse to run for a version lower than the highest version recorded
+  in `<app_folder>/CHANGELOG.md`, and append a row there on success.
+- **Version filtering:** only PRD items tagged `[vX.Y.Z]` <= the requested version are included;
+  strikethrough (`~~…~~`) items are deprecated and excluded.
+- **Traceability:** PRD item IDs (e.g., `[USHM00003]`, `[NFRHM0012]`) must be carried through
+  into every generated artifact.
+
+---
+
+## Phase 0 — Project Bootstrap
+
+### `util-projectinit`
+- **Invoke:** `/util-projectinit "<application idea or topic>"`
+- **What it does:** Sets up a file-based, turn-based **brainstorming session** in the project
+  folder: generates `<topic>.brainstorm.md` from the appdev template (seeded with the idea),
+  copies `brainstorm-protocol.md` and `co2-context-generation-guide.md` to the project root,
+  and ensures the `/brainstorm-loop` command is installed. It does NOT generate project context
+  directly and it NEVER starts the loop itself — it instructs the user to fill in the session
+  document and manually run `/brainstorm-loop`.
+- **Use when:** the user wants to start/init/bootstrap a NEW project, or brainstorm an
+  application idea into CO2 context. First skill of the workflow.
+- **Do NOT use when:** the project already has a `CLAUDE.md` and the user wants to evolve it
+  (use `util-projectsync` or `util-updprd`).
+- **Prerequisites:** an application idea (even one paragraph).
+- **Output:** `<topic>.brainstorm.md` (session document), `brainstorm-protocol.md`,
+  `co2-context-generation-guide.md` at the project root, and
+  `.claude/commands/brainstorm-loop.md` when the plugin command is not available — plus a
+  hand-off instruction block. Non-destructive — never overwrites existing files.
+
+### `/brainstorm-loop` (plugin command, not a skill)
+- **Invoke:** `/brainstorm-loop [scan-root] [max-watch-rounds]` — **run manually by the user**,
+  never auto-started by a skill.
+- **What it does:** In-session watch loop over `*.brainstorm.md` session documents. Each round
+  the agent drafts the CO2 context tree (Phase A: root `CLAUDE.md`; Phase B: one `PRD.md` per
+  application) per `co2-context-generation-guide.md`, appends questions, and waits for the
+  human to answer and flip a status row. Token-efficient: 60-second file polling, acts only on
+  status flips.
+- **Output:** root `CLAUDE.md` + `<app_folder>/context/PRD.md` per application (at the session's
+  destination), plus a `.brainstorm-loop-status.md` dashboard.
+
+### `util-projectsync`
+- **Invoke:** `/util-projectsync` (no arguments — reads everything from `CLAUDE.md`)
+- **What it does:** Synchronizes project folder structure with `CLAUDE.md`: validates
+  dependencies (circular, missing, logical) and orphaned services, creates missing application
+  folders, scaffolds `PRD.md`/`BUG.md` from templates, adds missing module sections, inserts
+  `[TODO]` annotations into `CLAUDE.md` for validation failures.
+- **Use when:** after the brainstorm closes, or any time `CLAUDE.md` applications/modules
+  changed and folders/PRDs must catch up ("sync project", "scaffold project folders",
+  "validate dependencies").
+- **Prerequisites:** `CLAUDE.md`.
+- **Output:** missing `<app_folder>/` folders, scaffolded `<app_folder>/context/PRD.md` and
+  `BUG.md`, missing module sections added to existing files, `[TODO]` annotations in
+  `CLAUDE.md` for validation failures, and a sync/validation summary report.
+
+---
+
+## Phase 1 — PRD Clean-Up
+
+### `util-usanalyzer`
+- **Invoke:** `/util-usanalyzer <application>`
+- **What it does:** Analyzes `PRD.md` for quality issues — incomplete sentences, broken
+  references, cross-module inconsistencies, contradictions, duplicate roles, process-flow
+  coverage gaps — and adds inline `[TODO]` annotations for each issue.
+- **Use when:** the user asks to validate/review/audit user stories or requirements quality,
+  or before tagging a freshly edited PRD.
+- **Prerequisites:** `PRD.md`.
+- **Output:** inline `[TODO]` annotations written into `PRD.md` at each issue, plus a summary
+  report of all issues found with improvement suggestions.
+
+### `util-ustagger`
+- **Invoke:** `/util-ustagger <application> <version>`
+- **What it does:** Tags every untagged top-level item in `PRD.md` (User Stories, NFRs,
+  Constraints, References, Tests) with a unique 9-character ID code and validates that no
+  duplicate tags exist.
+- **Use when:** new PRD items need IDs ("tag user stories", "add IDs to requirements",
+  "validate tags"). Run after any manual PRD edit and before artifact generation.
+- **Prerequisites:** `PRD.md`.
+- **Output:** updated `PRD.md` with every item tagged (e.g., `[USHM00003]`, `[NFRHM0012]`,
+  `[CONHM0009]`, `[REFHM0003]`), plus a duplicate-tag validation report.
+
+### `util-updprd` ⚠️ *not yet implemented — folder is an empty stub; do not invoke*
+- **Documented intent:** apply a free-form requirement change across all applications' PRD.md
+  files — decide add/cancel/modify per item, auto-classify major/minor/patch, layer changes
+  under a NEW version tag (prior versions immutable), tag via `util-ustagger`, append
+  CHANGELOG entries.
+
+---
+
+## Phase 2 — Context Artifact Generation
+
+> Run the four steps individually below, or all at once via `conductor-feature-prepare`.
+
+### `conductor-feature-prepare` (orchestrator)
+- **Invoke:** `/conductor-feature-prepare <application> [version:<v>] [module:<m>]`
+- **What it does:** Runs `util-ustagger` → `modelgen-*` → `mockgen-*` → `specgen-*` →
+  `testgen-functional` in sequence, auto-selecting the right variant per the application's
+  technology stack, tracking progress in `PREPARE_MASTER.md` (read first on resume to skip
+  already-completed steps/versions). Multiple versions are processed sequentially in ascending
+  semver order. Manages its own Ralph Loop internally for cross-session continuity.
+- **Use when:** "prepare artifacts", "generate context", "prepare for development",
+  "resume preparation".
+- **Prerequisites:** `PRD.md`, `CLAUDE.md`.
+- **Output:** the complete `context/` artifact tree — `model/`, `mockup/`, `specification/`
+  and `test/` (each as described under its sub-skill below) — plus `CHANGELOG.md` entries per
+  step and the `context/prepare/PREPARE_MASTER.md` progress tracker (inferred config, per-version
+  × per-artifact status) for cross-session resumption.
+
+### `modelgen-relational`
+- **Invoke:** `/modelgen-relational <application> <version> [module:<m>]`
+- **What it does:** Extracts relational (SQL) entity models from user stories using DDD —
+  ERD diagrams (Mermaid) + per-module model documentation. Also handles "update/upgrade the
+  model" for incremental evolution.
+- **Use when:** the app's datastore is a relational DB (MySQL, PostgreSQL, SQLite …).
+- **Output:** `context/model/` — `MODEL.md` index + per-module `model.md` / `erd.mermaid`.
+
+### `modelgen-nosql`
+- **Invoke:** `/modelgen-nosql <application> <version> [module:<m>]`
+- **What it does:** Extracts NoSQL document models (embed-vs-reference analysis, Mermaid class
+  diagrams, JSON schema examples per collection). Database-agnostic (MongoDB, Couchbase,
+  DynamoDB, Firestore, CosmosDB).
+- **Use when:** the app's datastore is document-oriented. **Not** for relational schemas —
+  use `modelgen-relational`.
+- **Output:** `context/model/` — `MODEL.md` index + per-module `model.md` (embed/reference
+  decisions), Mermaid class diagram, and `schemas.json` JSON schema examples per collection.
+
+### `mockgen-tailwind`
+- **Invoke:** `/mockgen-tailwind <application> <version> [module:<m>]`
+- **What it does:** Generates HTML mockup screens (Alpine.js + HTMX assets, admin
+  dashboard layout, organized by user role) for human designer review. All mockups are
+  served by the single shared **Mockup Hub** at `<root>/mockup` — a zero-dependency Node
+  server (created/upgraded automatically) with a landing page listing every application
+  and role (unclickable until ready) and a configurable port (`PORT` env /
+  `mockup.config.json`).
+- **Use when:** mockups are needed and the target stack is server-rendered or plain HTML;
+  default mockup generator.
+- **Prerequisites:** `PRD.md`, `modelgen-*` output.
+- **Output:** `context/mockup/` — `MOCKUP.html` index, `mockup-manifest.json`, partials,
+  role folders (assets only; no per-app server) + shared hub at `<root>/mockup/`.
+
+### `mockgen-shadcn`
+- **Invoke:** `/mockgen-shadcn <application> <version> [module:<m>]`
+- **What it does:** Generates React + shadcn/ui mockup screens (Vite + React 19 + TypeScript +
+  React Router v7, admin dashboard layout, organized by user role) with
+  `base`/`basename` = `/{app_slug}/`, builds them (`npm run build`), and serves the `dist/`
+  output through the same shared **Mockup Hub** at `<root>/mockup` (Vite dev server remains
+  for design iteration only).
+- **Use when:** the target application is React/shadcn-based (pairs naturally with
+  `specgen-nextjs-react-tailwind` / `specgen-node-cli-web`).
+- **Prerequisites:** `PRD.md`, `modelgen-*` output.
+- **Output:** `context/mockup/` — `MOCKUP.html` index page, `mockup-manifest.json`, Vite +
+  React project files, layout components, vendored shadcn/ui components, role-specific page
+  components, and built `dist/` + shared hub at `<root>/mockup/`.
+
+### `specgen-*` — Technical Specification Generators
+
+All specgens share the same contract: **Invoke** `/specgen-<variant> <application> <version>
+[module:<m>]`; **Prerequisites** `PRD.md` + `modelgen-*` output (+ `mockgen-*` output for
+UI-bearing stacks); **Output** `context/specification/` — root `SPECIFICATION.md` + one
+self-contained `SPEC.md` per module (or per command for CLI stacks), with complete code
+samples and traceability tables. **Pick exactly ONE variant, matching the application's
+technology stack** (declared in `CLAUDE.md` / PRD Architecture Principle):
+
+| Skill | Pick when the application is… |
+|-------|-------------------------------|
+| `specgen-spring-jpa-jtehtmx` | Spring Boot 3 server-rendered web app (JTE + Tailwind + Alpine.js + htmx, Spring Modulith; optional Keycloak, RabbitMQ, Quartz/Batch, i18n) |
+| `specgen-spring-jpa-restapi` | Spring Boot 3 REST API (Spring Modulith; optional Keycloak resource server / JWT, RabbitMQ, Quartz/Batch) |
+| `specgen-laravel-eloquent-bladehtmx` | Laravel 12 server-rendered web app (Blade + Tailwind + Alpine.js + htmx, nwidart modules; optional Keycloak/Breeze, RabbitMQ, scheduling, i18n) |
+| `specgen-react-mui` | React 19 SPA with Material UI v6 (TypeScript 5, Vite 6, React Router 7, TanStack Query 5, Zustand 5, RHF 7, Zod 3; optional Keycloak/OIDC, WebSocket, i18n, MUI X grids/charts) |
+| `specgen-react-tailwind` | React 19 SPA with Tailwind CSS v3 + Headless UI v2 + Heroicons (same data stack as react-mui, no component framework; optional TanStack Table, Recharts, react-day-picker, Tiptap, reporting) |
+| `specgen-flutter-riverpod` | Flutter 3 mobile app (Dart 3, Riverpod 2, Hive 2, Dio 5, go_router 14, Firebase Messaging, freezed/json_serializable; optional Keycloak PKCE, WebSocket, i18n) |
+| `specgen-ts-cli` | Distributable Node.js CLI **tool** (TypeScript 5, Commander 12, tsup, Zod, chalk/ora; optional prompts, conf/cosmiconfig, SQLite, execa, got, @yao-pkg/pkg binaries) — terminal-only, no web UI |
+| `specgen-node-cli-web` | Self-hosted **web application distributed as a global npm CLI** — installed `npm i -g`, started `<app> start`, opened at `http://IP:PORT`. Single Node 22 process: Hono 4 API + embedded pre-built React 19/Vite 6 SPA (Tailwind v4, shadcn/ui), Drizzle + SQLite, hand-rolled scrypt sessions with first-run admin + forced password change, tsup, Biome, Vitest + Playwright with built-binary smoke test |
+| `specgen-sdk-java` | Java SDK **library** wrapping a remote REST API — Maven Multi-Release fat JAR, JDK 8 baseline + JDK 11+ overlay, OkHttp as sole runtime dependency |
+
+> **`specgen-ts-cli` vs `specgen-node-cli-web`:** if the deliverable is a terminal tool with
+> commands and flags → `specgen-ts-cli`. If the deliverable is a browser-accessed web app that
+> merely *installs and starts* via a CLI → `specgen-node-cli-web`.
+
+⚠️ `specgen-nextjs-react-tailwind` (Next.js 15 App Router) is documented but **not yet
+implemented** (empty stub — no SKILL.md). Do not invoke; fall back to `specgen-react-tailwind`
++ a REST API specgen, or ask the user.
+
+### `testgen-functional`
+- **Invoke:** `/testgen-functional <application> <version> [module:<m>]`
+- **What it does:** Generates a Playwright E2E test plan and per-module test specifications as
+  Markdown blueprints (scenarios, data seeding, cleanup) — NOT actual test code.
+- **Use when:** "generate test plan/spec", after specgen completes. Last artifact step.
+- **Prerequisites:** `PRD.md`, `modelgen-*`, `mockgen-*`, `specgen-*` outputs.
+- **Output:** `context/test/` — `TEST_PLAN.md`/`TEST_PLAN.mmd` + per-module `TEST_SPEC.md`.
+
+---
+
+## Phase 3 — Infrastructure
+
+### `util-preparek8senv`
+- **Invoke:** `/util-preparek8senv [environment]`
+- **What it does:** Generates StatefulSet-based K8s manifests for ALL 3rd party supporting
+  applications (databases, queues, caches, SSO, gateways) for one target environment, and
+  creates/updates `ENVIRONMENT.md` with per-environment configs and credentials. Output goes
+  directly into the gitignored `environment/` folder.
+- **Use when:** "prepare k8s environment", "setup infrastructure" — run BEFORE application
+  development so backing services exist.
+- **Prerequisites:** `CLAUDE.md`, `DEVTOOL.md`.
+- **Output:** `ENVIRONMENT.md` (created/updated with per-environment configs and credentials)
+  and `environment/` — `namespace.yaml` plus one StatefulSet-based manifest per 3rd party
+  application (PVC, ConfigMap, Secret, headless Service, NodePort Service).
+
+---
+
+## Phase 4 — Development
+
+### `conductor-feature-develop` (orchestrator)
+- **Invoke:** `/conductor-feature-develop <application> [version:<v>] [module:<m>]`
+- **What it does:** Implements the full application module-by-module (code + Playwright E2E
+  tests) using all generated artifacts, tracking progress in `IMPLEMENTATION_MASTER.md` and
+  per-module `IMPLEMENTATION_MODULE.md`. Auto-starts a Ralph Loop for cross-session
+  continuity; invokes `tracegen-matrix` and `depgen-k8s` at the end.
+- **Use when:** "implement the application", "start development", "develop from specs",
+  "resume implementation".
+- **Prerequisites:** all `conductor-feature-prepare` outputs (model/, mockup/,
+  specification/, test/).
+- **Output:** application source code organized by module; `context/develop/` tracking files
+  (`IMPLEMENTATION_MASTER.md` with overall status/execution order/pre-implementation
+  checklist, and per-module `IMPLEMENTATION_MODULE.md` with resource tables, implementation
+  checklists, user-story/NFR completion checklists and timestamped logs); Playwright E2E test
+  suite per module; then via auto-invoked sub-skills: `context/TRACEABILITY.md`, `Dockerfile`
+  and `k8s/` manifests.
+
+### `tracegen-matrix`
+- **Invoke:** `/tracegen-matrix <application> [version] [module]`
+- **What it does:** Links every PRD requirement ID and bug code to the implementing source
+  code and writes `context/TRACEABILITY.md`. Resolves from in-source CO2 comments
+  (`Implements:` / `NFR:` / `Constraints:` / `Bug fixes:`) with a name-based fallback;
+  optional codebase-memory MCP enrichment (works fully without it).
+- **Use when:** "generate/update traceability", "link requirements to code" — usually invoked
+  automatically as the final step of `conductor-feature-develop` and `conductor-defect`.
+- **Prerequisites:** `PRD.md`, `specification/*/SPEC.md`, application source code.
+- **Output:** `context/TRACEABILITY.md` — per-application matrix mapping every requirement ID
+  and bug code to the implementing source files.
+
+### `depgen-k8s`
+- **Invoke:** `/depgen-k8s <application> [environment]`
+- **What it does:** Generates a production-ready multi-stage Dockerfile (application root) and
+  Kubernetes manifests in the gitignored `<app_folder>/k8s/` for one target environment.
+  Auto-detects the stack (Spring Boot / Laravel / Node.js) from project files. Only CUSTOM
+  applications — never 3rd party services (those are `util-preparek8senv`'s job).
+- **Use when:** "containerize", "create a Dockerfile", "generate k8s manifests", "deploy this
+  app" — auto-invoked by `conductor-feature-develop` after all modules complete.
+- **Prerequisites:** `SPECIFICATION.md`, `CLAUDE.md`, application source code.
+- **Output:** `<app_folder>/Dockerfile` (multi-stage, production-ready) and
+  `<app_folder>/k8s/` — namespace, ConfigMap, Secret, Deployment, Service and Ingress YAML
+  files with env-var mapping and health/readiness probes (gitignored, per-machine).
+
+---
+
+## Phase 5 — Bug Fixing
+
+### `conductor-defect` (orchestrator)
+- **Invoke:** `/conductor-defect <application> [version:<v>] [module:<m>]`
+- **What it does:** Fixes bugs from `<app_folder>/context/BUG.md` one at a time: tags untagged
+  bugs, creates `BUG_MASTER.md`, then per bug — reproduce with Playwright, write
+  `BUG_TEST_SPEC.md`, plan (`BUG_FIX_PLAN.md`), fix, verify, and sync affected artifacts
+  (mockups, specs, models, PRD). Manages Ralph Loop internally; runs `tracegen-matrix` at the
+  end.
+- **Use when:** "fix bugs", "bug fix session", "resolve bugs from BUG.md",
+  "resume bug fixing".
+- **Prerequisites:** `BUG.md`, all `conductor-feature-prepare` outputs.
+- **Output:** fixed source code; tagged `BUG.md` (`[BUG-XXX]`); `context/bug/BUG_MASTER.md`
+  tracking file (statuses: NEW, IN_PROGRESS, FIXED, CANNOT_REPRODUCE, HIGH_IMPACT); per-bug
+  folder `context/bug/<module>/<BUG-XXX>/` with `reproduce.spec.ts`,
+  `screenshot_reproduce.png`, `BUG_TEST_SPEC.md`, `BUG_FIX_PLAN.md`, `screenshot_fixed.png`;
+  synced artifacts (mockups, specs, models, PRD) and an updated `context/TRACEABILITY.md`.
+
+---
+
+## Quick Decision Table
+
+| User intent sounds like… | Invoke |
+|---|---|
+| "start a new project / I have an app idea" | `util-projectinit` (then user runs `/brainstorm-loop`) |
+| "sync folders / CLAUDE.md changed / scaffold PRDs" | `util-projectsync` |
+| "check my requirements / review user stories" | `util-usanalyzer` |
+| "tag the new PRD items / add requirement IDs" | `util-ustagger` |
+| "prepare everything for development" | `conductor-feature-prepare` |
+| "design the data model / ERD" | `modelgen-relational` or `modelgen-nosql` (by datastore) |
+| "generate mockups / UI screens" | `mockgen-tailwind` or `mockgen-shadcn` (by stack) |
+| "write the technical spec" | the ONE `specgen-*` matching the stack (see table) |
+| "generate the test plan" | `testgen-functional` |
+| "set up databases/queues in k8s" | `util-preparek8senv` |
+| "build/implement the app" | `conductor-feature-develop` |
+| "link requirements to code" | `tracegen-matrix` |
+| "dockerize / deploy the app" | `depgen-k8s` |
+| "fix the reported bugs" | `conductor-defect` |

package/plugin/co2.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 80" width="200" height="80">
+  <text x="100" y="55" font-family="Arial, Helvetica, sans-serif" font-size="48" font-weight="bold" fill="#2563EB" text-anchor="middle">
+    CO<tspan font-size="32" baseline-shift="-8">2</tspan>
+  </text>
+</svg>

package/plugin/commands/brainstorm-loop.md

@@ -0,0 +1,129 @@
+---
+description: In-session loop — watch a folder for AI brainstorm session documents and advance each per the shared protocol (60s polling, token-efficient)
+argument-hint: [scan-root] [max-watch-rounds]
+allowed-tools: Bash(find:*), Bash(sleep:*), Bash(md5sum:*), Bash(sort:*), Bash(bash:*), Read, Write, Edit, Glob, Grep
+---
+
+# Brainstorm Session Loop (in-session, token-efficient)
+
+You are the **AI Agent** actor defined in `brainstorm-protocol.md`. Read that file
+from the scan root FIRST and follow it exactly. This command defines only the
+polling mechanics; the protocol governs all document handling.
+
+**Scan root**: `$1` (default: current working directory)
+**Max watch rounds**: `$2` (default: 20 — each watch round blocks up to ~9 minutes,
+so the default covers roughly a 3-hour working session)
+
+## Core principle: pay tokens only for change
+
+You have session memory — use it. Maintain an in-memory cache across cycles:
+`{ file_path → (mtime, state, current_round, last_turn_decision) }`.
+Never fully re-read a file whose mtime is unchanged since you last processed it.
+
+## Phase 1 — Initial full scan (once, at invocation)
+
+1. `find <scan-root> -name '*.brainstorm.md' -not -path '*/node_modules/*' -printf '%p %T@\n'`
+2. For each file, read the frontmatter head; keep only `doc_type: ai-brainstorm-session`.
+3. Build the cache. For every document where it is YOUR TURN per the Status table
+   (protocol §5.1 NEW / §5.3 continue / §5.4 finalize), act now — one document at a
+   time, sequentially, with strict session isolation (§6.7) and the pre-write
+   re-read rule (§6.8). Update the cache after each write.
+4. Report one concise summary line.
+
+## Phase 2 — Watch loop (repeat up to max-watch-rounds)
+
+Run this single BLOCKING bash call (set the bash timeout to 600000 ms). It polls
+internally every 60 s and returns early only when something changed — idle waiting
+costs you zero tokens:
+
+```bash
+ROOT="<scan-root>"
+snap() { find "$ROOT" -name '*.brainstorm.md' -not -path '*/node_modules/*' -printf '%p %T@\n' | sort | md5sum; }
+S0=$(snap)
+for i in 1 2 3 4 5 6 7 8 9; do
+  sleep 60
+  S1=$(snap)
+  if [ "$S0" != "$S1" ]; then echo "CHANGED"; exit 0; fi
+done
+echo "UNCHANGED"
+```
+
+- On `UNCHANGED`: emit nothing except a minimal heartbeat (e.g. `…watching (round 4/20)`),
+  then start the next watch round. Do not re-read any files.
+- On `CHANGED`: re-run the find/printf listing, diff mtimes against the cache, and
+  fully re-read ONLY the changed files (plus any brand-new files). For each changed
+  document, derive the turn from its Status table (authoritative over frontmatter)
+  and act per protocol §5.1 / §5.3 / §5.4 if it is your turn. A human save without a
+  status flip is not your turn — update the cached mtime and resume watching.
+  Update the runtime status file, then report one concise line, e.g.:
+  `advanced api-key-rotation (round 2 → 3); finalized cost-model (xlsx written); 1 still awaiting human`
+
+## Runtime status file (compaction advisory)
+
+Maintain a runtime dashboard at `<scan-root>/.brainstorm-loop-status.md`. This file
+is intentionally OUTSIDE the `*.brainstorm.md` watch glob — the watcher must never
+see it (writing to it must not trigger a wake). Update it only at moments you are
+already awake: after the Phase 1 scan, after acting on any document, and at the end
+of every watch round. Never wake solely to update it.
+
+Format (override the whole file each update):
+
+```markdown
+# Brainstorm Loop Status
+- loop_started: <ISO timestamp>
+- watch_round: 7 / 20
+- agent_actions_this_conversation: 9
+- compact_advice: OK          <!-- OK | RECOMMENDED | REQUIRED -->
+- advice_reason: —
+
+## Sessions
+| session_id       | state          | round | last activity        |
+| ---------------- | -------------- | ----- | -------------------- |
+| api-key-rotation | AWAITING_HUMAN | 3     | agent asked round 3  |
+| cost-model       | CLOSED         | 5     | xlsx finalized       |
+```
+
+Advisory heuristic (token count is not directly observable — use work proxies):
+- `OK` — fewer than ~10 agent actions since the conversation started (or since the
+  user last compacted) and under 2/3 of max watch rounds.
+- `RECOMMENDED` — ~10+ agent actions, or watch rounds past 2/3 of max, or any
+  single action involved reading large reference files. Set advice_reason
+  accordingly (e.g. "12 actions incl. 2 large reference reads").
+- `REQUIRED` — max watch rounds reached; the loop is stopping. Reason:
+  "loop halted — run /compact then /brainstorm-loop to resume".
+
+If the user tells you they have compacted (or you detect compaction per the
+post-compaction rule), reset the action counter and advice to OK after the
+Phase 1 rescan.
+
+## Context hygiene
+
+- Keep per-cycle output to 1–2 lines. Never echo document contents back into chat
+  unless the user asks.
+- If ALL sessions reach `CLOSED`, say so and stop the loop early.
+- On reaching max watch rounds with sessions still active, stop and tell the user:
+  run `/compact` if the session is long, then re-invoke `/brainstorm-loop` — the
+  first phase-1 scan will rebuild the cache from the files, so nothing is lost.
+- All coordination state lives in the documents, never only in your memory: after
+  every action, frontmatter `state`/`current_round` must reflect reality, so a
+  compaction or restart is always safe.
+
+## Post-compaction rule
+
+If this conversation has been compacted (auto or manual) at any point since the
+last Phase 1 scan, treat your in-memory cache and any remembered per-session
+conclusions as INVALID. Immediately redo Phase 1 (full scan, rebuild cache,
+re-derive every turn from the Status tables) before taking any action. Never act
+on a summarized memory of a document's state — the files are the only truth.
+
+## Hard boundaries
+
+- Never set `Session completion` yourself.
+- Never edit Human-owned content (answers, feedback, Objective, Context,
+  Output Specification).
+- Never let one session's content influence another (protocol §6.7).
+
+## Portability note
+
+`find -printf` is GNU find (Linux / Git Bash / WSL). On macOS/BSD, substitute:
+`find "$ROOT" -name '*.brainstorm.md' -exec stat -f '%N %m' {} \; | sort | md5sum`