Spec Generator

Structured specification document generator producing a complete document chain (Product Brief -> PRD -> Architecture -> Epics).

Usage

# Via workflow command
/workflow:spec "Build a task management system"
/workflow:spec -y "User auth with OAuth2"    # Auto mode
/workflow:spec -c "task management"           # Resume session

Architecture

spec-generator/
|- SKILL.md                          # Entry point: metadata + architecture + flow
|- phases/
|  |- 01-discovery.md                # Seed analysis + codebase exploration + spec type selection
|  |- 01-5-requirement-clarification.md  # Interactive requirement expansion
|  |- 02-product-brief.md            # Multi-CLI product brief + glossary generation
|  |- 03-requirements.md             # PRD with MoSCoW priorities + RFC 2119 constraints
|  |- 04-architecture.md             # Architecture + state machine + config model + observability
|  |- 05-epics-stories.md            # Epic/Story decomposition
|  |- 06-readiness-check.md          # Quality validation + handoff + iterate option
|  |- 06-5-auto-fix.md               # Auto-fix loop for readiness issues (max 2 iterations)
|- specs/
|  |- document-standards.md          # Format, frontmatter, naming rules
|  |- quality-gates.md               # Per-phase quality criteria + iteration tracking
|  |- glossary-template.json         # Terminology glossary schema
|- templates/
|  |- product-brief.md               # Product brief template (+ Concepts & Non-Goals)
|  |- requirements-prd.md            # PRD template
|  |- architecture-doc.md            # Architecture template (+ state machine, config, observability)
|  |- epics-template.md              # Epic/Story template (+ versioning)
|  |- profiles/                      # Spec type specialization profiles
|     |- service-profile.md          # Service spec: lifecycle, observability, trust
|     |- api-profile.md              # API spec: endpoints, auth, rate limiting
|     |- library-profile.md          # Library spec: public API, examples, compatibility
|- README.md                         # This file

6-Phase Pipeline

Phase	Name	Output	CLI Tools	Key Features
1	Discovery	spec-config.json	Gemini (analysis)	Spec type selection
1.5	Req Expansion	refined-requirements.json	Gemini (analysis)	Multi-round interactive
2	Product Brief	product-brief.md, glossary.json	Gemini + Codex + Claude (parallel)	Terminology glossary
3	Requirements	requirements/	Gemini (analysis)	RFC 2119, data model
4	Architecture	architecture/	Gemini + Codex (sequential)	State machine, config, observability
5	Epics & Stories	epics/	Gemini (analysis)	Glossary consistency
6	Readiness Check	readiness-report.md, spec-summary.md	Gemini (validation)	Terminology + scope validation
6.5	Auto-Fix	Updated phase docs	Gemini (analysis)	Max 2 iterations

Runtime Output

.workflow/.spec/SPEC-{slug}-{YYYY-MM-DD}/
|- spec-config.json              # Session state
|- discovery-context.json        # Codebase context (optional)
|- refined-requirements.json     # Phase 1.5 (requirement expansion)
|- glossary.json                 # Phase 2 (terminology)
|- product-brief.md              # Phase 2
|- requirements/                 # Phase 3 (directory)
|  |- _index.md
|  |- REQ-*.md
|  └── NFR-*.md
|- architecture/                 # Phase 4 (directory)
|  |- _index.md
|  └── ADR-*.md
|- epics/                        # Phase 5 (directory)
|  |- _index.md
|  └── EPIC-*.md
|- readiness-report.md           # Phase 6
└── spec-summary.md              # Phase 6

Flags

-y|--yes: Auto mode - skip all interactive confirmations
-c|--continue: Resume from last completed phase

Spec type is selected interactively in Phase 1 (defaults to service in auto mode) Available types: service, api, library, platform

Handoff

After Phase 6, choose execution path:

workflow-lite-plan - Execute per Epic
workflow:req-plan-with-file - Roadmap decomposition
workflow-plan - Full planning
issue:new - Create issues per Epic

Design Principles

Document chain: Each phase builds on previous outputs
Multi-perspective: Gemini/Codex/Claude provide different viewpoints
Template-driven: Consistent format via templates + frontmatter
Resumable: spec-config.json tracks completed phases
Pure documentation: No code generation - clean handoff to execution workflows
Type-specialized: Profiles adapt templates to service/api/library/platform requirements
Iterative quality: Phase 6.5 auto-fix repairs issues, max 2 iterations before handoff
Terminology-first: glossary.json ensures consistent terminology across all documents

4.8 KiB Raw Blame History