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

name, description, argument-hint, allowed-tools

name	description	argument-hint	allowed-tools
plan	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.	[-y|--yes] [--explore] [--skip-explore] [--skip-clarify] "task description or feature keyword"	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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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