mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-15 02:42:45 +08:00
8475a724ae
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.
434 lines
15 KiB
Markdown
434 lines
15 KiB
Markdown
# 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 |
|