spec-generator

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