mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-07 16:41:06 +08:00
106 lines
4.8 KiB
Markdown
106 lines
4.8 KiB
Markdown
# Spec Generator
|
|
|
|
Structured specification document generator producing a complete document chain (Product Brief -> PRD -> Architecture -> Epics).
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
# 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
|