mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-01 15:03:57 +08:00
feat: add templates for architecture documents, epics, product briefs, and requirements PRD
- Introduced architecture document template for Phase 4, including structure and individual ADR records. - Added epics & stories template for Phase 5, detailing epic breakdown and dependencies. - Created product brief template for Phase 2, summarizing product vision, problem statement, and target users. - Developed requirements PRD template for Phase 3, outlining functional and non-functional requirements with traceability. - Implemented spec command for project spec management with subcommands for loading, listing, rebuilding, and initializing specs.
This commit is contained in:
catlog22
@@ -0,0 +1,698 @@
|
||||
# Command: Generate Document
|
||||
|
||||
Multi-CLI document generation for 4 document types: Product Brief, Requirements/PRD, Architecture, Epics & Stories.
|
||||
|
||||
## Pre-Steps (All Document Types)
|
||||
|
||||
```javascript
|
||||
// 1. Load document standards
|
||||
const docStandards = Read('../../specs/document-standards.md')
|
||||
|
||||
// 2. Load appropriate template
|
||||
const templateMap = {
|
||||
'product-brief': '../../templates/product-brief.md',
|
||||
'requirements': '../../templates/requirements-prd.md',
|
||||
'architecture': '../../templates/architecture-doc.md',
|
||||
'epics': '../../templates/epics-template.md'
|
||||
}
|
||||
const template = Read(templateMap[docType])
|
||||
|
||||
// 3. Build shared context
|
||||
const seedAnalysis = specConfig?.seed_analysis ||
|
||||
(priorDocs.discoveryContext ? JSON.parse(priorDocs.discoveryContext).seed_analysis : {})
|
||||
|
||||
const sharedContext = `
|
||||
SEED: ${specConfig?.topic || ''}
|
||||
PROBLEM: ${seedAnalysis.problem_statement || ''}
|
||||
TARGET USERS: ${(seedAnalysis.target_users || []).join(', ')}
|
||||
DOMAIN: ${seedAnalysis.domain || ''}
|
||||
CONSTRAINTS: ${(seedAnalysis.constraints || []).join(', ')}
|
||||
FOCUS AREAS: ${(specConfig?.focus_areas || []).join(', ')}
|
||||
${priorDocs.discoveryContext ? `
|
||||
CODEBASE CONTEXT:
|
||||
- Existing patterns: ${JSON.parse(priorDocs.discoveryContext).existing_patterns?.slice(0,5).join(', ') || 'none'}
|
||||
- Tech stack: ${JSON.stringify(JSON.parse(priorDocs.discoveryContext).tech_stack || {})}
|
||||
` : ''}`
|
||||
|
||||
// 4. Route to specific document type
|
||||
```
|
||||
|
||||
## DRAFT-001: Product Brief
|
||||
|
||||
3-way parallel CLI analysis (product/technical/user perspectives), then synthesize.
|
||||
|
||||
```javascript
|
||||
if (docType === 'product-brief') {
|
||||
// === Parallel CLI Analysis ===
|
||||
|
||||
// Product Perspective (Gemini)
|
||||
Bash({
|
||||
command: `ccw cli -p "PURPOSE: Product analysis for specification - identify market fit, user value, and success criteria.
|
||||
Success: Clear vision, measurable goals, competitive positioning.
|
||||
|
||||
${sharedContext}
|
||||
|
||||
TASK:
|
||||
- Define product vision (1-3 sentences, aspirational)
|
||||
- Analyze market/competitive landscape
|
||||
- Define 3-5 measurable success metrics
|
||||
- Identify scope boundaries (in-scope vs out-of-scope)
|
||||
- Assess user value proposition
|
||||
- List assumptions that need validation
|
||||
|
||||
MODE: analysis
|
||||
EXPECTED: Structured product analysis with: vision, goals with metrics, scope, competitive positioning, assumptions
|
||||
CONSTRAINTS: Focus on 'what' and 'why', not 'how'
|
||||
" --tool gemini --mode analysis`,
|
||||
run_in_background: true
|
||||
})
|
||||
|
||||
// Technical Perspective (Codex)
|
||||
Bash({
|
||||
command: `ccw cli -p "PURPOSE: Technical feasibility analysis for specification - assess implementation viability and constraints.
|
||||
Success: Clear technical constraints, integration complexity, technology recommendations.
|
||||
|
||||
${sharedContext}
|
||||
|
||||
TASK:
|
||||
- Assess technical feasibility of the core concept
|
||||
- Identify technical constraints and blockers
|
||||
- Evaluate integration complexity with existing systems
|
||||
- Recommend technology approach (high-level)
|
||||
- Identify technical risks and dependencies
|
||||
- Estimate complexity: simple/moderate/complex
|
||||
|
||||
MODE: analysis
|
||||
EXPECTED: Technical analysis with: feasibility assessment, constraints, integration complexity, tech recommendations, risks
|
||||
CONSTRAINTS: Focus on feasibility and constraints, not detailed architecture
|
||||
" --tool codex --mode analysis`,
|
||||
run_in_background: true
|
||||
})
|
||||
|
||||
// User Perspective (Claude)
|
||||
Bash({
|
||||
command: `ccw cli -p "PURPOSE: User experience analysis for specification - understand user journeys, pain points, and UX considerations.
|
||||
Success: Clear user personas, journey maps, UX requirements.
|
||||
|
||||
${sharedContext}
|
||||
|
||||
TASK:
|
||||
- Elaborate user personas with goals and frustrations
|
||||
- Map primary user journey (happy path)
|
||||
- Identify key pain points in current experience
|
||||
- Define UX success criteria
|
||||
- List accessibility and usability considerations
|
||||
- Suggest interaction patterns
|
||||
|
||||
MODE: analysis
|
||||
EXPECTED: User analysis with: personas, journey map, pain points, UX criteria, interaction recommendations
|
||||
CONSTRAINTS: Focus on user needs and experience, not implementation
|
||||
" --tool claude --mode analysis`,
|
||||
run_in_background: true
|
||||
})
|
||||
|
||||
// STOP: Wait for all 3 CLI results
|
||||
|
||||
// === Synthesize Three Perspectives ===
|
||||
const synthesis = {
|
||||
convergent_themes: [], // Themes consistent across all three perspectives
|
||||
conflicts: [], // Conflicting viewpoints
|
||||
product_insights: [], // Unique product perspective insights
|
||||
technical_insights: [], // Unique technical perspective insights
|
||||
user_insights: [] // Unique user perspective insights
|
||||
}
|
||||
|
||||
// Parse CLI outputs and identify:
|
||||
// - Common themes mentioned by 2+ perspectives
|
||||
// - Conflicts (e.g., product wants feature X, technical says infeasible)
|
||||
// - Unique insights from each perspective
|
||||
|
||||
// === Integrate Discussion Feedback ===
|
||||
if (discussionFeedback) {
|
||||
// Extract consensus and adjustments from discuss-001-scope.md
|
||||
// Merge discussion conclusions into synthesis
|
||||
}
|
||||
|
||||
// === Generate Document from Template ===
|
||||
const frontmatter = `---
|
||||
session_id: ${specConfig?.session_id || 'unknown'}
|
||||
phase: 2
|
||||
document_type: product-brief
|
||||
status: draft
|
||||
generated_at: ${new Date().toISOString()}
|
||||
version: 1
|
||||
dependencies:
|
||||
- spec-config.json
|
||||
- discovery-context.json
|
||||
---`
|
||||
|
||||
// Fill template sections:
|
||||
// - Vision (from product perspective + synthesis)
|
||||
// - Problem Statement (from seed analysis + user perspective)
|
||||
// - Target Users (from user perspective + personas)
|
||||
// - Goals (from product perspective + metrics)
|
||||
// - Scope (from product perspective + technical constraints)
|
||||
// - Success Criteria (from all three perspectives)
|
||||
// - Assumptions (from product + technical perspectives)
|
||||
|
||||
const filledContent = fillTemplate(template, {
|
||||
vision: productPerspective.vision,
|
||||
problem: seedAnalysis.problem_statement,
|
||||
users: userPerspective.personas,
|
||||
goals: productPerspective.goals,
|
||||
scope: synthesis.scope_boundaries,
|
||||
success_criteria: synthesis.convergent_themes,
|
||||
assumptions: [...productPerspective.assumptions, ...technicalPerspective.assumptions]
|
||||
})
|
||||
|
||||
Write(`${sessionFolder}/spec/product-brief.md`, `${frontmatter}\n\n${filledContent}`)
|
||||
|
||||
return {
|
||||
outputPath: 'spec/product-brief.md',
|
||||
documentSummary: `Product Brief generated with ${synthesis.convergent_themes.length} convergent themes, ${synthesis.conflicts.length} conflicts resolved`
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## DRAFT-002: Requirements/PRD
|
||||
|
||||
Gemini CLI expansion to generate REQ-NNN and NFR-{type}-NNN files.
|
||||
|
||||
```javascript
|
||||
if (docType === 'requirements') {
|
||||
// === Requirements Expansion CLI ===
|
||||
Bash({
|
||||
command: `ccw cli -p "PURPOSE: Generate detailed functional and non-functional requirements from product brief.
|
||||
Success: Complete PRD with testable acceptance criteria for every requirement.
|
||||
|
||||
PRODUCT BRIEF CONTEXT:
|
||||
${priorDocs.productBrief?.slice(0, 3000) || ''}
|
||||
|
||||
${sharedContext}
|
||||
|
||||
TASK:
|
||||
- For each goal in the product brief, generate 3-7 functional requirements
|
||||
- Each requirement must have:
|
||||
- Unique ID: REQ-NNN (zero-padded)
|
||||
- Clear title
|
||||
- Detailed description
|
||||
- User story: As a [persona], I want [action] so that [benefit]
|
||||
- 2-4 specific, testable acceptance criteria
|
||||
- Generate non-functional requirements:
|
||||
- Performance (response times, throughput)
|
||||
- Security (authentication, authorization, data protection)
|
||||
- Scalability (user load, data volume)
|
||||
- Usability (accessibility, learnability)
|
||||
- Assign MoSCoW priority: Must/Should/Could/Won't
|
||||
- Output structure per requirement: ID, title, description, user_story, acceptance_criteria[], priority, traces
|
||||
|
||||
MODE: analysis
|
||||
EXPECTED: Structured requirements with: ID, title, description, user story, acceptance criteria, priority, traceability to goals
|
||||
CONSTRAINTS: Every requirement must be specific enough to estimate and test. No vague requirements.
|
||||
" --tool gemini --mode analysis`,
|
||||
run_in_background: true
|
||||
})
|
||||
|
||||
// Wait for CLI result
|
||||
|
||||
// === Integrate Discussion Feedback ===
|
||||
if (discussionFeedback) {
|
||||
// Extract requirement adjustments from discuss-002-brief.md
|
||||
// Merge new/modified/deleted requirements
|
||||
}
|
||||
|
||||
// === Generate requirements/ Directory ===
|
||||
Bash(`mkdir -p "${sessionFolder}/spec/requirements"`)
|
||||
|
||||
const timestamp = new Date().toISOString()
|
||||
|
||||
// Parse CLI output → funcReqs[], nfReqs[]
|
||||
const funcReqs = parseFunctionalRequirements(cliOutput)
|
||||
const nfReqs = parseNonFunctionalRequirements(cliOutput)
|
||||
|
||||
// Write individual REQ-*.md files (one per functional requirement)
|
||||
funcReqs.forEach(req => {
|
||||
const reqFrontmatter = `---
|
||||
id: REQ-${req.id}
|
||||
title: "${req.title}"
|
||||
priority: ${req.priority}
|
||||
status: draft
|
||||
traces:
|
||||
- product-brief.md
|
||||
---`
|
||||
const reqContent = `${reqFrontmatter}
|
||||
|
||||
# REQ-${req.id}: ${req.title}
|
||||
|
||||
## Description
|
||||
${req.description}
|
||||
|
||||
## User Story
|
||||
${req.user_story}
|
||||
|
||||
## Acceptance Criteria
|
||||
${req.acceptance_criteria.map((ac, i) => `${i+1}. ${ac}`).join('\n')}
|
||||
`
|
||||
Write(`${sessionFolder}/spec/requirements/REQ-${req.id}-${req.slug}.md`, reqContent)
|
||||
})
|
||||
|
||||
// Write individual NFR-*.md files
|
||||
nfReqs.forEach(nfr => {
|
||||
const nfrFrontmatter = `---
|
||||
id: NFR-${nfr.type}-${nfr.id}
|
||||
type: ${nfr.type}
|
||||
title: "${nfr.title}"
|
||||
status: draft
|
||||
traces:
|
||||
- product-brief.md
|
||||
---`
|
||||
const nfrContent = `${nfrFrontmatter}
|
||||
|
||||
# NFR-${nfr.type}-${nfr.id}: ${nfr.title}
|
||||
|
||||
## Requirement
|
||||
${nfr.requirement}
|
||||
|
||||
## Metric & Target
|
||||
${nfr.metric} — Target: ${nfr.target}
|
||||
`
|
||||
Write(`${sessionFolder}/spec/requirements/NFR-${nfr.type}-${nfr.id}-${nfr.slug}.md`, nfrContent)
|
||||
})
|
||||
|
||||
// Write _index.md (summary + links)
|
||||
const indexFrontmatter = `---
|
||||
session_id: ${specConfig?.session_id || 'unknown'}
|
||||
phase: 3
|
||||
document_type: requirements-index
|
||||
status: draft
|
||||
generated_at: ${timestamp}
|
||||
version: 1
|
||||
dependencies:
|
||||
- product-brief.md
|
||||
---`
|
||||
const indexContent = `${indexFrontmatter}
|
||||
|
||||
# Requirements (PRD)
|
||||
|
||||
## Summary
|
||||
Total: ${funcReqs.length} functional + ${nfReqs.length} non-functional requirements
|
||||
|
||||
## Functional Requirements
|
||||
| ID | Title | Priority | Status |
|
||||
|----|-------|----------|--------|
|
||||
${funcReqs.map(r => `| [REQ-${r.id}](REQ-${r.id}-${r.slug}.md) | ${r.title} | ${r.priority} | draft |`).join('\n')}
|
||||
|
||||
## Non-Functional Requirements
|
||||
| ID | Type | Title |
|
||||
|----|------|-------|
|
||||
${nfReqs.map(n => `| [NFR-${n.type}-${n.id}](NFR-${n.type}-${n.id}-${n.slug}.md) | ${n.type} | ${n.title} |`).join('\n')}
|
||||
|
||||
## MoSCoW Summary
|
||||
- **Must**: ${funcReqs.filter(r => r.priority === 'Must').length}
|
||||
- **Should**: ${funcReqs.filter(r => r.priority === 'Should').length}
|
||||
- **Could**: ${funcReqs.filter(r => r.priority === 'Could').length}
|
||||
- **Won't**: ${funcReqs.filter(r => r.priority === "Won't").length}
|
||||
`
|
||||
Write(`${sessionFolder}/spec/requirements/_index.md`, indexContent)
|
||||
|
||||
return {
|
||||
outputPath: 'spec/requirements/_index.md',
|
||||
documentSummary: `Requirements generated: ${funcReqs.length} functional, ${nfReqs.length} non-functional`
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## DRAFT-003: Architecture
|
||||
|
||||
Two-stage CLI: Gemini architecture design + Codex architecture review.
|
||||
|
||||
```javascript
|
||||
if (docType === 'architecture') {
|
||||
// === Stage 1: Architecture Design (Gemini) ===
|
||||
Bash({
|
||||
command: `ccw cli -p "PURPOSE: Generate technical architecture for the specified requirements.
|
||||
Success: Complete component architecture, tech stack, and ADRs with justified decisions.
|
||||
|
||||
PRODUCT BRIEF (summary):
|
||||
${priorDocs.productBrief?.slice(0, 3000) || ''}
|
||||
|
||||
REQUIREMENTS:
|
||||
${priorDocs.requirementsIndex?.slice(0, 5000) || ''}
|
||||
|
||||
${sharedContext}
|
||||
|
||||
TASK:
|
||||
- Define system architecture style (monolith, microservices, serverless, etc.) with justification
|
||||
- Identify core components and their responsibilities
|
||||
- Create component interaction diagram (Mermaid graph TD format)
|
||||
- Specify technology stack: languages, frameworks, databases, infrastructure
|
||||
- Generate 2-4 Architecture Decision Records (ADRs):
|
||||
- Each ADR: context, decision, 2-3 alternatives with pros/cons, consequences
|
||||
- Focus on: data storage, API design, authentication, key technical choices
|
||||
- Define data model: key entities and relationships (Mermaid erDiagram format)
|
||||
- Identify security architecture: auth, authorization, data protection
|
||||
- List API endpoints (high-level)
|
||||
|
||||
MODE: analysis
|
||||
EXPECTED: Complete architecture with: style justification, component diagram, tech stack table, ADRs, data model, security controls, API overview
|
||||
CONSTRAINTS: Architecture must support all Must-have requirements. Prefer proven technologies.
|
||||
" --tool gemini --mode analysis`,
|
||||
run_in_background: true
|
||||
})
|
||||
|
||||
// Wait for Gemini result
|
||||
|
||||
// === Stage 2: Architecture Review (Codex) ===
|
||||
Bash({
|
||||
command: `ccw cli -p "PURPOSE: Critical review of proposed architecture - identify weaknesses and risks.
|
||||
Success: Actionable feedback with specific concerns and improvement suggestions.
|
||||
|
||||
PROPOSED ARCHITECTURE:
|
||||
${geminiArchitectureOutput.slice(0, 5000)}
|
||||
|
||||
REQUIREMENTS CONTEXT:
|
||||
${priorDocs.requirementsIndex?.slice(0, 2000) || ''}
|
||||
|
||||
TASK:
|
||||
- Challenge each ADR: are the alternatives truly the best options?
|
||||
- Identify scalability bottlenecks in the component design
|
||||
- Assess security gaps: authentication, authorization, data protection
|
||||
- Evaluate technology choices: maturity, community support, fit
|
||||
- Check for over-engineering or under-engineering
|
||||
- Verify architecture covers all Must-have requirements
|
||||
- Rate overall architecture quality: 1-5 with justification
|
||||
|
||||
MODE: analysis
|
||||
EXPECTED: Architecture review with: per-ADR feedback, scalability concerns, security gaps, technology risks, quality rating
|
||||
CONSTRAINTS: Be genuinely critical, not just validating. Focus on actionable improvements.
|
||||
" --tool codex --mode analysis`,
|
||||
run_in_background: true
|
||||
})
|
||||
|
||||
// Wait for Codex result
|
||||
|
||||
// === Integrate Discussion Feedback ===
|
||||
if (discussionFeedback) {
|
||||
// Extract architecture feedback from discuss-003-requirements.md
|
||||
// Merge into architecture design
|
||||
}
|
||||
|
||||
// === Codebase Integration Mapping (conditional) ===
|
||||
let integrationMapping = null
|
||||
if (priorDocs.discoveryContext) {
|
||||
const dc = JSON.parse(priorDocs.discoveryContext)
|
||||
if (dc.relevant_files) {
|
||||
integrationMapping = dc.relevant_files.map(f => ({
|
||||
new_component: '...',
|
||||
existing_module: f.path,
|
||||
integration_type: 'Extend|Replace|New',
|
||||
notes: f.rationale
|
||||
}))
|
||||
}
|
||||
}
|
||||
|
||||
// === Generate architecture/ Directory ===
|
||||
Bash(`mkdir -p "${sessionFolder}/spec/architecture"`)
|
||||
|
||||
const timestamp = new Date().toISOString()
|
||||
const adrs = parseADRs(geminiArchitectureOutput, codexReviewOutput)
|
||||
|
||||
// Write individual ADR-*.md files
|
||||
adrs.forEach(adr => {
|
||||
const adrFrontmatter = `---
|
||||
id: ADR-${adr.id}
|
||||
title: "${adr.title}"
|
||||
status: draft
|
||||
traces:
|
||||
- ../requirements/_index.md
|
||||
---`
|
||||
const adrContent = `${adrFrontmatter}
|
||||
|
||||
# ADR-${adr.id}: ${adr.title}
|
||||
|
||||
## Context
|
||||
${adr.context}
|
||||
|
||||
## Decision
|
||||
${adr.decision}
|
||||
|
||||
## Alternatives
|
||||
${adr.alternatives.map((alt, i) => `### Option ${i+1}: ${alt.name}\n- **Pros**: ${alt.pros.join(', ')}\n- **Cons**: ${alt.cons.join(', ')}`).join('\n\n')}
|
||||
|
||||
## Consequences
|
||||
${adr.consequences}
|
||||
|
||||
## Review Feedback
|
||||
${adr.reviewFeedback || 'N/A'}
|
||||
`
|
||||
Write(`${sessionFolder}/spec/architecture/ADR-${adr.id}-${adr.slug}.md`, adrContent)
|
||||
})
|
||||
|
||||
// Write _index.md (with Mermaid component diagram + ER diagram + links)
|
||||
const archIndexFrontmatter = `---
|
||||
session_id: ${specConfig?.session_id || 'unknown'}
|
||||
phase: 4
|
||||
document_type: architecture-index
|
||||
status: draft
|
||||
generated_at: ${timestamp}
|
||||
version: 1
|
||||
dependencies:
|
||||
- ../product-brief.md
|
||||
- ../requirements/_index.md
|
||||
---`
|
||||
|
||||
const archIndexContent = `${archIndexFrontmatter}
|
||||
|
||||
# Architecture Document
|
||||
|
||||
## System Overview
|
||||
${geminiArchitectureOutput.system_overview}
|
||||
|
||||
## Component Diagram
|
||||
\`\`\`mermaid
|
||||
${geminiArchitectureOutput.component_diagram}
|
||||
\`\`\`
|
||||
|
||||
## Technology Stack
|
||||
${geminiArchitectureOutput.tech_stack_table}
|
||||
|
||||
## Architecture Decision Records
|
||||
| ID | Title | Status |
|
||||
|----|-------|--------|
|
||||
${adrs.map(a => `| [ADR-${a.id}](ADR-${a.id}-${a.slug}.md) | ${a.title} | draft |`).join('\n')}
|
||||
|
||||
## Data Model
|
||||
\`\`\`mermaid
|
||||
${geminiArchitectureOutput.data_model_diagram}
|
||||
\`\`\`
|
||||
|
||||
## API Design
|
||||
${geminiArchitectureOutput.api_overview}
|
||||
|
||||
## Security Controls
|
||||
${geminiArchitectureOutput.security_controls}
|
||||
|
||||
## Review Summary
|
||||
${codexReviewOutput.summary}
|
||||
Quality Rating: ${codexReviewOutput.quality_rating}/5
|
||||
`
|
||||
|
||||
Write(`${sessionFolder}/spec/architecture/_index.md`, archIndexContent)
|
||||
|
||||
return {
|
||||
outputPath: 'spec/architecture/_index.md',
|
||||
documentSummary: `Architecture generated with ${adrs.length} ADRs, quality rating ${codexReviewOutput.quality_rating}/5`
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## DRAFT-004: Epics & Stories
|
||||
|
||||
Gemini CLI decomposition to generate EPIC-*.md files.
|
||||
|
||||
```javascript
|
||||
if (docType === 'epics') {
|
||||
// === Epic Decomposition CLI ===
|
||||
Bash({
|
||||
command: `ccw cli -p "PURPOSE: Decompose requirements into executable Epics and Stories for implementation planning.
|
||||
Success: 3-7 Epics with prioritized Stories, dependency map, and MVP subset clearly defined.
|
||||
|
||||
PRODUCT BRIEF (summary):
|
||||
${priorDocs.productBrief?.slice(0, 2000) || ''}
|
||||
|
||||
REQUIREMENTS:
|
||||
${priorDocs.requirementsIndex?.slice(0, 5000) || ''}
|
||||
|
||||
ARCHITECTURE (summary):
|
||||
${priorDocs.architectureIndex?.slice(0, 3000) || ''}
|
||||
|
||||
TASK:
|
||||
- Group requirements into 3-7 logical Epics:
|
||||
- Each Epic: EPIC-NNN ID, title, description, priority (Must/Should/Could)
|
||||
- Group by functional domain or user journey stage
|
||||
- Tag MVP Epics (minimum set for initial release)
|
||||
- For each Epic, generate 2-5 Stories:
|
||||
- Each Story: STORY-{EPIC}-NNN ID, title
|
||||
- User story format: As a [persona], I want [action] so that [benefit]
|
||||
- 2-4 acceptance criteria per story (testable)
|
||||
- Relative size estimate: S/M/L/XL
|
||||
- Trace to source requirement(s): REQ-NNN
|
||||
- Create dependency map:
|
||||
- Cross-Epic dependencies (which Epics block others)
|
||||
- Mermaid graph LR format
|
||||
- Recommended execution order with rationale
|
||||
- Define MVP:
|
||||
- Which Epics are in MVP
|
||||
- MVP definition of done (3-5 criteria)
|
||||
- What is explicitly deferred post-MVP
|
||||
|
||||
MODE: analysis
|
||||
EXPECTED: Structured output with: Epic list (ID, title, priority, MVP flag), Stories per Epic (ID, user story, AC, size, trace), dependency Mermaid diagram, execution order, MVP definition
|
||||
CONSTRAINTS: Every Must-have requirement must appear in at least one Story. Stories must be small enough to implement independently. Dependencies should be minimized across Epics.
|
||||
" --tool gemini --mode analysis`,
|
||||
run_in_background: true
|
||||
})
|
||||
|
||||
// Wait for CLI result
|
||||
|
||||
// === Integrate Discussion Feedback ===
|
||||
if (discussionFeedback) {
|
||||
// Extract execution feedback from discuss-004-architecture.md
|
||||
// Adjust Epic granularity, MVP scope
|
||||
}
|
||||
|
||||
// === Generate epics/ Directory ===
|
||||
Bash(`mkdir -p "${sessionFolder}/spec/epics"`)
|
||||
|
||||
const timestamp = new Date().toISOString()
|
||||
const epicsList = parseEpics(cliOutput)
|
||||
|
||||
// Write individual EPIC-*.md files (with stories)
|
||||
epicsList.forEach(epic => {
|
||||
const epicFrontmatter = `---
|
||||
id: EPIC-${epic.id}
|
||||
title: "${epic.title}"
|
||||
priority: ${epic.priority}
|
||||
mvp: ${epic.mvp}
|
||||
size: ${epic.size}
|
||||
requirements:
|
||||
${epic.reqs.map(r => ` - ${r}`).join('\n')}
|
||||
architecture:
|
||||
${epic.adrs.map(a => ` - ${a}`).join('\n')}
|
||||
dependencies:
|
||||
${epic.deps.map(d => ` - ${d}`).join('\n')}
|
||||
status: draft
|
||||
---`
|
||||
const storiesContent = epic.stories.map(s => `### ${s.id}: ${s.title}
|
||||
|
||||
**User Story**: ${s.user_story}
|
||||
**Size**: ${s.size}
|
||||
**Traces**: ${s.traces.join(', ')}
|
||||
|
||||
**Acceptance Criteria**:
|
||||
${s.acceptance_criteria.map((ac, i) => `${i+1}. ${ac}`).join('\n')}
|
||||
`).join('\n')
|
||||
|
||||
const epicContent = `${epicFrontmatter}
|
||||
|
||||
# EPIC-${epic.id}: ${epic.title}
|
||||
|
||||
## Description
|
||||
${epic.description}
|
||||
|
||||
## Stories
|
||||
${storiesContent}
|
||||
|
||||
## Requirements
|
||||
${epic.reqs.map(r => `- [${r}](../requirements/${r}.md)`).join('\n')}
|
||||
|
||||
## Architecture
|
||||
${epic.adrs.map(a => `- [${a}](../architecture/${a}.md)`).join('\n')}
|
||||
`
|
||||
Write(`${sessionFolder}/spec/epics/EPIC-${epic.id}-${epic.slug}.md`, epicContent)
|
||||
})
|
||||
|
||||
// Write _index.md (with Mermaid dependency diagram + MVP + links)
|
||||
const epicsIndexFrontmatter = `---
|
||||
session_id: ${specConfig?.session_id || 'unknown'}
|
||||
phase: 5
|
||||
document_type: epics-index
|
||||
status: draft
|
||||
generated_at: ${timestamp}
|
||||
version: 1
|
||||
dependencies:
|
||||
- ../requirements/_index.md
|
||||
- ../architecture/_index.md
|
||||
---`
|
||||
|
||||
const epicsIndexContent = `${epicsIndexFrontmatter}
|
||||
|
||||
# Epics & Stories
|
||||
|
||||
## Epic Overview
|
||||
| ID | Title | Priority | MVP | Size | Status |
|
||||
|----|-------|----------|-----|------|--------|
|
||||
${epicsList.map(e => `| [EPIC-${e.id}](EPIC-${e.id}-${e.slug}.md) | ${e.title} | ${e.priority} | ${e.mvp ? '✓' : ''} | ${e.size} | draft |`).join('\n')}
|
||||
|
||||
## Dependency Map
|
||||
\`\`\`mermaid
|
||||
${cliOutput.dependency_diagram}
|
||||
\`\`\`
|
||||
|
||||
## Execution Order
|
||||
${cliOutput.execution_order}
|
||||
|
||||
## MVP Scope
|
||||
${cliOutput.mvp_definition}
|
||||
|
||||
### MVP Epics
|
||||
${epicsList.filter(e => e.mvp).map(e => `- EPIC-${e.id}: ${e.title}`).join('\n')}
|
||||
|
||||
### Post-MVP
|
||||
${epicsList.filter(e => !e.mvp).map(e => `- EPIC-${e.id}: ${e.title}`).join('\n')}
|
||||
|
||||
## Traceability Matrix
|
||||
${generateTraceabilityMatrix(epicsList, funcReqs)}
|
||||
`
|
||||
|
||||
Write(`${sessionFolder}/spec/epics/_index.md`, epicsIndexContent)
|
||||
|
||||
return {
|
||||
outputPath: 'spec/epics/_index.md',
|
||||
documentSummary: `Epics generated: ${epicsList.length} total, ${epicsList.filter(e => e.mvp).length} in MVP`
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Helper Functions
|
||||
|
||||
```javascript
|
||||
function parseFunctionalRequirements(cliOutput) {
|
||||
// Parse CLI JSON output to extract functional requirements
|
||||
// Returns: [{ id, title, description, user_story, acceptance_criteria[], priority, slug }]
|
||||
}
|
||||
|
||||
function parseNonFunctionalRequirements(cliOutput) {
|
||||
// Parse CLI JSON output to extract non-functional requirements
|
||||
// Returns: [{ id, type, title, requirement, metric, target, slug }]
|
||||
}
|
||||
|
||||
function parseADRs(geminiOutput, codexOutput) {
|
||||
// Parse architecture outputs to extract ADRs with review feedback
|
||||
// Returns: [{ id, title, context, decision, alternatives[], consequences, reviewFeedback, slug }]
|
||||
}
|
||||
|
||||
function parseEpics(cliOutput) {
|
||||
// Parse CLI JSON output to extract Epics and Stories
|
||||
// Returns: [{ id, title, description, priority, mvp, size, stories[], reqs[], adrs[], deps[], slug }]
|
||||
}
|
||||
|
||||
function fillTemplate(template, data) {
|
||||
// Fill template placeholders with data
|
||||
// Apply document-standards.md formatting rules
|
||||
}
|
||||
|
||||
function generateTraceabilityMatrix(epics, requirements) {
|
||||
// Generate traceability matrix showing Epic → Requirement mappings
|
||||
}
|
||||
```
|
||||
257
.claude/skills_lib/team-lifecycle-v2/roles/writer/role.md
Normal file
257
.claude/skills_lib/team-lifecycle-v2/roles/writer/role.md
Normal file
@@ -0,0 +1,257 @@
|
||||
# Role: writer
|
||||
|
||||
Product Brief, Requirements/PRD, Architecture, and Epics & Stories document generation. Maps to spec-generator Phases 2-5.
|
||||
|
||||
## Role Identity
|
||||
|
||||
- **Name**: `writer`
|
||||
- **Task Prefix**: `DRAFT-*`
|
||||
- **Output Tag**: `[writer]`
|
||||
- **Responsibility**: Load Context → Generate Document → Incorporate Feedback → Report
|
||||
- **Communication**: SendMessage to coordinator only
|
||||
|
||||
## Role Boundaries
|
||||
|
||||
### MUST
|
||||
- Only process DRAFT-* tasks
|
||||
- Read templates before generating documents
|
||||
- Follow document-standards.md formatting rules
|
||||
- Integrate discussion feedback when available
|
||||
- Generate proper frontmatter for all documents
|
||||
|
||||
### MUST NOT
|
||||
- Create tasks for other roles
|
||||
- Contact other workers directly
|
||||
- Skip template loading
|
||||
- Modify discussion records
|
||||
- Generate documents without loading prior dependencies
|
||||
|
||||
## Message Types
|
||||
|
||||
| Type | Direction | Trigger | Description |
|
||||
|------|-----------|---------|-------------|
|
||||
| `draft_ready` | writer → coordinator | Document writing complete | With document path and type |
|
||||
| `draft_revision` | writer → coordinator | Document revised and resubmitted | Describes changes made |
|
||||
| `impl_progress` | writer → coordinator | Long writing progress | Multi-document stage progress |
|
||||
| `error` | writer → coordinator | Unrecoverable error | Template missing, insufficient context, etc. |
|
||||
|
||||
## Message Bus
|
||||
|
||||
Before every `SendMessage`, MUST call `mcp__ccw-tools__team_msg` to log:
|
||||
|
||||
```javascript
|
||||
// Document ready
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log",
|
||||
team: teamName,
|
||||
from: "writer",
|
||||
to: "coordinator",
|
||||
type: "draft_ready",
|
||||
summary: "[writer] Product Brief complete",
|
||||
ref: `${sessionFolder}/product-brief.md`
|
||||
})
|
||||
|
||||
// Document revision
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log",
|
||||
team: teamName,
|
||||
from: "writer",
|
||||
to: "coordinator",
|
||||
type: "draft_revision",
|
||||
summary: "[writer] Requirements revised per discussion feedback"
|
||||
})
|
||||
|
||||
// Error report
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log",
|
||||
team: teamName,
|
||||
from: "writer",
|
||||
to: "coordinator",
|
||||
type: "error",
|
||||
summary: "[writer] Input artifact missing, cannot generate document"
|
||||
})
|
||||
```
|
||||
|
||||
### CLI Fallback
|
||||
|
||||
When `mcp__ccw-tools__team_msg` MCP is unavailable:
|
||||
|
||||
```bash
|
||||
ccw team log --team "${teamName}" --from "writer" --to "coordinator" --type "draft_ready" --summary "[writer] Brief complete" --ref "${sessionFolder}/product-brief.md" --json
|
||||
```
|
||||
|
||||
## Toolbox
|
||||
|
||||
### Available Commands
|
||||
- `commands/generate-doc.md` - Multi-CLI document generation for 4 doc types
|
||||
|
||||
### Subagent Capabilities
|
||||
- None
|
||||
|
||||
### CLI Capabilities
|
||||
- `gemini`, `codex`, `claude` for multi-perspective analysis
|
||||
|
||||
## Execution (5-Phase)
|
||||
|
||||
### Phase 1: Task Discovery
|
||||
|
||||
```javascript
|
||||
const tasks = TaskList()
|
||||
const myTasks = tasks.filter(t =>
|
||||
t.subject.startsWith('DRAFT-') &&
|
||||
t.owner === 'writer' &&
|
||||
t.status === 'pending' &&
|
||||
t.blockedBy.length === 0
|
||||
)
|
||||
|
||||
if (myTasks.length === 0) return // idle
|
||||
|
||||
const task = TaskGet({ taskId: myTasks[0].id })
|
||||
TaskUpdate({ taskId: task.id, status: 'in_progress' })
|
||||
```
|
||||
|
||||
### Phase 2: Context & Discussion Loading
|
||||
|
||||
```javascript
|
||||
// Extract session folder from task description
|
||||
const sessionMatch = task.description.match(/Session:\s*(.+)/)
|
||||
const sessionFolder = sessionMatch ? sessionMatch[1].trim() : ''
|
||||
|
||||
// Load session config
|
||||
let specConfig = null
|
||||
try { specConfig = JSON.parse(Read(`${sessionFolder}/spec/spec-config.json`)) } catch {}
|
||||
|
||||
// Determine document type from task subject
|
||||
const docType = task.subject.includes('Product Brief') ? 'product-brief'
|
||||
: task.subject.includes('Requirements') || task.subject.includes('PRD') ? 'requirements'
|
||||
: task.subject.includes('Architecture') ? 'architecture'
|
||||
: task.subject.includes('Epics') ? 'epics'
|
||||
: 'unknown'
|
||||
|
||||
// Load discussion feedback (from preceding DISCUSS task)
|
||||
const discussionFiles = {
|
||||
'product-brief': 'discussions/discuss-001-scope.md',
|
||||
'requirements': 'discussions/discuss-002-brief.md',
|
||||
'architecture': 'discussions/discuss-003-requirements.md',
|
||||
'epics': 'discussions/discuss-004-architecture.md'
|
||||
}
|
||||
let discussionFeedback = null
|
||||
try { discussionFeedback = Read(`${sessionFolder}/${discussionFiles[docType]}`) } catch {}
|
||||
|
||||
// Load prior documents progressively
|
||||
const priorDocs = {}
|
||||
if (docType !== 'product-brief') {
|
||||
try { priorDocs.discoveryContext = Read(`${sessionFolder}/spec/discovery-context.json`) } catch {}
|
||||
}
|
||||
if (['requirements', 'architecture', 'epics'].includes(docType)) {
|
||||
try { priorDocs.productBrief = Read(`${sessionFolder}/spec/product-brief.md`) } catch {}
|
||||
}
|
||||
if (['architecture', 'epics'].includes(docType)) {
|
||||
try { priorDocs.requirementsIndex = Read(`${sessionFolder}/spec/requirements/_index.md`) } catch {}
|
||||
}
|
||||
if (docType === 'epics') {
|
||||
try { priorDocs.architectureIndex = Read(`${sessionFolder}/spec/architecture/_index.md`) } catch {}
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 3: Document Generation
|
||||
|
||||
**Delegate to command file**:
|
||||
|
||||
```javascript
|
||||
// Load and execute document generation command
|
||||
const generateDocCommand = Read('commands/generate-doc.md')
|
||||
|
||||
// Execute command with context:
|
||||
// - docType
|
||||
// - sessionFolder
|
||||
// - specConfig
|
||||
// - discussionFeedback
|
||||
// - priorDocs
|
||||
// - task
|
||||
|
||||
// Command will handle:
|
||||
// - Loading document standards
|
||||
// - Loading appropriate template
|
||||
// - Building shared context
|
||||
// - Routing to type-specific generation (DRAFT-001/002/003/004)
|
||||
// - Integrating discussion feedback
|
||||
// - Writing output files
|
||||
|
||||
// Returns: { outputPath, documentSummary }
|
||||
```
|
||||
|
||||
### Phase 4: Self-Validation
|
||||
|
||||
```javascript
|
||||
const docContent = Read(`${sessionFolder}/${outputPath}`)
|
||||
|
||||
const validationChecks = {
|
||||
has_frontmatter: /^---\n[\s\S]+?\n---/.test(docContent),
|
||||
sections_complete: /* verify all required sections present */,
|
||||
cross_references: docContent.includes('session_id'),
|
||||
discussion_integrated: !discussionFeedback || docContent.includes('Discussion')
|
||||
}
|
||||
|
||||
const allValid = Object.values(validationChecks).every(v => v)
|
||||
```
|
||||
|
||||
### Phase 5: Report to Coordinator
|
||||
|
||||
```javascript
|
||||
const docTypeLabel = {
|
||||
'product-brief': 'Product Brief',
|
||||
'requirements': 'Requirements/PRD',
|
||||
'architecture': 'Architecture Document',
|
||||
'epics': 'Epics & Stories'
|
||||
}
|
||||
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log", team: teamName,
|
||||
from: "writer", to: "coordinator",
|
||||
type: "draft_ready",
|
||||
summary: `[writer] ${docTypeLabel[docType]} 完成: ${allValid ? '验证通过' : '部分验证失败'}`,
|
||||
ref: `${sessionFolder}/${outputPath}`
|
||||
})
|
||||
|
||||
SendMessage({
|
||||
type: "message",
|
||||
recipient: "coordinator",
|
||||
content: `[writer] ## 文档撰写结果
|
||||
|
||||
**Task**: ${task.subject}
|
||||
**文档类型**: ${docTypeLabel[docType]}
|
||||
**验证状态**: ${allValid ? 'PASS' : 'PARTIAL'}
|
||||
|
||||
### 文档摘要
|
||||
${documentSummary}
|
||||
|
||||
### 讨论反馈整合
|
||||
${discussionFeedback ? '已整合前序讨论反馈' : '首次撰写'}
|
||||
|
||||
### 自验证结果
|
||||
${Object.entries(validationChecks).map(([k, v]) => '- ' + k + ': ' + (v ? 'PASS' : 'FAIL')).join('\n')}
|
||||
|
||||
### 输出位置
|
||||
${sessionFolder}/${outputPath}
|
||||
|
||||
文档已就绪，可进入讨论轮次。`,
|
||||
summary: `[writer] ${docTypeLabel[docType]} 就绪`
|
||||
})
|
||||
|
||||
TaskUpdate({ taskId: task.id, status: 'completed' })
|
||||
|
||||
// Check for next DRAFT task → back to Phase 1
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| No DRAFT-* tasks available | Idle, wait for coordinator assignment |
|
||||
| Prior document not found | Notify coordinator, request prerequisite |
|
||||
| CLI analysis failure | Retry with fallback tool, then direct generation |
|
||||
| Template sections incomplete | Generate best-effort, note gaps in report |
|
||||
| Discussion feedback contradicts prior docs | Note conflict in document, flag for next discussion |
|
||||
| Session folder missing | Notify coordinator, request session path |
|
||||
| Unexpected error | Log error via team_msg, report to coordinator |
|
||||
Reference in New Issue
Block a user