claude-code-workflow 7.2.11 → 7.2.12

package/.claude/commands/ddd/doc-refresh.md

@@ -1,218 +0,0 @@
----
-name: doc-refresh
-description: Incrementally update affected documents based on changed components/features. Layer 3 → 2 → 1 selective refresh. Called by sync/update or used standalone.
-argument-hint: "[-y|--yes] [--components <id1,id2,...>] [--features <id1,id2,...>] [--minimal] [--dry-run]"
-allowed-tools: TodoWrite(*), Agent(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*), Bash(*), Edit(*), Write(*)
----
-
-## Auto Mode
-
-When `--yes` or `-y`: Auto-update affected documents without confirmation prompts.
-
-# DDD Doc Refresh Command (/ddd:doc-refresh)
-
-## Purpose
-
-Incrementally update **only the affected documents** after code changes. Unlike `/ddd:doc-generate` (full generation), this command selectively refreshes documents for specific components and features.
-
-```
-affected component/feature IDs → update tech-registry (L3) → update feature-maps (L2) → update indexes (L1)
-```
-
-## When to Use
-
-| Scenario | Use |
-|----------|-----|
-| After `/ddd:sync` detects code changes | **doc-refresh** (auto-called by sync) |
-| After `/ddd:update` traces impact | **doc-refresh** (auto-called by update) |
-| Manual refresh of specific component docs | **doc-refresh --components tech-auth-service** |
-| Quick metadata-only update | **doc-refresh --minimal --components tech-auth-service** |
-| Preview what would change | **doc-refresh --dry-run --components tech-auth-service** |
-
-## Prerequisite
-
-- `doc-index.json` must exist at `.workflow/.doc-index/doc-index.json`
-- At least one of `--components` or `--features` must be provided (or received from caller)
-- Corresponding documents must already exist (generated by `/ddd:doc-generate`)
-- If documents missing → error: "Documents not found. Run /ddd:doc-generate first."
-
-## Phase 1: Determine Refresh Scope
-
-### 1.1 Resolve Affected Entities
-
-```
-IF --components provided:
-  affected_components = parse comma-separated IDs
-  affected_features = lookup featureIds for each component in doc-index.json
-
-IF --features provided:
-  affected_features = parse comma-separated IDs
-  affected_components = union of all component IDs linked to features
-
-Merge both sets if both flags provided.
-```
-
-### 1.2 Validate Entities Exist
-
-For each ID, verify it exists in doc-index.json. Warn and skip missing IDs.
-
-### 1.3 Check Document Existence
-
-For each affected entity, check if corresponding .md file exists:
-- Missing Layer 3 doc → warn: "Component doc not found. Run /ddd:doc-generate first."
-- Missing Layer 2 doc → warn: "Feature doc not found. Run /ddd:doc-generate first."
-
-## Phase 2: Layer 3 — Update Component Docs
-
-For each affected component's `tech-registry/{slug}.md`:
-
-```bash
-ccw cli -p "PURPOSE: Update component documentation for {component.name} after code changes
-TASK:
-• Update code locations and line ranges
-• Update symbol list (add new exports, remove deleted)
-• Add change entry to history table
-• Refresh usage examples if API changed
-MODE: write
-CONTEXT: @{component.codeLocations[].path}
-EXPECTED: Updated markdown with current API state
-CONSTRAINTS: Preserve existing structure | Only update changed sections
-" --tool gemini --mode write --cd .workflow/.doc-index/tech-registry/
-```
-
-Update frontmatter:
-```markdown
----
-layer: 3
-component_id: tech-auth-service
-generated_at: {original}
-last_updated: ISO8601
----
-```
-
-### 2.1 Minimal Mode (--minimal)
-
-With `--minimal`, only update:
-- `codeLocations` in frontmatter
-- `last_updated` timestamp
-- Skip CLI call for content regeneration
-
-## Phase 3: Layer 2 — Update Feature Docs
-
-For each affected feature's `feature-maps/{slug}.md`:
-
-```bash
-ccw cli -p "PURPOSE: Update feature documentation for {feature.name} after component changes
-TASK:
-• Update component list if new components added
-• Update status if requirements now fully implemented
-• Add change entry to history table
-• Refresh integration guide if component APIs changed
-MODE: write
-CONTEXT: @.workflow/.doc-index/tech-registry/{affected-components}.md
-EXPECTED: Updated markdown reflecting current feature state
-CONSTRAINTS: Reference updated Layer 3 docs | Preserve business language
-" --tool gemini --mode write --cd .workflow/.doc-index/feature-maps/
-```
-
-Update frontmatter:
-```markdown
----
-layer: 2
-feature_id: feat-auth
-depends_on_layer3: [tech-auth-service, tech-user-model]
-generated_at: {original}
-last_updated: ISO8601
----
-```
-
-### 3.1 Minimal Mode (--minimal)
-
-With `--minimal`, only update:
-- Component list in frontmatter
-- Feature status (if requirements mapping changed)
-- `last_updated` timestamp
-- Skip CLI call for content regeneration
-
-## Phase 4: Layer 1 — Update Index Docs (conditional)
-
-### 4.1 Trigger Conditions
-
-| Condition | Action |
-|-----------|--------|
-| New component registered | Update `tech-registry/_index.md` |
-| Component removed | Update `tech-registry/_index.md` |
-| Feature status changed | Update `feature-maps/_index.md` |
-| New feature added | Update `feature-maps/_index.md` + README.md |
-| Major architecture change | Update ARCHITECTURE.md |
-| New action-log entry | Update `action-logs/_index.md` |
-
-### 4.2 Update _index.md Files
-
-Refresh table entries for affected features/components:
-- `feature-maps/_index.md`
-- `tech-registry/_index.md`
-- `action-logs/_index.md` (if new action entry)
-
-### 4.3 Update Overview Docs (only if significant)
-
-If new features added or major status changes:
-
-```bash
-ccw cli -p "PURPOSE: Update project overview docs after feature changes
-TASK:
-• Update README.md feature list
-• Update ARCHITECTURE.md if new components added
-• Update planning/_index.md with new planning sessions
-MODE: write
-CONTEXT: @.workflow/.doc-index/feature-maps/*.md @.workflow/.doc-index/doc-index.json
-EXPECTED: Updated overview docs with current project state
-CONSTRAINTS: High-level only | Link to Layer 2 for details
-" --tool gemini --mode write --cd .workflow/.doc-index/
-```
-
-### 4.4 Skip Layer 1
-
-With `--minimal` or when changes are minor (only code location updates): skip Layer 1 entirely.
-
-## Phase 5: Refresh Report
-
-```
-Document Refresh Report
-
-Affected Scope:
-  Components: {N} ({component IDs})
-  Features: {N} ({feature IDs})
-
-Updated:
-  Layer 3 (Components): {N} documents refreshed
-  Layer 2 (Features):   {N} documents refreshed
-  Layer 1 (Indexes):    {N} documents refreshed (or "skipped")
-
-Mode: {full|minimal}
-```
-
-## Dry-Run Mode
-
-With `--dry-run`:
-- Execute Phase 1 (scope determination)
-- Display what would be updated (affected files list)
-- Skip all file writes (Phase 2-4)
-- Output: "Dry-run complete. {N} documents would be refreshed."
-
-## Flags
-
-| Flag | Effect |
-|------|--------|
-| `-y, --yes` | Auto-confirm all updates |
-| `--components <ids>` | Comma-separated component IDs to refresh |
-| `--features <ids>` | Comma-separated feature IDs to refresh |
-| `--minimal` | Only update metadata/frontmatter, skip content regeneration |
-| `--dry-run` | Preview what would change without modifying files |
-
-## Integration Points
-
-- **Input from**: `doc-index.json`, affected entity IDs (from `/ddd:sync` or `/ddd:update`)
-- **Called by**: `/ddd:sync` (after change detection + index update), `/ddd:update` (after impact tracing + index update)
-- **Standalone**: Can be run independently to refresh specific component/feature docs
-- **Prerequisite**: Documents must exist (generated by `/ddd:doc-generate`)

package/.claude/commands/ddd/execute.md

@@ -1,416 +0,0 @@
----
-name: execute
-description: Document-aware execution engine — executes plan.json + TASK-*.json with doc-index context enrichment, per-batch impact verification, and post-completion doc sync.
-argument-hint: "[-y|--yes] [--skip-sync] [--skip-verify] [--plan <path>] [--in-memory] \"optional task description\""
-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, 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[]`
-- Load `doc_context.symbol_docs[]` documentation content (if present)
-
-### 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
-
-```markdown
-## 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}
-
-### Symbol Documentation
-${if doc_context.symbol_docs is non-empty:
-  for each component in doc_context.component_ids:
-    #### ${component.name} Symbols (Top-5)
-    ${for each symbol in component.symbol_docs.slice(0, 5):
-      - **${symbol.name}** (${symbol.type}): ${symbol.doc_summary}
-        Source: `${symbol.source_path}` | Freshness: ${symbol.freshness}
-    }
-}
-
-### 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**:
-```bash
-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:
-
-```json
-{
-  "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:
-
-```json
-{
-  "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