Claude-Code-Workflow/.claude/commands/ddd/plan.md

---
name: plan
description: Document-driven planning pipeline — queries doc-index, explores codebase with doc-aware angles, clarifies ambiguities, and produces unified plan.json + TASK-*.json artifacts with doc_context traceability.
argument-hint: "[-y|--yes] [--explore] [--skip-explore] [--skip-clarify] \"task description or feature keyword\""
allowed-tools: TodoWrite(*), Agent(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*), Bash(*), Write(*), mcp__ace-tool__search_context(*)
---

## Auto Mode

When `--yes` or `-y`: Skip clarification (Phase 3), auto-select ddd:execute (Phase 5), skip interactive refinement.

# DDD Plan Command (/ddd:plan)

## Purpose

Full planning pipeline for document-driven development. Unlike simple context lookup, this command:
1. **Queries** the doc-index for instant context (features, requirements, components, ADRs)
2. **Explores** the codebase with doc-index-informed angles (not generic presets)
3. **Clarifies** ambiguities from exploration results and doc-index gaps
4. **Plans** with unified schema output (plan.json + TASK-*.json with doc_context)
5. **Hands off** to ddd:execute or other execution engines

### Key Differentiation from lite-plan
- Phase 1 provides instant context from doc-index (no cold-start exploration)
- Exploration angles are doc-index-informed (not generic preset selection)
- Tasks carry doc_context for traceability (features → requirements → code)
- Architecture decisions (ADRs) automatically surface as constraints

## Prerequisite

- `doc-index.json` must exist at `.workflow/.doc-index/doc-index.json`
- If not found → suggest running `/ddd:index-build` or `/ddd:scan` first

## Session Folder

```
.workflow/.doc-index/planning/{task-slug}-{YYYY-MM-DD}/
├── exploration-{angle}.json        # Per-angle exploration (Phase 2)
├── explorations-manifest.json      # Exploration index
├── plan.json                       # Plan overview (Phase 4)
├── planning-context.md             # Legacy context package (Phase 0+1 combined)
└── .task/
    ├── TASK-001.json
    └── TASK-002.json
```

---

## Phase 0: Parse Task Intent (enhanced)

### 0.1 Extract Keywords

From the user's task description, extract:
- **Domain keywords**: feature names, module names, business terms
- **Technical keywords**: file paths, class names, function names
- **Action type**: feature | bugfix | refactor | optimization | migration

### 0.2 Glossary Match

Cross-reference extracted keywords against `doc-index.json.glossary[]`:
- Match terms and aliases
- Expand user's vocabulary with canonical terms

### 0.3 Classify Complexity

Assess task complexity based on:
- Number of features potentially affected (from keyword matching)
- Whether new components are needed or existing ones modified
- Cross-feature impact (single feature vs multiple)

| Signal | Complexity |
|--------|-----------|
| Single feature, existing components | Low |
| 1-2 features, some new components | Medium |
| 3+ features, new architecture needed | High |

---

## Phase 1: Doc-Index Query

### 1.1 Feature Search

```
Search doc-index.json.features[] where:
  - name CONTAINS keyword (fuzzy)
  - tags INTERSECT keywords
  - requirementIds link to matching requirements
→ Output: matched feature IDs + names
```

### 1.2 Requirement Search

```
Search doc-index.json.requirements[] where:
  - title CONTAINS keyword
  - id matches explicit REQ-NNN reference
  - featureId matches found features
→ Output: matched requirement IDs + titles + priorities
```

### 1.3 Component Search

```
Search doc-index.json.technicalComponents[] where:
  - name CONTAINS keyword
  - codeLocations[].path CONTAINS file path keyword
  - codeLocations[].symbols CONTAINS symbol keyword
  - featureIds INTERSECT found features
→ Output: matched component IDs + code locations
```

### 1.4 ADR Search

```
Search doc-index.json.architectureDecisions[] where:
  - componentIds INTERSECT found components
→ Output: matched ADR IDs + titles
```

### 1.5 Action History Search

```
Search doc-index.json.actions[] where:
  - related to found features or components
→ Output: recent actions with descriptions
```

### 1.6 Build Impact Map

Assemble all found references into a structured impact map:

```json
{
  "affected_features": ["feat-auth"],
  "affected_requirements": ["REQ-001", "REQ-002"],
  "affected_components": ["tech-auth-service", "tech-user-model"],
  "architecture_constraints": ["ADR-001"],
  "recent_actions": ["task-123"],
  "complexity": "Medium"
}
```

Save as `planning-context.md` (legacy format for backward compatibility).

### Phase 1.7: Symbol Query (DeepWiki Bridge)

If DeepWiki is available (`deepwiki_feature_to_symbol_index` exists in doc-index.json):

1. Collect all `codeLocations[].path` from matched `technicalComponents[]`
2. Query DeepWiki: `POST /api/deepwiki/symbols-for-paths { paths: unique_paths }`
3. Build symbol_docs by component, sorted by type priority (class > function > method)
4. Populate `doc_context.symbol_docs[]` with Top-5 symbols per component

**Graceful degradation**: If DeepWiki unavailable → log warning → skip symbol injection → continue flow.

---

## Phase 2: Doc-Index-Guided Exploration (NEW)

Use Phase 1 results to **SELECT exploration angles intelligently**:

### 2.1 Angle Selection Logic

| Phase 1 Signal | Add Exploration Angle |
|----------------|----------------------|
| feat-auth or security-related ADR affected | `security` |
| Multiple features crossed (2+) | `integration-points` |
| New component needed (no matching tech-*) | `architecture` |
| Performance-related requirements | `performance` |
| Default (always included) | `patterns` + `dependencies` |

Select 1-4 angles total. More angles for higher complexity.

### 2.2 Skip & Trigger Conditions

| Complexity | Default Behavior | Override |
|-----------|-----------------|---------|
| **Low** | Auto-skip Phase 2 | `--explore` forces exploration |
| **Medium** | Ask user (unless `-y` → skip) | `--explore` forces, `--skip-explore` forces skip |
| **High** | Always run | `--skip-explore` forces skip |

Skip Phase 2 entirely when:
- Complexity is Low AND `--explore` not set
- OR `--skip-explore` flag is set
- OR `-y` flag AND complexity is Medium

### 2.3 Parallel Exploration

Launch 1-4 parallel `cli-explore-agent` runs:

```
For each selected angle:
  Agent(subagent_type="cli-explore-agent", prompt="
    Explore codebase for: {user task description}
    Angle: {angle}

    ## Doc-Index Context (pre-loaded)
    Features affected: {feature names + IDs}
    Components: {component names + code locations}
    Requirements: {requirement titles}
    Architecture decisions: {ADR titles + decisions}

    Focus exploration on {angle}-specific concerns.
    Output: explore-json-schema format.
  ")
```

Each agent receives doc-index context (feature-maps, tech-registry docs) to avoid cold-start.

### 2.4 Save Exploration Results

- Each exploration → `exploration-{angle}.json` (explore-json-schema)
- Manifest → `explorations-manifest.json`:

```json
{
  "explorations": [
    { "angle": "patterns", "path": "exploration-patterns.json", "file_count": 12 },
    { "angle": "security", "path": "exploration-security.json", "file_count": 8 }
  ],
  "total_files_discovered": 18,
  "timestamp": "ISO8601"
}
```

---

## Phase 3: Clarification (NEW)

### 3.1 Aggregate Clarification Needs

Collect from three sources:
1. **Exploration results**: `clarification_needs[]` from each exploration JSON
2. **Doc-index gaps**: unmapped requirements, orphan components, missing feature coverage
3. **Conflicting constraints**: contradictory architecture decisions, requirement priority conflicts

### 3.2 Deduplicate & Batch

- Merge duplicate/similar questions across exploration angles
- Group into rounds (max 4 questions per AskUserQuestion call)
- Prioritize: blocking questions first, nice-to-have last

### 3.3 Skip Conditions

Skip Phase 3 when:
- `-y` flag is set
- `--skip-clarify` flag is set
- No clarification needs collected from any source
- Complexity is Low AND Phase 2 was skipped (no exploration results to aggregate)

### 3.4 Execute Clarification

```
AskUserQuestion(questions=[
  {
    question: "Which authentication strategy should the new endpoint use?",
    header: "Auth strategy",
    options: [
      { label: "JWT Bearer (Recommended)", description: "Consistent with ADR-001 and existing auth middleware" },
      { label: "API Key", description: "Simpler but inconsistent with current architecture" },
      { label: "OAuth2", description: "Most flexible but higher implementation cost" }
    ],
    multiSelect: false
  }
])
```

Feed answers back into Phase 4 as constraints.

---

## Phase 4: Task Planning (NEW — produces plan.json + TASK-*.json)

### 4.1 Planning Strategy Selection

| Complexity | Strategy |
|-----------|---------|
| Low | Direct Claude planning (inline) |
| Medium | cli-lite-planning-agent with doc-index context |
| High | cli-lite-planning-agent with full exploration + doc-index context |

### 4.2 Planning Input Assembly

Combine:
- User's original task description
- Phase 1 impact map (features, requirements, components, ADRs)
- Phase 2 exploration results (if executed)
- Phase 3 clarification answers (if collected)
- Relevant feature-map and tech-registry doc excerpts

### 4.3 Execute Planning

For **Low complexity** (direct):
```
Generate plan.json + TASK-*.json directly based on assembled context.
```

For **Medium/High complexity**:
```
Agent(subagent_type="cli-lite-planning-agent", prompt="
  Task: {user task description}

  ## Doc-Index Impact Map
  {Phase 1 results}

  ## Exploration Context
  {Phase 2 results summary}

  ## Clarification Answers
  {Phase 3 answers}

  ## Architecture Constraints
  {ADR excerpts}

  Generate plan following plan-overview-base-schema.
  Generate tasks following task-schema.
  Include doc_context in both plan.json and each TASK-*.json.
")
```

### 4.4 Output Schema: plan.json

Follows `plan-overview-base-schema` with ddd-specific `doc_context` extension:

```json
{
  "summary": "...",
  "approach": "...",
  "task_ids": ["TASK-001", "TASK-002"],
  "task_count": 2,
  "complexity": "Medium",
  "doc_context": {
    "affected_features": ["feat-auth"],
    "affected_requirements": ["REQ-001", "REQ-002"],
    "affected_components": ["tech-auth-service"],
    "architecture_constraints": ["ADR-001"],
    "index_path": ".workflow/.doc-index/doc-index.json",
    "symbol_docs": [
      {
        "symbol_urn": "deepwiki:symbol:<path>#L<start>-L<end>",
        "name": "SymbolName",
        "type": "class|function|method",
        "doc_summary": "Generated documentation summary...",
        "source_path": "src/path/to/file.ts",
        "doc_path": ".deepwiki/file.md",
        "freshness": "fresh|stale|unknown"
      }
    ]
  },
  "_metadata": {
    "timestamp": "ISO8601",
    "source": "cli-lite-planning-agent",
    "plan_type": "feature",
    "schema_version": "2.0",
    "exploration_angles": ["patterns", "security"]
  }
}
```

### 4.5 Output Schema: TASK-*.json

Follows `task-schema` with ddd-specific `doc_context` extension:

```json
{
  "id": "TASK-001",
  "title": "Add rate limiting middleware",
  "description": "...",
  "depends_on": [],
  "convergence": {
    "criteria": ["Rate limiter middleware exists and is registered", "Tests pass"],
    "verification": "npm test -- --grep rate-limit",
    "definition_of_done": "API endpoints enforce rate limits per ADR-001 specifications"
  },
  "doc_context": {
    "feature_ids": ["feat-auth"],
    "requirement_ids": ["REQ-001"],
    "component_ids": ["tech-auth-service"],
    "adr_ids": ["ADR-001"],
    "feature_docs": ["feature-maps/auth.md"],
    "component_docs": ["tech-registry/auth-service.md"],
    "symbol_docs": [
      {
        "symbol_urn": "deepwiki:symbol:<path>#L<start>-L<end>",
        "name": "SymbolName",
        "type": "class|function|method",
        "doc_summary": "Generated documentation summary...",
        "source_path": "src/path/to/file.ts",
        "doc_path": ".deepwiki/file.md",
        "freshness": "fresh|stale|unknown"
      }
    ]
  },
  "files": [...],
  "implementation": [...]
}
```

### 4.6 Enrichment Rules

Each task is enriched with:
- `feature_ids`, `requirement_ids`, `component_ids`, `adr_ids` — traced from Phase 1
- Relevant feature-map and tech-registry doc paths
- Requirement acceptance criteria as convergence criteria source
- ADR decisions as implementation constraints

---

## Phase 5: Confirmation & Handoff Selection

### 5.1 Display Plan Summary

Show:
- Plan overview (summary, approach, complexity)
- Task list with dependencies
- Doc-index impact: which features/requirements/components will be affected
- Estimated scope

### 5.2 Handoff Options

| Option | Description | When |
|--------|-------------|------|
| **ddd:execute** | Document-aware execution (recommended) | Default for ddd workflow |
| **lite-execute** | Standard execution (no doc awareness) | When doc traceability not needed |
| **direct** | Output context, manual work | User prefers manual coding |
| **stop** | Planning only, no execution | Research/analysis tasks |

### 5.3 Auto-Selection

With `-y`: auto-select `ddd:execute`.

Without `-y`: present options via AskUserQuestion.

---

## Phase 6: Handoff

### 6.1 Build Execution Context

Build `executionContext` compatible with lite-execute format:

```json
{
  "plan_path": ".workflow/.doc-index/planning/{slug}/plan.json",
  "task_dir": ".workflow/.doc-index/planning/{slug}/.task/",
  "doc_index_path": ".workflow/.doc-index/doc-index.json",
  "exploration_manifest": ".workflow/.doc-index/planning/{slug}/explorations-manifest.json",
  "original_input": "user's task description"
}
```

### 6.2 Invoke Selected Engine

| Selection | Action |
|-----------|--------|
| `ddd:execute` | Invoke `/ddd:execute --in-memory` with executionContext |
| `lite-execute` | Invoke `/workflow:lite-execute` with plan.json path |
| `direct` | Display context package + file list for manual work |
| `stop` | Output plan summary, end here |

---

## Flags

| Flag | Effect |
|------|--------|
| `-y, --yes` | Skip clarification, auto-select ddd:execute |
| `--explore` | Force Phase 2 exploration even for Low complexity |
| `--skip-explore` | Skip Phase 2 (doc-index-guided exploration) |
| `--skip-clarify` | Skip Phase 3 (clarification) only |

## Output

- **Primary**: plan.json + TASK-*.json in session folder
- **Secondary**: planning-context.md (legacy format)
- **Exploration**: exploration-{angle}.json files (if Phase 2 ran)
- **Console**: Plan summary with doc-index impact

## Integration Points

- **Input from**: `doc-index.json` (built by `/ddd:index-build` or `/ddd:scan`)
- **Output to**: `/ddd:execute`, `/workflow:lite-execute`, `/ddd:sync` post-task
- **Schemas**: `plan-overview-ddd-schema.json` (plan output), `task-schema.json` + `task-ddd-extension-schema.json` (task output), `explore-json-schema.json`
- **Triggers**: Before any development task in ddd workflow