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

name, description, argument-hint, allowed-tools

name	description	argument-hint	allowed-tools
execute	Document-aware execution engine — executes plan.json + TASK-*.json with doc-index context enrichment, per-batch impact verification, and post-completion doc sync.	[-y|--yes] [--skip-sync] [--skip-verify] [--plan <path>] [--in-memory] "optional task description"	TodoWrite(*), Agent(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*), Bash(*), Edit(*), Write(*), mcp__ace-tool__search_context(*)

Auto Mode

When --yes or -y: Auto-confirm all decisions, auto-sync after completion.

DDD Execute Command (/ddd:execute)

Purpose

Same execution engine model as lite-execute, but each step is doc-index-aware:

• Tasks are enriched with feature context, component docs, and architecture constraints
• Per-batch impact verification ensures changes stay within planned scope
• Post-completion automatically syncs the document index

Core Differentiator

Unlike generic execution engines, ddd:execute leverages the document architecture:

• Feature-maps provide business context for each task
• Tech-registry provides implementation patterns to follow
• ADRs surface as hard constraints during execution
• Requirement acceptance criteria inform convergence verification

Prerequisite

• plan.json + .task/TASK-*.json files from /ddd:plan
• doc-index.json at .workflow/.doc-index/doc-index.json
• If --in-memory: receives executionContext from /ddd:plan handoff

---

Step 1: Initialize & Load Context

1.1 Locate Plan

IF --in-memory:
  Load executionContext from ddd:plan handoff
  plan_path = executionContext.plan_path
  task_dir = executionContext.task_dir
ELIF --plan <path>:
  plan_path = <path>
  task_dir = {dirname(path)}/.task/
ELSE:
  Scan .workflow/.doc-index/planning/ for most recent session
  plan_path = {latest_session}/plan.json
  task_dir = {latest_session}/.task/

1.2 Load Plan & Tasks

• Read plan.json — validate against plan-overview-base-schema
• Read all TASK-*.json from .task/ directory — validate against task-schema
• Read doc-index.json from .workflow/.doc-index/

1.3 Pre-Load Doc Context

For each task with doc_context:

• Load referenced feature_docs (feature-maps/{slug}.md)
• Load referenced component_docs (tech-registry/{slug}.md)
• Load ADR excerpts from doc-index architectureDecisions[]
• Extract requirement acceptance criteria from doc-index requirements[]

1.4 Echo Strategy

Display execution summary:

DDD Execute: {plan.summary}
Complexity: {plan.complexity}
Tasks: {plan.task_count}

Doc-Index Impact:
  Features: {doc_context.affected_features}
  Requirements: {doc_context.affected_requirements}
  Components: {doc_context.affected_components}
  Constraints: {doc_context.architecture_constraints}

Execution plan: {batch count} batches, {parallel tasks} parallel where possible

---

Step 2: Task Grouping & Batch Creation

2.1 Extract Dependencies

From each TASK-*.json, read depends_on[] to build dependency graph.

2.2 Group into Batches

Batch 1: Tasks with no dependencies (depends_on: [])
Batch 2: Tasks depending only on Batch 1 tasks
Batch 3: Tasks depending on Batch 1 + 2 tasks
...

Within each batch, tasks with the same parallel_group can run concurrently.

2.3 Assign Executor per Task

Signal	Executor
meta.execution_config.method == "cli"	CLI tool (gemini/codex/qwen)
meta.execution_config.method == "agent"	Agent (code-developer/universal-executor)
Default	Agent (code-developer)

---

Step 3: Doc-Enriched Execution

For each task in batch order, build an enriched prompt:

3.1 Task Prompt Template

## Goal
${plan.summary} — specifically: ${task.title}

## Document Context

### Feature: ${feature.name} (${feature.id})
${feature-map content excerpt — overview + requirements section}

### Components
${for each component in task.doc_context.component_ids:
  tech-registry excerpt — responsibility + code locations + key patterns}

### Architecture Constraints
${for each ADR in task.doc_context.adr_ids:
  ADR title + decision + rationale from doc-index}

### Requirement Acceptance Criteria
${for each requirement in task.doc_context.requirement_ids:
  requirement title + priority + success criteria from doc-index}

## Task Details
${task.description}

### Files to Modify
${task.files[] — path, action, changes}

### Implementation Steps
${task.implementation[] — step-by-step guide}

## Done When
${task.convergence.criteria[]}
${task.convergence.verification}

3.2 Execute Task

Agent execution:

Agent(subagent_type="code-developer", prompt="{enriched prompt}")

CLI execution:

ccw cli -p "{enriched prompt}" --tool {cli_tool} --mode write

3.3 Record & Persist Result

After each task completes:

• Update TASK-*.json with status, executed_at, result
• Track result.files_modified for impact verification
• Persist result to TASK-{id}.result.json alongside the task file:

{
  "task_id": "TASK-001",
  "status": "completed|failed",
  "executed_at": "ISO8601",
  "executor": "code-developer|gemini|codex",
  "files_modified": [
    { "path": "src/services/auth.ts", "action": "modified", "symbols_changed": ["AuthService.validate"] },
    { "path": "src/routes/login.ts", "action": "created", "symbols_changed": ["loginRoute"] }
  ],
  "convergence_result": {
    "criteria_met": ["Rate limiter middleware exists"],
    "criteria_unmet": [],
    "verification_output": "test output snippet..."
  },
  "error": null
}

This file serves as the durable handoff between execute and sync — survives process interruptions.

---

Step 4: Per-Batch Impact Verification

After each batch completes (unless --skip-verify):

4.1 Trace Changed Files

For each file modified in the batch:

changed_file → match to doc-index.technicalComponents[].codeLocations[].path
  → component_ids → featureIds → requirementIds

4.2 Scope Verification

Compare actual impact to planned impact:

Planned scope:
  Features: [feat-auth]
  Components: [tech-auth-service, tech-user-model]

Actual impact:
  Features: [feat-auth]              ← OK, within scope
  Components: [tech-auth-service, tech-user-model, tech-email-service]
                                     ← WARNING: tech-email-service not in plan

4.3 Flag Unexpected Impact

If changes affect features/components NOT in plan.doc_context:

• Warning: Display unexpected impact
• No -y: Ask user to confirm continuation
• With -y: Log warning, continue execution

4.4 Skip Conditions

Skip verification when:

• --skip-verify flag is set
• Only 1 batch (no intermediate verification needed for simple plans)

---

Step 4.5: Post-Execution Verify Gate

After all batches complete, before doc sync (unless --skip-verify):

4.5.1 Convergence Verification

For each completed task with convergence.verification:

Execute: {task.convergence.verification}
  → e.g., "npm test -- --grep rate-limit"
Record: pass/fail → update TASK-{id}.result.json.convergence_result

4.5.2 Build & Lint Check

Run project build command (if configured):
  → npm run build / tsc --noEmit / etc.
Run project lint command (if configured):
  → npm run lint / eslint src/ / etc.

If build or lint fails:

• No -y: Display errors, ask user: fix now / continue anyway / abort
• With -y: Log warning, continue (non-blocking)

4.5.3 Regression Test

Run project test suite:
  → npm test / pytest / etc.
Compare: test results before execution (baseline) vs after

If tests fail:

• No -y: Display failures, ask user: fix now / skip sync / abort
• With -y: Log failures as warning in execution results, continue

4.5.4 Verify Summary

Verify Gate Results:
  Convergence: {passed}/{total} tasks verified
  Build: pass|fail|skipped
  Lint: pass|fail|skipped
  Tests: {passed}/{total} ({new_failures} regressions)

  Gate: PASS / WARN (continue with warnings) / FAIL (blocked)

4.5.5 Persist Verify Manifest

Write execution-manifest.json to session folder:

{
  "session_id": "{session-id}",
  "plan_path": "planning/{slug}/plan.json",
  "completed_at": "ISO8601",
  "tasks": [
    {
      "task_id": "TASK-001",
      "status": "completed",
      "result_file": ".task/TASK-001.result.json"
    }
  ],
  "files_modified": [
    { "path": "src/services/auth.ts", "action": "modified", "task_id": "TASK-001" },
    { "path": "src/routes/login.ts", "action": "created", "task_id": "TASK-001" }
  ],
  "verify": {
    "convergence": { "passed": 2, "total": 2 },
    "build": "pass",
    "lint": "pass",
    "tests": { "passed": 42, "total": 42, "regressions": 0 },
    "gate": "PASS"
  }
}

This manifest is the single source of truth consumed by ddd:sync --from-manifest.

---

Step 5: Post-Completion Doc Sync

After all batches complete (unless --skip-sync):

5.1 Auto-Trigger ddd:sync

Invoke /ddd:sync [-y] --task-id {session-id} --from-manifest {session}/execution-manifest.json "{plan.summary}"

Note: /ddd:sync automatically creates a backup of doc-index.json before modifications.

When --from-manifest is provided, sync uses the execution manifest as its primary data source instead of git diff. This ensures:

• Precise file-level and symbol-level change tracking (from TASK-*.result.json)
• Task-to-file attribution (which task modified which file)
• Convergence verification results carried forward
• Survives process interruptions (manifest is persisted to disk)

Fallback: If manifest is unavailable (e.g., manual mode), sync falls back to git diff discovery.

5.2 Generate Action Log

Create action entry with:

• All tasks executed and their results
• Files modified across all batches
• Features and requirements addressed

5.3 Update Feature Status

Based on execution results:

• Requirements with verified convergence → update status
• Features with all requirements met → status: "implemented"

---

Step 6: Summary & Follow-up

6.1 Execution Results

DDD Execute Complete

Tasks: {completed}/{total} ({failed} failed)
Files modified: {count}
Batches: {batch_count}

Doc-Index Changes:
  Features updated: {list}
  Components updated: {list}
  New components registered: {list}
  Requirements addressed: {list}

Convergence:
  {for each task: task.id — criteria met: X/Y}

6.2 Follow-up Suggestions

Based on execution results, suggest:

• New issues: If unexpected scope expansion was detected
• Additional tests: If convergence criteria only partially met
• Documentation gaps: If new components were created without docs
• Next tasks: If plan had tasks marked as future/deferred

---

Flags

Flag	Effect
-y, --yes	Auto-confirm, auto-sync
--skip-sync	Skip post-completion ddd:sync (Step 5)
--skip-verify	Skip per-batch impact verification (Step 4) AND post-execution verify gate (Step 4.5)
--plan <path>	Explicit plan.json path
--in-memory	Accept executionContext from ddd:plan handoff

Integration Points

• Input from: /ddd:plan output (plan.json + TASK-*.json), doc-index.json
• Output to: Updated doc-index.json (via ddd:sync), TASK-*.result.json (per-task), execution-manifest.json (session-level)
• Schemas: plan-overview-ddd-schema.json (input), task-schema.json + task-ddd-extension-schema.json (input), doc-index.json (enrichment)
• Delegates to: /ddd:sync for post-completion synchronization