Claude-Code-Workflow/.claude/commands/ddd/doc-generate.md

name, description, argument-hint, allowed-tools

name	description	argument-hint	allowed-tools
doc-generate	Generate full document tree from doc-index.json. Layer 3 (components) → Layer 2 (features) → Layer 1 (indexes/overview). Standalone or called by scan/index-build.	[-y|--yes] [--layer <3|2|1|all>] [--force] [--skip-overview] [--skip-schema]	TodoWrite(*), Agent(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*), Bash(*), Edit(*), Write(*)

Auto Mode

When --yes or -y: Auto-generate all layers without confirmation prompts.

DDD Doc Generate Command (/ddd:doc-generate)

Purpose

Generate the complete document tree from doc-index.json. Single source of truth for all document generation logic, following bottom-up Layer 3 → 2 → 1 strategy.

doc-index.json → tech-registry/*.md (L3) → feature-maps/*.md (L2) → _index.md + README + ARCHITECTURE (L1)

When to Use

Scenario	Use
After /ddd:scan builds doc-index.json	doc-generate (auto-called by scan)
After /ddd:index-build builds doc-index.json	doc-generate (auto-called by index-build)
Rebuild all docs from existing index	doc-generate --force
Regenerate only component docs	doc-generate --layer 3
Regenerate only overview/index docs	doc-generate --layer 1

Prerequisite

• doc-index.json must exist at .workflow/.doc-index/doc-index.json
• If not found → error: "No doc-index.json found. Run /ddd:scan or /ddd:index-build first."

Storage Output

.workflow/.doc-index/
├── doc-index.json              ← Input (read-only, not modified)
├── SCHEMA.md                   ← Schema documentation
├── README.md                   ← Project overview (Layer 1)
├── ARCHITECTURE.md             ← Architecture overview (Layer 1)
├── feature-maps/               ← Feature documentation (Layer 2)
│   ├── _index.md
│   └── {feature-slug}.md
├── tech-registry/              ← Component documentation (Layer 3)
│   ├── _index.md
│   └── {component-slug}.md
└── sessions/
    └── _index.md               ← Planning sessions index (Layer 1)

Phase 1: Load & Validate

1.1 Load doc-index.json

Read .workflow/.doc-index/doc-index.json
Validate: features[], technicalComponents[] are non-empty arrays

1.2 Schema Version Check

const schemaVersion = docIndex.schema_version || '0.0';
if (schemaVersion !== '1.0') {
  warn(`Schema version mismatch: found ${schemaVersion}, expected 1.0`);
}

1.3 Determine Generation Scope

IF --layer 3:  generate Layer 3 only
IF --layer 2:  generate Layer 2 only (requires Layer 3 exists)
IF --layer 1:  generate Layer 1 only (requires Layer 2 exists)
IF --layer all (default): generate Layer 3 → 2 → 1

1.4 Check Existing Docs

IF docs already exist AND NOT --force:
  Warn: "Documents already exist. Use --force to overwrite."
  Ask user (unless -y → overwrite)

Phase 2: Layer 3 — Component Documentation

For each component in technicalComponents[]:

ccw cli -p "PURPOSE: Generate component documentation for {component.name}
TASK:
• Document component purpose and responsibility
• List exported symbols (classes, functions, types)
• Document dependencies (internal and external)
• Include code examples for key APIs
• Document integration points with other components
MODE: write
CONTEXT: @{component.codeLocations[].path}
EXPECTED: Markdown file with: Overview, API Reference, Dependencies, Usage Examples
CONSTRAINTS: Focus on public API | Include type signatures
" --tool gemini --mode write --cd .workflow/.doc-index/tech-registry/

Output: .workflow/.doc-index/tech-registry/{component-slug}.md

Frontmatter:

---
layer: 3
component_id: tech-{slug}
name: ComponentName
type: service|controller|model|...
features: [feat-auth]
code_locations:
  - path: src/services/auth.ts
    symbols: [AuthService, AuthService.login]
generated_at: ISO8601
---

Sections: Responsibility, Code Locations, Related Requirements, Architecture Decisions, Dependencies (in/out)

Phase 3: Layer 2 — Feature Documentation

For each feature in features[]:

ccw cli -p "PURPOSE: Generate feature documentation for {feature.name}
TASK:
• Describe feature purpose and business value
• List requirements (from requirementIds)
• Document components involved (from techComponentIds)
• Include architecture decisions (from adrIds)
• Provide integration guide
MODE: write
CONTEXT: @.workflow/.doc-index/tech-registry/{related-components}.md
EXPECTED: Markdown file with: Overview, Requirements, Components, Architecture, Integration
CONSTRAINTS: Reference Layer 3 component docs | Business-focused language
" --tool gemini --mode write --cd .workflow/.doc-index/feature-maps/

Output: .workflow/.doc-index/feature-maps/{feature-slug}.md

Frontmatter:

---
layer: 2
feature_id: feat-{slug}
name: Feature Name
epic_id: EPIC-NNN|null
status: implemented|in-progress|planned|partial
requirements: [REQ-001, REQ-002]
components: [tech-auth-service, tech-user-model]
depends_on_layer3: [tech-auth-service, tech-user-model]
tags: [auth, security]
generated_at: ISO8601
---

Sections: Overview, Requirements (with mapping status), Technical Components, Architecture Decisions, Change History

Phase 4: Layer 1 — Index & Overview Documentation

4.1 Index Documents

Generate catalog files:

• feature-maps/_index.md — Feature overview table with status
• tech-registry/_index.md — Component registry table with types
• action-logs/_index.md — Action history table (empty initially for new projects)

4.2 README.md (unless --skip-overview)

ccw cli -p "PURPOSE: Generate project README with overview and navigation
TASK:
• Project summary and purpose
• Quick start guide
• Navigation to features, components, and architecture
• Link to doc-index.json
MODE: write
CONTEXT: @.workflow/.doc-index/doc-index.json @.workflow/.doc-index/feature-maps/_index.md
EXPECTED: README.md with: Overview, Quick Start, Navigation, Links
CONSTRAINTS: High-level only | Entry point for new developers
" --tool gemini --mode write --cd .workflow/.doc-index/

4.3 ARCHITECTURE.md (unless --skip-overview)

ccw cli -p "PURPOSE: Generate architecture overview document
TASK:
• System design overview
• Component relationships and dependencies
• Key architecture decisions (from ADRs)
• Technology stack
MODE: write
CONTEXT: @.workflow/.doc-index/doc-index.json @.workflow/.doc-index/tech-registry/*.md
EXPECTED: ARCHITECTURE.md with: System Design, Component Diagram, ADRs, Tech Stack
CONSTRAINTS: Architecture-focused | Reference component docs for details
" --tool gemini --mode write --cd .workflow/.doc-index/

4.4 sessions/_index.md (unless --skip-overview)

ccw cli -p "PURPOSE: Generate planning sessions index
TASK:
• List all planning session folders chronologically
• Link to each session's plan.json
• Show session status and task count
MODE: write
CONTEXT: @.workflow/.doc-index/planning/*/plan.json
EXPECTED: sessions/_index.md with: Session List, Links, Status
CONSTRAINTS: Chronological order | Link to session folders
" --tool gemini --mode write --cd .workflow/.doc-index/sessions/

Layer 1 frontmatter:

---
layer: 1
depends_on_layer2: [feat-auth, feat-orders]
generated_at: ISO8601
---

Phase 5: SCHEMA.md (unless --skip-schema)

5.1 Generate Schema Documentation

ccw cli -p "PURPOSE: Document doc-index.json schema structure and versioning
TASK:
• Document current schema structure (all fields)
• Define versioning policy (semver: major.minor)
• Document migration protocol for version upgrades
• Provide examples for each schema section
MODE: write
CONTEXT: @.workflow/.doc-index/doc-index.json
EXPECTED: SCHEMA.md with: Schema Structure, Versioning Policy, Migration Protocol, Examples
CONSTRAINTS: Complete field documentation | Clear migration steps
" --tool gemini --mode write --cd .workflow/.doc-index/

5.2 Versioning Policy

Semantic Versioning:

• Major (X.0): Breaking changes (field removal, type changes, incompatible structure)
• Minor (X.Y): Non-breaking additions (new optional fields, new sections)

Migration Protocol:

1. Detect version mismatch in ddd:plan/ddd:sync
2. Log warning with migration instructions
3. Provide migration script or regeneration option
4. Update schema_version after successful migration

Phase 6: Generation Report

Document Generation Report

Project: {name}
Source: doc-index.json (build_path: {spec-first|code-first})

Generated:
  Layer 3 (Components): {N} documents in tech-registry/
  Layer 2 (Features):   {N} documents in feature-maps/
  Layer 1 (Indexes):    {N} documents (_index.md, README, ARCHITECTURE)
  Schema:               SCHEMA.md

Total: {N} documents generated

Flags

Flag	Effect
-y, --yes	Auto-confirm all decisions
--layer <3|2|1|all>	Generate specific layer only (default: all)
--force	Overwrite existing documents
--skip-overview	Skip README.md, ARCHITECTURE.md, sessions/_index.md
--skip-schema	Skip SCHEMA.md generation

Integration Points

• Input from: doc-index.json (from /ddd:scan or /ddd:index-build)
• Called by: /ddd:scan (after index assembly), /ddd:index-build (after index assembly)
• Standalone: Can be run independently on any project with existing doc-index.json
• Output: Complete document tree in .workflow/.doc-index/