Spec Generator
Structured specification document generator producing a complete specification package (Product Brief, PRD, Architecture, Epics, Issues) through 7 sequential phases with multi-CLI analysis, Codex review gates, and interactive refinement. Heavy document phases are delegated to doc-generator agents to minimize main context usage. Document generation only - execution handoff via issue export to team-planex or existing workflows.
Architecture Overview
Phase 0: Specification Study (Read specs/ + templates/ - mandatory prerequisite) [Inline]
|
Phase 1: Discovery -> spec-config.json + discovery-context.json [Inline]
| (includes spec_type selection)
Phase 1.5: Req Expansion -> refined-requirements.json [Inline]
| (interactive discussion + CLI gap analysis)
Phase 2: Product Brief -> product-brief.md + glossary.json [Agent]
| (3-CLI parallel + synthesis)
Phase 3: Requirements (PRD) -> requirements/ (_index.md + REQ-*.md + NFR-*.md) [Agent]
| (Gemini + Codex review)
Phase 4: Architecture -> architecture/ (_index.md + ADR-*.md) [Agent]
| (Gemini + Codex review)
Phase 5: Epics & Stories -> epics/ (_index.md + EPIC-*.md) [Agent]
| (Gemini + Codex review)
Phase 6: Readiness Check -> readiness-report.md + spec-summary.md [Inline]
| (Gemini + Codex dual validation + per-req verification)
+-- Pass (>=80%): Handoff or Phase 7
+-- Review (60-79%): Handoff with caveats or Phase 7
+-- Fail (<60%): Phase 6.5 Auto-Fix (max 2 iterations)
|
Phase 6.5: Auto-Fix -> Updated Phase 2-5 documents [Agent]
|
+-- Re-run Phase 6 validation
|
Phase 7: Issue Export -> issue-export-report.md [Inline]
(Epic->Issue mapping, ccw issue create, wave assignment)
Key Design Principles
- Document Chain: Each phase builds on previous outputs, creating a traceable specification chain from idea to executable issues
- Agent-Delegated: Heavy document phases (2-5, 6.5) run in
doc-generatoragents viaspawn_agent, keeping main context lean (summaries only) - Multi-Perspective Analysis: CLI tools (Gemini/Codex/Claude) provide product, technical, and user perspectives in parallel
- Codex Review Gates: Phases 3, 5, 6 include Codex CLI review for quality validation before output
- Interactive by Default: Each phase offers user confirmation points;
-yflag enables full auto mode - Resumable Sessions:
spec-config.jsontracks completed phases;-cflag resumes from last checkpoint - Template-Driven: All documents generated from standardized templates with YAML frontmatter
- Pure Documentation: No code generation or execution - clean handoff via issue export to execution workflows
- Spec Type Specialization: Templates adapt to spec type (service/api/library/platform) via profiles for domain-specific depth
- Iterative Quality: Phase 6.5 auto-fix loop repairs issues found in readiness check (max 2 iterations)
- Terminology Consistency: glossary.json generated in Phase 2, injected into all subsequent phases
Agent Registry
| Agent | task_name | Role File | Responsibility | Pattern | fork_turns |
|-------|-----------|-----------|----------------|---------|-------------|
| doc-generator (Phase 2) | doc-gen-p2 | ~/.codex/agents/doc-generator.toml | Product brief + glossary generation | 2.1 Standard | "none" |
| doc-generator (Phase 3) | doc-gen-p3 | ~/.codex/agents/doc-generator.toml | Requirements / PRD generation | 2.1 Standard | "none" |
| doc-generator (Phase 4) | doc-gen-p4 | ~/.codex/agents/doc-generator.toml | Architecture + ADR generation | 2.1 Standard | "none" |
| doc-generator (Phase 5) | doc-gen-p5 | ~/.codex/agents/doc-generator.toml | Epics & Stories generation | 2.1 Standard | "none" |
| doc-generator (Phase 6.5) | doc-gen-fix | ~/.codex/agents/doc-generator.toml | Auto-fix readiness issues | 2.1 Standard | "none" |
| cli-explore-agent (Phase 1) | spec-explorer | ~/.codex/agents/cli-explore-agent.toml | Codebase exploration | 2.1 Standard | "none" |
COMPACT PROTECTION: Agent files are execution documents. When context compression occurs and agent instructions are reduced to summaries, you MUST immediately
Readthe corresponding agent file to reload before continuing execution.
Fork Context Strategy
| Agent | task_name | fork_turns | fork_from | Rationale |
|-------|-----------|-------------|-----------|-----------|
| cli-explore-agent | spec-explorer | "none" | — | Independent utility: codebase scan, isolated task |
| doc-generator (P2) | doc-gen-p2 | "none" | — | Sequential pipeline: context passed via file paths in message |
| doc-generator (P3) | doc-gen-p3 | "none" | — | Sequential pipeline: reads P2 output files from disk |
| doc-generator (P4) | doc-gen-p4 | "none" | — | Sequential pipeline: reads P2-P3 output files from disk |
| doc-generator (P5) | doc-gen-p5 | "none" | — | Sequential pipeline: reads P2-P4 output files from disk |
| doc-generator (P6.5) | doc-gen-fix | "none" | — | Utility fix: reads readiness-report.md + affected phase files |
Why all fork_turns: "none": This is a Pipeline pattern (2.5) — each phase produces files on disk and the next phase reads them. No agent needs the orchestrator's conversation history; all context is explicitly passed via file paths in the spawn message.
Mandatory Prerequisites
Do NOT skip: Before performing any operations, you must completely read the following documents. Proceeding without reading the specifications will result in outputs that do not meet quality standards.
Specification Documents (Required Reading)
| Document | Purpose | Priority | |----------|---------|----------| | specs/document-standards.md | Document format, frontmatter, naming conventions | P0 - Must read before execution | | specs/quality-gates.md | Per-phase quality gate criteria and scoring | P0 - Must read before execution |
Template Files (Must read before generation)
| Document | Purpose | |----------|---------| | templates/product-brief.md | Product brief document template | | templates/requirements-prd.md | PRD document template | | templates/architecture-doc.md | Architecture document template | | templates/epics-template.md | Epic/Story document template |
Execution Flow
Input Parsing:
|- Parse $ARGUMENTS: extract idea/topic, flags (-y, -c, -m)
|- Detect mode: new | continue
|- If continue: read spec-config.json, resume from first incomplete phase
|- If new: proceed to Phase 1
Phase 0 → 1: functions.update_plan([{id:"phase-0",status:"completed"},{id:"phase-1",status:"in_progress"}])
Phase 1: Discovery & Seed Analysis
|- Ref: phases/01-discovery.md
|- Generate session ID: SPEC-{YYYY-MM-DD}-{slug}
|- Parse input (text or file reference)
|- Gemini CLI seed analysis (problem, users, domain, dimensions)
|- Codebase exploration (conditional, if project detected)
| |- spawn_agent({ task_name: "spec-explorer", fork_turns: "none", message: ... })
| |- wait_agent({ timeout_ms: 1800000 })
| |- close_agent({ target: "spec-explorer" })
|- Spec type selection: service|api|library|platform (interactive, -y defaults to service)
|- User confirmation (interactive, -y skips)
|- Output: spec-config.json, discovery-context.json (optional)
Phase 1 → 1.5: functions.update_plan([{id:"phase-1",status:"completed"},{id:"phase-1.5",status:"in_progress"}])
Phase 1.5: Requirement Expansion & Clarification
|- Ref: phases/01-5-requirement-clarification.md
|- CLI gap analysis: completeness scoring, missing dimensions detection
|- Multi-round interactive discussion (max 5 rounds)
| |- Round 1: present gap analysis + expansion suggestions
| |- Round N: follow-up refinement based on user responses
|- User final confirmation of requirements
|- Auto mode (-y): CLI auto-expansion without interaction
|- Output: refined-requirements.json
Phase 1.5 → 2: functions.update_plan([{id:"phase-1.5",status:"completed"},{id:"phase-2",status:"in_progress"}])
Phase 2: Product Brief [AGENT: doc-generator]
|- spawn_agent({ task_name: "doc-gen-p2", fork_turns: "none", message: <context envelope> })
|- Agent reads: phases/02-product-brief.md
|- Agent executes: 3 parallel CLI analyses + synthesis + glossary generation
|- Agent writes: product-brief.md, glossary.json
|- wait_agent({ timeout_ms: 1800000 })
|- close_agent({ target: "doc-gen-p2" })
|- Orchestrator validates: files exist, spec-config.json updated
Phase 2 → 3: functions.update_plan([{id:"phase-2",status:"completed"},{id:"phase-3",status:"in_progress"}])
Phase 3: Requirements / PRD [AGENT: doc-generator]
|- spawn_agent({ task_name: "doc-gen-p3", fork_turns: "none", message: <context envelope> })
|- Agent reads: phases/03-requirements.md
|- Agent executes: Gemini expansion + Codex review (Step 2.5) + priority sorting
|- Agent writes: requirements/ directory (_index.md + REQ-*.md + NFR-*.md)
|- wait_agent({ timeout_ms: 1800000 })
|- close_agent({ target: "doc-gen-p3" })
|- Orchestrator validates: directory exists, file count matches
Phase 3 → 4: functions.update_plan([{id:"phase-3",status:"completed"},{id:"phase-4",status:"in_progress"}])
Phase 4: Architecture [AGENT: doc-generator]
|- spawn_agent({ task_name: "doc-gen-p4", fork_turns: "none", message: <context envelope> })
|- Agent reads: phases/04-architecture.md
|- Agent executes: Gemini analysis + Codex review + codebase mapping
|- Agent writes: architecture/ directory (_index.md + ADR-*.md)
|- wait_agent({ timeout_ms: 1800000 })
|- close_agent({ target: "doc-gen-p4" })
|- Orchestrator validates: directory exists, ADR files present
Phase 4 → 5: functions.update_plan([{id:"phase-4",status:"completed"},{id:"phase-5",status:"in_progress"}])
Phase 5: Epics & Stories [AGENT: doc-generator]
|- spawn_agent({ task_name: "doc-gen-p5", fork_turns: "none", message: <context envelope> })
|- Agent reads: phases/05-epics-stories.md
|- Agent executes: Gemini decomposition + Codex review (Step 2.5) + validation
|- Agent writes: epics/ directory (_index.md + EPIC-*.md)
|- wait_agent({ timeout_ms: 1800000 })
|- close_agent({ target: "doc-gen-p5" })
|- Orchestrator validates: directory exists, MVP epics present
Phase 5 → 6: functions.update_plan([{id:"phase-5",status:"completed"},{id:"phase-6",status:"in_progress"}])
Phase 6: Readiness Check [INLINE + ENHANCED]
|- Ref: phases/06-readiness-check.md
|- Gemini CLI: cross-document validation (completeness, consistency, traceability)
|- Codex CLI: technical depth review (ADR quality, data model, security, observability)
|- Per-requirement verification: iterate all REQ-*.md / NFR-*.md
| |- Check: AC exists + testable, Brief trace, Story coverage, Arch coverage
| |- Generate: Per-Requirement Verification table
|- Merge dual CLI scores into quality report
|- Output: readiness-report.md, spec-summary.md
|- Handoff options: Phase 7 (issue export), lite-plan, req-plan, plan, iterate
Phase 6.5: Auto-Fix (conditional) [AGENT: doc-generator]
|- spawn_agent({ task_name: "doc-gen-fix", fork_turns: "none", message: <context envelope> })
|- Agent reads: phases/06-5-auto-fix.md + readiness-report.md
|- Agent executes: fix affected Phase 2-5 documents
|- wait_agent({ timeout_ms: 1800000 })
|- close_agent({ target: "doc-gen-fix" })
|- Re-run Phase 6 validation
|- Max 2 iterations, then force handoff
Phase 6 → 7: functions.update_plan([{id:"phase-6",status:"completed"},{id:"phase-7",status:"in_progress"}])
Phase 7: Issue Export [INLINE]
|- Ref: phases/07-issue-export.md
|- Read EPIC-*.md files, assign waves (MVP->wave-1, others->wave-2)
|- Create issues via ccw issue create (one per Epic)
|- Map Epic dependencies to issue dependencies
|- Generate issue-export-report.md
|- Update spec-config.json with issue_ids
|- Handoff: team-planex, wave-1 only, view issues, done
Phase 7 complete: functions.update_plan([{id:"phase-7",status:"completed"}])
Complete: Full specification package with issues ready for execution
Phase 6/7 -> Handoff Bridge (conditional, based on user selection):
+- team-planex: Execute issues via coordinated team workflow
+- lite-plan: Extract first MVP Epic description -> direct text input
+- plan / req-plan: Create WFS session + .brainstorming/ bridge files
| +- guidance-specification.md (synthesized from spec outputs)
| +- feature-specs/feature-index.json (Epic -> Feature mapping)
| +-- feature-specs/F-{num}-{slug}.md (one per Epic)
+- context-search-agent auto-discovers .brainstorming/
-> context-package.json.brainstorm_artifacts populated
-> action-planning-agent consumes: guidance_spec (P1) -> feature_index (P2)
Directory Setup
// Session ID generation
const slug = topic.toLowerCase().replace(/[^a-z0-9\u4e00-\u9fff]+/g, '-').slice(0, 40);
const date = new Date().toISOString().slice(0, 10);
const sessionId = `SPEC-${date}-${slug}`;
const workDir = `.workflow/.spec/${sessionId}`;
Bash(`mkdir -p "${workDir}"`);
// Initialize progress tracking (MANDATORY)
functions.update_plan([
{ id: "phase-0", title: "Phase 0: Specification Study", status: "in_progress" },
{ id: "phase-1", title: "Phase 1: Discovery", status: "pending" },
{ id: "phase-1.5", title: "Phase 1.5: Req Expansion", status: "pending" },
{ id: "phase-2", title: "Phase 2: Product Brief", status: "pending" },
{ id: "phase-3", title: "Phase 3: Requirements (PRD)", status: "pending" },
{ id: "phase-4", title: "Phase 4: Architecture", status: "pending" },
{ id: "phase-5", title: "Phase 5: Epics & Stories", status: "pending" },
{ id: "phase-6", title: "Phase 6: Readiness Check", status: "pending" },
{ id: "phase-7", title: "Phase 7: Issue Export", status: "pending" }
])
Output Structure
.workflow/.spec/SPEC-{YYYY-MM-DD}-{slug}/
+-- spec-config.json # Session configuration + phase state
+-- discovery-context.json # Codebase exploration results (optional)
+-- refined-requirements.json # Phase 1.5: Confirmed requirements after discussion
+-- glossary.json # Phase 2: Terminology glossary for cross-doc consistency
+-- product-brief.md # Phase 2: Product brief
+-- requirements/ # Phase 3: Detailed PRD (directory)
| +-- _index.md # Summary, MoSCoW table, traceability, links
| +-- REQ-NNN-{slug}.md # Individual functional requirement
| +-- NFR-{type}-NNN-{slug}.md # Individual non-functional requirement
+-- architecture/ # Phase 4: Architecture decisions (directory)
| +-- _index.md # Overview, components, tech stack, links
| +-- ADR-NNN-{slug}.md # Individual Architecture Decision Record
+-- epics/ # Phase 5: Epic/Story breakdown (directory)
| +-- _index.md # Epic table, dependency map, MVP scope
| +-- EPIC-NNN-{slug}.md # Individual Epic with Stories
+-- readiness-report.md # Phase 6: Quality report (+ per-req verification table)
+-- spec-summary.md # Phase 6: One-page executive summary
+-- issue-export-report.md # Phase 7: Issue mapping table + spec links
State Management
spec-config.json serves as core state file:
{
"session_id": "SPEC-xxx-2026-02-11",
"seed_input": "User input text",
"input_type": "text",
"timestamp": "ISO8601",
"mode": "interactive",
"complexity": "moderate",
"depth": "standard",
"focus_areas": [],
"spec_type": "service",
"iteration_count": 0,
"iteration_history": [],
"seed_analysis": {
"problem_statement": "...",
"target_users": [],
"domain": "...",
"constraints": [],
"dimensions": []
},
"has_codebase": false,
"refined_requirements_file": "refined-requirements.json",
"issue_ids": [],
"issues_created": 0,
"phasesCompleted": [
{ "phase": 1, "name": "discovery", "output_file": "spec-config.json", "completed_at": "ISO8601" },
{ "phase": 1.5, "name": "requirement-clarification", "output_file": "refined-requirements.json", "discussion_rounds": 2, "completed_at": "ISO8601" },
{ "phase": 3, "name": "requirements", "output_dir": "requirements/", "output_index": "requirements/_index.md", "file_count": 8, "completed_at": "ISO8601" }
]
}
Resume mechanism: -c|--continue flag reads spec-config.json.phasesCompleted, resumes from first incomplete phase.
Core Rules
- Start Immediately: First action is
functions.update_planinitialization, then Phase 0 (spec study), then Phase 1 - Progressive Phase Loading: Read phase docs ONLY when that phase is about to execute
- Auto-Continue: All phases run autonomously; proceed to next phase after current completes
- Parse Every Output: Extract required data from each phase for next phase context
- DO NOT STOP: Continuous 7-phase pipeline until all phases complete or user exits
- Respect -y Flag: When auto mode, skip all user interaction calls, use recommended defaults
- Respect -c Flag: When continue mode, load spec-config.json and resume from checkpoint
- Inject Glossary: From Phase 3 onward, inject glossary.json terms into every CLI prompt
- Load Profile: Read templates/profiles/{spec_type}-profile.md and inject requirements into Phase 2-5 prompts
- Iterate on Failure: When Phase 6 score < 60%, auto-trigger Phase 6.5 (max 2 iterations)
- Agent Delegation: Phase 2-5 and 6.5 MUST be delegated to
doc-generatoragents viaspawn_agent— never execute inline - Lean Context: Orchestrator only sees agent return summaries from
wait_agent, never the full document content - Validate Agent Output: After each
wait_agentreturns, verify files exist on disk and spec-config.json was updated - Lifecycle Balance: Every
spawn_agentMUST have a matchingclose_agentafterwait_agentretrieves results
Agent Delegation Protocol
For Phase 2-5 and 6.5, the orchestrator delegates to a doc-generator agent via spawn_agent. The orchestrator builds a lean context envelope — passing only paths, never file content.
Context Envelope Template
spawn_agent({
task_name: "doc-gen-p<N>",
fork_turns: "none",
message: `
## Spec Generator - Phase <N>: <phase-name>
### MANDATORY FIRST STEPS (Agent Execute)
1. **Read role definition**: ~/.codex/agents/doc-generator.toml (MUST read first)
2. Read: <skill-dir>/phases/<phase-file>
---
### Session
- ID: <session-id>
- Work Dir: <work-dir>
- Auto Mode: <auto-mode>
- Spec Type: <spec-type>
### Input (read from disk)
<input-files-list>
### Instructions
Read: <skill-dir>/phases/<phase-file>
Apply template: <skill-dir>/templates/<template-file>
### Glossary (Phase 3+ only)
Read: <work-dir>/glossary.json
### Output
Write files to: <work-dir>/<output-path>
Update: <work-dir>/spec-config.json (phasesCompleted)
Return: JSON summary { files_created, quality_notes, key_decisions }
`
})
Orchestrator Post-Agent Validation
After each agent phase, the orchestrator validates output:
// 1. Wait for agent completion
const result = wait_agent({ timeout_ms: 1800000 })
// 2. Handle timeout (4-step cascade)
if (result.timed_out) {
// Step 1: Status probe
followup_task({
target: "doc-gen-p<N>",
message: "STATUS_CHECK: Report current progress, findings so far, and estimated remaining work."
})
const status = wait_agent({ timeout_ms: 180000 }) // 3 min
if (status.timed_out) {
// Step 2: Force finalize
followup_task({
target: "doc-gen-p<N>",
message: "FINALIZE: Output all current findings immediately. Time limit reached.",
interrupt: true
})
const forced = wait_agent({ timeout_ms: 180000 }) // 3 min
if (forced.timed_out) {
// Step 3: Close agent
close_agent({ target: "doc-gen-p<N>" })
// Step 4: Fall back to inline execution for this phase
}
}
}
// 3. Close agent (lifecycle balance)
close_agent({ target: "doc-gen-p<N>" })
// 4. Parse agent return summary
const summary = parseJSON(result.status["doc-gen-p<N>"].completed)
// 5. Validate files exist
summary.files_created.forEach(file => {
const exists = Glob(`<work-dir>/${file}`)
if (!exists.length) → Error: agent claimed file but not found
})
// 6. Verify spec-config.json updated
const config = JSON.parse(Read(`<work-dir>/spec-config.json`))
const phaseComplete = config.phasesCompleted.some(p => p.phase === N)
if (!phaseComplete) → Error: agent did not update phasesCompleted
// 7. Store summary for downstream context (do NOT read full documents)
phasesSummaries[N] = summary
Lifecycle Management
Timeout Protocol
| Phase | task_name | Default Timeout | On Timeout |
|-------|-----------|-----------------|------------|
| Phase 1 (explore) | spec-explorer | 1800000ms (30min) | Status probe (3 min) → force finalize (3 min) → close |
| Phase 2 | doc-gen-p2 | 1800000ms (30min) | Status probe (3 min) → force finalize (3 min) → close + inline fallback |
| Phase 3 | doc-gen-p3 | 1800000ms (30min) | Status probe (3 min) → force finalize (3 min) → close + inline fallback |
| Phase 4 | doc-gen-p4 | 1800000ms (30min) | Status probe (3 min) → force finalize (3 min) → close + inline fallback |
| Phase 5 | doc-gen-p5 | 1800000ms (30min) | Status probe (3 min) → force finalize (3 min) → close + inline fallback |
| Phase 6.5 | doc-gen-fix | 1800000ms (30min) | Status probe (3 min) → force finalize (3 min) → close + force handoff |
Cleanup Protocol
At the end of each agent-delegated phase, close the agent immediately after retrieving results. Each phase spawns a fresh agent — no agent persists across phases.
// Standard per-phase cleanup (after wait_agent succeeds)
close_agent({ target: "doc-gen-p<N>" })
// On workflow abort / user cancellation
const activeAgents = ["doc-gen-p2", "doc-gen-p3", "doc-gen-p4", "doc-gen-p5", "doc-gen-fix", "spec-explorer"]
activeAgents.forEach(name => {
try { close_agent({ target: name }) } catch { /* not active */ }
})
Reference Documents by Phase
Phase 1: Discovery
| Document | Purpose | When to Use | |----------|---------|-------------| | phases/01-discovery.md | Seed analysis and session setup | Phase start | | templates/profiles/ | Spec type profiles | Spec type selection | | specs/document-standards.md | Frontmatter format for spec-config.json | Config generation |
Phase 1.5: Requirement Expansion & Clarification
| Document | Purpose | When to Use | |----------|---------|-------------| | phases/01-5-requirement-clarification.md | Interactive requirement discussion workflow | Phase start | | specs/quality-gates.md | Quality criteria for refined requirements | Validation |
Phase 2: Product Brief
| Document | Purpose | When to Use | |----------|---------|-------------| | phases/02-product-brief.md | Multi-CLI analysis orchestration | Phase start | | templates/product-brief.md | Document template | Document generation | | specs/glossary-template.json | Glossary schema | Glossary generation |
Phase 3: Requirements
| Document | Purpose | When to Use | |----------|---------|-------------| | phases/03-requirements.md | PRD generation workflow | Phase start | | templates/requirements-prd.md | Document template | Document generation |
Phase 4: Architecture
| Document | Purpose | When to Use | |----------|---------|-------------| | phases/04-architecture.md | Architecture decision workflow | Phase start | | templates/architecture-doc.md | Document template | Document generation |
Phase 5: Epics & Stories
| Document | Purpose | When to Use | |----------|---------|-------------| | phases/05-epics-stories.md | Epic/Story decomposition | Phase start | | templates/epics-template.md | Document template | Document generation |
Phase 6: Readiness Check
| Document | Purpose | When to Use | |----------|---------|-------------| | phases/06-readiness-check.md | Cross-document validation | Phase start | | specs/quality-gates.md | Quality scoring criteria | Validation |
Phase 6.5: Auto-Fix
| Document | Purpose | When to Use | |----------|---------|-------------| | phases/06-5-auto-fix.md | Auto-fix workflow for readiness issues | When Phase 6 score < 60% | | specs/quality-gates.md | Iteration exit criteria | Validation |
Phase 7: Issue Export
| Document | Purpose | When to Use | |----------|---------|-------------| | phases/07-issue-export.md | Epic->Issue mapping and export | Phase start | | specs/quality-gates.md | Issue export quality criteria | Validation |
Debugging & Troubleshooting
| Issue | Solution Document | |-------|-------------------| | Phase execution failed | Refer to the relevant Phase documentation | | Output does not meet expectations | specs/quality-gates.md | | Document format issues | specs/document-standards.md |
Error Handling
| Phase | Error | Blocking? | Action | |-------|-------|-----------|--------| | Phase 1 | Empty input | Yes | Error and exit | | Phase 1 | CLI seed analysis fails | No | Use basic parsing fallback | | Phase 1 | Codebase explore agent timeout | No | close_agent, proceed without discovery-context | | Phase 1.5 | Gap analysis CLI fails | No | Skip to user questions with basic prompts | | Phase 1.5 | User skips discussion | No | Proceed with seed_analysis as-is | | Phase 1.5 | Max rounds reached (5) | No | Force confirmation with current state | | Phase 2 | Single CLI perspective fails | No | Continue with available perspectives | | Phase 2 | All CLI calls fail | No | Generate basic brief from seed analysis | | Phase 3 | Gemini CLI fails | No | Use codex fallback | | Phase 4 | Architecture review fails | No | Skip review, proceed with initial analysis | | Phase 5 | Story generation fails | No | Generate epics without detailed stories | | Phase 6 | Validation CLI fails | No | Generate partial report with available data | | Phase 6.5 | Auto-fix CLI fails | No | Log failure, proceed to handoff with Review status | | Phase 6.5 | Max iterations reached | No | Force handoff, report remaining issues | | Phase 7 | ccw issue create fails for one Epic | No | Log error, continue with remaining Epics | | Phase 7 | No EPIC files found | Yes | Error and return to Phase 5 | | Phase 7 | All issue creations fail | Yes | Error with CLI diagnostic, suggest manual creation | | Phase 2-5 | Agent timeout (wait_agent timed_out) | No | Status probe (3 min) → force finalize (3 min) → close + inline fallback | | Phase 2-5 | Agent returns incomplete files | No | Log gaps, attempt inline completion for missing files | | Any | close_agent on non-existent agent | No | Catch error, continue (agent may have self-terminated) |
CLI Fallback Chain
Gemini -> Codex -> Claude -> degraded mode (local analysis only)