mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-07 16:41:06 +08:00
feat: add DDD scan, sync, and update commands for document indexing
- Implemented `/ddd:scan` command to analyze existing codebases and generate document indices without specifications. This includes phases for project structure analysis, component discovery, feature inference, and requirement extraction. - Introduced `/ddd:sync` command for post-task synchronization, updating document indices, generating action logs, and refreshing feature/component documentation after development tasks. - Added `/ddd:update` command for lightweight incremental updates to the document index, allowing for quick impact checks during development and pre-commit validation. - Created `execute.md` for the coordinator role in the team lifecycle, detailing the spawning of executor team-workers for IMPL tasks. - Added `useHasHydrated` hook to determine if the Zustand workflow store has been rehydrated from localStorage, improving state management reliability.
This commit is contained in:
catlog22
451
.claude/commands/ddd/plan.md
Normal file
451
.claude/commands/ddd/plan.md
Normal file
@@ -0,0 +1,451 @@
|
||||
---
|
||||
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 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"
|
||||
},
|
||||
"_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"]
|
||||
},
|
||||
"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
|
||||
Reference in New Issue
Block a user