Spec Generator

Structured specification document generator producing a complete specification package (Product Brief, PRD, Architecture, Epics) through 6 sequential phases with multi-CLI analysis and interactive refinement. Document generation only - execution handoff to existing workflows (lite-plan, plan, req-plan).

Architecture Overview

Phase 0:   Specification Study (Read specs/ + templates/ - mandatory prerequisite)
           |
Phase 1:   Discovery               -> spec-config.json + discovery-context.json
           |                           (includes spec_type selection)
Phase 1.5: Req Expansion           -> refined-requirements.json (interactive discussion + CLI gap analysis)
           |                           (-y auto mode: auto-expansion, skip interaction)
Phase 2:   Product Brief            -> product-brief.md + glossary.json  (multi-CLI parallel analysis)
           |
Phase 3:   Requirements (PRD)      -> requirements/  (_index.md + REQ-*.md + NFR-*.md)
           |                           (RFC 2119 keywords, data model definitions)
Phase 4:   Architecture            -> architecture/  (_index.md + ADR-*.md, multi-CLI review)
           |                           (state machine, config model, error handling, observability)
Phase 5:   Epics & Stories         -> epics/  (_index.md + EPIC-*.md)
           |
Phase 6:   Readiness Check         -> readiness-report.md + spec-summary.md
           |                           (terminology + scope consistency validation)
           ├── Pass (>=80%): Handoff to execution workflows
           ├── Review (60-79%): Handoff with caveats
           └── Fail (<60%): Phase 6.5 Auto-Fix (max 2 iterations)
                 |
Phase 6.5: Auto-Fix               -> Updated Phase 2-5 documents
                 |
                 └── Re-run Phase 6 validation

Key Design Principles

1. Document Chain: Each phase builds on previous outputs, creating a traceable specification chain from idea to executable stories
2. Multi-Perspective Analysis: CLI tools (Gemini/Codex/Claude) provide product, technical, and user perspectives in parallel
3. Interactive by Default: Each phase offers user confirmation points; -y flag enables full auto mode
4. Resumable Sessions: spec-config.json tracks completed phases; -c flag resumes from last checkpoint
5. Template-Driven: All documents generated from standardized templates with YAML frontmatter
6. Pure Documentation: No code generation or execution - clean handoff to existing execution workflows
7. Spec Type Specialization: Templates adapt to spec type (service/api/library/platform) via profiles for domain-specific depth
8. Iterative Quality: Phase 6.5 auto-fix loop repairs issues found in readiness check (max 2 iterations)
9. Terminology Consistency: glossary.json generated in Phase 2, injected into all subsequent phases

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)

Template Files (Must read before generation)

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 1: Discovery & Seed Analysis
   |- Ref: phases/01-discovery.md
   |- Generate session ID: SPEC-{slug}-{YYYY-MM-DD}
   |- Parse input (text or file reference)
   |- Gemini CLI seed analysis (problem, users, domain, dimensions)
   |- Codebase exploration (conditional, if project detected)
   |- 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.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 2: Product Brief
   |- Ref: phases/02-product-brief.md
   |- 3 parallel CLI analyses: Product (Gemini) + Technical (Codex) + User (Claude)
   |- Synthesize perspectives: convergent themes + conflicts
   |- Generate glossary.json (terminology from product brief + CLI analysis)
   |- Interactive refinement (-y skips)
   |- Output: product-brief.md (from template), glossary.json

Phase 3: Requirements / PRD
   |- Ref: phases/03-requirements.md
   |- Gemini CLI: expand goals into functional + non-functional requirements
   |- Generate acceptance criteria per requirement
   |- RFC 2119 behavioral constraints (MUST/SHOULD/MAY)
   |- Core entity data model definitions
   |- Glossary injection for terminology consistency
   |- User priority sorting: MoSCoW (interactive, -y auto-assigns)
   |- Output: requirements/ directory (_index.md + REQ-*.md + NFR-*.md, from template)

Phase 4: Architecture
   |- Ref: phases/04-architecture.md
   |- Gemini CLI: core components, tech stack, ADRs
   |- Codebase integration mapping (conditional)
   |- State machine generation (ASCII diagrams for lifecycle entities)
   |- Configuration model definition (fields, types, defaults, constraints)
   |- Error handling strategy (per-component classification + recovery)
   |- Observability specification (metrics, logs, health checks)
   |- Spec type profile injection (templates/profiles/{type}-profile.md)
   |- Glossary injection for terminology consistency
   |- Codex CLI: architecture challenge + review
   |- Interactive ADR decisions (-y auto-accepts)
   |- Output: architecture/ directory (_index.md + ADR-*.md, from template)

Phase 5: Epics & Stories
   |- Ref: phases/05-epics-stories.md
   |- Gemini CLI: requirement grouping into Epics, MVP subset tagging
   |- Story generation: As a...I want...So that...
   |- Dependency mapping (Mermaid)
   |- Interactive validation (-y skips)
   |- Output: epics/ directory (_index.md + EPIC-*.md, from template)

Phase 6: Readiness Check
   |- Ref: phases/06-readiness-check.md
   |- Cross-document validation (completeness, consistency, traceability)
   |- Quality scoring per dimension
   |- Terminology consistency validation (glossary compliance)
   |- Scope containment validation (PRD <= Brief scope)
   |- Output: readiness-report.md, spec-summary.md
   |- Handoff options: lite-plan, req-plan, plan, issue:new, export only, iterate

Phase 6.5: Auto-Fix (conditional, triggered when Phase 6 score < 60%)
   |- Ref: phases/06-5-auto-fix.md
   |- Parse readiness-report.md for Error/Warning items
   |- Group issues by originating Phase (2-5)
   |- Re-generate affected sections via CLI with error context
   |- Re-run Phase 6 validation
   |- Max 2 iterations, then force handoff
   |- Output: Updated Phase 2-5 documents

Complete: Full specification package ready for execution

Phase 6 → Handoff Bridge (conditional, based on user selection):
   ├─ 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)
   ├─ issue:new: Create issues 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-${slug}-${date}`;
const workDir = `.workflow/.spec/${sessionId}`;

Bash(`mkdir -p "${workDir}"`);

Output Structure

.workflow/.spec/SPEC-{slug}-{YYYY-MM-DD}/
├── 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
└── spec-summary.md               # Phase 6: One-page executive summary

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",
  "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

1. Start Immediately: First action is TaskCreate initialization, then Phase 0 (spec study), then Phase 1
2. Progressive Phase Loading: Read phase docs ONLY when that phase is about to execute
3. Auto-Continue: All phases run autonomously; check TaskList to execute next pending phase
4. Parse Every Output: Extract required data from each phase for next phase context
5. DO NOT STOP: Continuous 6-phase pipeline until all phases complete or user exits
6. Respect -y Flag: When auto mode, skip all AskUserQuestion calls, use recommended defaults
7. Respect -c Flag: When continue mode, load spec-config.json and resume from checkpoint
8. Inject Glossary: From Phase 3 onward, inject glossary.json terms into every CLI prompt
9. Load Profile: Read templates/profiles/{spec_type}-profile.md and inject requirements into Phase 2-5 prompts
10. Iterate on Failure: When Phase 6 score < 60%, auto-trigger Phase 6.5 (max 2 iterations)

Reference Documents by Phase

Phase 1: Discovery

Phase 1.5: Requirement Expansion & Clarification

Phase 2: Product Brief

Phase 3: Requirements

Phase 4: Architecture

Phase 5: Epics & Stories

Phase 6: Readiness Check

Phase 6.5: Auto-Fix

Debugging & Troubleshooting

Error Handling

CLI Fallback Chain

Gemini -> Codex -> Claude -> degraded mode (local analysis only)