gru-ai 0.1.0

package/.claude/skills/brainstorm/SKILL.md

@@ -0,0 +1,340 @@
+---
+name: "brainstorm"
+description: "Structured brainstorm — from quick Socratic refinement to full C-suite strategy sessions. The missing step before /directive: figure out WHAT to do before telling agents to DO it. Takes a question or topic as argument."
+---
+
+# Brainstorm — Structured Strategic Thinking
+
+## Role Resolution
+
+Read `.claude/agent-registry.json` to map roles to agent names. Use each agent's `id` as the `subagent_type` when spawning. The COO = operations/orchestration, the CTO = architecture/technical, the CPO = product/UX, the CMO = growth/marketing.
+
+---
+
+The CEO has a question: $ARGUMENTS
+
+## Step 0: Triage
+
+Read the question. Classify it before doing anything else.
+
+**Lightweight** — single agent, Socratic dialogue, no external research:
+- Focused design question ("how should I structure this component?")
+- Single-domain topic (just architecture, or just UX, or just process)
+- Answer can be reached in one conversation
+- No cross-cutting impact (doesn't change multiple systems)
+
+**Heavyweight** — multi-agent parallel research, synthesis, options:
+- Strategic question affecting multiple systems ("how should goal tracking work?")
+- Crosses domains (architecture + UX + operations)
+- Needs external research (how do others solve this?)
+- Decision has lasting consequences (data models, project structure, user flows)
+
+State the classification:
+```
+Classification: {lightweight | heavyweight}
+Reasoning: {one sentence}
+```
+
+---
+
+## Lightweight Path — Socratic Refinement
+
+For focused questions. One agent, interactive dialogue. Think 5-minute whiteboard chat.
+
+**Pick the right agent** based on the question domain:
+- Architecture / data model → the CTO
+- User experience / product → the CPO
+- Process / operations → the COO
+- Growth / positioning → the CMO
+
+Spawn the agent (using the registry's `id` as `subagent_type`) with:
+- Their personality file (auto-loaded via `subagent_type`)
+- The CEO's question
+- `.context/vision.md` and `.context/preferences.md`
+- Relevant files the question touches
+
+```
+You are {Name}, {Title}. The CEO wants to think through a design question with you.
+
+QUESTION: {question}
+
+Your job: Socratic refinement. Don't jump to an answer. Instead:
+
+1. CLARIFY — Ask 2-3 sharpening questions to make sure you understand what the CEO really needs. What are the constraints? What matters most? What have they already considered?
+
+2. EXPLORE — Once you understand, propose 2 options with clear trade-offs. Be opinionated. "I'd go with A because..." not "both have merit."
+
+3. DETAIL — After the CEO picks a direction, flesh it out: what changes, what the structure looks like, what to watch out for.
+
+Keep it conversational. Short responses. This is a dialogue, not a report.
+
+CRITICAL OUTPUT FORMAT: JSON only. First character `{`, last `}`.
+
+{
+  "agent": "{name}",
+  "clarifying_questions": ["question 1", "question 2", "question 3"],
+  "initial_instinct": "Your gut reaction to the question in 1-2 sentences"
+}
+```
+
+**After the agent asks questions**, present them to the CEO via AskUserQuestion or as text. Let the CEO answer. Then re-spawn the agent (or resume) with the answers to get the options.
+
+**Final output:** Write a brief design note to `.context/directives/{relevant-directive}/brainstorm.md` capturing the decision. Keep it short — this is a lightweight brainstorm, not a design doc.
+
+**If the question turns out to be bigger than expected** (agent's questions reveal cross-cutting complexity), upgrade to heavyweight. Tell the CEO: "This is bigger than it looked — upgrading to full brainstorm."
+
+---
+
+## Heavyweight Path — Multi-Agent Strategy Session
+
+For strategic questions. Full C-suite, parallel research, synthesis, options.
+
+**The pattern:** Diverge (independent perspectives) → Converge (synthesize options) → Decide (CEO picks) → Capture (design doc).
+
+## Step 1: Frame the Question
+
+Read the CEO's question. If it's vague, clarify it with AskUserQuestion before proceeding.
+
+Read context:
+- `.context/vision.md` — current north star
+- `.context/preferences.md` — CEO preferences
+- `.context/goals/*/goal.json` — current goal structure
+- `.context/lessons/scenarios.md` — standing user scenarios (if relevant)
+
+Frame the question as a clear design challenge:
+- **What we're deciding**: one sentence
+- **Why it matters**: what breaks if we get this wrong
+- **Constraints**: non-negotiables from vision.md or preferences.md
+- **Current state**: how things work today (brief)
+
+Show the framing to the CEO before spawning agents. This prevents wasted work on a misunderstood question.
+
+## Step 2: Diverge — Independent Perspectives
+
+Spawn 2-3 C-suite agents **in parallel**. Pick the most relevant agents for the question domain:
+
+- **Architecture / data model / system design** → the CTO
+- **User experience / product design / workflows** → the CPO
+- **Operations / process / project structure** → the COO
+- **Growth / positioning / external patterns** → the CMO
+
+**Always include the COO** (they synthesize in Step 3). Pick 1-2 others based on the question.
+
+Each agent receives:
+- Their personality from `.claude/agents/{name}.md`
+- The framed question from Step 1
+- `.context/vision.md` and `.context/preferences.md`
+- Relevant context files (goal structure, current system docs, etc.)
+- These instructions:
+
+```
+You are {Name}, {Title}. The CEO is brainstorming a strategic question and wants your independent perspective.
+
+QUESTION: {framed question}
+CURRENT STATE: {how it works today}
+CONSTRAINTS: {non-negotiables}
+
+Your job:
+1. RESEARCH first — use WebSearch if external patterns would help (how do other tools/frameworks handle this?). Use Read/Grep/Glob if you need to understand the current system.
+2. THINK from your domain expertise — what matters most from your perspective?
+3. PROPOSE — give 1-2 concrete options with trade-offs. Don't hedge. Have an opinion.
+
+Structure your response:
+
+{
+  "agent": "{name}",
+  "perspective": "Your 2-3 sentence framing of the problem from your domain",
+  "research": [
+    {
+      "finding": "What you found externally or internally",
+      "source": "URL or file path",
+      "relevance": "Why it matters to this question"
+    }
+  ],
+  "proposals": [
+    {
+      "name": "short-name",
+      "summary": "One paragraph describing the approach",
+      "pros": ["advantage 1", "advantage 2"],
+      "cons": ["disadvantage 1", "disadvantage 2"],
+      "effort": "quick (hours) | medium (days) | large (weeks)",
+      "opinion": "Why you'd pick this one (or not)"
+    }
+  ],
+  "non_negotiables": ["Things that MUST be true regardless of which option we pick"],
+  "watch_outs": ["Risks or gotchas the CEO should know about"]
+}
+
+CRITICAL: First character `{`, last character `}`. JSON only. Have a STRONG opinion — the CEO wants perspectives, not waffling.
+```
+
+All agents: `subagent_type: "general-purpose"`, `model: "opus"`.
+
+## Step 3: Converge — COO Synthesizes
+
+After all agents return, spawn the COO with a synthesis task.
+
+The COO receives:
+- Their personality
+- All agent outputs from Step 2
+- The original framed question
+- Vision + preferences
+
+```
+You are the COO. The team has brainstormed independently. Your job: synthesize their perspectives into 2-3 clear OPTIONS for the CEO to choose from.
+
+AGENT PERSPECTIVES:
+{all agent outputs}
+
+SYNTHESIS RULES:
+1. Find the OVERLAPS — where do agents agree? This is the foundation.
+2. Find the CONFLICTS — where do they disagree? These are the real decision points.
+3. Design 2-3 OPTIONS that represent genuinely different approaches (not just variations).
+4. For each option, be honest about trade-offs. Don't create a strawman "bad option" to make one look good.
+5. Include a "COO'S PICK" — your recommendation with reasoning.
+6. Include the NON-NEGOTIABLES that all agents agreed on (these apply regardless of option).
+
+{
+  "agreements": ["Things all agents agreed on — the foundation"],
+  "tensions": [
+    {
+      "topic": "What they disagree about",
+      "positions": {"sarah": "her view", "marcus": "his view"},
+      "why_it_matters": "What depends on this decision"
+    }
+  ],
+  "options": [
+    {
+      "name": "Option A: descriptive name",
+      "summary": "2-3 sentence description",
+      "inspired_by": ["which agent roles/perspectives contributed"],
+      "pros": ["advantages"],
+      "cons": ["disadvantages"],
+      "effort": "quick | medium | large",
+      "best_when": "This option is best if the CEO values X over Y"
+    }
+  ],
+  "non_negotiables": ["Must be true regardless of option chosen"],
+  "coo_pick": {
+    "option": "Option name",
+    "reasoning": "Why — in 2-3 sentences"
+  }
+}
+
+CRITICAL: First character `{`, last character `}`. JSON only.
+```
+
+## Step 4: Present to CEO
+
+Present the synthesized options in a readable format:
+
+```
+# Brainstorm: {question title}
+
+## The Team Agrees On
+{non-negotiables — things that are true regardless of direction}
+
+## The Key Tensions
+{where agents disagreed — these are the real decisions}
+
+## Options
+
+### Option A: {name}
+{summary}
+**Pros:** {list}
+**Cons:** {list}
+**Effort:** {estimate}
+**Best if:** {when to pick this}
+
+### Option B: {name}
+...
+
+### Option C: {name} (if applicable)
+...
+
+## COO's Recommendation
+{COO's pick and reasoning}
+
+## Research Highlights
+{Most interesting external findings from agents — URLs included}
+```
+
+Ask the CEO using AskUserQuestion:
+- Option A / Option B / Option C / "Hybrid — let me explain"
+
+## Step 5: Capture Decision
+
+After the CEO decides:
+
+1. **Write a design doc** to `.context/directives/{relevant-directive}/brainstorm.md`:
+   ```markdown
+   # {Question Title}
+   Date: {date}
+   Decision: {chosen option}
+   Participants: {agents involved}
+
+   ## Context
+   {framed question + why it matters}
+
+   ## Options Considered
+   {brief summary of each option}
+
+   ## Decision
+   {which option + CEO's reasoning}
+
+   ## Non-Negotiables
+   {agreed constraints}
+
+   ## Next Steps
+   {what needs to happen to implement this — becomes /directive input}
+   ```
+
+2. **If the decision requires implementation**, ask the CEO:
+   - "Create directive" — write a directive to directives/ based on the decision
+   - "Add to backlog" — write to the relevant goal's backlog
+   - "Design doc only" — just capture the decision, implement later
+
+## Failure Handling
+
+| Situation | Action |
+|-----------|--------|
+| Agent output doesn't parse | Log error, continue with others. 2/3 perspectives is fine. |
+| Agents all agree | Great — present the consensus as the recommendation. Still offer 2 options (the consensus + a contrarian alternative). |
+| CEO wants to explore further | Spawn additional research on the specific area. Don't re-run the whole brainstorm. |
+| Question is too broad | Break it into sub-questions. Brainstorm the most foundational one first. |
+
+## How Brainstorm Fits the Conductor Flow
+
+**Normal path (auto-triggered):** Strategic directives trigger a brainstorm automatically inside the /directive pipeline. The CEO never needs to invoke /brainstorm separately — the team detects when strategic thinking is needed and handles it.
+
+```
+CEO gives direction → /directive → triage as "strategic" → C-suite brainstorms → COO plans → execute
+```
+
+**Standalone path (CEO-invoked):** The CEO can still invoke /brainstorm directly for questions that don't need a directive — strategy decisions, process design, framework choices, or "I want to think through X with the team" moments.
+
+```
+CEO invokes /brainstorm → triage → lightweight or heavyweight brainstorm → design doc
+```
+
+**Not every directive needs a brainstorm** (simple fixes don't). But strategic work — new data models, workflow changes, architectural shifts — benefits from the team exploring approaches before the COO plans execution.
+
+## Rules
+
+### NEVER
+- Skip triage (Step 0) — always classify before spawning
+- Use heavyweight for a focused question (wastes tokens and CEO time)
+- Use lightweight for a strategic question (misses perspectives)
+- Start heavyweight agents without framing the question first (Step 1)
+- Let heavyweight agents see each other's output during Step 2 (independent thinking prevents groupthink)
+- Present more than 3 options (decision paralysis)
+- Skip the COO's synthesis in heavyweight (raw perspectives without synthesis is a data dump)
+
+### ALWAYS
+- Triage first — lightweight or heavyweight
+- Capture the decision to a discussion file (reasoning dies in context windows)
+- Upgrade lightweight → heavyweight if clarifying questions reveal cross-cutting complexity
+- Include at least the COO + one other agent for heavyweight
+- Have the COO state a recommendation for heavyweight (no "it depends" cop-outs)
+- Include external research in heavyweight (agents should WebSearch, not just opine)
+- Frame the question before spawning heavyweight agents (prevents wasted work)

package/.claude/skills/code-review-excellence/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: code-review-excellence
+description: |
+  Provides comprehensive code review guidance for React 19, Vue 3, Rust, TypeScript, Java, Python, and C/C++.
+  Helps catch bugs, improve code quality, and give constructive feedback.
+  Use when: reviewing pull requests, conducting PR reviews, code review, reviewing code changes,
+  establishing review standards, mentoring developers, architecture reviews, security audits,
+  checking code quality, finding bugs, giving feedback on code.
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash      # 运行 lint/test/build 命令验证代码质量
+  - WebFetch  # 查阅最新文档和最佳实践
+---
+
+# Code Review Excellence
+
+Transform code reviews from gatekeeping to knowledge sharing through constructive feedback, systematic analysis, and collaborative improvement.
+
+## When to Use This Skill
+
+- Reviewing pull requests and code changes
+- Establishing code review standards for teams
+- Mentoring junior developers through reviews
+- Conducting architecture reviews
+- Creating review checklists and guidelines
+- Improving team collaboration
+- Reducing code review cycle time
+- Maintaining code quality standards
+
+## Core Principles
+
+### 1. The Review Mindset
+
+**Goals of Code Review:**
+- Catch bugs and edge cases
+- Ensure code maintainability
+- Share knowledge across team
+- Enforce coding standards
+- Improve design and architecture
+- Build team culture
+
+**Not the Goals:**
+- Show off knowledge
+- Nitpick formatting (use linters)
+- Block progress unnecessarily
+- Rewrite to your preference
+
+### 2. Effective Feedback
+
+**Good Feedback is:**
+- Specific and actionable
+- Educational, not judgmental
+- Focused on the code, not the person
+- Balanced (praise good work too)
+- Prioritized (critical vs nice-to-have)
+
+```markdown
+❌ Bad: "This is wrong."
+✅ Good: "This could cause a race condition when multiple users
+         access simultaneously. Consider using a mutex here."
+
+❌ Bad: "Why didn't you use X pattern?"
+✅ Good: "Have you considered the Repository pattern? It would
+         make this easier to test. Here's an example: [link]"
+
+❌ Bad: "Rename this variable."
+✅ Good: "[nit] Consider `userCount` instead of `uc` for
+         clarity. Not blocking if you prefer to keep it."
+```
+
+### 3. Review Scope
+
+**What to Review:**
+- Logic correctness and edge cases
+- Security vulnerabilities
+- Performance implications
+- Test coverage and quality
+- Error handling
+- Documentation and comments
+- API design and naming
+- Architectural fit
+
+**What Not to Review Manually:**
+- Code formatting (use Prettier, Black, etc.)
+- Import organization
+- Linting violations
+- Simple typos
+
+## Review Process
+
+### Phase 1: Context Gathering (2-3 minutes)
+
+Before diving into code, understand:
+1. Read PR description and linked issue
+2. Check PR size (>400 lines? Ask to split)
+3. Review CI/CD status (tests passing?)
+4. Understand the business requirement
+5. Note any relevant architectural decisions
+
+### Phase 2: High-Level Review (5-10 minutes)
+
+1. **Architecture & Design** - Does the solution fit the problem?
+   - For significant changes, consult [Architecture Review Guide](reference/architecture-review-guide.md)
+   - Check: SOLID principles, coupling/cohesion, anti-patterns
+2. **Performance Assessment** - Are there performance concerns?
+   - For performance-critical code, consult [Performance Review Guide](reference/performance-review-guide.md)
+   - Check: Algorithm complexity, N+1 queries, memory usage
+3. **File Organization** - Are new files in the right places?
+4. **Testing Strategy** - Are there tests covering edge cases?
+
+### Phase 3: Line-by-Line Review (10-20 minutes)
+
+For each file, check:
+- **Logic & Correctness** - Edge cases, off-by-one, null checks, race conditions
+- **Security** - Input validation, injection risks, XSS, sensitive data
+- **Performance** - N+1 queries, unnecessary loops, memory leaks
+- **Maintainability** - Clear names, single responsibility, comments
+
+### Phase 4: Summary & Decision (2-3 minutes)
+
+1. Summarize key concerns
+2. Highlight what you liked
+3. Make clear decision:
+   - ✅ Approve
+   - 💬 Comment (minor suggestions)
+   - 🔄 Request Changes (must address)
+4. Offer to pair if complex
+
+## Review Techniques
+
+### Technique 1: The Checklist Method
+
+Use checklists for consistent reviews. See [Security Review Guide](reference/security-review-guide.md) for comprehensive security checklist.
+
+### Technique 2: The Question Approach
+
+Instead of stating problems, ask questions:
+
+```markdown
+❌ "This will fail if the list is empty."
+✅ "What happens if `items` is an empty array?"
+
+❌ "You need error handling here."
+✅ "How should this behave if the API call fails?"
+```
+
+### Technique 3: Suggest, Don't Command
+
+Use collaborative language:
+
+```markdown
+❌ "You must change this to use async/await"
+✅ "Suggestion: async/await might make this more readable. What do you think?"
+
+❌ "Extract this into a function"
+✅ "This logic appears in 3 places. Would it make sense to extract it?"
+```
+
+### Technique 4: Differentiate Severity
+
+Use labels to indicate priority:
+
+- 🔴 `[blocking]` - Must fix before merge
+- 🟡 `[important]` - Should fix, discuss if disagree
+- 🟢 `[nit]` - Nice to have, not blocking
+- 💡 `[suggestion]` - Alternative approach to consider
+- 📚 `[learning]` - Educational comment, no action needed
+- 🎉 `[praise]` - Good work, keep it up!
+
+## Language-Specific Guides
+
+根据审查的代码语言，查阅对应的详细指南：
+
+| Language/Framework | Reference File | Key Topics |
+|-------------------|----------------|------------|
+| **React** | [React Guide](reference/react.md) | Hooks, useEffect, React 19 Actions, RSC, Suspense, TanStack Query v5 |
+| **Vue 3** | [Vue Guide](reference/vue.md) | Composition API, 响应性系统, Props/Emits, Watchers, Composables |
+| **Rust** | [Rust Guide](reference/rust.md) | 所有权/借用, Unsafe 审查, 异步代码, 错误处理 |
+| **TypeScript** | [TypeScript Guide](reference/typescript.md) | 类型安全, async/await, 不可变性 |
+| **Python** | [Python Guide](reference/python.md) | 可变默认参数, 异常处理, 类属性 |
+| **Java** | [Java Guide](reference/java.md) | Java 17/21 新特性, Spring Boot 3, 虚拟线程, Stream/Optional |
+| **Go** | [Go Guide](reference/go.md) | 错误处理, goroutine/channel, context, 接口设计 |
+| **C** | [C Guide](reference/c.md) | 指针/缓冲区, 内存安全, UB, 错误处理 |
+| **C++** | [C++ Guide](reference/cpp.md) | RAII, 生命周期, Rule of 0/3/5, 异常安全 |
+| **CSS/Less/Sass** | [CSS Guide](reference/css-less-sass.md) | 变量规范, !important, 性能优化, 响应式, 兼容性 |
+| **Qt** | [Qt Guide](reference/qt.md) | 对象模型, 信号/槽, 内存管理, 线程安全, 性能 |
+
+## Additional Resources
+
+- [Architecture Review Guide](reference/architecture-review-guide.md) - 架构设计审查指南（SOLID、反模式、耦合度）
+- [Performance Review Guide](reference/performance-review-guide.md) - 性能审查指南（Web Vitals、N+1、复杂度）
+- [Common Bugs Checklist](reference/common-bugs-checklist.md) - 按语言分类的常见错误清单
+- [Security Review Guide](reference/security-review-guide.md) - 安全审查指南
+- [Code Review Best Practices](reference/code-review-best-practices.md) - 代码审查最佳实践
+- [PR Review Template](assets/pr-review-template.md) - PR 审查评论模板
+- [Review Checklist](assets/review-checklist.md) - 快速参考清单

package/.claude/skills/directive/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: "directive"
+description: "Execute work through the directive pipeline — evaluate, plan, cast agents, build, review, and report. Takes a directive name (matching .context/directives/), a project path, or an ad-hoc CEO request.\n\nTRIGGER: Use this skill whenever the user requests non-trivial work that goes beyond a one-liner fix. This includes: building features, running projects with project.json, executing multiple tasks, multi-file changes, or any work with defined DOD/reviewers. Route through this pipeline so reviews and verification steps fire. Do NOT spawn builder agents directly.\n\nFor heavyweight/strategic work, create a directive file in .context/directives/ first. For medium work with an existing project.json, pass the project path. For quick multi-step tasks, pass an ad-hoc description — no directive file needed."
+---
+
+# Execute Directive
+
+Execute the CEO directive: $ARGUMENTS
+
+## Role Resolution — Read First
+
+Before executing, read `.claude/agent-registry.json` to map roles to agent names. The pipeline uses role-based language throughout. Resolve roles to concrete agent names using the registry:
+
+- **COO** = the agent with `"title": "COO"` (plans projects, orchestrates execution)
+- **CTO** = the agent with `"title": "CTO"` (architecture, audits, reviews, technical decomposition)
+- **CPO** = the agent with `"title": "CPO"` (product strategy, UX review, user perspective)
+- **CMO** = the agent with `"title": "CMO"` (growth, SEO, content strategy)
+- **Frontend Developer** = the agent with `"title": "FE"` (React, Tailwind, components)
+- **Backend Developer** = the agent with `"title": "BE"` (server, API, infrastructure)
+- **Full-Stack Engineer** = the agent with `"title": "FS"` (cross-domain work)
+- **Data Engineer** = the agent with `"title": "DE"` (pipelines, parsers, indexing)
+- **Content Builder** = the agent with `"title": "CB"` (MDX, documentation, copywriting)
+- **QA Engineer** = the agent with `"title": "QA"` (testing, investigation, validation)
+- **UI/UX Designer** = the agent with `"title": "UX"` (design review, wireframes, visual quality)
+
+Use each agent's `id` field as the `subagent_type` value when spawning. Use the `agentFile` field to locate personality files. The registry is the single source of truth for who fills each role.
+
+---
+
+## MANDATORY: Start with Triage — DO NOT SKIP
+
+**YOU MUST read and execute [00-delegation-and-triage.md](docs/pipeline/00-delegation-and-triage.md) BEFORE doing anything else.**
+
+DO NOT read source code. DO NOT edit files. DO NOT start solving the problem. The pipeline exists to ensure quality — every shortcut you take skips a review, a gate, or a verification step.
+
+Your FIRST action must be: Read the triage doc, classify the directive weight, output the triage block, and create directive.json. Only then proceed to the next pipeline step.
+
+If you catch yourself wanting to "just fix it quickly" — STOP. That impulse is exactly what the pipeline prevents. Even lightweight directives have a defined process (triage → context → plan → audit → build → review → digest → completion). The COO plans for ALL weights.
+
+---
+
+## How to Use This Routing Map
+
+This file is a routing table. Each row points to a modular doc containing full instructions for that step. **Read only the docs you need for the current step** — don't load everything at once.
+
+### Pipeline Progress Protocol
+
+**After completing each pipeline step**, update `.context/directives/{id}/directive.json`:
+1. Set `pipeline.{stepId}.status` to `"completed"` with:
+   - `agent`: who performed this step (e.g. "CEO", "COO", "CTO, full-stack engineer")
+   - `output`: REQUIRED object with at least a `summary` string (1-2 sentences of what happened/decided). Add other keys as relevant (e.g. `decision`, `weight`, `projects`).
+   - `artifacts`: array of file paths produced (if any)
+2. Set `current_step` to the next step's ID
+3. Set `updated_at` to the current ISO timestamp
+4. Use the Write tool to overwrite the full directive.json
+
+**When starting a step**, set `pipeline.{stepId}.status` to `"active"`.
+
+> **Why output is mandatory:** The dashboard renders pipeline step details directly from directive.json. Without `output.summary`, the UI shows empty steps — the CEO can't see what happened. Every step must leave a trace.
+
+The server's directive-watcher reads `directive.json` directly (NOT `current.json`) and pushes pipeline state to the dashboard via WebSocket. Keeping `pipeline` updated is what makes the stepper UI show real-time progress.
+
+### Pipeline Steps
+
+| # | Step ID | Doc | Purpose | Depends On |
+|---|---------|-----|---------|------------|
+| 1 | triage | [00-delegation-and-triage.md](docs/pipeline/00-delegation-and-triage.md) | Triage directive weight + select process | — |
+| 2 | checkpoint | [01-checkpoint.md](docs/pipeline/01-checkpoint.md) | Check for existing checkpoint, resume if found | — |
+| 3 | read | [02-read-directive.md](docs/pipeline/02-read-directive.md) | Read directive file + create directive.json | triage |
+| 4 | context | [03-read-context.md](docs/pipeline/03-read-context.md) | Read all context files before planning | read |
+| 5 | challenge | [04-challenge.md](docs/pipeline/04-challenge.md) | C-suite challenge (heavyweight only) | context |
+| 6 | plan | [05-planning.md](docs/pipeline/05-planning.md) | COO strategic planning | context |
+| 7 | audit | [06-technical-audit.md](docs/pipeline/06-technical-audit.md) | Technical codebase audit | plan |
+| 8 | approve | [07-plan-approval.md](docs/pipeline/07-plan-approval.md) | Present plan to CEO for approval | audit |
+| 9 | project-brainstorm | [07b-project-brainstorm.md](docs/pipeline/07b-project-brainstorm.md) | CTO + builder decompose projects into tasks with DOD | approve |
+| 10 | setup | [08-worktree-and-state.md](docs/pipeline/08-worktree-and-state.md) | Worktree isolation + directive state init | project-brainstorm |
+| 11 | execute | [09-execute-projects.md](docs/pipeline/09-execute-projects.md) | Execute all tasks (phases, agents, UX) | setup |
+| 12 | review-gate | [09-execute-projects.md](docs/pipeline/09-execute-projects.md) | Review verification gate (end of doc) | execute |
+| 13 | wrapup | [10-wrapup.md](docs/pipeline/10-wrapup.md) | OKRs, follow-ups, stale doc detection, digest, lessons, report | review-gate |
+| 14 | completion | [11-completion-gate.md](docs/pipeline/11-completion-gate.md) | CEO completion gate -- approve or reopen | wrapup |
+
+### Reference Docs — Schemas
+
+| Doc | Content |
+|-----|---------|
+| [plan-schema.md](docs/reference/schemas/plan-schema.md) | COO plan output JSON schema |
+| [audit-output.md](docs/reference/schemas/audit-output.md) | Architect output JSON schema (design recommendations — second phase of two-agent audit) |
+| [investigation-output.md](docs/reference/schemas/investigation-output.md) | QA Engineer's investigation output JSON schema (pure data — first phase of two-agent audit) |
+| [checkpoint.md](docs/reference/schemas/checkpoint.md) | Checkpoint JSON schema (includes dod_verification field) |
+| [directive-json.md](docs/reference/schemas/directive-json.md) | Directive JSON schema (THE source of truth — includes pipeline progress for dashboard) |
+| [challenger-output.md](docs/reference/schemas/challenger-output.md) | Challenger output JSON schema |
+| [brainstorm-output.md](docs/reference/schemas/brainstorm-output.md) | Brainstorm output JSON schema (proposals + rebuttals) |
+
+### Reference Docs — Templates
+
+| Doc | Content |
+|-----|---------|
+| [planner-prompt.md](docs/reference/templates/planner-prompt.md) | Full COO planning prompt |
+| [investigator-prompt.md](docs/reference/templates/investigator-prompt.md) | Investigation prompt template for the QA Engineer (pure data gathering — first phase of audit) |
+| [architect-prompt.md](docs/reference/templates/architect-prompt.md) | Architect prompt template (design recommendations — second phase of audit) |
+| [auditor-prompt.md](docs/reference/templates/auditor-prompt.md) | Combined audit prompt for the CTO (single-agent path for simple tasks) |
+| [challenger-prompt.md](docs/reference/templates/challenger-prompt.md) | Challenger prompt template |
+| [brainstorm-prompt.md](docs/reference/templates/brainstorm-prompt.md) | Brainstorm agent prompt template (Phase 1 proposals + Phase 2 deliberation) |
+| [digest.md](docs/reference/templates/digest.md) | Digest report template |
+
+### Reference Docs — Rules
+
+| Doc | Content |
+|-----|---------|
+| [casting-rules.md](docs/reference/rules/casting-rules.md) | Agent casting: delegation, auditing, reviewing, specialists |
+| [phase-definitions.md](docs/reference/rules/phase-definitions.md) | Phase building blocks + common patterns |
+| [scope-and-dod.md](docs/reference/rules/scope-and-dod.md) | Scope format + Definition of Done rules |
+| [failure-handling.md](docs/reference/rules/failure-handling.md) | Failure handling table |
+
+### Validation Scripts
+
+| Script | Content |
+|--------|---------|
+| [validate-cast.sh](../../hooks/validate-cast.sh) | Mechanical casting validation — checks auditor present, builder != reviewer, complex has C-suite reviewer |
+| [validate-project-json.sh](../../hooks/validate-project-json.sh) | Pre-execution gate — blocks execute step if project.json missing or incomplete (no tasks, no DOD, no scope) |
+| [detect-stale-docs.sh](../../hooks/detect-stale-docs.sh) | Post-directive — scans docs for references to modified files, flags potentially stale docs |