spec-generator

# 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 1. **Document Chain**: Each phase builds on previous outputs, creating a traceable specification chain from idea to executable issues 2. **Agent-Delegated**: Heavy document phases (2-5, 6.5) run in `doc-generator` agents via `spawn_agent`, keeping main context lean (summaries only) 3. **Multi-Perspective Analysis**: CLI tools (Gemini/Codex/Claude) provide product, technical, and user perspectives in parallel 4. **Codex Review Gates**: Phases 3, 5, 6 include Codex CLI review for quality validation before output 5. **Interactive by Default**: Each phase offers user confirmation points; `-y` flag enables full auto mode 6. **Resumable Sessions**: `spec-config.json` tracks completed phases; `-c` flag resumes from last checkpoint 7. **Template-Driven**: All documents generated from standardized templates with YAML frontmatter 8. **Pure Documentation**: No code generation or execution - clean handoff via issue export to execution workflows 9. **Spec Type Specialization**: Templates adapt to spec type (service/api/library/platform) via profiles for domain-specific depth 10. **Iterative Quality**: Phase 6.5 auto-fix loop repairs issues found in readiness check (max 2 iterations) 11. **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 `Read` the 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](specs/document-standards.md) | Document format, frontmatter, naming conventions | **P0 - Must read before execution** | | [specs/quality-gates.md](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](templates/product-brief.md) | Product brief document template | | [templates/requirements-prd.md](templates/requirements-prd.md) | PRD document template | | [templates/architecture-doc.md](templates/architecture-doc.md) | Architecture document template | | [templates/epics-template.md](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 })