gru-ai 0.1.0

package/.claude/skills/directive/docs/pipeline/00-delegation-and-triage.md

@@ -0,0 +1,181 @@
+<!-- Pipeline doc: 00-delegation-and-triage.md | Source: SKILL.md restructure -->
+
+## Step 0b: Triage (Complexity Assessment)
+
+### Pre-flight Cleanup
+
+Before doing anything else, kill orphaned CLI agents from prior runs. These accumulate when a directive session gets killed mid-execution (context limit, timeout, cancellation) and the spawned child processes keep running as zombies. Left unchecked, they saturate API rate limits and cause new spawns to hang indefinitely.
+
+```bash
+# Kill orphaned CLI agent processes from prior runs
+ps aux | grep "claude.*--agent.*-p" | grep -v grep | awk '{print $2}' | xargs kill 2>/dev/null
+# Also kill any orphaned -p (print mode) processes without --agent
+ps aux | grep "claude -p" | grep -v grep | awk '{print $2}' | xargs kill 2>/dev/null
+echo "Pre-flight cleanup: killed orphaned agent processes"
+```
+
+This is safe — active CLI agents for the current directive haven't been spawned yet, so there's nothing to accidentally kill.
+
+### Classify the Directive
+
+Read the directive, then classify its weight. This determines how much process overhead is needed. Not everything needs the full pipeline.
+
+Read the directive file: `.context/directives/$ARGUMENTS.md`
+Read `.context/vision.md` guardrails and `.context/preferences.md`.
+
+### Classification Rules
+
+**Lightweight** — the COO plans, but minimal overhead. No C-suite challenges, no CEO approval:
+- Single clear task (fix a bug, delete dead code, update a config)
+- All changes are in well-understood files
+- No user-facing impact
+- No guardrail risk (check vision.md)
+- Scope fits in one engineer agent's work
+
+**Medium** — the COO plans, but no C-suite challenges, no CEO approval:
+- 2-3 related tasks that need coordination
+- Touches multiple files but within one system
+- Low-to-medium risk (no revenue/auth/schema impact)
+- the COO plans the projects, pipeline executes tasks, CEO gets the summary
+
+**Heavyweight** — Full pipeline with challenges, audit, and CEO approval gate:
+- Crosses system boundaries (frontend + backend + infra)
+- Touches revenue, auth, user data, or database schema
+- Architectural decisions needed
+- Violates or tests a guardrail in vision.md
+- CEO has explicitly flagged this area as sensitive
+- 4+ tasks or multi-day scope
+
+**Security classification examples** (to resolve ambiguity):
+- Hardening existing code (fixing injection, removing hardcoded creds, adding input validation to existing routes) = **Medium**
+- Changing auth flows, adding new auth mechanisms, modifying access controls, changing session handling = **Heavyweight**
+
+**Strategic** — Full pipeline with brainstorm phase before the COO plans:
+- Multiple valid approaches and the directive doesn't prescribe one
+- Architectural or process-level change — affects HOW the system works, not just WHAT it does
+- Crosses 2+ domain boundaries where C-suite members would have conflicting opinions
+- Lasting consequences expensive to reverse — new schemas, API contracts, conventions
+- The directive asks a question or states a problem without specifying the solution
+- NOT strategic just because it's big — a directive with a clear prescribed approach is heavyweight, not strategic
+
+### Triage Output
+
+State the classification clearly before proceeding:
+
+```
+Directive: {name}
+Classification: {lightweight | medium | heavyweight | strategic}
+Reasoning: {1-2 sentences why}
+Process: {what steps will be used}
+```
+
+### Lightweight Process
+
+1. Read context files (lessons/ topic files, preferences.md — skip the full context load)
+2. Spawn the COO to plan projects (plan) — even for simple work, the COO produces the plan so the CEO session stays clean
+3. Spawn auditor for technical baseline (audit) — lightweight audit, not full investigation
+4. **No plan-approval gate** — auto-approve
+5. Create branch (setup) — worktree only if working directory is dirty
+6. Execute tasks (execute)
+7. Review verification (review-gate)
+8. Generate a short digest to `.context/reports/`
+9. Return CEO summary (Done / Changes / Needs CEO Eyes / Next)
+
+No C-suite challenges. No brainstorm. No plan-approval gate. No worktree (unless the CEO has uncommitted changes). No OKR updates. CEO approves completion after the fact (completion step).
+
+**CEO SESSION RULE: The CEO session NEVER plans or builds — it triages, delegates to the COO/agents, and reviews results. This applies to ALL weights including lightweight.**
+
+### Medium Process
+
+1. Read full context (read + context steps)
+2. Spawn the COO to plan projects (plan) -- the COO's inline challenge is always included, but skip separate C-suite challengers (challenge step)
+3. Spawn auditor for technical baseline (audit)
+4. **No plan-approval gate** -- auto-approve the plan based on directive scope and guardrails
+5. Create branch (setup) — worktree only if working directory is dirty
+6. Execute tasks (execute)
+7. Review verification (review-gate)
+8. Update OKRs, generate digest, update lessons (wrapup)
+9. Output CEO summary
+
+No pause for plan sign-off. The CEO reviews the digest after the fact and approves completion (completion step). If something in the plan looks risky (touches a guardrail), **upgrade to heavyweight**.
+
+### Strategic Process
+
+Same as heavyweight but with an additional deliberation round during brainstorm. The team figures out the approach, debates it, and the CEO answers 2-3 clarifying questions.
+
+1. Read full context (read + context steps)
+2. **Brainstorm phase (with deliberation)** — spawn the brainstorm team in parallel using `run_in_background: true`. The brainstorm team includes:
+   - **2-3 relevant C-suite agents** (the CTO for architecture, the CPO for product, the CMO for growth — pick based on directive domain)
+   - **The named auditor** from the project cast (defaulting to the CTO if none assigned) -- grounds proposals in codebase reality
+
+   Each agent gets:
+   - Their personality from `.claude/agents/{name}.md`
+   - The directive text
+   - `.context/vision.md` and `.context/preferences.md`
+   - The Phase 1 prompt from the brainstorm prompt template
+   - `model: "sonnet"` (cheap, fast -- this is approach exploration, not code)
+
+   ```
+   Agent tool call (per brainstorm agent):
+     subagent_type: "{agent_name}"
+     model: "sonnet"
+     run_in_background: true
+     prompt: |
+       {Phase 1 brainstorm prompt from template}
+   ```
+
+   **Collect results** — after spawning all brainstorm agents, collect results using TaskOutput for each agent ID. Wait for all background agents to return before synthesizing.
+
+   **Error handling** — if a brainstorm agent fails or times out, log the error and continue with the remaining proposals. If ALL brainstorm agents fail, skip the brainstorm synthesis and proceed to the COO planning with a note: "brainstorm phase failed — the COO must derive the approach independently."
+
+3. **Deliberation round (strategic only)** — after collecting all Phase 1 proposals, spawn each agent again with all proposals visible. Each agent writes ONE rebuttal targeting the proposal they most disagree with. Use the Phase 2 prompt from the brainstorm prompt template.
+
+   ```
+   Agent tool call (per brainstorm agent, round 2):
+     subagent_type: "{agent_name}"
+     model: "sonnet"
+     run_in_background: true
+     prompt: |
+       {Phase 2 deliberation prompt from template, with all Phase 1 outputs included}
+   ```
+
+   **Collect rebuttals** — same collection pattern as Phase 1. If a rebuttal agent fails, continue without it.
+
+4. **Synthesize** — collect all proposals AND rebuttals. Identify which critiques landed, which proposals survived challenge. Write synthesis to `.context/directives/{directive-id}/brainstorm.md`
+5. **CEO clarification** — write 2-3 clarifying questions based on unresolved disagreements from the deliberation. STOP and return to CEO: "This directive is strategic. The team brainstormed N approaches and debated. Here are questions before we proceed: [questions]"
+6. **After CEO answers** — feed brainstorm synthesis + CEO answers into the COO's prompt as additional context. Continue as heavyweight from the plan step onward.
+
+> See [docs/reference/templates/brainstorm-prompt.md](../reference/templates/brainstorm-prompt.md) for the full brainstorm agent prompt template (Phase 1 + Phase 2).
+
+> See [docs/reference/schemas/brainstorm-output.md](../reference/schemas/brainstorm-output.md) for the brainstorm agent output JSON schema (proposals + rebuttals).
+
+### Heavyweight Process
+
+Full pipeline: triage → read → context → challenge → **Brainstorm** → plan → audit → approve → project-brainstorm → setup → execute → review-gate → wrapup → completion.
+
+**Brainstorm phase (mandatory for heavyweight):** Before the COO plans, spawn the brainstorm team in parallel using `run_in_background: true`. The brainstorm team includes:
+- **2-3 relevant C-suite agents** (the CTO for architecture, the CPO for product, the CMO for growth — pick based on directive domain)
+- **The named auditor** from the project cast (defaulting to the CTO if none assigned) -- grounds proposals in codebase reality
+
+Each agent gets the **Phase 1 prompt only** from the brainstorm prompt template. No deliberation round for heavyweight — proposals only, then synthesis.
+
+```
+Agent tool call (per brainstorm agent):
+  subagent_type: "{agent_name}"
+  model: "sonnet"
+  run_in_background: true
+  prompt: |
+    {Phase 1 brainstorm prompt from template}
+```
+
+**Collect results** using TaskOutput for each agent ID. Wait for all background agents to return before synthesizing.
+
+**Error handling** — if a brainstorm agent fails or times out, log the error and continue with the remaining proposals. If ALL brainstorm agents fail, skip the brainstorm synthesis and proceed to the COO planning with a note: "brainstorm phase failed — the COO must derive the approach independently."
+
+**Synthesize** — collect all proposals (NO rebuttals for heavyweight). Identify convergence points and key disagreements. Write synthesis to `.context/directives/{directive-id}/brainstorm.md`. CEO clarification questions are included in the plan-for-approval artifact rather than as a separate STOP gate. This ensures the team thinks through the approach before the COO plans, without adding a separate round-trip to the CEO.
+
+> See [docs/reference/templates/brainstorm-prompt.md](../reference/templates/brainstorm-prompt.md) for the full brainstorm agent prompt template.
+
+> See [docs/reference/schemas/brainstorm-output.md](../reference/schemas/brainstorm-output.md) for the brainstorm agent output JSON schema.
+
+For the CEO approval gate (approve step): write the plan to `.context/directives/{directive-id}/plan-for-approval.md` and STOP. Output a summary asking the CEO to approve. Include brainstorm synthesis and any clarifying questions alongside the COO's plan. After CEO approval, continue execution from the setup step.

package/.claude/skills/directive/docs/pipeline/01-checkpoint.md

@@ -0,0 +1,34 @@
+<!-- Pipeline doc: 01-checkpoint.md | Source: SKILL.md restructure -->
+
+## Step 0: Check for Existing Progress
+
+Check if `.context/directives/$ARGUMENTS.json` exists AND has a `current_step` field (indicating previous execution progress).
+
+**If not found or no `current_step`:** Proceed to the read step normally.
+
+**If found with `current_step`:** Parse the directive JSON and present a resume summary:
+
+```
+Found progress for {id}:
+- Started: {started_at}, last updated: {updated_at}
+- Progress: {completed}/{total} tasks complete
+- Current step: {current_step}
+- Tasks: {list each with status}
+
+Resume or restart fresh?
+```
+
+Ask the CEO using AskUserQuestion: **Resume** or **Restart**.
+
+**If Restart:** Remove the pipeline/execution fields from directive.json (keep metadata). Delete project artifacts (`rm -rf .context/directives/{id}/projects/`). Proceed to the read step.
+
+**If Resume:** Load directive.json data and skip to the appropriate step:
+- `current_step` is `plan` or `audit` → Load `planning.coo_plan`, skip to approve (CEO approval)
+- `current_step` is `approve` → Re-present plan for CEO approval. Previous approval carries over — show it and ask CEO to confirm: "Plan was previously approved. Confirm to continue?"
+- `current_step` is `project-brainstorm` or `setup` → Load `planning.worktree_path`, verify `directive.json` pipeline state is consistent, then skip to execute
+- `current_step` is `execute` or `review-gate` → Load tasks array. Skip tasks with `status: "completed"` or `status: "skipped"`. Restart any `in_progress` task from its first phase (do not attempt partial phase resume). Continue with `pending` tasks.
+- `current_step` is `wrapup` or `completion` → Load wrapup state, skip completed wrapup sub-steps, continue from the first incomplete one
+
+For resumed execute step: when restarting an in-progress task, read its artifact files (if any) for context but re-execute all phases from scratch. Only truly completed tasks are skipped.
+
+> See [docs/reference/schemas/directive-json.md](../reference/schemas/directive-json.md) for the full directive.json schema.

package/.claude/skills/directive/docs/pipeline/02-read-directive.md

@@ -0,0 +1,38 @@
+<!-- Pipeline doc: 02-read-directive.md | Source: SKILL.md restructure -->
+
+## Step 1: Read the Directive
+
+**If a directive file exists:** Read `.context/directives/$ARGUMENTS/directive.md` (or `.context/directives/$ARGUMENTS.md` for legacy flat files).
+
+**If no directive file exists (ad-hoc request):** The CEO gave an ad-hoc description instead of a directive name. Generate a kebab-case ID from the description (e.g., "run these 3 projects" → `run-3-projects`, "comprehensive system review" → `system-review-2026-03-04`). Create a directive directory `mkdir -p .context/directives/{id}/` with both `directive.md` and `directive.json`. The `.md` should contain the CEO's original request as the directive brief.
+
+**If $ARGUMENTS looks like a project path** (contains `/`): Read the project.json at `.context/directives/{directive}/projects/{project}/project.json`. Generate a directive ID from the project name. Create the directive files.
+
+**Naming convention:** Directive filenames must be kebab-case (e.g., `improve-security.md`). The name is used in git branch names (`directive/$ARGUMENTS`) and file paths.
+
+### Create directive.json (ALWAYS — for all directive types including ad-hoc)
+
+Create `.context/directives/$ARGUMENTS/directive.json` if it doesn't already exist (create the directory first: `mkdir -p .context/directives/$ARGUMENTS/`). This companion JSON provides structured metadata for the pipeline and dashboard.
+
+> See [docs/reference/schemas/directive-json.md](../reference/schemas/directive-json.md) for the full directive.json schema.
+
+```json
+{
+  "id": "$ARGUMENTS",
+  "title": "{extracted from first heading of the .md}",
+  "status": "in_progress",
+  "created": "{today's date YYYY-MM-DD}",
+  "completed": null,
+  "weight": "{classification from triage: lightweight | medium | heavyweight | strategic}",
+  "category": "{one of: framework, pipeline, dashboard, game — infer from directive name/scope}",
+  "produced_features": [],
+  "report": null,
+  "backlog_sources": []
+}
+```
+
+Extract `category` from the directive .md content:
+- Look for `**Category**: {category}` in the directive text
+- If not found, infer from the directive name/scope (e.g., `game-*` -> `game`, `pipeline-*` -> `pipeline`, `dashboard-*` -> `dashboard`)
+- Valid categories: `framework`, `pipeline`, `dashboard`, `game`
+- Every directive MUST have a category

package/.claude/skills/directive/docs/pipeline/03-read-context.md

@@ -0,0 +1,15 @@
+<!-- Pipeline doc: 03-read-context.md | Source: SKILL.md restructure -->
+
+## Step 2: Read Context
+
+Read ALL of these before spawning the COO:
+- `.context/vision.md` — north star + guardrails (agents must respect guardrails)
+- `.context/preferences.md` — CEO standing orders (agents must follow these)
+- `.context/directives/*/directive.json` — current directives, their categories, and status
+- `.context/lessons/*.md` — project gotchas and patterns (read topic files as needed per agent role)
+- `.context/lessons/orchestration.md` — for the COO and orchestration
+- `.context/lessons/agent-behavior.md` — for all agents
+- All `.context/directives/*/projects/*/project.json` — current project states and task status
+- The C-suite agent personality files (resolve names from `.claude/agent-registry.json`)
+
+Also note the directive's `category` field — this goes to the auditor in the audit step for domain context.

package/.claude/skills/directive/docs/pipeline/04-challenge.md

@@ -0,0 +1,38 @@
+<!-- Pipeline doc: 04-challenge.md | Source: SKILL.md restructure -->
+
+## Challenge: C-Suite Challenge (Heavyweight Directives Only)
+
+**Default behavior:** Challenge is INLINED into the COO's planning prompt (see plan step). The COO identifies the top 3 risks and flags over-engineering concerns as part of the planning output.
+
+**Separate challenger agents are only spawned when:**
+- The CEO explicitly flags the directive as controversial
+- The directive is heavyweight AND crosses multiple domains (e.g., touches revenue + auth + UI)
+
+When separate challengers ARE needed, spawn 1-2 relevant C-suite members:
+- Security / architecture / technical debt → **the CTO**
+- User-facing features / product changes → **the CPO**
+- Growth / SEO / marketing / positioning → **the CMO**
+- Operational / process / resource changes → spawn **two** of the above (most relevant pair)
+
+> See [docs/reference/templates/challenger-prompt.md](../reference/templates/challenger-prompt.md) for the full challenger prompt template.
+
+> See [docs/reference/schemas/challenger-output.md](../reference/schemas/challenger-output.md) for the challenger JSON output schema.
+
+**Spawn challengers in parallel** using `run_in_background: true`. Each is a lightweight agent call — use the agent's `id` from the registry as the `subagent_type`, `model: "sonnet"` (fast, cheap — this is a gut check, not deep analysis).
+
+```
+Agent tool call (per challenger):
+  subagent_type: "{agent_name}"
+  model: "sonnet"
+  run_in_background: true
+  prompt: |
+    {challenger prompt from template}
+```
+
+**Collect results** — after spawning all challengers, collect results using TaskOutput for each agent ID. Wait for all background agents to return before proceeding.
+
+**Error handling** — if a background agent fails or times out, log the error and continue. Challenge is advisory — a failed challenger does not block the pipeline. If ALL challengers fail, note "challenge phase unavailable" and proceed to COO planning.
+
+**Parse responses** as JSON. If any fail to parse, log the error and continue.
+
+**Store challenges** — they get presented alongside the COO's plan in the approve step.

package/.claude/skills/directive/docs/pipeline/05-planning.md

@@ -0,0 +1,64 @@
+<!-- Pipeline doc: 05-planning.md | Source: SKILL.md restructure -->
+
+## Step 3: Spawn the COO (Strategic Planning)
+
+Spawn the COO as an Agent (model: opus, subagent_type: COO's ID from registry).
+
+**The COO's prompt must include:**
+- The CEO directive text (personality is auto-loaded via the `subagent_type`)
+- The goals index, lessons, and agent summaries from the context step
+- These explicit instructions:
+
+> See [docs/reference/templates/planner-prompt.md](../reference/templates/planner-prompt.md) for the full COO planning prompt.
+
+> See [docs/reference/schemas/plan-schema.md](../reference/schemas/plan-schema.md) for the COO's output JSON schema.
+
+> See [docs/reference/rules/casting-rules.md](../reference/rules/casting-rules.md) for full casting rules.
+
+> See [docs/reference/rules/phase-definitions.md](../reference/rules/phase-definitions.md) for phase composable building blocks.
+
+> See [docs/reference/rules/scope-and-dod.md](../reference/rules/scope-and-dod.md) for scope format rules, Definition of Done rules, and user scenario rules.
+
+**If this directive was classified as strategic**, also include in the COO's prompt:
+- The brainstorm synthesis from `.context/directives/{directive-id}/brainstorm.md`
+- CEO's clarification answers
+- Additional instruction to the COO: "The team has brainstormed approach options for this directive. Use the brainstorm synthesis and CEO's answers to inform your plan — you don't need to re-derive the approach from scratch. Focus on execution planning, not strategy."
+
+**Parse the COO's response** as JSON. Extract the JSON object from the response (find the first `{` and last `}`). If it fails to parse, show the error and stop.
+
+### Save the COO's plan (DO NOT create project.json yet)
+
+Save the COO's parsed JSON plan to `.context/directives/{directive-id}/plan.json` for reference. The directive directory should already exist from the read step.
+
+**Do NOT create project.json at this step.** The project.json is created in the approve step (after CEO approval) so that CEO modifications to the plan are reflected in the source of truth. Creating it before approval causes plan/project drift when the CEO requests changes.
+
+### Handle Multi-Project Plans
+
+If the COO's plan contains a `projects` array (triggered when genuinely complex work can't be decomposed into simple tasks):
+
+1. **Verify projects are independent** — if project B depends on project A's output (shared code, shared data structures, one builds on the other), they MUST be merged into a single project with ordered tasks. Task array ordering IS the dependency mechanism. There is no cross-project dependency field.
+2. **Create a separate project directory and project.json for each independent project** in the approve step (after CEO approval)
+3. **Each project gets its own brainstorm** (2-3 agents + deliberation) before build
+4. **Each project gets its own execution cycle** in the execute step: brainstorm -> audit -> build -> review -> verify
+5. **Projects execute sequentially by priority tier** (all P0 projects before P1)
+6. **Project directories**: `.context/directives/{directive-id}/projects/{project-id}/` (use the project's `id`, not the directive name)
+
+Most directives should use a single project with simple tasks. Multi-project is the exception for genuinely complex AND independent work.
+
+**Validate the cast** — pipe the parsed JSON through `validate-cast.sh` to mechanically check casting rules:
+
+```bash
+echo "$PLAN_JSON" | .claude/hooks/validate-cast.sh
+```
+
+The script checks:
+1. Every task has an auditor assigned
+2. Builder is not in the reviewers array (conflict of interest)
+3. Complex tasks (5+ phases) have at least one C-suite reviewer
+4. Agents don't review changes to their own behavior/prompts
+
+If validation fails (`valid: false`), log the violations and either:
+- **Auto-fix** if the violation is clear (e.g., swap a conflicting reviewer for the next-best match per casting rules)
+- **Block** and re-prompt the COO with the violations if auto-fix isn't possible
+
+> See [.claude/hooks/validate-cast.sh](../../../../.claude/hooks/validate-cast.sh) for the validation script.

package/.claude/skills/directive/docs/pipeline/06-technical-audit.md

@@ -0,0 +1,88 @@
+<!-- Pipeline doc: 06-technical-audit.md | Source: SKILL.md restructure, updated by redesign-pipeline-steps -->
+
+## Audit: Technical Audit (Two-Agent Flow)
+
+After parsing the COO's plan, run a two-agent sequential audit: **the QA engineer (Investigation)** (pure data) then **Architect** (design recommendations). This separation prevents investigation findings from anchoring the design.
+
+**Complexity gating:** For projects that touch integration points (data flows between systems, state management, API boundaries) or have moderate/complex scope, use the full two-agent flow. For simple projects with tight scope (single-domain), use the single-agent auditor pattern (skip the QA engineer's investigation, spawn only the named auditor -- defaulting to the CTO -- with the combined prompt from [auditor-prompt.md](../reference/templates/auditor-prompt.md)). Note: single-project directives are often `simple`; projects in multi-project plans may be moderate/complex and should always use the two-agent flow.
+
+### Phase 1: Investigation
+
+Spawn the QA engineer in investigation mode to scan the codebase and gather raw data. The QA engineer does NOT recommend approaches -- they report facts only.
+
+**Group projects by scope overlap** -- if multiple projects touch similar areas, send them to a single investigation agent to avoid redundant scanning.
+
+**Investigation spawn rules:**
+- `subagent_type`: the QA engineer's ID from the registry -- operates in investigation mode when given the investigator prompt
+- Spawn as Agent (model: opus)
+- `run_in_background: true` if multiple investigation groups exist
+
+**The QA engineer's investigation prompt must include:**
+- The COO's projects (the ones assigned to this investigation group)
+- The directive's category (from directive.json `category` field) — for domain context
+- `.context/vision.md` guardrails section — for constraint awareness
+- `.context/preferences.md` — CEO standing orders
+- `.context/lessons/agent-behavior.md` — agent behavior lessons
+- Explicit instruction: "You are operating in INVESTIGATION MODE. Pure data gathering — scan, measure, report. Do NOT recommend approaches."
+
+> See [docs/reference/templates/investigator-prompt.md](../reference/templates/investigator-prompt.md) for the full investigation prompt template.
+
+> See [docs/reference/schemas/investigation-output.md](../reference/schemas/investigation-output.md) for the investigation output JSON schema.
+
+**Parse the QA engineer's response** as JSON. If it fails to parse, show the error and stop.
+
+### Phase 2: Architecture (Design Recommendations)
+
+Spawn the Architect to read the Investigator's data + the COO's plan and recommend technical approaches.
+
+**The Architect role is filled by the named auditor from the COO's cast** -- not a separate agent definition. This ensures domain expertise informs the design.
+
+**Architect spawn rules:**
+- Use the auditor's `id` from the registry as the `subagent_type`
+- If no named auditor is assigned, default to the CTO (handles unassigned audits)
+- Spawn as Agent (model: opus)
+
+**Architect's prompt must include:**
+- Their personality file (for named agents — auto-loaded via `subagent_type`)
+- The COO's projects (the ones assigned to this auditor)
+- **The QA engineer's full investigation JSON output** — this is the Architect's primary input
+- `.context/vision.md` guardrails section — for risk classification reference
+- `.context/preferences.md` — CEO standing orders
+- `.context/lessons/review-quality.md` — review lessons (for the CTO)
+- `.context/lessons/agent-behavior.md` — agent behavior lessons
+
+> See [docs/reference/templates/architect-prompt.md](../reference/templates/architect-prompt.md) for the full Architect prompt template.
+
+> See [docs/reference/schemas/audit-output.md](../reference/schemas/audit-output.md) for the Architect's output JSON schema.
+
+**Parse the Architect's response** as JSON. If it fails to parse, show the error and stop.
+
+### Phase 2b: Design Prototype (UI-Touching Projects Only)
+
+**Trigger:** If any project in the plan touches UI files (`*.tsx`, `*.jsx`, `*.css`, `src/components/`, `src/styles/`, or game canvas code), spawn the UI/UX designer to produce a design prototype.
+
+**UI/UX designer spawn rules:**
+- `subagent_type`: the UI/UX designer's ID from the registry
+- Spawn as Agent (model: opus)
+- Only for projects flagged as UI-touching (use file-pattern matching from the audit's `active_files`)
+
+**The UI/UX designer's prompt must include:**
+- The COO's projects (the UI-touching ones)
+- The Architect's audit output (so she knows the technical constraints)
+- `.context/preferences.md` — CEO standing orders
+- `.context/lessons/agent-behavior.md` — agent behavior lessons
+- Existing UI patterns: have them read the relevant component files from `active_files` to understand current patterns
+- Instruction: "Produce a design prototype for each UI-touching project. Include ASCII wireframes, component specs, interaction notes, and responsive breakpoints. Your prototype goes into the plan markdown — builders use it as the visual spec."
+
+**The UI/UX designer's output** is a markdown document with design prototypes. Write it to `.context/directives/{id}/design-prototype.md`. This file is:
+- Presented to the CEO during the approval step alongside the COO's plan
+- Included in the builder's prompt during the execute step as the visual spec to follow
+- Referenced by the UI/UX designer during design review (review-gate) to check implementation fidelity
+
+### After All Audit Phases
+
+**Update directive.json:** Set `current_step: "audit"`, `planning.coo_plan` to the parsed JSON. Update `pipeline.audit` status/agent/output.
+
+**If a project has no active files and all dead code:** Flag it for removal in the CEO presentation.
+
+**Artifact:** Write the combined audit output (investigation data + architect recommendations) to the project directory as `audit-findings.json`. If design prototype was produced, note its path in the directive.json pipeline object.

package/.claude/skills/directive/docs/pipeline/07-plan-approval.md

@@ -0,0 +1,145 @@
+<!-- Pipeline doc: 07-plan-approval.md | Source: SKILL.md restructure -->
+
+## Approve: Present Combined Plan to CEO
+
+### Pre-approval: Complexity Floor Check
+
+After the audit and before presenting the plan, validate that all tasks are genuinely `simple` using the audit's `active_files` as mechanical ground truth:
+
+- If a task has **>5 active_files**: it's NOT simple. **Flag for re-decomposition** — the COO must break it into 2-3 smaller simple tasks.
+- If a task has **>10 active_files** or spans **>2 directories**: it's genuinely complex. **Flag as needing its own project** with brainstorm.
+- Log any flags: `[COMPLEXITY FLAG] {task title}: touches 7 active files -- needs decomposition`
+
+**If any tasks are flagged:**
+1. Re-spawn the COO with the flagged tasks + audit findings, instructing them to decompose the tasks into simple tasks (or escalate to a separate project if genuinely complex)
+2. Re-validate the updated plan
+3. Present the final plan to CEO
+
+This prevents the COO (an LLM optimistic about complexity) from classifying everything as "simple". The audit's active_files count is mechanical ground truth that overrides the COO's judgment.
+
+---
+
+**If running in a dedicated CLI session (non-interactive):** Write the full plan to `.context/directives/$ARGUMENTS/plan-for-approval.md` using the format below, update directive.json, and stop. The CEO reviews and re-launches with approval.
+
+**If running inline (CEO session):** Present as described below.
+
+### CEO Quick Summary (present FIRST — before any detail)
+
+Always lead with a 3-5 bullet TL;DR that the CEO can read in 20 seconds:
+
+```
+## TL;DR
+
+- **What**: {1-sentence goal}
+- **Scope**: {N} tasks{, M in K projects if multi-project}
+- **Risk**: {the COO's recommendation -- proceed / scope down / defer}
+- **Auto-ships**: {count} low-risk tasks execute without approval
+- **Needs your call**: {count} items need CEO decision {brief description}
+
+Approve all / Approve with changes / Reject
+```
+
+The CEO should be able to approve from the TL;DR alone for medium-risk directives. The full detail below is for heavyweight review or "Approve with changes" scenarios.
+
+### Challenges (from the COO's inline analysis + challenge step if separate challengers were spawned)
+
+First, present the COO's built-in challenge analysis:
+
+```
+## Risk & Scope Assessment (COO)
+
+Risks: {the COO's top 3 risks from challenges.risks}
+Over-engineering flags: {challenges.over_engineering_flags}
+Recommendation: {challenges.recommendation}
+```
+
+If separate C-suite challengers were spawned (heavyweight/controversial directives only), present their responses:
+
+```
+**{Agent Name}** — {ENDORSE | CHALLENGE | FLAG}
+{reasoning}
+{If challenge: "Alternative: {alternative}"}
+{If risk flags: "Risks: {list}"}
+```
+
+If any challenge (the COO's or separate) recommends scoping down, highlight it prominently. The CEO should consider the challenge before approving the plan.
+
+### Plan (from plan + audit steps)
+
+Merge the COO's strategic plan with the audit findings and present **grouped by priority**:
+
+For each task, display:
+- Title + priority + complexity
+- Scope (from the COO)
+- User scenario (from the COO — the one-sentence user experience)
+- Audit findings: active files, dead code flagged, recommended approach
+- Phases + agent cast
+- Definition of Done items (from the COO's plan — for CEO to review before approving)
+
+Flag tasks where the audit found nothing to fix or all dead code -- recommend removal.
+
+Example format:
+```
+## P0 — Must Ship
+
+  1. {Task Title} (phases: {phases list}) — {cast summary}
+     Scope: {the COO's scope description}
+     User scenario: {user_scenario}
+     Audit: {baseline} | {N} active files | {M} dead code files flagged
+     Approach: {auditor's recommended approach}
+     DOD: {criterion 1} | {criterion 2} | {criterion 3}
+
+  2. {Task Title} — RECOMMEND REMOVE
+     Audit: No active issues found. {explanation}
+
+## P1 — Should Ship
+  ...
+
+## P2 — Nice to Have
+  ...
+```
+
+Ask the CEO to approve using AskUserQuestion:
+- "Approve all" — execute everything as planned
+- "Approve with changes" -- CEO adjusts priorities or removes tasks
+- "Reject" — stop, explain what's wrong
+
+**DOD review guidance:** Before approving, scan each task's DOD items. Flag any that are:
+- Too vague to verify ("improve quality" vs "all routes have Zod schemas")
+- Missing CEO-intent alignment (DOD doesn't reflect what you actually want)
+- Incomplete (fewer than 3 items, or missing a testability dimension)
+
+If DOD items are weak, use "Approve with changes" to request better criteria before execution starts.
+
+If CEO wants changes, adjust the plan accordingly.
+
+### Create project.json (after CEO approves)
+
+Once the CEO approves (or approves with changes), create the project.json — this is the source of truth for execution. Builders read it to know what to do. The dashboard shows it for progress tracking.
+
+1. Create directory: `mkdir -p .context/directives/{directive-id}/projects/{project-id}/` (for each project in the COO's plan)
+2. Write `project.json` with fields derived from the COO's plan (incorporating any CEO modifications):
+   - `id`: directive name
+   - `title`: from the COO's plan goal title
+   - `category`: from the COO's `category` field (or directive.json `category`)
+   - `status`: `"in_progress"`
+   - `priority`: highest priority from tasks (P0 > P1 > P2)
+   - `agent`: array of builder agent IDs from the COO's cast (e.g. `["frontend-engineer-id"]`, `["backend-engineer-id", "data-engineer-id"]`)
+   - `reviewers`: array of reviewer agent IDs from the COO's cast (e.g. `["cto-id"]`, `["cto-id", "cpo-id"]`)
+   - `description`: from the directive brief
+   - `source_directive`: directive name
+   - `scope.in`: aggregated from all task scopes
+   - `scope.out`: anything explicitly excluded
+   - `dod`: from the COO's `definition_of_done` arrays — each criterion starts as `{ "criterion": "...", "met": false }`
+   - `browser_test`: `true` if any task touches UI files
+   - `tasks`: one entry per task from the COO's plan, each with `status: "pending"`, `agent: []`, `dod` from the task's DOD -- each criterion starts as `{ "criterion": "...", "met": false }`. **CRITICAL: The key MUST be `tasks`.** The validator will reject any other key name.
+   - `created`: current ISO 8601 timestamp with actual time (e.g. `new Date().toISOString()` — NEVER use `T00:00:00Z` placeholder)
+   - `updated`: same as `created` initially
+
+3. If the project.json already exists (from a prior partial run or brainstorm), UPDATE it — merge new tasks, don't duplicate existing ones. Apply any CEO modifications from "Approve with changes."
+
+This project.json will be updated by the project-brainstorm step with the full `tasks` array, then incrementally during execution as tasks complete and reviews finish. The finalization step at the end sets status to completed, updates DOD met status, etc.
+
+**Next step:** Proceed to [07b-project-brainstorm.md](07b-project-brainstorm.md) (project-brainstorm) to decompose each project into tasks with DOD.
+
+**Update directive.json:** Set `current_step: "approve"`, `planning.ceo_approval` to `{status: "approved", modifications: [...]}` (or rejected). Update `pipeline.approve.status` to `"completed"` with output. This is CRITICAL — CEO decisions cannot be reconstructed after context loss.