--- name: index-build description: Build document index from spec-generator outputs + codebase mapping. Requires existing spec session. For projects without specs, use /ddd:scan instead. argument-hint: "[-y|--yes] [-s|--spec ] [--from-scratch]" allowed-tools: 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 provided: Load from .workflow/.doc-index/specs// OR .workflow/.spec// 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: ```bash 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`: ```markdown --- 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`: ```markdown --- 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 ```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 ` | 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