@rashidee/co2 1.2.5

package/plugin/skills/util-projectinit/SKILL.md

@@ -0,0 +1,307 @@
+---
+name: util-projectinit
+model: claude-sonnet-4-6
+effort: medium
+description: >
+  Initialize a new CO2 project by validating a hand-authored brainstorm session document and
+  setting up the file-based, turn-based BRAINSTORMING session kit around it. The ONLY valid
+  input is the path to an EXISTING `<topic>.brainstorm.md` file the user authored from the CO2
+  application-development template (`brainstorm-template-appdev.md`) — free-form prompts, idea
+  text or topic slugs are NOT accepted. The skill strictly validates the session document
+  against the template, rejecting with a report on any deviation — it never creates or edits
+  the session document. On a clean pass it scaffolds the rest of the brainstorm kit in the
+  project folder: the shared `brainstorm-protocol.md`, the `co2-context-generation-guide.md`
+  artifact rules, and the `/brainstorm-loop` slash command. The user then manually runs
+  `/brainstorm-loop` — an iterative, token-efficient loop that converges the root `CLAUDE.md`
+  (Phase A) and every application's `PRD.md` (Phase B) round by round. This skill seeds the
+  project — it is the first skill to run before any `modelgen-*`, `mockgen-*`, `specgen-*`,
+  `testgen-*`, `util-projectsync` or `util-preparek8senv` invocation.
+  Trigger on keywords: "init project", "initialize project", "start project", "bootstrap project",
+  "scaffold project", "new project", "project init", "brainstorm project", "brainstorm app idea",
+  "setup brainstorm", "start brainstorming", "brainstorm session", "generate CLAUDE.md".
+  Accepts one MANDATORY argument: the path to an existing `<topic>.brainstorm.md` session
+  document based on the CO2 template. If the argument is missing, is not a `.brainstorm.md`
+  path, or the file does not exist, the skill stops and instructs the user to copy the
+  template manually.
+---
+
+# Util Project Init — CO2 Brainstorm Session Setup
+
+Bootstrap a new CO2 project by validating a **user-authored brainstorming session document**
+and setting up the brainstorm kit around it. A one-shot generation from a one-paragraph brief
+produces shallow, guessed context; the brainstorm loop instead converges the context **round by
+round** — the agent drafts, asks focused questions, the user answers in the document, and the
+drafts improve until the user locks them.
+
+The brainstorm produces the complete CO2 project context tree:
+
+- **Phase A** — root `CLAUDE.md` (apps, modules, bounded contexts, App Codes, App × Module matrix)
+- **Phase B** — one `PRD.md` per custom application (versioned User Stories / NFRs / Constraints /
+  References / Tests)
+
+`DEVTOOL.md` and `ENVIRONMENT.md` are NOT produced by the brainstorm — they come later
+(`util-preparek8senv` and per-developer setup). Once the brainstorm session is CLOSED, downstream
+skills (`util-projectsync`, `modelgen-*`, `mockgen-*`, `specgen-*`, `testgen-*`, `conductor-*`)
+take over.
+
+**This skill validates and sets up the kit only. It never creates or edits the session
+document, and it never runs the brainstorm loop itself** — the user authors the session
+document from the template beforehand and manually runs `/brainstorm-loop` when ready.
+
+## The Kit
+
+The session document is the **input** — hand-authored by the user from
+`reference/brainstorm-template-appdev.md`. Three supporting files are copied from this skill's
+`reference/` folder:
+
+| File | Copied to | Role |
+|------|-----------|------|
+| `<topic>.brainstorm.md` | — (input — hand-authored by the user from `brainstorm-template-appdev.md`) | The session document the user fills in and the loop iterates on — validated by this skill, never created or edited by it |
+| `brainstorm-protocol.md` | `<project-root>/brainstorm-protocol.md` | Shared static protocol (state machine, turn rules) — never edited during sessions |
+| `co2-context-generation-guide.md` | `<project-root>/co2-context-generation-guide.md` | Artifact rules the agent follows when drafting CLAUDE.md and PRD.md — referenced from the session document |
+| `brainstorm-loop.md` | `<project-root>/.claude/commands/brainstorm-loop.md` (only if the command is not already available) | The `/brainstorm-loop` slash command — the polling watch loop |
+
+> **Plugin note:** when this skill is installed as part of the `co2-skills` plugin, the
+> `/brainstorm-loop` command ships with the plugin (`commands/brainstorm-loop.md`) and is already
+> available — the project-local copy is a fallback for setups where the skill files were copied
+> manually into `.claude/skills/`.
+
+Generated at runtime by the loop (never created by this skill):
+`<project-root>/.brainstorm-loop-status.md` — the live dashboard + compaction advisory.
+
+## Input Resolution
+
+```
+/util-projectinit <path-to-topic.brainstorm.md>
+```
+
+| Argument | Required | Example | Description |
+|----------|----------|---------|-------------|
+| `<session-file>` | **Yes** | `recruitment-hub.brainstorm.md` | Path to an EXISTING session document authored by the user from `brainstorm-template-appdev.md`. Free-form idea text or topic slugs are NOT accepted. |
+
+### Argument Rules
+
+1. The argument is **mandatory**, must be a path whose filename ends in `.brainstorm.md`, and
+   must point to an existing file.
+2. If the argument is omitted, is not a `.brainstorm.md` path, or the file does not exist →
+   **stop** and print the block below, substituting `<template-path>` with the resolved
+   absolute path of `reference/brainstorm-template-appdev.md` inside this skill's folder:
+
+   ```
+   ## util-projectinit — session document required
+
+   This skill takes exactly one argument: the path to an existing
+   <topic>.brainstorm.md authored from the CO2 template. Free-form prompts
+   or idea text are not accepted.
+
+   To create one:
+     1. Copy the template
+          <template-path>
+        to your project root as <topic>.brainstorm.md
+        (topic = short kebab-case slug, e.g. recruitment-hub.brainstorm.md)
+     2. Fill in the human-owned parts:
+        - frontmatter: session_id (<topic>-co2-context), title, created (today, YYYY-MM-DD)
+        - # Context: describe your application idea
+        - ## References: optional style-reference files (relative paths; keep the `./co2-context-generation-guide.md` line)
+        - # Output Specification: confirm destination (default ./)
+        Leave untouched: state, current_round, protocol_version, # Objective,
+        # Status, # Question, # Output, # Feedback.
+     3. Re-run: /util-projectinit <topic>.brainstorm.md
+   ```
+
+3. **Never create the session document on the user's behalf** — not even a template copy.
+
+## Validation
+
+Read the session document and check it against `reference/brainstorm-template-appdev.md`.
+Validation is **read-only and strict**: if ANY check fails, print the validation report
+(format below) listing EVERY failed check with expected vs. found, and **stop** — do not set
+up the kit. Never edit the session document; the user fixes it and re-runs.
+
+| # | Check | Rule |
+|---|-------|------|
+| V1 | Frontmatter | YAML frontmatter present with `doc_type: ai-brainstorm-session` |
+| V2 | `session_id` | Set, contains no `CHANGE-ME`, is kebab-case, ends with `-co2-context`, and its `<topic>` part matches the filename (`<topic>.brainstorm.md`) |
+| V3 | `title` | Set, contains no `CHANGE ME` and no `<Project Name>` placeholder |
+| V4 | `created` | A real `YYYY-MM-DD` date (not the `<YYYY-MM-DD>` placeholder) |
+| V5 | `state` / `current_round` | Requires `state: NEW` and `current_round: 0`; if `state` instead holds a recognized in-progress/finished value (`AWAITING_HUMAN`, `AWAITING_AGENT`, `ERROR`, `CLOSED`), reject with *"this session is already in progress — resume it with `/brainstorm-loop` instead"*; if the fields are missing or hold an unrecognized value, report a plain expected-vs-found row instead |
+| V6 | `protocol_version` | Exactly `"2.0"` |
+| V7 | Sections | All template sections present: `# Objective`, `# Context` (with `## References`), `# Output Specification`, `# Status`, `# Question`, `# Output`, `# Feedback` |
+| V8 | `# Context` filled | The `[DESCRIBE YOUR APPLICATION IDEA HERE]` placeholder is gone and the section contains non-empty prose |
+| V9 | Guide reference | `## References` still lists `./co2-context-generation-guide.md` |
+| V10 | Output Specification | `format` is `co2-tree` and `destination` is set |
+| V11 | `# Status` table | Exactly the template's single row 0: `Session completion | Human | PENDING` |
+| V12 | Agent-owned sections | `# Question`, `# Output` and `# Feedback` bodies are empty (HTML comments allowed) |
+
+### Validation report format
+
+```
+## Session Document Validation FAILED — <file>
+
+| # | Check | Expected | Found |
+|---|-------|----------|-------|
+| V4 | created date | real YYYY-MM-DD | <YYYY-MM-DD> (placeholder) |
+| V8 | # Context filled | idea prose | [DESCRIBE YOUR APPLICATION IDEA HERE] |
+
+Fix the items above in <file> and re-run:
+    /util-projectinit <file>
+(This skill never edits your session document.)
+```
+
+## Pre-Flight Checks
+
+Inspect the project root (the folder where Claude Code was launched) before writing anything.
+The skill is **non-destructive** — it never overwrites any existing file:
+
+| Condition | Action |
+|-----------|--------|
+| Another `*.brainstorm.md` with `session_id: *-co2-context` exists (besides the input file) and is not `state: CLOSED` | Warn: a CO2 context session is already in progress; ask whether to set up this second session anyway or resume the existing one with `/brainstorm-loop`. |
+| `CLAUDE.md` exists at the project root | Warn: the project looks already initialized. The brainstorm's destination will **overwrite CLAUDE.md draft-by-draft** once the loop runs. Since this skill never edits the session document, advise the user to change the session's `destination` to `./output/<project-code-lower>/` themselves and re-run if they want to keep the current CLAUDE.md untouched. Confirm before proceeding with `destination: ./`. |
+| `brainstorm-protocol.md` / `co2-context-generation-guide.md` exist | Skip copying that file (log "already present"). |
+| `.claude/commands/brainstorm-loop.md` exists | Skip the command copy. |
+
+## Workflow
+
+### 1. Validate the session document
+
+Run the full V1–V12 validation above. On any failure: print the validation report and stop.
+Only continue to the setup steps below on a clean pass.
+
+### 2. Ensure the `/brainstorm-loop` command is available
+
+1. If running as the `co2-skills` plugin, the command is already installed with the plugin —
+   nothing to do.
+2. Otherwise (or when unsure), copy `reference/brainstorm-loop.md` from this skill's folder to
+   `<project-root>/.claude/commands/brainstorm-loop.md` (create the `.claude/commands/` folder if
+   needed). Do not modify the file content.
+3. Remind the user in the final instructions: if `/brainstorm-loop` is not recognized, restart the
+   Claude Code session so newly added commands are picked up.
+
+### 3. Copy the protocol and the generation guide to the project root
+
+Copy verbatim from this skill's `reference/` folder:
+
+- `brainstorm-protocol.md` → `<project-root>/brainstorm-protocol.md`
+- `co2-context-generation-guide.md` → `<project-root>/co2-context-generation-guide.md`
+
+Both must sit at the **scan root** (the project root): the loop reads the protocol from there,
+and the session document references the guide as `./co2-context-generation-guide.md`.
+
+### 4. Recommend permission pre-approval (Claude Code CLI)
+
+The watch loop's blocking poll uses `find`, `sleep`, `md5sum` and `sort` via Bash. An unanswered
+permission prompt **silently pauses the loop** while the user thinks it is watching. Tell the
+user to either:
+
+- choose **"Yes, and don't ask again"** on the first permission prompt after starting the loop, or
+- pre-approve in `<project-root>/.claude/settings.json`:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash(find:*)",
+      "Bash(sleep:*)",
+      "Bash(md5sum:*)",
+      "Bash(sort:*)"
+    ]
+  }
+}
+```
+
+If the user asks the skill to do it, merge these entries into the existing
+`.claude/settings.json` (or `.claude/settings.local.json` if the user prefers not to commit
+them) without removing anything already there.
+
+### 5. Print the instruction block
+
+End with a single instruction block. This is the hand-off — the skill stops here and the user
+drives the rest from the Claude Code CLI:
+
+```
+## Brainstorm Session Ready
+
+### Files set up
+| File | Status |
+|------|--------|
+| <topic>.brainstorm.md | Validated — YOUR session document (V1–V12 passed) |
+| brainstorm-protocol.md | Copied |
+| co2-context-generation-guide.md | Copied |
+| .claude/commands/brainstorm-loop.md | Copied | (or "Provided by co2-skills plugin")
+
+### Next steps (manual)
+
+1. VERIFY the session document <topic>.brainstorm.md one last time in your editor:
+   - `# Context` — your application idea is stated the way you want it; the
+     agent probes for the rest round by round.
+   - `## References` — style-reference files (an existing CLAUDE.md or PRD.md)
+     are listed as relative paths, if you want them used.
+   - `# Output Specification` — `destination` is where you want the context
+     tree drafted (default `./` = this project root).
+   - Do NOT touch `state`, `current_round`, `# Status`, `# Question`, `# Output`.
+
+2. START the loop in this Claude Code session:
+
+       /brainstorm-loop
+
+   (add the folder as an argument if your session file lives elsewhere:
+   `/brainstorm-loop <scan-root>`). If the command is not recognized, restart
+   Claude Code and run it again.
+
+3. ITERATE — each round:
+   - The agent drafts CLAUDE.md/PRD.md to the destination and appends numbered
+     questions under `# Question > ## Round N`.
+   - Answer under each `### Answer X` (unanswered = "agent's judgment"), save as
+     often as you like — saves alone never trigger the agent.
+   - COMMIT your turn by flipping exactly ONE row in the `# Status` table:
+       keep iterating → set `Round N answers and feedback` to COMPLETED
+       finish        → set `Session completion` (row 0) to COMPLETED
+   - The agent wakes within ~60 s of the flip.
+
+4. WATCH `.brainstorm-loop-status.md` (the live dashboard):
+   - `compact_advice: RECOMMENDED/REQUIRED` → at your next pause run /compact,
+     then /brainstorm-loop again. Nothing is lost — the documents are the database.
+
+5. WHEN CLOSED — the CO2 context tree (CLAUDE.md + per-app PRD.md) is at the
+   destination. Continue the CO2 workflow:
+   - /util-projectsync         → scaffold app folders, PRD.md/BUG.md reconciliation
+   - /conductor-feature-prepare → models, mockups, specifications, test specs
+```
+
+Adapt the block to what actually happened (files skipped because they existed, plugin-provided
+command).
+
+## Important Rules
+
+- **Validate-only for the session document.** Never create, copy, template-fill, or edit
+  `<topic>.brainstorm.md` — not to fix a placeholder, not to correct a date, not even when the
+  user asks during setup. On any validation failure, report and stop; the user edits the file.
+- **Setup only — never run the loop.** Always end by instructing the user to run
+  `/brainstorm-loop` manually.
+- **Non-destructive.** Never overwrite an existing `brainstorm-protocol.md`,
+  `co2-context-generation-guide.md`, or `.claude/commands/brainstorm-loop.md`. Skip and report.
+- **Copy verbatim.** The protocol, guide, and command files are copied byte-for-byte from
+  `reference/` — never edited, summarized, or "improved" during setup.
+- **One session document per topic.** Multiple independent sessions are allowed (the protocol
+  isolates them), but warn before setting up a second `*-co2-context` session for the same
+  project.
+- **The session document is fully human-owned.** This skill reads it for validation and
+  nothing more. It never pre-answers questions, never adds rounds, never touches the Status
+  table.
+- **Claude Code CLI is the interaction surface.** Instructions must be terminal-friendly: the
+  loop runs inside the live session (no headless `claude -p`), the user edits the session file in
+  a separate editor while the loop watches, and permission prompts appear in the terminal — an
+  unanswered one silently pauses the loop (hence the pre-approval step).
+- **Do not create per-application folders, DEVTOOL.md, ENVIRONMENT.md, or K8s manifests.** The
+  brainstorm produces CLAUDE.md + PRD.md; folder scaffolding is `util-projectsync`'s job and
+  environment expansion is `util-preparek8senv`'s job.
+
+## Reference Files
+
+| File | Read when |
+|------|-----------|
+| `reference/brainstorm-setup-guide.md` | For the full end-to-end walkthrough (setup, iteration cycle, compaction, troubleshooting) — use it to answer any user question about how the loop works |
+| `reference/brainstorm-protocol.md` | To answer questions about the state machine, turn rules, or error handling |
+| `reference/brainstorm-template-appdev.md` | The template users copy manually to author their session document — also the validation baseline for V1–V12 |
+| `reference/co2-context-generation-guide.md` | The artifact rules the loop's agent follows (Phase A/B, probing checklists, CLAUDE.md/PRD.md content rules) |
+| `reference/brainstorm-loop.md` | The `/brainstorm-loop` command source |

package/plugin/skills/util-projectinit/reference/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`

package/plugin/skills/util-projectinit/reference/brainstorm-protocol.md

@@ -0,0 +1,144 @@
+# AI Brainstorm Session Protocol (v2.0)
+
+This document defines the shared protocol for all AI brainstorm session documents.
+It is **static** — never edited during a session. All per-session state lives in the
+session documents themselves.
+
+---
+
+## 1. Discovery
+
+The AI Agent identifies session documents by scanning a root folder **recursively** using:
+
+1. **Filename pre-filter**: glob pattern `**/*.brainstorm.md`
+2. **Authoritative marker**: YAML frontmatter containing `doc_type: ai-brainstorm-session`
+
+A file matching the glob but missing the frontmatter marker is **ignored** (not an error).
+A file with the marker but a malformed structure is moved to `state: ERROR` (see §7).
+
+## 2. Session Document Anatomy
+
+Every session document contains, in order:
+
+| Section                | Owner    | Purpose                                                        |
+| ---------------------- | -------- | -------------------------------------------------------------- |
+| YAML frontmatter       | AI Agent | Machine-readable state for cheap scanning (human sets it once at creation) |
+| `# Objective`          | Human    | What this session must produce                                 |
+| `# Context`            | Human    | Background the agent needs; may include `## References` to external files |
+| `# Output Specification` | Human  | Format, destination, and versioning of the final artifact      |
+| `# Status`             | Both     | The turn-based state table — the **single source of truth**    |
+| `# Question`           | Both     | Agent appends `## Round N` with questions; Human writes answers |
+| `# Output`             | AI Agent | The inline draft, overridden every round                       |
+| `# Feedback`           | Human    | Optional per-round free-form feedback                          |
+
+## 3. Frontmatter Schema
+
+```yaml
+---
+doc_type: ai-brainstorm-session   # REQUIRED — discovery marker
+session_id: <unique-slug>          # REQUIRED — set by human at creation
+title: <short human-readable name>
+created: <YYYY-MM-DD>
+state: NEW                         # NEW | AWAITING_HUMAN | AWAITING_AGENT | CLOSED | ERROR
+current_round: 0                   # maintained by AI Agent
+protocol_version: "2.0"
+---
+```
+
+- `state` and `current_round` are **maintained by the AI Agent only**. The Human never edits them.
+- The Human's sole write surfaces are: answers, feedback, and the `Status` table.
+
+## 4. State Machine
+
+```
+             agent writes Round 1 questions
+  NEW ──────────────────────────────────────► AWAITING_HUMAN
+                                                   │
+                       human flips "Round N answers and feedback" → COMPLETED
+                                                   │
+                                                   ▼
+        agent updates draft +                AWAITING_AGENT
+        writes Round N+1 questions                 │
+  AWAITING_HUMAN ◄─────────────────────────────────┘
+        │
+        │  human flips "Session completion" → COMPLETED
+        ▼
+      agent renders final artifact per Output Specification
+        │
+        ▼
+      CLOSED          (ERROR is reachable from any state on malformed input)
+```
+
+The frontmatter `state` is a **cache** of the state derived from the Status table.
+If they ever disagree, the **Status table wins** and the agent repairs the frontmatter.
+
+## 5. Turn Protocol (Steps)
+
+### 5.1 AI Agent turn — starting a session (`state: NEW`)
+1. Read `Objective`, `Context` (fetch and read every file listed under `References`), and `Output Specification`.
+2. Write an initial draft in the `Output` section (points form, concise).
+3. Append `## Round 1` under `# Question` with numbered `### Question X` / `### Answer X` pairs.
+4. Append `## Round 1` under `# Feedback` (empty, for the Human to fill).
+5. Append **two** rows to the Status table:
+   - `Round 1 questions development` — Action By: AI Agent — `COMPLETED`
+   - `Round 1 answers and feedback` — Action By: Human — `PENDING`
+6. Set frontmatter `state: AWAITING_HUMAN`, `current_round: 1`.
+7. Write ordering rule: content sections first, Status table second, frontmatter state **last**
+   (the state flip is the agent's commit signal).
+
+### 5.2 Human turn (`state: AWAITING_HUMAN`)
+1. Write answers below each question in the current `Round N` section.
+2. Optionally write feedback under `Feedback > Round N`.
+3. Commit by flipping **exactly one** status:
+   - Continue iterating → set `Round N answers and feedback` to `COMPLETED`
+   - End the session   → set `Session completion` (row 0) to `COMPLETED`
+4. The Human may save the file any number of times before the flip; the agent
+   acts **only** on the status flip.
+
+### 5.3 AI Agent turn — continuing (`Round N answers = COMPLETED`, session not complete)
+1. Re-read the entire document (answers + feedback for round N).
+2. **Override** (never append) the `Output` section with the improved draft.
+3. Append `## Round N+1` questions and the matching empty `Feedback` round.
+4. Append the two status rows for round N+1 (agent row `COMPLETED`, human row `PENDING`).
+5. Update frontmatter `current_round`, keep `state: AWAITING_HUMAN`.
+
+### 5.4 AI Agent turn — finalizing (`Session completion = COMPLETED`)
+1. Incorporate any final answers/feedback into the draft.
+2. Render the **final artifact** exactly as declared in `Output Specification`:
+   - `md-inline` → final content stays in the `Output` section
+   - `md-file` / `xlsx` / `docx` / `pptx` → generate the file at `destination`,
+     honoring the `versioning` policy (`overwrite` or `timestamped` suffix `-YYYYMMDD-HHmmss`)
+3. Record the artifact location in the `Output` section under `## Final Artifact`.
+4. Set frontmatter `state: CLOSED`.
+
+## 6. Rules
+
+1. The Status table is the single source of truth for turn-taking; frontmatter is a scan cache.
+2. The AI Agent must wait for the relevant Human status to be `COMPLETED` before acting.
+3. Drafts in `Output` are in points form, concise, and **overridden** every round.
+4. There is no maximum number of rounds.
+5. The AI Agent never sets `Session completion` — only the Human ends a session.
+6. Round sections are appended dynamically — never pre-create empty rounds.
+7. **Session isolation**: each document is an independent session. The agent must not
+   carry objectives, assumptions, or conclusions from one session into another, even
+   within a single loop run. Re-derive all context from the document (and its
+   References) on every turn.
+8. **Write safety**: before writing to a document, the agent re-reads it (or re-checks
+   its mtime against the value captured at scan time). If it changed since the scan,
+   restart processing of that document from a fresh read.
+9. Unanswered questions in a completed round are treated as "Human defers to the
+   agent's judgment" — the agent proceeds and notes the assumption in the draft.
+10. The agent processes documents one at a time, fully completing its turn on one
+    session before touching the next.
+
+## 7. Error Handling
+
+If a document carries the discovery marker but is structurally unusable (missing
+Status table, missing Objective, unreadable Reference file, contradictory statuses):
+
+1. The agent appends a `# Agent Notice` section at the end of the document describing
+   exactly what is wrong and what the Human must fix.
+2. The agent sets frontmatter `state: ERROR`.
+3. On subsequent cycles the agent re-checks `ERROR` documents **only** if their mtime
+   is newer than the notice (i.e., the Human has edited since). If the problem is
+   fixed, the agent removes the notice and resumes from the derived state.