@rashidee/co2 1.2.5

package/plugin/skills/util-projectinit/reference/brainstorm-setup-guide.md

@@ -0,0 +1,153 @@
+# Brainstorm Session Loop — Complete Setup Guide
+
+A file-based, turn-based brainstorming protocol between you (Human) and Claude Code
+(AI Agent), running entirely inside your live Claude Code session — no headless
+`claude -p` calls, no extra API token cost for idle waiting.
+
+**The kit (3 files):**
+
+| File                      | Role                                            | Where it lives                              |
+| ------------------------- | ----------------------------------------------- | ------------------------------------------- |
+| `brainstorm-protocol.md`  | Shared static protocol (rules, state machine)   | Root of your scan folder                    |
+| `TEMPLATE.brainstorm.md`  | Scaffold copied for every new session           | Anywhere handy                              |
+| `brainstorm-loop.md`      | The `/brainstorm-loop` slash command            | `.claude/commands/` (project or `~/.claude/commands/` global) |
+
+Generated at runtime by the agent (do not create manually):
+`<scan-root>/.brainstorm-loop-status.md` — live dashboard + compaction advisory.
+
+---
+
+## Part 1 — One-time setup
+
+1. **Choose a scan root** — the folder the agent will scan recursively,
+   e.g. `~/projects/brainstorms/`. Subfolders are fine; each can hold different
+   topics/projects.
+
+2. **Place `brainstorm-protocol.md` at the scan root.** It is never edited during
+   sessions.
+
+3. **Install the slash command** — copy `brainstorm-loop.md` to:
+   - `<project>/.claude/commands/` → available in that project, or
+   - `~/.claude/commands/` → available in every Claude Code session.
+
+4. **Pre-approve the bash patterns** the watcher needs (`find`, `sleep`, `md5sum`,
+   `sort`), either via "always allow" on first prompt or in
+   `.claude/settings.json` permissions. This matters: an unanswered permission
+   prompt silently pauses the loop while you think it's watching.
+
+5. Keep `TEMPLATE.brainstorm.md` somewhere convenient for copying.
+
+## Part 2 — Creating a session
+
+6. Copy the template into the scan root (or any subfolder) and name it
+   `<topic>.brainstorm.md` — the `.brainstorm.md` suffix is the discovery
+   pre-filter.
+
+7. Fill in the four human-owned parts:
+   - **Frontmatter**: `session_id` (unique slug) and `title`. Leave
+     `state: NEW` and `current_round: 0` untouched — the agent owns those.
+   - **# Objective**: what the session must produce.
+   - **# Context**: background and constraints; list any external input files
+     under `## References` (relative paths) — the agent reads them before Round 1.
+   - **# Output Specification**: `format` (`md-inline` / `md-file` / `xlsx` /
+     `docx` / `pptx`), `destination` path (unless md-inline), `versioning`
+     (`overwrite` / `timestamped`), and optional `structure` hints.
+
+8. Save. Create as many session files as you want — each is fully independent;
+   the agent never lets one session's content influence another.
+
+## Part 3 — Running the loop
+
+9. In your Claude Code session, run:
+
+   ```
+   /brainstorm-loop <scan-root>
+   ```
+
+   (or just `/brainstorm-loop` if Claude Code was launched from the scan root).
+
+10. **Phase 1 (immediate)**: full scan. Every `state: NEW` session gets an initial
+    draft in `# Output` plus `## Round 1` questions. Sessions move to
+    `AWAITING_HUMAN`.
+
+11. **Phase 2 (ongoing)**: the agent enters a token-efficient watch loop — a
+    blocking bash call polls file mtimes every 60 s and returns only on change
+    (or after ~9 min). Idle waiting costs essentially zero tokens. Default bound:
+    20 watch rounds ≈ 3 hours.
+
+12. Keep two editor tabs open: your session file(s) and
+    `.brainstorm-loop-status.md` (the live dashboard).
+
+## Part 4 — The iteration cycle (repeat per round)
+
+13. Read the draft in `# Output` and the questions in the current `## Round N`.
+
+14. Write answers under each `### Answer X`; optional notes under
+    `Feedback > Round N`. **Save as often as you like** — saves alone never
+    trigger the agent. Unanswered questions mean "agent's judgment".
+
+15. **Commit your turn** by flipping exactly ONE status in the Status table:
+    - Continue iterating → `Round N answers and feedback` → `COMPLETED`
+    - Satisfied with output → `Session completion` (row 0) → `COMPLETED`
+
+16. Within ~60 s the agent wakes, re-reads only changed files, and:
+    - **Continue**: overrides the `# Output` draft, appends `## Round N+1`
+      questions → back to step 13.
+    - **Complete**: renders the final artifact exactly per your Output
+      Specification, records its path under `Output > ## Final Artifact`, sets
+      `state: CLOSED`. Closed sessions cost zero tokens from then on.
+
+    How it decides: the Status table is the single source of truth. Row 0
+    (`Session completion = COMPLETED`) is checked FIRST — so final-round answers
+    written before/with the flip are incorporated into the final artifact rather
+    than triggering another round. Frontmatter `state` is only a scan cache /
+    processed-acknowledgment (`CLOSED` is the idempotency guard against
+    double-finalization).
+
+## Part 5 — Context management (compaction)
+
+17. Watch `compact_advice` in `.brainstorm-loop-status.md`:
+    - `OK` — keep working.
+    - `RECOMMENDED` — at your next natural pause: finish the current answer, flip
+      your status, let the agent's turn land, then run `/compact` followed by
+      `/brainstorm-loop` to resume.
+    - `REQUIRED` — the loop hit its watch-round bound and has stopped; run
+      `/compact` then `/brainstorm-loop`.
+
+18. Why the manual pair beats relying on auto-compact: auto-compact fires exactly
+    when context grows — i.e., mid-action — and leaves the agent running on a
+    *summary* of its instructions. `/compact` + re-invoking `/brainstorm-loop`
+    compacts at a known-idle boundary AND reloads the verbatim command text.
+    Auto-compact is still SAFE (all state lives in the files; the command's
+    post-compaction rule forces a full rescan before any action) — just less
+    deterministic.
+
+19. Nothing is ever lost across compaction, restarts, or closed terminals: the
+    documents are the database. Re-invoking `/brainstorm-loop` rebuilds everything
+    from Phase 1.
+
+## Part 6 — Troubleshooting
+
+- **Session stuck in `state: ERROR`** → open it, read the appended
+  `# Agent Notice`, fix the described issue, save. The agent re-checks it on the
+  next change detection and resumes if fixed.
+- **Agent didn't react to your edit** → confirm you flipped a status in the table
+  (a content save alone is deliberately ignored), and that the file matches
+  `*.brainstorm.md` under the scan root.
+- **Loop seems frozen** → check the terminal for a pending permission prompt
+  (see step 4), and check `watch_round` in the status file — the loop may simply
+  be mid-watch (up to 9 min between heartbeats is normal).
+- **macOS/BSD** → the watcher snippet uses GNU `find -printf`; the command file
+  includes the `stat -f` substitution in its Portability note.
+
+## Quick reference — who writes what
+
+| Surface                          | Human | AI Agent |
+| -------------------------------- | :---: | :------: |
+| Objective / Context / Output Spec |  ✔️   |    —     |
+| Answers, Feedback                |  ✔️   |    —     |
+| Status table flips               |  ✔️   | ✔️ (its own rows) |
+| Question rounds, Output draft    |   —   |    ✔️    |
+| Frontmatter `state` / `current_round` | — |    ✔️    |
+| `.brainstorm-loop-status.md`     |   —   |    ✔️    |
+| Final artifact file              |   —   |    ✔️    |

package/plugin/skills/util-projectinit/reference/brainstorm-template-appdev.md

@@ -0,0 +1,87 @@
+---
+doc_type: ai-brainstorm-session
+session_id: CHANGE-ME-<project-code-lower>-co2-context
+title: CHANGE ME — <Project Name> CO2 context generation
+created: <YYYY-MM-DD>
+state: NEW
+current_round: 0
+protocol_version: "2.0"
+---
+
+<!-- CO2 application-idea session. Protocol: brainstorm-protocol.md at the scan
+     root. Artifact rules: co2-context-generation-guide.md (listed in References —
+     the agent MUST read it in full before Round 1). -->
+
+# Objective
+
+Brainstorm the application idea described in `# Context` and generate the complete
+CO2 project context tree — a root `CLAUDE.md` plus one `PRD.md` per custom
+application (`<app_folder>/context/PRD.md`) — following
+`co2-context-generation-guide.md` exactly:
+
+- **Phase A**: converge CLAUDE.md (apps, modules, bounded contexts, App Codes,
+  App × Module matrix) until I lock the inventory.
+- **Phase B**: generate and refine every application's PRD.md
+  (modules → versioned User Stories / NFRs / Constraints / References / Tests),
+  where User Stories drive UI/UX, NFRs drive validation and business logic,
+  Constraints define scope, References support, and Tests define the test specs.
+
+Drafts are written directly to the destination tree every round; the `Output`
+section below holds only the dashboard (phase, inventory, matrix, TODO ledger,
+round diff).
+
+# Context
+
+<!-- Human: describe the application idea — even one paragraph is enough for
+     Round 0. Include, if known: the problem and who feels it, the actors,
+     desired outcomes, channels (web/mobile/API), known integrations,
+     compliance/regional constraints, expected scale, what is explicitly
+     out of scope. Leave the rest to the agent's probing. -->
+
+[DESCRIBE YOUR APPLICATION IDEA HERE]
+
+## References
+
+- ./co2-context-generation-guide.md
+<!-- Optional additional inputs, e.g. an existing CLAUDE.md or PRD.md to use as a
+     style reference:
+- ./reference/skolafund/CLAUDE.md
+- ./reference/skolafund/skolafund_web/context/PRD.md
+-->
+
+# Output Specification
+
+| Field       | Value                                                          |
+| ----------- | -------------------------------------------------------------- |
+| format      | co2-tree                                                        |
+| destination | ./  <!-- project root to scaffold; use ./output/<project-code-lower>/ to draft into a subfolder instead --> |
+| versioning  | overwrite                                                       |
+| structure   | CLAUDE.md + <app_folder>/context/PRD.md per custom application, per co2-context-generation-guide.md §2 |
+
+
+# Status
+
+| No  | Status of          | Action By | Status  |
+| :-: | ------------------ | --------- | ------- |
+|  0  | Session completion | Human     | PENDING |
+
+
+# Question
+
+<!-- AI Agent appends "## Round N" sections here. Expect Phase A rounds to probe
+     framing/actors/data/workflows/integrations (co2-context-generation-guide.md §5),
+     then the inventory-lock question, then Phase B rounds probing per-module
+     stories, rules, scope and tests (§10). -->
+
+
+# Output
+
+<!-- AI Agent dashboard — overridden every round:
+     phase & round, inventory summary (project code, apps + App Codes + ports,
+     module counts), App × Module matrix, [TODO] ledger, diff since last round.
+     On completion: ## Final Artifact with destination path + hand-off summary. -->
+
+
+# Feedback
+
+<!-- AI Agent appends "## Round N" here in lockstep with Question. -->