Claude-Code-Workflow/.claude/skills/spec-generator/phases/06-readiness-check.md

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

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

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

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

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

// 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

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:

// 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