mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-12 02:37:45 +08:00
feat: add spec-generator handoff bridge to workflow:plan consumption pipeline
Phase 6 now creates brainstorm_artifacts-compatible bridge files (.brainstorming/guidance-specification.md, feature-index.json, feature-specs) when handing off to workflow:plan or req-plan, enabling context-search-agent auto-discovery without modifying downstream consumers.
This commit is contained in:
catlog22
107
.claude/commands/workflow/spec.md
Normal file
107
.claude/commands/workflow/spec.md
Normal file
@@ -0,0 +1,107 @@
|
||||
---
|
||||
name: spec
|
||||
description: Specification generator - 6 phase document chain producing product brief, PRD, architecture, and epics. Triggers on "generate spec", "create specification", "spec generator".
|
||||
argument-hint: "[-y|--yes] [-c|--continue] \"idea or requirement description\""
|
||||
allowed-tools: TodoWrite(*), Task(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*), Bash(*), Edit(*), Write(*)
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Auto-confirm decisions, use recommended defaults, skip interactive validation.
|
||||
|
||||
# Workflow Spec Command (/workflow:spec)
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Basic usage
|
||||
/workflow:spec "Build a task management system with real-time collaboration"
|
||||
|
||||
# Auto mode (skip all confirmations)
|
||||
/workflow:spec -y "User authentication system with OAuth2 and 2FA"
|
||||
|
||||
# Continue existing session
|
||||
/workflow:spec -c "task management"
|
||||
|
||||
# Combined
|
||||
/workflow:spec -y -c "task management"
|
||||
```
|
||||
|
||||
**Skill**: `spec-generator`
|
||||
**Output Directory**: `.workflow/.spec/SPEC-{slug}-{YYYY-MM-DD}/`
|
||||
**Core Flow**: Discovery -> Product Brief -> PRD -> Architecture -> Epics -> Readiness Check
|
||||
|
||||
## What This Command Does
|
||||
|
||||
Generates a complete specification package through 6 sequential phases:
|
||||
|
||||
1. **Discovery**: Analyze seed idea, explore codebase (optional), establish session
|
||||
2. **Product Brief**: Multi-CLI analysis (Product/Technical/User perspectives)
|
||||
3. **Requirements (PRD)**: Functional + non-functional requirements with MoSCoW priorities
|
||||
4. **Architecture**: Component design, tech stack, ADRs with review
|
||||
5. **Epics & Stories**: Implementation breakdown with dependency mapping
|
||||
6. **Readiness Check**: Cross-document validation, quality scoring, handoff
|
||||
|
||||
## Output Artifacts
|
||||
|
||||
| Phase | Artifact | Description |
|
||||
|-------|----------|-------------|
|
||||
| 1 | `spec-config.json` | Session configuration and state |
|
||||
| 1 | `discovery-context.json` | Codebase exploration (optional) |
|
||||
| 2 | `product-brief.md` | Product brief with multi-perspective synthesis |
|
||||
| 3 | `requirements.md` | Detailed PRD with acceptance criteria |
|
||||
| 4 | `architecture.md` | Architecture decisions and component design |
|
||||
| 5 | `epics.md` | Epic/Story breakdown with dependencies |
|
||||
| 6 | `readiness-report.md` | Quality validation report |
|
||||
| 6 | `spec-summary.md` | One-page executive summary |
|
||||
|
||||
## Flags
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `-y`, `--yes` | Auto mode: skip all confirmations, use defaults |
|
||||
| `-c`, `--continue` | Resume from last completed phase |
|
||||
|
||||
## After Completion
|
||||
|
||||
The readiness check (Phase 6) offers handoff to execution workflows:
|
||||
|
||||
- `/workflow:lite-plan` - Execute one Epic at a time (direct text input)
|
||||
- `/workflow:req-plan-with-file` - Generate execution roadmap
|
||||
- `/workflow:plan` - Full planning for entire scope
|
||||
- `/issue:new` - Create issues per Epic
|
||||
|
||||
### Plan Integration (Automatic Bridge)
|
||||
|
||||
When selecting "Full planning" or "Create roadmap", Phase 6 automatically:
|
||||
|
||||
1. Creates a WFS session via `/workflow:session:start`
|
||||
2. Generates `.brainstorming/` bridge files in the session directory:
|
||||
- `guidance-specification.md` — synthesized from spec outputs (product-brief + requirements + architecture key decisions)
|
||||
- `feature-specs/feature-index.json` — maps each Epic to a Feature entry
|
||||
- `feature-specs/F-{num}-{slug}.md` — individual feature spec per Epic
|
||||
3. Invokes the downstream workflow (`/workflow:plan` or `/workflow:req-plan-with-file`)
|
||||
|
||||
The `context-search-agent` auto-discovers these `.brainstorming/` files and populates `context-package.json.brainstorm_artifacts`, which `action-planning-agent` consumes via the standard priority chain: `guidance_specification` → `feature_index` → `feature_specs`. No manual bridging required.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Starting a new product/feature from scratch
|
||||
- Need structured specification before implementation
|
||||
- Want multi-perspective analysis of an idea
|
||||
- Need traceable requirement -> architecture -> story chain
|
||||
- Replacing ad-hoc brainstorming with structured output
|
||||
|
||||
## Compared to Other Workflows
|
||||
|
||||
| Workflow | Use When |
|
||||
|----------|----------|
|
||||
| `/workflow:spec` | Need full specification package before any coding |
|
||||
| `/workflow:brainstorm-with-file` | Exploring ideas, not ready for structure |
|
||||
| `/workflow:lite-plan` | Have clear requirements, ready to implement |
|
||||
| `/workflow:plan` | Have requirements, need detailed task planning |
|
||||
| `/workflow:req-plan-with-file` | Have requirements, need layered roadmap |
|
||||
|
||||
---
|
||||
|
||||
**Now execute spec-generator for**: $ARGUMENTS
|
||||
258
.claude/skills/spec-generator/SKILL.md
Normal file
258
.claude/skills/spec-generator/SKILL.md
Normal file
@@ -0,0 +1,258 @@
|
||||
---
|
||||
name: spec-generator
|
||||
description: Specification generator - 6 phase document chain producing product brief, PRD, architecture, and epics. Triggers on "generate spec", "create specification", "spec generator", "workflow:spec".
|
||||
allowed-tools: Task, AskUserQuestion, TaskCreate, TaskUpdate, TaskList, Read, Write, Edit, Bash, Glob, Grep, Skill
|
||||
---
|
||||
|
||||
# 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
|
||||
|
|
||||
Phase 2: Product Brief -> product-brief.md (multi-CLI parallel analysis)
|
||||
|
|
||||
Phase 3: Requirements (PRD) -> requirements.md
|
||||
|
|
||||
Phase 4: Architecture -> architecture.md (multi-CLI review)
|
||||
|
|
||||
Phase 5: Epics & Stories -> epics.md
|
||||
|
|
||||
Phase 6: Readiness Check -> readiness-report.md + spec-summary.md
|
||||
|
|
||||
Handoff to execution workflows
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
## 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 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)
|
||||
|- User confirmation (interactive, -y skips)
|
||||
|- Output: spec-config.json, discovery-context.json (optional)
|
||||
|
||||
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
|
||||
|- Interactive refinement (-y skips)
|
||||
|- Output: product-brief.md (from template)
|
||||
|
||||
Phase 3: Requirements / PRD
|
||||
|- Ref: phases/03-requirements.md
|
||||
|- Gemini CLI: expand goals into functional + non-functional requirements
|
||||
|- Generate acceptance criteria per requirement
|
||||
|- User priority sorting: MoSCoW (interactive, -y auto-assigns)
|
||||
|- Output: requirements.md (from template)
|
||||
|
||||
Phase 4: Architecture
|
||||
|- Ref: phases/04-architecture.md
|
||||
|- Gemini CLI: core components, tech stack, ADRs
|
||||
|- Codebase integration mapping (conditional)
|
||||
|- Codex CLI: architecture challenge + review
|
||||
|- Interactive ADR decisions (-y auto-accepts)
|
||||
|- Output: architecture.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.md (from template)
|
||||
|
||||
Phase 6: Readiness Check
|
||||
|- Ref: phases/06-readiness-check.md
|
||||
|- Cross-document validation (completeness, consistency, traceability)
|
||||
|- Quality scoring per dimension
|
||||
|- Output: readiness-report.md, spec-summary.md
|
||||
|- Handoff options: lite-plan, req-plan, plan, issue:new, export only, iterate
|
||||
|
||||
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
|
||||
|
||||
```javascript
|
||||
// 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)
|
||||
|- product-brief.md # Phase 2: Product brief
|
||||
|- requirements.md # Phase 3: Detailed PRD
|
||||
|- architecture.md # Phase 4: Architecture decisions
|
||||
|- epics.md # Phase 5: Epic/Story breakdown
|
||||
|- 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:
|
||||
```json
|
||||
{
|
||||
"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": [],
|
||||
"seed_analysis": {
|
||||
"problem_statement": "...",
|
||||
"target_users": [],
|
||||
"domain": "...",
|
||||
"constraints": [],
|
||||
"dimensions": []
|
||||
},
|
||||
"has_codebase": false,
|
||||
"phasesCompleted": [
|
||||
{ "phase": 1, "name": "discovery", "output_file": "spec-config.json", "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
|
||||
|
||||
## Reference Documents by Phase
|
||||
|
||||
### Phase 1: Discovery
|
||||
| Document | Purpose | When to Use |
|
||||
|----------|---------|-------------|
|
||||
| [phases/01-discovery.md](phases/01-discovery.md) | Seed analysis and session setup | Phase start |
|
||||
| [specs/document-standards.md](specs/document-standards.md) | Frontmatter format for spec-config.json | Config generation |
|
||||
|
||||
### Phase 2: Product Brief
|
||||
| Document | Purpose | When to Use |
|
||||
|----------|---------|-------------|
|
||||
| [phases/02-product-brief.md](phases/02-product-brief.md) | Multi-CLI analysis orchestration | Phase start |
|
||||
| [templates/product-brief.md](templates/product-brief.md) | Document template | Document generation |
|
||||
|
||||
### Phase 3: Requirements
|
||||
| Document | Purpose | When to Use |
|
||||
|----------|---------|-------------|
|
||||
| [phases/03-requirements.md](phases/03-requirements.md) | PRD generation workflow | Phase start |
|
||||
| [templates/requirements-prd.md](templates/requirements-prd.md) | Document template | Document generation |
|
||||
|
||||
### Phase 4: Architecture
|
||||
| Document | Purpose | When to Use |
|
||||
|----------|---------|-------------|
|
||||
| [phases/04-architecture.md](phases/04-architecture.md) | Architecture decision workflow | Phase start |
|
||||
| [templates/architecture-doc.md](templates/architecture-doc.md) | Document template | Document generation |
|
||||
|
||||
### Phase 5: Epics & Stories
|
||||
| Document | Purpose | When to Use |
|
||||
|----------|---------|-------------|
|
||||
| [phases/05-epics-stories.md](phases/05-epics-stories.md) | Epic/Story decomposition | Phase start |
|
||||
| [templates/epics-template.md](templates/epics-template.md) | Document template | Document generation |
|
||||
|
||||
### Phase 6: Readiness Check
|
||||
| Document | Purpose | When to Use |
|
||||
|----------|---------|-------------|
|
||||
| [phases/06-readiness-check.md](phases/06-readiness-check.md) | Cross-document validation | Phase start |
|
||||
| [specs/quality-gates.md](specs/quality-gates.md) | Quality scoring criteria | Validation |
|
||||
|
||||
### Debugging & Troubleshooting
|
||||
| Issue | Solution Document |
|
||||
|-------|-------------------|
|
||||
| Phase execution failed | Refer to the relevant Phase documentation |
|
||||
| Output does not meet expectations | [specs/quality-gates.md](specs/quality-gates.md) |
|
||||
| Document format issues | [specs/document-standards.md](specs/document-standards.md) |
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Phase | Error | Blocking? | Action |
|
||||
|-------|-------|-----------|--------|
|
||||
| Phase 1 | Empty input | Yes | Error and exit |
|
||||
| Phase 1 | CLI seed analysis fails | No | Use basic parsing fallback |
|
||||
| Phase 2 | Single CLI perspective fails | No | Continue with available perspectives |
|
||||
| Phase 2 | All CLI calls fail | No | Generate basic brief from seed analysis |
|
||||
| Phase 3 | Gemini CLI fails | No | Use codex fallback |
|
||||
| Phase 4 | Architecture review fails | No | Skip review, proceed with initial analysis |
|
||||
| Phase 5 | Story generation fails | No | Generate epics without detailed stories |
|
||||
| Phase 6 | Validation CLI fails | No | Generate partial report with available data |
|
||||
|
||||
### CLI Fallback Chain
|
||||
|
||||
Gemini -> Codex -> Claude -> degraded mode (local analysis only)
|
||||
433
.claude/skills/spec-generator/phases/06-readiness-check.md
Normal file
433
.claude/skills/spec-generator/phases/06-readiness-check.md
Normal file
@@ -0,0 +1,433 @@
|
||||
# Phase 6: Readiness Check
|
||||
|
||||
Validate the complete specification package, generate quality report and executive summary, provide execution handoff options.
|
||||
|
||||
## Objective
|
||||
|
||||
- Cross-document validation: completeness, consistency, traceability, depth
|
||||
- Generate quality scores per dimension
|
||||
- Produce readiness-report.md with issue list and traceability matrix
|
||||
- Produce spec-summary.md as one-page executive summary
|
||||
- Update all document frontmatter to `status: complete`
|
||||
- Present handoff options to execution workflows
|
||||
|
||||
## Input
|
||||
|
||||
- All Phase 2-5 outputs: `product-brief.md`, `requirements.md`, `architecture.md`, `epics.md`
|
||||
- Config: `{workDir}/spec-config.json`
|
||||
- Reference: `specs/quality-gates.md`
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1: Load All Documents
|
||||
|
||||
```javascript
|
||||
const specConfig = JSON.parse(Read(`${workDir}/spec-config.json`));
|
||||
const productBrief = Read(`${workDir}/product-brief.md`);
|
||||
const requirements = Read(`${workDir}/requirements.md`);
|
||||
const architecture = Read(`${workDir}/architecture.md`);
|
||||
const epics = Read(`${workDir}/epics.md`);
|
||||
const qualityGates = Read('specs/quality-gates.md');
|
||||
```
|
||||
|
||||
### Step 2: Cross-Document Validation via Gemini CLI
|
||||
|
||||
```javascript
|
||||
Bash({
|
||||
command: `ccw cli -p "PURPOSE: Validate specification package for completeness, consistency, traceability, and depth.
|
||||
Success: Comprehensive quality report with scores, issues, and traceability matrix.
|
||||
|
||||
DOCUMENTS TO VALIDATE:
|
||||
|
||||
=== PRODUCT BRIEF ===
|
||||
${productBrief.slice(0, 3000)}
|
||||
|
||||
=== REQUIREMENTS ===
|
||||
${requirements.slice(0, 4000)}
|
||||
|
||||
=== ARCHITECTURE ===
|
||||
${architecture.slice(0, 3000)}
|
||||
|
||||
=== EPICS ===
|
||||
${epics.slice(0, 3000)}
|
||||
|
||||
QUALITY CRITERIA (from quality-gates.md):
|
||||
${qualityGates.slice(0, 2000)}
|
||||
|
||||
TASK:
|
||||
Perform 4-dimension validation:
|
||||
|
||||
1. COMPLETENESS (25%):
|
||||
- All required sections present in each document?
|
||||
- All template fields filled with substantive content?
|
||||
- Score 0-100 with specific gaps listed
|
||||
|
||||
2. CONSISTENCY (25%):
|
||||
- Terminology uniform across documents?
|
||||
- User personas consistent?
|
||||
- Scope consistent (PRD does not exceed brief)?
|
||||
- Tech stack references match between architecture and epics?
|
||||
- Score 0-100 with inconsistencies listed
|
||||
|
||||
3. TRACEABILITY (25%):
|
||||
- Every goal has >= 1 requirement?
|
||||
- Every Must requirement has architecture coverage?
|
||||
- Every Must requirement appears in >= 1 story?
|
||||
- ADR choices reflected in epics?
|
||||
- Build traceability matrix: Goal -> Requirement -> Architecture -> Epic/Story
|
||||
- Score 0-100 with orphan items listed
|
||||
|
||||
4. DEPTH (25%):
|
||||
- Acceptance criteria specific and testable?
|
||||
- Architecture decisions justified with alternatives?
|
||||
- Stories estimable by dev team?
|
||||
- Score 0-100 with vague areas listed
|
||||
|
||||
ALSO:
|
||||
- List all issues found, classified as Error/Warning/Info
|
||||
- Generate overall weighted score
|
||||
- Determine gate: Pass (>=80) / Review (60-79) / Fail (<60)
|
||||
|
||||
MODE: analysis
|
||||
EXPECTED: JSON-compatible output with: dimension scores, overall score, gate, issues list (severity + description + location), traceability matrix
|
||||
CONSTRAINTS: Be thorough but fair. Focus on actionable issues.
|
||||
" --tool gemini --mode analysis`,
|
||||
run_in_background: true
|
||||
});
|
||||
|
||||
// Wait for CLI result
|
||||
```
|
||||
|
||||
### Step 3: Generate readiness-report.md
|
||||
|
||||
```javascript
|
||||
const frontmatterReport = `---
|
||||
session_id: ${specConfig.session_id}
|
||||
phase: 6
|
||||
document_type: readiness-report
|
||||
status: complete
|
||||
generated_at: ${new Date().toISOString()}
|
||||
stepsCompleted: ["load-all", "cross-validation", "scoring", "report-generation"]
|
||||
version: 1
|
||||
dependencies:
|
||||
- product-brief.md
|
||||
- requirements.md
|
||||
- architecture.md
|
||||
- epics.md
|
||||
---`;
|
||||
|
||||
// Report content from CLI validation output:
|
||||
// - Quality Score Summary (4 dimensions + overall)
|
||||
// - Gate Decision (Pass/Review/Fail)
|
||||
// - Issue List (grouped by severity: Error, Warning, Info)
|
||||
// - Traceability Matrix (Goal -> Req -> Arch -> Epic/Story)
|
||||
// - Recommendations for improvement
|
||||
|
||||
Write(`${workDir}/readiness-report.md`, `${frontmatterReport}\n\n${reportContent}`);
|
||||
```
|
||||
|
||||
### Step 4: Generate spec-summary.md
|
||||
|
||||
```javascript
|
||||
const frontmatterSummary = `---
|
||||
session_id: ${specConfig.session_id}
|
||||
phase: 6
|
||||
document_type: spec-summary
|
||||
status: complete
|
||||
generated_at: ${new Date().toISOString()}
|
||||
stepsCompleted: ["synthesis"]
|
||||
version: 1
|
||||
dependencies:
|
||||
- product-brief.md
|
||||
- requirements.md
|
||||
- architecture.md
|
||||
- epics.md
|
||||
- readiness-report.md
|
||||
---`;
|
||||
|
||||
// One-page executive summary:
|
||||
// - Product Name & Vision (from product-brief.md)
|
||||
// - Problem & Target Users (from product-brief.md)
|
||||
// - Key Requirements count (Must/Should/Could from requirements.md)
|
||||
// - Architecture Style & Tech Stack (from architecture.md)
|
||||
// - Epic Overview (count, MVP scope from epics.md)
|
||||
// - Quality Score (from readiness-report.md)
|
||||
// - Recommended Next Step
|
||||
// - File manifest with links
|
||||
|
||||
Write(`${workDir}/spec-summary.md`, `${frontmatterSummary}\n\n${summaryContent}`);
|
||||
```
|
||||
|
||||
### Step 5: Update All Document Status
|
||||
|
||||
```javascript
|
||||
// Update frontmatter status to 'complete' in all documents
|
||||
const docs = ['product-brief.md', 'requirements.md', 'architecture.md', 'epics.md'];
|
||||
for (const doc of docs) {
|
||||
const content = Read(`${workDir}/${doc}`);
|
||||
const updated = content.replace(/status: draft/, 'status: complete');
|
||||
Write(`${workDir}/${doc}`, updated);
|
||||
}
|
||||
|
||||
// Update spec-config.json
|
||||
specConfig.phasesCompleted.push({
|
||||
phase: 6,
|
||||
name: "readiness-check",
|
||||
output_file: "readiness-report.md",
|
||||
completed_at: new Date().toISOString()
|
||||
});
|
||||
Write(`${workDir}/spec-config.json`, JSON.stringify(specConfig, null, 2));
|
||||
```
|
||||
|
||||
### Step 6: Handoff Options
|
||||
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [
|
||||
{
|
||||
question: "Specification package is complete. What would you like to do next?",
|
||||
header: "Next Step",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{
|
||||
label: "Execute via lite-plan",
|
||||
description: "Start implementing with /workflow:lite-plan, one Epic at a time"
|
||||
},
|
||||
{
|
||||
label: "Create roadmap",
|
||||
description: "Generate execution roadmap with /workflow:req-plan-with-file"
|
||||
},
|
||||
{
|
||||
label: "Full planning",
|
||||
description: "Detailed planning with /workflow:plan for the full scope"
|
||||
},
|
||||
{
|
||||
label: "Create Issues",
|
||||
description: "Generate issues for each Epic via /issue:new"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
});
|
||||
|
||||
// Based on user selection, execute the corresponding handoff:
|
||||
|
||||
if (selection === "Execute via lite-plan") {
|
||||
// lite-plan accepts a text description directly
|
||||
const epicsContent = Read(`${workDir}/epics.md`);
|
||||
// Extract first MVP Epic's title + description as task input
|
||||
const firstEpic = extractFirstMvpEpicDescription(epicsContent);
|
||||
Skill(skill="workflow:lite-plan", args=`"${firstEpic}"`)
|
||||
}
|
||||
|
||||
if (selection === "Full planning" || selection === "Create roadmap") {
|
||||
// === Bridge: Build brainstorm_artifacts compatible structure ===
|
||||
// This enables workflow:plan's context-search-agent to discover spec artifacts
|
||||
// via the standard .brainstorming/ directory convention.
|
||||
|
||||
// Step A: Read all spec documents
|
||||
const specSummary = Read(`${workDir}/spec-summary.md`);
|
||||
const productBrief = Read(`${workDir}/product-brief.md`);
|
||||
const requirements = Read(`${workDir}/requirements.md`);
|
||||
const architecture = Read(`${workDir}/architecture.md`);
|
||||
const epics = Read(`${workDir}/epics.md`);
|
||||
|
||||
// Step B: Build structured description from spec-summary
|
||||
const structuredDesc = `GOAL: ${extractGoal(specSummary)}
|
||||
SCOPE: ${extractScope(specSummary)}
|
||||
CONTEXT: Generated from spec session ${specConfig.session_id}. Source: ${workDir}/`;
|
||||
|
||||
// Step C: Create WFS session (provides session directory + .brainstorming/)
|
||||
Skill(skill="workflow:session:start", args=`--auto "${structuredDesc}"`)
|
||||
// → Produces sessionId (WFS-xxx) and session directory at .workflow/active/{sessionId}/
|
||||
|
||||
// Step D: Create .brainstorming/ bridge files
|
||||
const brainstormDir = `.workflow/active/${sessionId}/.brainstorming`;
|
||||
Bash(`mkdir -p "${brainstormDir}/feature-specs"`);
|
||||
|
||||
// D.1: guidance-specification.md (highest priority - action-planning-agent reads first)
|
||||
// Synthesized from spec-summary + product-brief key decisions + architecture decisions
|
||||
Write(`${brainstormDir}/guidance-specification.md`, `
|
||||
# ${specConfig.seed_analysis.problem_statement} - Confirmed Guidance Specification
|
||||
|
||||
**Source**: spec-generator session ${specConfig.session_id}
|
||||
**Generated**: ${new Date().toISOString()}
|
||||
**Spec Directory**: ${workDir}
|
||||
|
||||
## 1. Project Positioning & Goals
|
||||
${extractSection(productBrief, "Vision")}
|
||||
${extractSection(productBrief, "Goals")}
|
||||
|
||||
## 2. Requirements Summary
|
||||
${extractSection(requirements, "Requirement Summary")}
|
||||
|
||||
## 3. Architecture Decisions
|
||||
${extractSection(architecture, "Architecture Decision Records")}
|
||||
${extractSection(architecture, "Technology Stack")}
|
||||
|
||||
## 4. Implementation Scope
|
||||
${extractSection(epics, "Epic Overview")}
|
||||
${extractSection(epics, "MVP Scope")}
|
||||
|
||||
## Feature Decomposition
|
||||
${extractFeatureTable(epics)}
|
||||
|
||||
## Appendix: Source Documents
|
||||
| Document | Path | Description |
|
||||
|----------|------|-------------|
|
||||
| Product Brief | ${workDir}/product-brief.md | Vision, goals, scope |
|
||||
| Requirements | ${workDir}/requirements.md | Functional + non-functional requirements |
|
||||
| Architecture | ${workDir}/architecture.md | ADRs, tech stack, components |
|
||||
| Epics | ${workDir}/epics.md | Epic/Story breakdown |
|
||||
| Readiness Report | ${workDir}/readiness-report.md | Quality validation |
|
||||
`);
|
||||
|
||||
// D.2: feature-index.json (each Epic mapped to a Feature)
|
||||
// Path: feature-specs/feature-index.json (matches context-search-agent discovery at line 344)
|
||||
const epicsList = parseEpics(epics); // Extract: id, slug, name, description, mvp, stories[]
|
||||
const featureIndex = {
|
||||
version: "1.0",
|
||||
source: "spec-generator",
|
||||
spec_session: specConfig.session_id,
|
||||
features: epicsList.map(epic => ({
|
||||
id: `F-${epic.id.replace('EPIC-', '')}`,
|
||||
slug: epic.slug,
|
||||
name: epic.name,
|
||||
description: epic.description,
|
||||
priority: epic.mvp ? "High" : "Medium",
|
||||
spec_path: `${brainstormDir}/feature-specs/F-${epic.id.replace('EPIC-','')}-${epic.slug}.md`,
|
||||
source_epic: epic.id,
|
||||
stories: epic.stories
|
||||
})),
|
||||
cross_cutting_specs: []
|
||||
};
|
||||
Write(`${brainstormDir}/feature-specs/feature-index.json`, JSON.stringify(featureIndex, null, 2));
|
||||
|
||||
// D.3: Individual feature-spec files (one per Epic)
|
||||
// Filename pattern: F-{num}-{slug}.md (matches context-search-agent glob F-*-*.md)
|
||||
epicsList.forEach(epic => {
|
||||
const epicDetail = extractEpicDetail(epics, epic.id);
|
||||
const relatedReqs = extractRelatedRequirements(requirements, epic.id);
|
||||
Write(`${brainstormDir}/feature-specs/F-${epic.id.replace('EPIC-','')}-${epic.slug}.md`, `
|
||||
# Feature Spec: ${epic.id} - ${epic.name}
|
||||
|
||||
**Source**: ${workDir}/epics.md
|
||||
**Priority**: ${epic.mvp ? "MVP" : "Post-MVP"}
|
||||
**Related Requirements**: ${relatedReqs.join(', ')}
|
||||
|
||||
## Scope
|
||||
${epicDetail.scope}
|
||||
|
||||
## Stories
|
||||
${epicDetail.stories.map(s => `- ${s.id}: ${s.title} (${s.estimate})`).join('\n')}
|
||||
|
||||
## Acceptance Criteria
|
||||
${epicDetail.acceptanceCriteria}
|
||||
|
||||
## Architecture Notes
|
||||
${extractArchitectureNotes(architecture, epic.id)}
|
||||
`);
|
||||
});
|
||||
|
||||
// Step E: Invoke downstream workflow
|
||||
// context-search-agent will auto-discover .brainstorming/ files
|
||||
// → context-package.json.brainstorm_artifacts populated
|
||||
// → action-planning-agent loads guidance_specification (priority 1) + feature_index (priority 2)
|
||||
if (selection === "Full planning") {
|
||||
Skill(skill="workflow:plan", args=`"${structuredDesc}"`)
|
||||
} else {
|
||||
Skill(skill="workflow:req-plan-with-file", args=`"${extractGoal(specSummary)}"`)
|
||||
}
|
||||
}
|
||||
|
||||
if (selection === "Create Issues") {
|
||||
// For each Epic, create an issue
|
||||
const epics = Read(`${workDir}/epics.md`);
|
||||
const epicsList = parseEpics(epics);
|
||||
epicsList.forEach(epic => {
|
||||
Skill(skill="issue:new", args=`"${epic.name}: ${epic.description}"`)
|
||||
});
|
||||
}
|
||||
|
||||
// If user selects "Other": Export only or return to specific phase
|
||||
```
|
||||
|
||||
#### Helper Functions Reference (pseudocode)
|
||||
|
||||
The following helper functions are used in the handoff bridge. They operate on the markdown content loaded from spec documents:
|
||||
|
||||
```javascript
|
||||
// Extract the first MVP Epic's title + scope as a one-line task description
|
||||
function extractFirstMvpEpicDescription(epicsContent) {
|
||||
// Find first Epic marked as MVP, return: "Epic Name - Brief scope description"
|
||||
}
|
||||
|
||||
// Extract GOAL/SCOPE from spec-summary frontmatter or ## sections
|
||||
function extractGoal(specSummary) { /* Return the Vision/Goal line */ }
|
||||
function extractScope(specSummary) { /* Return the Scope/MVP boundary */ }
|
||||
|
||||
// Extract a named ## section from a markdown document
|
||||
function extractSection(markdown, sectionName) {
|
||||
// Return content between ## {sectionName} and next ## heading
|
||||
}
|
||||
|
||||
// Build a markdown table of Epics from epics.md
|
||||
function extractFeatureTable(epicsContent) {
|
||||
// Return: | Epic ID | Name | Priority | Story Count |
|
||||
}
|
||||
|
||||
// Parse epics.md into structured Epic objects
|
||||
function parseEpics(epicsContent) {
|
||||
// Returns: [{ id, slug, name, description, mvp, stories[] }]
|
||||
}
|
||||
|
||||
// Extract detailed Epic section (scope, stories, acceptance criteria)
|
||||
function extractEpicDetail(epicsContent, epicId) {
|
||||
// Returns: { scope, stories[], acceptanceCriteria }
|
||||
}
|
||||
|
||||
// Find requirements related to a specific Epic
|
||||
function extractRelatedRequirements(requirementsContent, epicId) {
|
||||
// Returns: ["REQ-001", "REQ-003"] based on traceability references
|
||||
}
|
||||
|
||||
// Extract architecture notes relevant to a specific Epic
|
||||
function extractArchitectureNotes(architectureContent, epicId) {
|
||||
// Returns: relevant ADRs, component references, tech stack notes
|
||||
}
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
- **File**: `readiness-report.md` - Quality validation report
|
||||
- **File**: `spec-summary.md` - One-page executive summary
|
||||
- **Format**: Markdown with YAML frontmatter
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
- [ ] All 4 documents validated (product-brief, requirements, architecture, epics)
|
||||
- [ ] All frontmatter parseable and valid
|
||||
- [ ] Cross-references checked
|
||||
- [ ] Overall quality score calculated
|
||||
- [ ] No unresolved Error-severity issues
|
||||
- [ ] Traceability matrix generated
|
||||
- [ ] spec-summary.md created
|
||||
- [ ] All document statuses updated to 'complete'
|
||||
- [ ] Handoff options presented
|
||||
|
||||
## Completion
|
||||
|
||||
This is the final phase. The specification package is ready for execution handoff.
|
||||
|
||||
### Output Files Manifest
|
||||
|
||||
| File | Phase | Description |
|
||||
|------|-------|-------------|
|
||||
| `spec-config.json` | 1 | Session configuration and state |
|
||||
| `discovery-context.json` | 1 | Codebase exploration (optional) |
|
||||
| `product-brief.md` | 2 | Product brief with multi-perspective synthesis |
|
||||
| `requirements.md` | 3 | Detailed PRD with MoSCoW priorities |
|
||||
| `architecture.md` | 4 | Architecture decisions and component design |
|
||||
| `epics.md` | 5 | Epic/Story breakdown with dependencies |
|
||||
| `readiness-report.md` | 6 | Quality validation report |
|
||||
| `spec-summary.md` | 6 | One-page executive summary |
|
||||
Reference in New Issue
Block a user