claude-code-workflow 7.2.29 → 7.2.30

package/.claude/skills/ccw-chain/phases/spec-generator/phases/02-product-brief.md

@@ -0,0 +1,274 @@
+# Phase 2: Product Brief
+
+Generate a product brief through multi-perspective CLI analysis, establishing "what" and "why".
+
+## Objective
+
+- Read Phase 1 outputs (spec-config.json, discovery-context.json)
+- Launch 3 parallel CLI analyses from product, technical, and user perspectives
+- Synthesize convergent themes and conflicting views
+- Optionally refine with user input
+- Generate product-brief.md using template
+
+## Input
+
+- Dependency: `{workDir}/spec-config.json`
+- Primary: `{workDir}/refined-requirements.json` (Phase 1.5 output, preferred over raw seed_analysis)
+- Optional: `{workDir}/discovery-context.json`
+- Config: `{workDir}/spec-config.json`
+- Template: `templates/product-brief.md`
+
+## Execution Steps
+
+### Step 1: Load Phase 1 Context
+
+```javascript
+const specConfig = JSON.parse(Read(`${workDir}/spec-config.json`));
+const { seed_analysis, seed_input, has_codebase, depth, focus_areas } = specConfig;
+
+// Load refined requirements (Phase 1.5 output) - preferred over raw seed_analysis
+let refinedReqs = null;
+try {
+  refinedReqs = JSON.parse(Read(`${workDir}/refined-requirements.json`));
+} catch (e) {
+  // No refined requirements, fall back to seed_analysis
+}
+
+let discoveryContext = null;
+if (has_codebase) {
+  try {
+    discoveryContext = JSON.parse(Read(`${workDir}/discovery-context.json`));
+  } catch (e) {
+    // No discovery context available, proceed without
+  }
+}
+
+// Build shared context string for CLI prompts
+// Prefer refined requirements over raw seed_analysis
+const problem = refinedReqs?.clarified_problem_statement || seed_analysis.problem_statement;
+const users = refinedReqs?.confirmed_target_users?.map(u => u.name || u).join(', ')
+  || seed_analysis.target_users.join(', ');
+const domain = refinedReqs?.confirmed_domain || seed_analysis.domain;
+const constraints = refinedReqs?.boundary_conditions?.constraints?.join(', ')
+  || seed_analysis.constraints.join(', ');
+const features = refinedReqs?.confirmed_features?.map(f => f.name).join(', ') || '';
+const nfrs = refinedReqs?.non_functional_requirements?.map(n => `${n.type}: ${n.details}`).join('; ') || '';
+
+const sharedContext = `
+SEED: ${seed_input}
+PROBLEM: ${problem}
+TARGET USERS: ${users}
+DOMAIN: ${domain}
+CONSTRAINTS: ${constraints}
+FOCUS AREAS: ${focus_areas.join(', ')}
+${features ? `CONFIRMED FEATURES: ${features}` : ''}
+${nfrs ? `NON-FUNCTIONAL REQUIREMENTS: ${nfrs}` : ''}
+${discoveryContext ? `
+CODEBASE CONTEXT:
+- Existing patterns: ${discoveryContext.existing_patterns?.slice(0,5).join(', ') || 'none'}
+- Architecture constraints: ${discoveryContext.architecture_constraints?.slice(0,3).join(', ') || 'none'}
+- Tech stack: ${JSON.stringify(discoveryContext.tech_stack || {})}
+` : ''}`;
+```
+
+### Step 2: Multi-CLI Parallel Analysis (3 perspectives)
+
+Launch 3 CLI calls in parallel:
+
+**Product Perspective (Gemini)**:
+```javascript
+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)**:
+```javascript
+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)**:
+```javascript
+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 before continuing
+```
+
+### Step 3: Synthesize Perspectives
+
+```javascript
+// After receiving all 3 CLI results:
+// Extract convergent themes (all agree)
+// Identify conflicting views (need resolution)
+// Note unique contributions from each perspective
+
+const synthesis = {
+  convergent_themes: [], // themes all 3 perspectives agree on
+  conflicts: [],         // areas where perspectives differ
+  product_insights: [],  // unique from product perspective
+  technical_insights: [], // unique from technical perspective
+  user_insights: []      // unique from user perspective
+};
+```
+
+### Step 4: Interactive Refinement (Optional)
+
+```javascript
+if (!autoMode) {
+  // Present synthesis summary to user
+  // AskUserQuestion with:
+  // - Confirm vision statement
+  // - Resolve any conflicts between perspectives
+  // - Adjust scope if needed
+  AskUserQuestion({
+    questions: [
+      {
+        question: "Review the synthesized product brief. Any adjustments needed?",
+        header: "Review",
+        multiSelect: false,
+        options: [
+          { label: "Looks good", description: "Proceed to PRD generation" },
+          { label: "Adjust scope", description: "Narrow or expand the scope" },
+          { label: "Revise vision", description: "Refine the vision statement" }
+        ]
+      }
+    ]
+  });
+}
+```
+
+### Step 5: Generate product-brief.md
+
+```javascript
+// Read template
+const template = Read('templates/product-brief.md');
+
+// Fill template with synthesized content
+// Apply document-standards.md formatting rules
+// Write with YAML frontmatter
+
+const frontmatter = `---
+session_id: ${specConfig.session_id}
+phase: 2
+document_type: product-brief
+status: ${autoMode ? 'complete' : 'draft'}
+generated_at: ${new Date().toISOString()}
+stepsCompleted: ["load-context", "multi-cli-analysis", "synthesis", "generation"]
+version: 1
+dependencies:
+  - spec-config.json
+---`;
+
+// Combine frontmatter + filled template content
+Write(`${workDir}/product-brief.md`, `${frontmatter}\n\n${filledContent}`);
+
+// Update spec-config.json
+specConfig.phasesCompleted.push({
+  phase: 2,
+  name: "product-brief",
+  output_file: "product-brief.md",
+  completed_at: new Date().toISOString()
+});
+Write(`${workDir}/spec-config.json`, JSON.stringify(specConfig, null, 2));
+```
+
+### Step 5.5: Generate glossary.json
+
+```javascript
+// Extract terminology from product brief and CLI analysis
+// Generate structured glossary for cross-document consistency
+
+const glossary = {
+  session_id: specConfig.session_id,
+  terms: [
+    // Extract from product brief content:
+    // - Key domain nouns from problem statement
+    // - User persona names
+    // - Technical terms from multi-perspective synthesis
+    // Each term should have:
+    // { term: "...", definition: "...", aliases: [], first_defined_in: "product-brief.md", category: "core|technical|business" }
+  ]
+};
+
+Write(`${workDir}/glossary.json`, JSON.stringify(glossary, null, 2));
+```
+
+**Glossary Injection**: In all subsequent phase prompts, inject the following into the CONTEXT section:
+```
+TERMINOLOGY GLOSSARY (use these terms consistently):
+${JSON.stringify(glossary.terms, null, 2)}
+```
+
+## Output
+
+- **File**: `product-brief.md`
+- **Format**: Markdown with YAML frontmatter
+
+## Quality Checklist
+
+- [ ] Vision statement: clear, 1-3 sentences
+- [ ] Problem statement: specific and measurable
+- [ ] Target users: >= 1 persona with needs
+- [ ] Goals: >= 2 with measurable metrics
+- [ ] Scope: in-scope and out-of-scope defined
+- [ ] Multi-perspective synthesis included
+- [ ] YAML frontmatter valid
+
+## Next Phase
+
+Proceed to [Phase 3: Requirements](03-requirements.md) with the generated product-brief.md.

package/.claude/skills/ccw-chain/phases/spec-generator/phases/03-requirements.md

@@ -0,0 +1,184 @@
+# Phase 3: Requirements (PRD)
+
+Generate a detailed Product Requirements Document with functional/non-functional requirements, acceptance criteria, and MoSCoW prioritization.
+
+## Objective
+
+- Read product-brief.md and extract goals, scope, constraints
+- Expand each goal into functional requirements with acceptance criteria
+- Generate non-functional requirements
+- Apply MoSCoW priority labels (user input or auto)
+- Generate requirements.md using template
+
+## Input
+
+- Dependency: `{workDir}/product-brief.md`
+- Config: `{workDir}/spec-config.json`
+- Template: `templates/requirements-prd.md` (directory structure: `_index.md` + `REQ-*.md` + `NFR-*.md`)
+
+## Execution Steps
+
+### Step 1: Load Phase 2 Context
+
+```javascript
+const specConfig = JSON.parse(Read(`${workDir}/spec-config.json`));
+const productBrief = Read(`${workDir}/product-brief.md`);
+
+// Extract key sections from product brief
+// - Goals & Success Metrics table
+// - Scope (in-scope items)
+// - Target Users (personas)
+// - Constraints
+// - Technical perspective insights
+```
+
+### Step 2: Requirements Expansion via Gemini CLI
+
+```javascript
+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:
+${productBrief}
+
+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 initial MoSCoW priority based on:
+  - Must: Core functionality, cannot launch without
+  - Should: Important but has workaround
+  - Could: Nice-to-have, enhances experience
+  - Won't: Explicitly deferred
+- Use RFC 2119 keywords (MUST, SHOULD, MAY, MUST NOT, SHOULD NOT) to define behavioral constraints for each requirement. Example: 'The system MUST return a 401 response within 100ms for invalid tokens.'
+- For each core domain entity referenced in requirements, define its data model: fields, types, constraints, and relationships to other entities
+- Maintain terminology consistency with the glossary below:
+  TERMINOLOGY GLOSSARY:
+  \${glossary ? JSON.stringify(glossary.terms, null, 2) : 'N/A - generate terms inline'}
+
+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 like 'system should be fast'.
+" --tool gemini --mode analysis`,
+  run_in_background: true
+});
+
+// Wait for CLI result
+```
+
+### Step 3: User Priority Sorting (Interactive)
+
+```javascript
+if (!autoMode) {
+  // Present requirements grouped by initial priority
+  // Allow user to adjust MoSCoW labels
+  AskUserQuestion({
+    questions: [
+      {
+        question: "Review the Must-Have requirements. Any that should be reprioritized?",
+        header: "Must-Have",
+        multiSelect: false,
+        options: [
+          { label: "All correct", description: "Must-have requirements are accurate" },
+          { label: "Too many", description: "Some should be Should/Could" },
+          { label: "Missing items", description: "Some Should requirements should be Must" }
+        ]
+      },
+      {
+        question: "What is the target MVP scope?",
+        header: "MVP Scope",
+        multiSelect: false,
+        options: [
+          { label: "Must-Have only (Recommended)", description: "MVP includes only Must requirements" },
+          { label: "Must + key Should", description: "Include critical Should items in MVP" },
+          { label: "Comprehensive", description: "Include all Must and Should" }
+        ]
+      }
+    ]
+  });
+  // Apply user adjustments to priorities
+} else {
+  // Auto mode: accept CLI-suggested priorities as-is
+}
+```
+
+### Step 4: Generate requirements/ directory
+
+```javascript
+// Read template
+const template = Read('templates/requirements-prd.md');
+
+// Create requirements directory
+Bash(`mkdir -p "${workDir}/requirements"`);
+
+const status = autoMode ? 'complete' : 'draft';
+const timestamp = new Date().toISOString();
+
+// Parse CLI output into structured requirements
+const funcReqs = parseFunctionalRequirements(cliOutput);  // [{id, slug, title, priority, ...}]
+const nfReqs = parseNonFunctionalRequirements(cliOutput);  // [{id, type, slug, title, ...}]
+
+// Step 4a: Write individual REQ-*.md files (one per functional requirement)
+funcReqs.forEach(req => {
+  // Use REQ-NNN-{slug}.md template from templates/requirements-prd.md
+  // Fill: id, title, priority, description, user_story, acceptance_criteria, traces
+  Write(`${workDir}/requirements/REQ-${req.id}-${req.slug}.md`, reqContent);
+});
+
+// Step 4b: Write individual NFR-*.md files (one per non-functional requirement)
+nfReqs.forEach(nfr => {
+  // Use NFR-{type}-NNN-{slug}.md template from templates/requirements-prd.md
+  // Fill: id, type, category, title, requirement, metric, target, traces
+  Write(`${workDir}/requirements/NFR-${nfr.type}-${nfr.id}-${nfr.slug}.md`, nfrContent);
+});
+
+// Step 4c: Write _index.md (summary + links to all individual files)
+// Use _index.md template from templates/requirements-prd.md
+// Fill: summary table, functional req links table, NFR links tables,
+//       data requirements, integration requirements, traceability matrix
+Write(`${workDir}/requirements/_index.md`, indexContent);
+
+// Update spec-config.json
+specConfig.phasesCompleted.push({
+  phase: 3,
+  name: "requirements",
+  output_dir: "requirements/",
+  output_index: "requirements/_index.md",
+  file_count: funcReqs.length + nfReqs.length + 1,
+  completed_at: timestamp
+});
+Write(`${workDir}/spec-config.json`, JSON.stringify(specConfig, null, 2));
+```
+
+## Output
+
+- **Directory**: `requirements/`
+  - `_index.md` — Summary, MoSCoW table, traceability matrix, links
+  - `REQ-NNN-{slug}.md` — Individual functional requirement (per requirement)
+  - `NFR-{type}-NNN-{slug}.md` — Individual non-functional requirement (per NFR)
+- **Format**: Markdown with YAML frontmatter, cross-linked via relative paths
+
+## Quality Checklist
+
+- [ ] Functional requirements: >= 3 with REQ-NNN IDs, each in own file
+- [ ] Every requirement file has >= 1 acceptance criterion
+- [ ] Every requirement has MoSCoW priority tag in frontmatter
+- [ ] Non-functional requirements: >= 1, each in own file
+- [ ] User stories present for Must-have requirements
+- [ ] `_index.md` links to all individual requirement files
+- [ ] Traceability links to product-brief.md goals
+- [ ] All files have valid YAML frontmatter
+
+## Next Phase
+
+Proceed to [Phase 4: Architecture](04-architecture.md) with the generated requirements.md.

package/.claude/skills/ccw-chain/phases/spec-generator/phases/04-architecture.md

@@ -0,0 +1,248 @@
+# Phase 4: Architecture
+
+Generate technical architecture decisions, component design, and technology selections based on requirements.
+
+## Objective
+
+- Analyze requirements to identify core components and system architecture
+- Generate Architecture Decision Records (ADRs) with alternatives
+- Map architecture to existing codebase (if applicable)
+- Challenge architecture via Codex CLI review
+- Generate architecture.md using template
+
+## Input
+
+- Dependency: `{workDir}/requirements/_index.md` (and individual `REQ-*.md` files)
+- Reference: `{workDir}/product-brief.md`
+- Optional: `{workDir}/discovery-context.json`
+- Config: `{workDir}/spec-config.json`
+- Template: `templates/architecture-doc.md`
+
+## Execution Steps
+
+### Step 1: Load Phase 2-3 Context
+
+```javascript
+const specConfig = JSON.parse(Read(`${workDir}/spec-config.json`));
+const productBrief = Read(`${workDir}/product-brief.md`);
+const requirements = Read(`${workDir}/requirements.md`);
+
+let discoveryContext = null;
+if (specConfig.has_codebase) {
+  try {
+    discoveryContext = JSON.parse(Read(`${workDir}/discovery-context.json`));
+  } catch (e) { /* no context */ }
+}
+
+// Load glossary for terminology consistency
+let glossary = null;
+try {
+  glossary = JSON.parse(Read(`${workDir}/glossary.json`));
+} catch (e) { /* proceed without */ }
+
+// Load spec type profile for specialized sections
+const specType = specConfig.spec_type || 'service';
+let profile = null;
+try {
+  profile = Read(`templates/profiles/${specType}-profile.md`);
+} catch (e) { /* use base template only */ }
+```
+
+### Step 2: Architecture Analysis via Gemini CLI
+
+```javascript
+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):
+${productBrief.slice(0, 3000)}
+
+REQUIREMENTS:
+${requirements.slice(0, 5000)}
+
+${discoveryContext ? `EXISTING CODEBASE:
+- Tech stack: ${JSON.stringify(discoveryContext.tech_stack || {})}
+- Existing patterns: ${discoveryContext.existing_patterns?.slice(0,5).join('; ') || 'none'}
+- Architecture constraints: ${discoveryContext.architecture_constraints?.slice(0,3).join('; ') || 'none'}
+` : ''}
+
+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)
+${discoveryContext ? '- Map new components to existing codebase modules' : ''}
+- For each core entity with a lifecycle, create an ASCII state machine diagram showing:
+  - All states and transitions
+  - Trigger events for each transition
+  - Side effects of transitions
+  - Error states and recovery paths
+- Define a Configuration Model: list all configurable fields with name, type, default value, constraint, and description
+- Define Error Handling strategy:
+  - Classify errors (transient/permanent/degraded)
+  - Per-component error behavior using RFC 2119 keywords
+  - Recovery mechanisms
+- Define Observability requirements:
+  - Key metrics (name, type: counter/gauge/histogram, labels)
+  - Structured log format and key log events
+  - Health check endpoints
+\${profile ? \`
+SPEC TYPE PROFILE REQUIREMENTS (\${specType}):
+\${profile}
+\` : ''}
+\${glossary ? \`
+TERMINOLOGY GLOSSARY (use consistently):
+\${JSON.stringify(glossary.terms, null, 2)}
+\` : ''}
+
+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 over cutting-edge.
+" --tool gemini --mode analysis`,
+  run_in_background: true
+});
+
+// Wait for CLI result
+```
+
+### Step 3: Architecture Review via Codex CLI
+
+```javascript
+// After receiving Gemini analysis, challenge it with 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:
+${requirements.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 CLI result
+```
+
+### Step 4: Interactive ADR Decisions (Optional)
+
+```javascript
+if (!autoMode) {
+  // Present ADRs with review feedback to user
+  // For each ADR where review raised concerns:
+  AskUserQuestion({
+    questions: [
+      {
+        question: "Architecture review raised concerns. How should we proceed?",
+        header: "ADR Review",
+        multiSelect: false,
+        options: [
+          { label: "Accept as-is", description: "Architecture is sound, proceed" },
+          { label: "Incorporate feedback", description: "Adjust ADRs based on review" },
+          { label: "Simplify", description: "Reduce complexity, fewer components" }
+        ]
+      }
+    ]
+  });
+  // Apply user decisions to architecture
+}
+```
+
+### Step 5: Codebase Integration Mapping (Conditional)
+
+```javascript
+if (specConfig.has_codebase && discoveryContext) {
+  // Map new architecture components to existing code
+  const integrationMapping = discoveryContext.relevant_files.map(f => ({
+    new_component: "...", // matched from architecture
+    existing_module: f.path,
+    integration_type: "Extend|Replace|New",
+    notes: f.rationale
+  }));
+  // Include in architecture document
+}
+```
+
+### Step 6: Generate architecture/ directory
+
+```javascript
+const template = Read('templates/architecture-doc.md');
+
+// Create architecture directory
+Bash(`mkdir -p "${workDir}/architecture"`);
+
+const status = autoMode ? 'complete' : 'draft';
+const timestamp = new Date().toISOString();
+
+// Parse CLI outputs into structured ADRs
+const adrs = parseADRs(geminiArchitectureOutput, codexReviewOutput);  // [{id, slug, title, ...}]
+
+// Step 6a: Write individual ADR-*.md files (one per decision)
+adrs.forEach(adr => {
+  // Use ADR-NNN-{slug}.md template from templates/architecture-doc.md
+  // Fill: id, title, status, context, decision, alternatives, consequences, traces
+  Write(`${workDir}/architecture/ADR-${adr.id}-${adr.slug}.md`, adrContent);
+});
+
+// Step 6b: Write _index.md (overview + components + tech stack + links to ADRs)
+// Use _index.md template from templates/architecture-doc.md
+// Fill: system overview, component diagram, tech stack, ADR links table,
+//       data model, API design, security controls, infrastructure, codebase integration
+Write(`${workDir}/architecture/_index.md`, indexContent);
+
+// Update spec-config.json
+specConfig.phasesCompleted.push({
+  phase: 4,
+  name: "architecture",
+  output_dir: "architecture/",
+  output_index: "architecture/_index.md",
+  file_count: adrs.length + 1,
+  completed_at: timestamp
+});
+Write(`${workDir}/spec-config.json`, JSON.stringify(specConfig, null, 2));
+```
+
+## Output
+
+- **Directory**: `architecture/`
+  - `_index.md` — Overview, component diagram, tech stack, data model, security, links
+  - `ADR-NNN-{slug}.md` — Individual Architecture Decision Record (per ADR)
+- **Format**: Markdown with YAML frontmatter, cross-linked to requirements via relative paths
+
+## Quality Checklist
+
+- [ ] Component diagram present in `_index.md` (Mermaid or ASCII)
+- [ ] Tech stack specified (languages, frameworks, key libraries)
+- [ ] >= 1 ADR file with alternatives considered
+- [ ] Each ADR file lists >= 2 options
+- [ ] `_index.md` ADR table links to all individual ADR files
+- [ ] Integration points identified
+- [ ] Data model described
+- [ ] Codebase mapping present (if has_codebase)
+- [ ] All files have valid YAML frontmatter
+- [ ] ADR files link back to requirement files
+
+## Next Phase
+
+Proceed to [Phase 5: Epics & Stories](05-epics-stories.md) with the generated architecture.md.