gru-ai 0.1.0

package/.claude/skills/directive/docs/pipeline/10-wrapup.md

@@ -0,0 +1,242 @@
+<!-- Pipeline doc: 10-wrapup.md | Source: SKILL.md restructure -->
+
+## Step 6: Category Context (if applicable)
+
+The directive's category (from directive.json `category` field) provides domain context. No OKR updates needed -- categories are flat labels, not goals with OKRs.
+
+## Step 6b: Process Follow-Up Actions
+
+Collect all `follow_ups` from the audit findings (audit step) across all tasks. Process them by risk level:
+
+### Low Risk — Auto-Execute
+
+Spawn an engineer agent to execute all low-risk follow-ups in a single batch. The agent receives:
+- The list of low-risk follow-up actions with affected files
+- `.context/preferences.md` and `.context/lessons/*.md` topic files
+- Instruction: "Execute these cleanup actions. They've been classified as low-risk (safe to do without CEO approval). Report what you changed."
+
+**Low-risk examples:** Delete dead code files, remove unused imports, delete unused variables, create backlog tickets, update OKR status files, fix typos.
+
+### Medium Risk — Auto-Execute + Report with Revert Commands
+
+Medium-risk follow-ups auto-execute without CEO approval, matching the low-risk pattern. The safety net is revert commands in the digest — the CEO can undo any action by copy-pasting the revert command.
+
+Spawn an engineer agent to execute all medium-risk follow-ups in a single batch. The agent receives:
+- The list of medium-risk follow-up actions with affected files
+- `.context/preferences.md` and `.context/lessons/*.md` topic files
+- Instruction: "Execute these follow-up actions. They've been classified as medium-risk (auto-executed, CEO can revert). For EACH action: (1) note the current git state before the change, (2) execute the action, (3) capture a revert command. Report what you changed and provide revert commands."
+
+**Revert command generation:** After each medium-risk action, the engineer captures the information needed to undo it:
+- For file modifications: `git checkout {commit-hash} -- {file-path}` (using the commit hash or HEAD before the change)
+- For new files: `rm {file-path}`
+- For deleted files: `git checkout {commit-hash} -- {file-path}`
+- For multi-file changes: a combined revert command or script
+
+The revert commands are included in the digest (see "Revert Commands" section in digest template).
+
+**Medium-risk examples:** Fix auth gaps, add input validation, add middleware, refactor modules, change API behavior, update dependencies.
+
+### High Risk — Write to Backlog
+
+For each high-risk follow-up, create a new directive in `.context/directives/{follow-up-id}/directive.json` as a pending directive:
+
+```json
+{
+  "id": "{kebab-case-action-slug}",
+  "title": "{action title}",
+  "status": "pending",
+  "priority": "P1",
+  "source_directive": "$ARGUMENTS",
+  "context": "{what the audit found + risk rationale}",
+  "created": "{today YYYY-MM-DD}",
+  "updated": "{today YYYY-MM-DD}",
+  "promoted_to_feature": null,
+  "promoted_at": null
+}
+```
+
+Set `source_directive` to the current directive name so the backlog item is traceable back to this directive. This enables the cross-reference system to answer "which directive created this backlog item?"
+
+**High-risk examples:** Schema changes, new API endpoints, infrastructure changes, auth flow changes, anything user-facing, anything that could affect revenue or SEO.
+
+### Skip follow-ups if:
+- The directive is research-only (no code changes expected)
+- No follow-ups were identified in the audit
+- All tasks were skipped or failed (follow-ups may be invalid)
+
+## Step 6c: Detect Potentially Stale Docs
+
+Run the stale documentation detection hook to find docs that reference files modified in this directive but were not themselves updated:
+
+```bash
+.claude/hooks/detect-stale-docs.sh --from-diff main
+```
+
+Or, if working in a worktree with a directive branch:
+
+```bash
+.claude/hooks/detect-stale-docs.sh --from-diff directive/$ARGUMENTS
+```
+
+The script scans `.context/` and `.claude/` docs for literal file path references to modified files, excluding docs that were also modified (zero false positives). Runs in <5 seconds.
+
+Capture the output — it goes into the "Potentially Stale Docs" section of the digest. If the script outputs "No potentially stale docs detected," include that line in the digest section as-is.
+
+## Step 6d: Generate Digest
+
+**This step runs LAST** — after OKRs are updated, follow-ups are processed, and stale docs are detected, so all data is available.
+
+Write a digest to `.context/reports/$ARGUMENTS-{date}.md`.
+
+**After writing the digest**, update directive.json with the report link:
+- Read `.context/directives/$ARGUMENTS/directive.json`
+- Set `report` to the report filename without extension (e.g., `"improve-security-2026-03-01"`)
+- Also update `produced_features` if any features were registered in the "After Each Task" step but the directive.json wasn't updated yet
+
+> See [docs/reference/templates/digest.md](../reference/templates/digest.md) for the full digest report template.
+
+## Step 6e: Update Lessons
+
+If the directive produced new learnings, append them to the appropriate topic file:
+- Agent behavior lessons → `.context/lessons/agent-behavior.md`
+- Orchestration/planning lessons → `.context/lessons/orchestration.md`
+- State/checkpoint/dashboard lessons → `.context/lessons/state-management.md`
+- Review/quality lessons → `.context/lessons/review-quality.md`
+- Pipeline/skill/repo lessons → `.context/lessons/skill-design.md`
+- Project/codebase lessons → `.context/lessons/{topic}.md`
+
+**Only add if:** something unexpected happened, a pattern emerged that prevents future mistakes, or a workaround was needed. Skip if the directive completed cleanly with no surprises.
+
+**Format:** For failure-mode lessons, include what was tried and why it failed — not just the fix. Example: `**The COO produces prose before JSON despite "output ONLY JSON" instructions.** Fix: stronger preamble ("first character must be {") AND parse defensively.` For stable patterns/facts, a single sentence is fine.
+
+Read existing topic files first to avoid duplicates.
+
+**Consolidation trigger:** After every 10th directive (count reports in `.context/reports/`), re-read all reports and consolidate recurring patterns into the topic files. Remove one-off entries that haven't recurred. This keeps lessons actionable, not bloated.
+
+**Personality evolution trigger:** On the same 10th-directive cycle, also update the `## Learned Patterns` section in each agent's personality file (`.claude/agents/*.md`). For each agent, extract lessons from `.context/lessons/` topic files that are relevant to their role:
+- **COO** — operational patterns (sequencing, scoping, casting, compression)
+- **CTO** — technical patterns (audit accuracy, review findings, schema issues, build failures)
+- **CPO** — product patterns (UX verification, user perspective, feature management)
+- **CMO** — growth patterns (content strategy, SEO, browser testing)
+
+Replace the contents between `## Learned Patterns` and the next `##` heading. Keep each pattern as a single bullet with bold lead + explanation. Max 8 patterns per agent — keep only the most impactful.
+
+## Step 6f: Re-index State
+
+The dashboard reads source files directly via glob + chokidar. No indexer step needed. Changes to project.json, directive.json are picked up automatically.
+
+**Update directive.json:** Set `wrapup.digest_path` to the report path. Set `current_step: "wrapup"`. Update `pipeline.wrapup.status` to `"completed"` with output summary.
+
+## Step 6g: Mark Directive Awaiting Completion
+
+Update the directive JSON to signal the CEO completion gate. The directive is NOT marked `completed` here -- that happens in the completion step after CEO approval.
+
+### Pre-completion Checks
+
+1. **Browser test check (IC2 fix):** If the directive has `browser_test: true` in any project.json, verify that UI review has been logged. If UI review is pending, do NOT proceed -- log: `[BLOCKED] UI review pending for {project}. Cannot mark awaiting_completion.`
+2. **Failed tasks check (IC3 fix):** If any tasks have `failed` or `partial` status, include an explanation in the digest. The CEO must be aware of incomplete work before approving completion.
+
+### Directive JSON
+- Read `.context/directives/$ARGUMENTS/directive.json`
+- Set `status` to `"awaiting_completion"`
+- Set `report_summary` to the digest filename
+- Write the updated JSON back
+
+### Project JSON(s)
+- For each project in the directive's `produced_projects` array, read its `project.json`
+- Do NOT set project status to `"completed"` yet -- that happens in the completion step after CEO approval
+- If some tasks are incomplete, note this in the digest with explanations
+
+Directives stay in `directives/` -- status is tracked in JSON, not by directory location.
+
+**Next step:** Proceed to Report to CEO (below), then [completion gate](11-completion-gate.md) for CEO sign-off.
+
+## Step 7: Report to CEO
+
+Show the CEO:
+1. The digest summary (not the full file — just the key points)
+2. Run `git diff --stat main..directive/$ARGUMENTS` to show ONLY this directive's changes — not pre-existing uncommitted work
+3. Any review findings that need attention
+4. Recommended next steps
+5. The branch name: "Review with `git log directive/$ARGUMENTS` and merge when ready"
+
+## Failure Handling
+
+> See [docs/reference/rules/failure-handling.md](../reference/rules/failure-handling.md) for the full failure handling table.
+
+| Situation | Action |
+|-----------|--------|
+| Challenger's output doesn't parse as JSON | Log the error, continue. Challenge is advisory, not blocking. |
+| All challengers endorse | Note in approval presentation, proceed normally. |
+| A challenger challenges the directive | Highlight prominently in approval presentation. CEO decides whether to proceed. |
+| The COO's plan doesn't parse as JSON | Stop, show the raw output, ask CEO to intervene |
+| Worktree creation fails | Warn CEO, work in the main repo instead. All changes are uncommitted, CEO can review with `git diff`. |
+| Audit finds nothing for ALL tasks | Skip to stale doc detection, generate digest noting "no issues found", recommend CEO review the directive scope. |
+| CEO rejects the plan | Stop. CEO can re-run with adjusted directive or manually edit the plan |
+| Agent fails mid-task | Skip remaining phases in that task, continue to next. Log in digest. |
+| Reviewer finds issues | Non-fatal. Include in digest. CEO decides whether to address. |
+| Task is blocked | Skip, note in digest, continue to next task |
+| All tasks fail | Generate digest showing failures, recommend CEO review |
+| Audit finds nothing to fix | Remove task from plan, note in digest |
+| Context exhaustion mid-directive | directive.json preserves state (it IS the checkpoint). Re-run `/directive {name}` to resume. |
+| Brainstorm agents disagree on approach | Present all approaches with trade-offs in clarifying questions. Let CEO pick direction. Don't synthesize conflicting approaches into a compromise. |
+
+## Rules
+
+### NEVER
+- Skip triage — must classify before choosing the process weight
+- Run heavyweight process for lightweight work (wastes tokens and CEO attention)
+- Run lightweight process for heavyweight work (skips critical safety gates)
+- Execute heavyweight directives without CEO approval of the combined plan (COO + audit)
+- Skip the planning phase (COO evaluation)
+- Skip the technical audit (audit step) — always verify scope before CEO approval
+- Skip the challenge step — the COO's inline challenge is always required; separate challengers only for heavyweight/controversial
+- Have the COO scan the codebase (the COO plans strategy, not code)
+- Run tasks in parallel without checking active_files overlap (see Parallelism Analysis in 09-execute-projects.md) -- tasks sharing files MUST be sequential; only non-overlapping tasks in the same priority tier can be parallelized
+- Treat reviewer findings as blockers (they're advisory)
+- Accept a review that only covers code quality without user-perspective evaluation
+- Spawn agents without their personality files (for named agents)
+- Commit, push, checkout, or reset git state (CEO manages git). Note: `git checkout -b` (setup step), `git worktree add` (setup step), and `git diff --stat` (wrapup report) are allowed — they're read-only or isolated operations.
+- Add clarification phase to simple tasks with just ["build", "review"] phases -- tight scope makes it unnecessary token overhead
+- Have the same agent review changes to its own behavior, prompts, or personality (conflict of interest)
+- Run strategic process for directives with a clear prescribed approach (that's heavyweight, not strategic)
+- Mark a directive as awaiting_completion when UI review is pending -- UI checks must pass first
+- Set directive status to `completed` directly -- always go through `awaiting_completion` first (wrapup step), then CEO approves in completion step
+
+### ALWAYS
+- Triage the directive before choosing which process to run
+- Upgrade to heavyweight if ANY guardrail in vision.md could be affected
+- Include the COO's inline challenge analysis in every plan — separate challengers for heavyweight/controversial only
+- Read preferences.md + vision.md guardrails before spawning any agent
+- Run technical audit before CEO approval to verify scope
+- Read .context/lessons/ topic files before spawning any agent
+- Include personality text in named agent prompts
+- Include preferences.md + guardrails in all agent prompts
+- Include audit findings in engineer prompts (active files, recommended approach)
+- Include "propose what's missing" instruction in engineer prompts
+- Log UI verification checks in the digest when tasks touch UI code -- CEO verifies from dashboard or game
+- Include user-perspective evaluation in every reviewer prompt (not just code quality)
+- Require `user_walkthrough` in engineer build reports and `user_perspective` in reviewer output
+- Process follow-ups by risk level after tasks complete
+- Run stale doc detection before generating the digest
+- Include stale doc detection results in the digest
+- Include self-assessment metrics in the digest
+- Include agent-proposed improvements in the digest
+- Include UX verification results in the digest
+- Update lessons if the directive produced new learnings
+- Log task status after each completes
+- ~~Generate a digest even if everything fails~~ _Hook-enforced: stop hook blocks if no digest artifact for medium+ weight_
+- Dashboard reads source files directly — no re-indexing needed
+- Show the CEO what happened at the end
+- Update directive.json after every phase transition (plan, approve, setup, execute phases, wrapup) — it IS the checkpoint
+- Write artifact files after every phase output in execute step
+- Update directive.json status to "awaiting_completion" after digest is written (wrapup) -- CEO approves in completion step
+- Pipeline data stays in directive.json permanently — it's the execution record
+- Include clarification phase before build when task has design/research/product-spec phases (the COO's phase list should already include it)
+- Include task's definition_of_done in every reviewer prompt
+- Include Standing Corrections check in every reviewer prompt
+- Match reviewers to the domain being changed (process→COO, product→CPO, architecture→CTO)
+- Never assign an agent to review changes to its own behavior or prompts
+- Use file-pattern matching (*.tsx, *.jsx, *.css, etc.) to detect UI-touching tasks -- don't rely on subjective judgment
+- Cast multiple reviewers when task crosses domains (UI + backend, process + product)
+- Classify as strategic when the directive states a problem without prescribing an approach AND the work has lasting architectural/process consequences

package/.claude/skills/directive/docs/pipeline/11-completion-gate.md

@@ -0,0 +1,75 @@
+<!-- Pipeline doc: 11-completion-gate.md | Source: pipeline-v2 directive -->
+
+## Completion: CEO Completion Gate
+
+After the wrapup step generates the digest and reports to the CEO, the directive enters the completion gate. ALL directives -- including lightweight -- require CEO sign-off before the status changes to `completed`.
+
+### Status Flow
+
+```
+executing -> awaiting_completion -> completed
+                                 -> reopened (CEO provides feedback, new projects added)
+```
+
+### After Wrapup
+
+The wrapup step sets the directive status to `awaiting_completion` (NOT `completed`). This applies to all weight classes:
+
+- **Lightweight**: Wrapup produces a short digest. Status becomes `awaiting_completion`. CEO reviews the digest summary and approves.
+- **Medium**: Wrapup produces a full digest. Status becomes `awaiting_completion`. CEO reviews and approves.
+- **Heavyweight/Strategic**: Wrapup produces a full digest. Status becomes `awaiting_completion`. CEO reviews digest + git diff + review findings before approving.
+
+### CEO Actions
+
+Present the completion gate to the CEO with:
+
+1. The digest summary (key points, not the full file)
+2. `git diff --stat main..directive/$ARGUMENTS` showing this directive's changes
+3. Any review findings that need attention
+4. Tasks with `failed` or `partial` status (if any) -- with explanations from the digest
+
+Then ask the CEO:
+
+```
+Directive {name} is ready for completion review.
+
+- Approve: Mark as completed. All work is satisfactory.
+- Reopen: Provide feedback on what's missing. The COO will plan new projects.
+```
+
+### Approve Flow
+
+When the CEO approves:
+
+1. Update `.context/directives/{id}/directive.json`:
+   - Set `status` to `"completed"`
+   - Set `completed` to today's date (`YYYY-MM-DD`)
+2. Update all project.json files in the directive's `produced_projects`:
+   - If all tasks completed, set project `status` to `"completed"`
+3. Log: `[COMPLETED] Directive {name} approved by CEO`
+
+### Reject / Reopen Flow
+
+When the CEO reopens with feedback:
+
+1. Update `.context/directives/{id}/directive.json`:
+   - Set `status` to `"reopened"`
+   - Increment `revision` counter
+   - Add new entry to `iterations[]` with `opened_at` timestamp and CEO feedback
+2. Restart the pipeline from the plan step (COO planning) for NEW projects only
+   - Existing completed projects are untouched
+   - The COO plans additional projects to address CEO feedback
+   - Same approval flow applies to new projects
+3. Log: `[REOPENED] Directive {name} -- CEO feedback: {summary}`
+
+### Non-Interactive Sessions
+
+When the directive runs as a CLI session (non-interactive):
+- Write the digest to `.context/reports/`
+- Set status to `awaiting_completion`
+- The CEO reviews and approves via a subsequent session or dashboard action
+- The directive is NOT done until the CEO explicitly approves
+
+### Update directive.json
+
+Set `current_step: "completion"`. Set `pipeline.completion.status` to `"awaiting_completion"` with the digest path.

package/.claude/skills/directive/docs/reference/rules/casting-rules.md

@@ -0,0 +1,78 @@
+<!-- Reference: casting-rules.md | Source: SKILL.md restructure -->
+
+# Casting Rules
+
+## Delegation Principle
+
+C-suite agents (CTO, CPO, COO, CMO) focus on STRATEGY -- planning, auditing, challenging, and cross-cutting reviews. Specialists (frontend engineer, backend engineer, data engineer, content builder, QA engineer, full-stack engineer, UI/UX designer) handle EXECUTION -- building AND routine domain-specific reviews. Do NOT have C-suite do work that a specialist can handle. The orchestrator (directive session) delegates but does NOT build, review, or audit.
+
+## Auditing
+
+- Security/architecture audits → the CTO
+- User-facing/product audits → the CPO or CTO
+- Growth/marketing audits → the CMO
+- Routine codebase audits for simple tasks → specialists can audit their own domain (frontend engineer audits frontend, backend engineer audits backend, data engineer audits data pipelines)
+
+## Reviewing
+
+- Simple frontend work → the frontend engineer reviews (not the CTO, unless security-sensitive)
+- Simple backend work → the backend engineer reviews (not the CTO, unless architecture-sensitive)
+- Simple data/pipeline work → the data engineer reviews
+- QA/testing/validation → the QA engineer reviews
+- UI design and visual quality → the UI/UX designer reviews (design review for any UI-touching task)
+- Cross-cutting or architecture-sensitive work → the CTO reviews
+- User-facing product/UX decisions → the CPO reviews
+- Process/pipeline/operational changes → the COO reviews
+- Growth/SEO/content quality → the CMO reviews
+- Complex or risky work → C-suite reviewer + specialist reviewer (dual review)
+
+## General
+
+- Simple work (1-2 phases) → specialist builder + specialist reviewer (same domain, different person if possible; same person OK if solo domain)
+- Moderate work (3-4 phases) → specialist builder + C-suite reviewer (for strategic oversight)
+- Complex work (5+ phases) → full team: C-suite designs/audits, specialist builds, C-suite + specialist review
+- Every project MUST have an auditor — this is who scans the codebase in the audit step
+- Match reviewers to the domain being changed -- don't default to the CTO for everything
+- Never have the builder review their own build (conflict of interest)
+- Never have an agent review changes to its own behavior/prompts (conflict of interest)
+
+## Specialist Builder Assignment (file-pattern matching)
+
+When the audit reveals which files an task will touch, assign the matching specialist:
+- Files in `src/components/`, `*.tsx`, `*.jsx`, or UI/styling work → the frontend engineer
+- Files in `server/`, API routes, WebSocket, watchers, or backend logic → the backend engineer
+- Files in `scripts/`, `server/parsers/`, `server/state/`, data pipelines, or indexing → the data engineer
+- Files in `.context/`, `*.md`, `*.mdx`, documentation, or content creation → the content builder
+- Testing, verification, type-checking, or QA-focused work → the QA engineer
+- When scope crosses domains, use the DOMINANT domain's specialist
+- When no clear domain match or scope is very broad → the full-stack engineer
+- The full-stack engineer handles cross-domain work that doesn't clearly belong to a single specialist
+
+## Reviewer-Type Definitions
+
+When casting reviewers, each type focuses on their domain:
+
+### C-Suite reviewers (strategic/cross-cutting -- use for complex, risky, or multi-domain work):
+- **CTO (architecture/security)**: Code patterns, type safety, security vulnerabilities, performance, schema correctness, dependency risks. Use when work is security-sensitive, touches data models, or crosses system boundaries.
+- **CPO (product/UX)**: User workflow completeness, product spec alignment, dead-end UI, first-impression clarity, CEO-intent match. Use when work affects what the CEO sees or touches.
+- **COO (operations/process)**: Conductor process compliance, operational correctness, sequencing logic, casting rule adherence, checkpoint integrity. Use when work changes how the pipeline operates.
+- **CMO (growth/content)**: SEO preservation, content quality, keyword targeting, internal linking, growth metric impact. Use when work affects public content or growth metrics.
+
+### Specialist reviewers (domain-specific -- use for routine, single-domain work):
+- **Frontend engineer**: Component patterns, Tailwind conventions, state management, UI consistency, responsive behavior, accessibility. Use for routine frontend builds.
+- **UI/UX designer**: Layout fidelity, visual consistency, usability, responsiveness, polish. Use as design reviewer on any UI-touching task. During planning, collaborates with the CTO to produce design prototypes.
+- **Backend engineer**: API patterns, error handling, WebSocket correctness, watcher logic, server performance. Use for routine backend builds.
+- **Data engineer**: Parser correctness, indexer logic, state file integrity, data pipeline accuracy. Use for data/pipeline builds.
+- **QA engineer**: Type safety, build validation, test coverage, verification completeness, regression risk. Use as a second reviewer on any build for quality assurance.
+
+## Multi-Reviewer Casting Guidance
+
+- Simple frontend work → the frontend engineer reviews (CTO only if security-sensitive)
+- Simple backend work → the backend engineer reviews (CTO only if architecture-sensitive)
+- Simple data work → the data engineer reviews
+- UI-touching tasks that affect CEO workflow → the frontend engineer builds + UI/UX designer design-reviews + CPO reviews
+- Complex/risky work → specialist builds + C-suite reviews (dual layer)
+- Process/conductor changes → the COO reviews (owns the pipeline)
+- Content/SEO work → the CMO reviews + the content builder builds
+- Any task → optionally add the QA engineer as second reviewer for QA coverage
+- Default: single specialist reviewer is fine for simple, single-domain work. Escalate to C-suite reviewer when the work is risky, cross-cutting, or user-facing.

package/.claude/skills/directive/docs/reference/rules/failure-handling.md

@@ -0,0 +1,20 @@
+<!-- Reference: failure-handling.md | Source: SKILL.md restructure -->
+
+# Failure Handling
+
+| Situation | Action |
+|-----------|--------|
+| Challenger's output doesn't parse as JSON | Log the error, continue. Challenge is advisory, not blocking. |
+| All challengers endorse | Note in approval presentation, proceed normally. |
+| A challenger challenges the directive | Highlight prominently in approval presentation. CEO decides whether to proceed. |
+| The COO's plan doesn't parse as JSON | Stop, show the raw output, ask CEO to intervene |
+| Worktree creation fails | Warn CEO, work in the main repo instead. All changes are uncommitted, CEO can review with `git diff`. |
+| Audit finds nothing for ALL tasks | Skip to stale doc detection, generate digest noting "no issues found", recommend CEO review the directive scope. |
+| CEO rejects the plan | Stop. CEO can re-run with adjusted directive or manually edit the plan |
+| Agent fails mid-task | Skip remaining tasks in that task, continue to next. Log in digest. |
+| Reviewer finds issues | Non-fatal. Include in digest. CEO decides whether to address. |
+| Task is blocked | Skip, note in digest, continue to next task |
+| All tasks fail | Generate digest showing failures, recommend CEO review |
+| Audit finds nothing to fix | Remove task from plan, note in digest |
+| Context exhaustion mid-directive | directive.json preserves state. Re-run `/directive {name}` to resume. |
+| Brainstorm agents disagree on approach | Present all approaches with trade-offs in clarifying questions. Let CEO pick direction. Don't synthesize conflicting approaches into a compromise. |

package/.claude/skills/directive/docs/reference/rules/phase-definitions.md

@@ -0,0 +1,42 @@
+<!-- Reference: phase-definitions.md | Source: SKILL.md restructure -->
+
+# Phase Definitions — Composable Building Blocks
+
+Instead of picking from a fixed process type taxonomy, specify the exact phases each task needs as an ordered array. Available phases:
+
+- "research" — investigation, analysis, competitive intel (researcher agent)
+- "product-spec" — product requirements + acceptance criteria (the CPO)
+- "design" — technical approach document (the CTO)
+- "keyword-research" — SEO keyword analysis (the CMO, for content work)
+- "outline" — content structure and plan (the CMO, for content work)
+- "clarification" — pre-build Q&A between engineer and designer/auditor (auto-added for complex work)
+- "build" — implementation (engineer agent)
+- "draft" — content writing (engineer, for content work)
+- "seo-review" — SEO quality review (the CMO, for content work)
+- "code-review" — independent review using cast reviewers with full files + diff but no builder reasoning (fresh eyes catch bugs)
+- "review" — code/quality review (reviewer agents from cast — checks DOD, user perspective, corrections)
+- "tech-review" — architecture review (the CTO, for complex work)
+- "product-review" — product spec verification (the CPO, for complex work)
+
+## Common Phase Patterns (guidance, not rigid rules)
+
+- Simple fix: ["build", "review"]
+- Integration-touching fix: ["build", "code-review", "review"]
+- Complex project task: ["design", "clarification", "build", "code-review", "review"] (only within multi-project plans)
+- Research only: ["research"] (no build — produces a report)
+- Migration: ["research", "design", "clarification", "build", "review"] (build is incremental)
+- Content: ["keyword-research", "outline", "draft", "seo-review", "review"]
+
+## Code-Review Phase Rules
+
+- Include "code-review" between "build" and "review" when the task touches integration points (data flows between systems, state management, API boundaries) or has >3 DOD criteria
+- Skip for trivial fixes (rename, config change, single-file edit with 1-2 DOD criteria)
+- The code-review phase uses the SAME reviewers from the cast, but with full files + diff and NO builder reasoning/design docs. Fresh eyes catch bugs that contextual reviewers miss.
+- If the builder is also in the reviewers list, they are skipped for code-review (conflict of interest).
+- For moderate/complex tasks inside projects: always include code-review.
+
+## Clarification Phase Rules
+
+- Auto-add "clarification" before "build" when the task has "design", "research", or "product-spec" phases
+- Skip clarification for simple ["build", "review"] tasks — scope is tight enough
+- Skip for ["research"] only tasks — no build phase to clarify

package/.claude/skills/directive/docs/reference/rules/scope-and-dod.md

@@ -0,0 +1,30 @@
+<!-- Reference: scope-and-dod.md | Source: SKILL.md restructure -->
+
+# Scope Format, Definition of Done, and User Scenario Rules
+
+## User Scenario Rules
+
+- Every task must include a `user_scenario` — one sentence describing the user experience after this ships
+- Good: "The CEO runs /directive and sees a telemetry summary with token costs and wall times at the end of the digest"
+- Bad: "Improves the system" (too vague — what does the user actually experience?)
+- Reviewers walk this scenario during review to verify the work delivers the promised experience
+
+## Scope Format
+
+Write 2-4 sentences describing what needs to happen. Focus on the outcome and approach, not specific files or line numbers. Example: "All API endpoints that accept user input need input validation and parameterized queries. Currently using string interpolation for SQL. Switch to Prisma parameterized queries and add Zod validation schemas."
+
+## Definition of Done Rules
+
+- Each task must include 3-5 specific, testable acceptance criteria in `definition_of_done`
+- These are what the reviewer will verify — concrete conditions, not vague outcomes
+- Good DOD: "Every /api/* route has a Zod schema and type-check passes"
+- Bad DOD: "Security is improved" (too vague to verify)
+- DOD should cover: functional correctness, scope completeness, and CEO-intent alignment
+- If the directive has explicit success criteria, each criterion should map to at least one DOD item
+
+Also from the first DOD block in the COO's prompt:
+- Every task MUST have a definition_of_done array with 2-5 concrete, testable criteria
+- Each criterion must be verifiable (not vague like "improve quality")
+- DOD is what the CEO reviews to approve/reject the task's result
+- Examples of good DOD: "All directive.json files have category field", "Watcher reads directive.json and populates category field", "Type-check passes"
+- Examples of bad DOD: "Improve goal structure", "Make it work", "Better code quality"

package/.claude/skills/directive/docs/reference/schemas/audit-output.md

@@ -0,0 +1,44 @@
+<!-- Reference: audit-output.md | Source: SKILL.md restructure, updated by redesign-pipeline-steps -->
+
+# Audit Output JSON Schema (Architect)
+
+This is the **Architect's** output schema — the second phase of the two-agent audit flow. The Architect receives the Investigator's raw data (see [investigation-output.md](investigation-output.md)) and the COO's plan, then produces design recommendations.
+
+For the Investigator's output schema (pure data, no recommendations), see [investigation-output.md](investigation-output.md).
+
+```json
+{
+  "projects": [
+    {
+      "id": "slug matching the COO's project id",
+      "baseline": "Carried forward from investigation data",
+      "active_files": ["Carried forward from investigation data"],
+      "dead_code": ["Carried forward from investigation data"],
+      "findings": "Investigation findings + additional design-relevant observations",
+      "recommended_approach": "How to implement this, referencing real patterns and files from the investigation",
+      "follow_ups": [
+        {
+          "action": "Short description of what to do",
+          "risk": "low | medium | high",
+          "rationale": "Why this risk level — what could go wrong?",
+          "files": ["affected files, if known"]
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Two-Agent Audit Flow
+
+1. **Investigator** scans the codebase and produces investigation-output.md (pure data)
+2. **Architect** reads investigation data + the COO's plan and produces this schema (design recommendations)
+
+The separation prevents investigation findings from anchoring the design — the Architect sees raw data and forms independent recommendations.
+
+## Field Definitions
+
+- **baseline, active_files, dead_code**: Carried forward from the Investigator's output for downstream reference.
+- **findings**: Investigation findings plus any additional observations the Architect makes about design implications.
+- **recommended_approach**: Specific implementation recommendation referencing real files and patterns discovered by the Investigator. This field is passed verbatim to the builder as implementation context and to the code-reviewer for deviation checking. Be concrete — name files, functions, and patterns.
+- **follow_ups**: Actions discovered during design, each with a risk classification (low/medium/high). The Investigator does not produce follow-ups — only the Architect does.

package/.claude/skills/directive/docs/reference/schemas/brainstorm-output.md

@@ -0,0 +1,52 @@
+<!-- Reference: brainstorm-output.md | Source: SKILL.md restructure -->
+
+# Brainstorm Agent Output JSON Schema
+
+## Phase 1: Initial Proposal
+
+All brainstorm participants (C-suite + auditor) output this in both heavyweight and strategic directives.
+
+```json
+{
+  "agent": "{name}",
+  "approach": "Your recommended approach in 3-5 sentences — be specific about what to build/change and in what order",
+  "tradeoffs": ["Key trade-off 1", "Key trade-off 2"],
+  "avoid": "What approach you'd explicitly NOT take and why",
+  "confidence": "high | medium | low — how certain are you this is the right approach?",
+  "feasibility_flags": ["Codebase constraints or existing patterns that affect this approach — auditor fills this, others may leave empty"]
+}
+```
+
+## Phase 2: Rebuttal (Strategic Directives ONLY)
+
+Each agent outputs one rebuttal after seeing all proposals. **Not used for heavyweight directives.**
+
+```json
+{
+  "agent": "{name}",
+  "target_agent": "name of the agent whose proposal is being rebutted",
+  "critique": "What's wrong with their approach — specific about what they missed or got wrong",
+  "alternative": "What should be done instead, referencing original proposal or a new variation"
+}
+```
+
+## Collected Output Structure
+
+The orchestrator collects all outputs into a single brainstorm artifact:
+
+```json
+{
+  "directive": "{directive-name}",
+  "weight": "heavyweight | strategic",
+  "participants": ["agent names"],
+  "proposals": [
+    { "agent": "...", "approach": "...", "tradeoffs": [], "avoid": "...", "confidence": "...", "feasibility_flags": [] }
+  ],
+  "rebuttals": [
+    { "agent": "...", "target_agent": "...", "critique": "...", "alternative": "..." }
+  ],
+  "synthesis": "Synthesis of convergence points, key disagreements, and (for strategic) which critiques landed"
+}
+```
+
+**Note:** `rebuttals` array is empty for heavyweight directives (no deliberation round).

package/.claude/skills/directive/docs/reference/schemas/challenger-output.md

@@ -0,0 +1,13 @@
+<!-- Reference: challenger-output.md | Source: SKILL.md restructure -->
+
+# C-Suite Challenger JSON Output Schema
+
+```json
+{
+  "agent": "{name}",
+  "verdict": "endorse | challenge | flag",
+  "reasoning": "Your 3-5 sentence evaluation from your domain perspective",
+  "alternative": "If challenging: what would you do instead? If endorsing/flagging: null",
+  "risk_flags": ["Short risk statements, if any. Empty array if none."]
+}
+```

package/.claude/skills/directive/docs/reference/schemas/checkpoint.md

@@ -0,0 +1,18 @@
+<!-- Reference: checkpoint.md — DEPRECATED, merged into directive-json.md -->
+
+# Checkpoint Schema — MERGED INTO directive.json
+
+**There is no separate checkpoint file.** All checkpoint data lives in `directive.json`.
+
+See [directive-json.md](directive-json.md) for the full schema including:
+- `pipeline{}` — per-step status, agent, output, artifacts
+- `current_step` — for resume
+- `tasks[]` — with phases, artifact_paths, dod_verification
+- `planning{}` — plan, ceo_approval, worktree_path
+- `wrapup{}` — digest_path, lessons_updated, follow_ups_processed
+
+**Resume:** Read `.context/directives/{name}/directive.json` and check `current_step`.
+
+**Write protocol:** Overwrite directive.json at each step transition. Always update `updated_at`.
+
+**DOD Verification:** Written by the review phase into `tasks[].dod_verification`. The review-gate checks this field.

package/.claude/skills/directive/docs/reference/schemas/current-json.md

@@ -0,0 +1,5 @@
+# DEPRECATED — Use directive-json.md
+
+`current.json` is no longer used. The directive-watcher reads pipeline state directly from `.context/directives/{id}/directive.json`.
+
+See [directive-json.md](./directive-json.md) for the authoritative schema.