Claude-Code-Workflow/.claude/commands/ddd/index-build.md

name, description, argument-hint, allowed-tools

name	description	argument-hint	allowed-tools
index-build	Build document index from spec-generator outputs + codebase mapping. Requires existing spec session. For projects without specs, use /ddd:scan instead.	[-y|--yes] [-s|--spec <spec-session-id>] [--from-scratch]	TodoWrite(*), Agent(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*), Bash(*), Edit(*), Write(*), mcp__ace-tool__search_context(*)

Auto Mode

When --yes or -y: Auto-confirm all decisions, use inferred mappings, skip interactive review.

DDD Index Build Command (/ddd:index-build)

Purpose

From spec-generator outputs (requirements, architecture, epics), construct the central document index and map spec entities to actual code locations.

Spec outputs (REQ, ADR, EPIC) + Codebase → doc-index.json

No spec? Use /ddd:scan instead — it reverse-engineers the index from code alone.

Prerequisite

• At least one spec session in .workflow/.doc-index/specs/ or .workflow/.spec/
• If no spec found → error with suggestion: "No spec session found. Run /ddd:scan for code-first indexing, or /spec-generator to create specs."

Storage Location

.workflow/.doc-index/
├── doc-index.json              ← Central index (primary output)
├── specs/                      ← Spec-generator outputs
│   └── SPEC-{slug}-{date}/
├── feature-maps/               ← Feature documentation (from Epics)
│   ├── _index.md
│   └── {feature-slug}.md
├── tech-registry/              ← Technical component docs (from code mapping)
│   ├── _index.md
│   └── {component-slug}.md
└── action-logs/                ← Change history (initially empty)
    └── _index.md

Phase 1: Discover & Parse Spec Sources

1.1 Locate Spec Session

IF --spec <id> provided:
  Load from .workflow/.doc-index/specs/<id>/ OR .workflow/.spec/<id>/
ELSE:
  Scan for all SPEC-* directories
  IF multiple → present list, ask user to select (-y picks latest)
  IF none → ERROR: "No spec session found. Use /ddd:scan or /spec-generator."

1.2 Migrate Specs (if needed)

If spec in .workflow/.spec/ but not in .workflow/.doc-index/specs/:

• Copy to .workflow/.doc-index/specs/
• Preserve original (backward compatibility)

1.3 Extract Structured Entities

Source File	Extract To
spec-config.json	project name, domain, spec_type
glossary.json	→ index glossary[]
product-brief.md	vision, goals
requirements/REQ-*.md	→ index requirements[] (with MoSCoW priority)
requirements/NFR-*.md	→ index requirements[] (non-functional)
architecture/ADR-*.md	→ index architectureDecisions[]
epics/EPIC-*.md	→ feature grouping seeds

Phase 2: Codebase Mapping

Map spec entities to actual code locations using Gemini:

ccw cli -p "PURPOSE: Map codebase to specification entities for documentation indexing.
TASK:
• Scan the codebase and identify all major modules/components
• For each component: extract file paths, exported symbols (classes, functions, types)
• Match components to these specification entities by name/domain similarity:
  Requirements: {REQ-001: desc, REQ-002: desc, ...extracted from Phase 1}
  Architecture decisions: {ADR-001: title, ...extracted from Phase 1}
• Report unmatched components (exist in code but no spec counterpart)
• Report unmatched requirements (in spec but no code found)
MODE: analysis
CONTEXT: @**/*
EXPECTED: JSON: { components: [{ name, type, files, symbols, matched_req_ids, matched_adr_id, is_orphan }], unmatched_reqs: [REQ-NNN] }
CONSTRAINTS: Focus on source directories | Ignore node_modules, dist, build" --tool gemini --mode analysis

2.1 Generate Component IDs & Link

For each discovered component:

• ID: tech-{kebab-case-name}
• Link to matched REQ-NNN and ADR-NNN
• Flag orphans for user review

Phase 3: Build Feature Map (from Epics)

3.1 Epic → Feature Mapping

Each EPIC-NNN → one feat-{slug}
  - id: feat-{slug} (from epic slug)
  - name: from Epic name
  - epicId: EPIC-NNN
  - status: inferred from code mapping
    - all requirements have matched components → "implemented"
    - some matched → "in-progress"
    - none matched → "planned"
  - requirementIds: from Epic's stories → requirement links
  - tags: from domain keywords

3.2 Generate Feature Map Documents

For each feature → feature-maps/{slug}.md:

---
id: feat-{slug}
name: Feature Name
epic_id: EPIC-NNN
status: implemented
requirements: [REQ-001, REQ-002]
components: [tech-auth-service, tech-user-model]
tags: [auth, security]
last_updated: ISO8601
---

# Feature Name

## Overview
{Description from epic}

## Requirements
- **REQ-001**: {title} (Must) — {component mapping status}
- **REQ-002**: {title} (Should) — {component mapping status}

## Technical Components
- **AuthService** (`src/services/auth.ts`): {role}

## Architecture Decisions
- **ADR-001**: {title}

## Change History
| Date | Task | Description |
|------|------|-------------|
| {date} | Initial | Indexed from spec SPEC-{session} |

3.3 Generate Tech Registry Documents

For each component → tech-registry/{slug}.md:

---
id: tech-{slug}
name: ComponentName
type: service
features: [feat-auth]
code_locations:
  - path: src/services/auth.ts
    symbols: [AuthService, AuthService.login]
last_updated: ISO8601
---

# ComponentName

## Responsibility
{From Gemini analysis}

## Code Locations
- `src/services/auth.ts`: Main implementation

## Related Requirements
- **REQ-001**: {title}

## Architecture Decisions
- **ADR-001**: {title}

Phase 4: Assemble doc-index.json

{
  "version": "1.0",
  "project": "{project-name}",
  "build_path": "spec-first",
  "spec_session": "SPEC-{slug}-{date}",
  "last_updated": "ISO8601",
  "glossary": [
    { "id": "gloss-{slug}", "term": "Term", "definition": "...", "aliases": [], "category": "core|technical|business" }
  ],
  "features": [
    { "id": "feat-{slug}", "name": "...", "epicId": "EPIC-NNN", "status": "...", "docPath": "feature-maps/{slug}.md", "requirementIds": ["REQ-NNN"], "tags": [] }
  ],
  "requirements": [
    { "id": "REQ-NNN", "title": "...", "source": "spec", "priority": "Must|Should|Could|Won't", "sourcePath": "specs/SPEC-*/requirements/REQ-NNN-*.md", "techComponentIds": ["tech-{slug}"], "featureId": "feat-{slug}" }
  ],
  "technicalComponents": [
    { "id": "tech-{slug}", "name": "...", "type": "...", "responsibility": "...", "adrId": "ADR-NNN|null", "docPath": "tech-registry/{slug}.md", "codeLocations": [{ "path": "...", "symbols": [], "lineRange": [0,0] }], "dependsOn": [], "featureIds": ["feat-{slug}"], "actionIds": [] }
  ],
  "architectureDecisions": [
    { "id": "ADR-NNN", "title": "...", "source": "spec", "sourcePath": "specs/SPEC-*/architecture/ADR-NNN-*.md", "componentIds": ["tech-{slug}"] }
  ],
  "actions": []
}

Merge with Existing Code-First Index

If a code-first index exists (from prior /ddd:scan):

• Replace IREQ-NNN with matching REQ-NNN where content overlaps
• Keep IREQ-NNN without spec counterpart (mark source: "legacy-inferred")
• Replace IADR-NNN with ADR-NNN where applicable
• Update build_path to "spec-first"
• Preserve existing tech-* components (update links only)

Phase 5: Generate Index Documents & Validation

5.1 Index Documents

• feature-maps/_index.md — feature overview table
• tech-registry/_index.md — component registry table
• action-logs/_index.md — empty, populated by /ddd:sync

5.2 Coverage Report

Index Build Report (spec-first)

Spec: {session-id}
Features: {N} (from {N} Epics)
Requirements: {N} (REQ: {n}, NFR: {n})
Components: {N} ({orphan} orphans without spec match)
ADRs: {N}

Mapping Coverage:
  Requirements → Components: {%} ({unmapped} unmapped)
  Components → Features: {%}
  Epics → Features: 100%

Gaps:
  - {N} requirements have no matching code component
  - {N} code components are not linked to any requirement

Flags

Flag	Effect
-y, --yes	Skip all interactive prompts
-s, --spec <id>	Use specific spec session
--from-scratch	Delete existing index and rebuild

Integration Points

• Input from: spec-generator outputs, codebase, existing /ddd:scan index
• Output to: ddd:plan, ddd:sync, ddd:update
• Upgrades: Can merge with prior code-first (/ddd:scan) index