Skip to content

Commit 7ee9b57

Browse files
author
catlog22
committed
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.
1 parent a9469a5 commit 7ee9b57

18 files changed

Lines changed: 2737 additions & 153 deletions

File tree

‎.claude/commands/ddd/auto.md‎

Lines changed: 359 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,359 @@
1+
---
2+
name: auto
3+
description: Chain command - automated document-driven development flow. Detects project state and runs the appropriate chain for new or existing projects.
4+
argument-hint: "[-y|--yes] [--skip-spec] [--skip-build] [--spec <session-id>] [--resume] \"project idea or task description\""
5+
allowed-tools: TodoWrite(*), Agent(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*), Bash(*), Edit(*), Write(*)
6+
---
7+
8+
## Auto Mode
9+
10+
When `--yes` or `-y`: All sub-commands run in auto mode. Minimal human intervention.
11+
12+
# DDD Auto Command (/ddd:auto)
13+
14+
## Purpose
15+
16+
Orchestrate the full document-driven development lifecycle. **Adapts to project state** — works for both new projects and existing codebases.
17+
18+
## Flow Variants
19+
20+
### Variant 1: New Project (no code, no spec)
21+
```
22+
spec-generator → ddd:index-build → ddd:plan → ddd:execute → verify → ddd:sync
23+
```
24+
25+
### Variant 2: Existing Project (has code, no spec)
26+
```
27+
ddd:scan → ddd:plan → ddd:execute → verify → ddd:sync
28+
```
29+
30+
### Variant 3: Existing Project with Spec (has code + spec)
31+
```
32+
ddd:index-build → ddd:plan → ddd:execute → verify → ddd:sync
33+
```
34+
35+
### Variant 4: Index Exists (has doc-index.json)
36+
```
37+
ddd:plan → ddd:execute → verify → ddd:sync
38+
```
39+
40+
## Flow Diagram
41+
42+
```
43+
┌────────────────────────────────────────────────────────────┐
44+
│ /ddd:auto │
45+
│ │
46+
│ Stage 0: Detect Project State │
47+
│ ┌───────────────────────────────────┐ │
48+
│ │ has_codebase? has_spec? has_index?│ │
49+
│ └────────────┬──────────────────────┘ │
50+
│ │ │
51+
│ ┌──────────┼──────────────┐ │
52+
│ ▼ ▼ ▼ │
53+
│ No Code Code Only Code + Spec Index Exists │
54+
│ │ │ │ │ │
55+
│ ▼ │ │ │ │
56+
│ Stage 1 │ │ │ │
57+
│ Spec Gen │ │ │ │
58+
│ │ │ │ │ │
59+
│ ▼ │ ▼ │ │
60+
│ Stage 2a Stage 2b Stage 2a │ │
61+
│ index-build ddd:scan index-build │ │
62+
│ (Path A or Path B auto-detected) │ │
63+
│ │ │ │
64+
│ └───────────────────┬───────────────────┘ │
65+
│ ▼ │
66+
│ Stage 3: DDD Plan (enhanced) │
67+
│ (doc-index query + exploration + │
68+
│ clarification + task planning) │
69+
│ │ │
70+
│ ▼ │
71+
│ Stage 4: Execute │
72+
│ (ddd:execute = doc-aware execution) │
73+
│ │ │
74+
│ ▼ │
75+
│ Stage 4.5: Verify Gate │
76+
│ (convergence + build + lint + tests │
77+
│ → execution-manifest.json) │
78+
│ │ │
79+
│ PASS / WARN → continue │
80+
│ FAIL → ask user │
81+
│ │ │
82+
│ ▼ │
83+
│ Stage 5: Doc Sync │
84+
│ (auto-triggered with --from-manifest, │
85+
│ or manual /ddd:sync) │
86+
└────────────────────────────────────────────────────────────┘
87+
```
88+
89+
## Stage 0: Project State Detection
90+
91+
Automatically detect project state to determine which stages to run:
92+
93+
```
94+
Check 1: doc-index.json exists? → has_index
95+
Check 2: SPEC-* directories exist? → has_spec
96+
Check 3: Source code directories? → has_codebase
97+
Check 4: project-tech.json exists? → has_tech_analysis
98+
```
99+
100+
### Decision Matrix
101+
102+
| has_codebase | has_spec | has_index | Action |
103+
|:---:|:---:|:---:|--------|
104+
| No | No | No | Stage 1 (spec-gen) → Stage 2a (index-build) → Stage 3-5 |
105+
| No | Yes | No | Stage 2a (index-build) → Stage 3-5 |
106+
| Yes | No | No | **Stage 2b (ddd:scan)** → Stage 3-5 |
107+
| Yes | Yes | No | Stage 2a (index-build) → Stage 3-5 |
108+
| Yes | * | Yes | **Skip to Stage 3** (index exists) |
109+
110+
### Override Flags
111+
112+
| Flag | Effect |
113+
|------|--------|
114+
| `--skip-spec` | Never run spec-generator |
115+
| `--skip-build` | Never run index-build |
116+
| `--spec <id>` | Use specific spec session, force Path A |
117+
| `--from-scratch` | Rebuild index even if exists |
118+
119+
## Stage 1: Specification (conditional)
120+
121+
### Run When
122+
- No codebase AND no spec AND `--skip-spec` not set
123+
- User provides a new project idea (not an existing task description)
124+
125+
### Skip When
126+
- `--skip-spec` flag
127+
- Codebase already exists (existing project)
128+
- `--spec <id>` pointing to existing session
129+
130+
### Execution
131+
```
132+
Invoke /spec-generator with user input
133+
→ Output: .workflow/.doc-index/specs/SPEC-{slug}-{date}/
134+
```
135+
136+
## Stage 2: Index Construction (conditional)
137+
138+
### Run When
139+
- `doc-index.json` does not exist
140+
- OR `--from-scratch` flag
141+
142+
### Route Selection
143+
144+
```
145+
Has spec outputs → Stage 2a: /ddd:index-build (spec-first)
146+
No spec, has code → Stage 2b: /ddd:scan (code-first)
147+
```
148+
149+
### Stage 2a: /ddd:index-build (has spec)
150+
```
151+
Invoke /ddd:index-build [-y] [-s <spec-id>]
152+
→ Output: doc-index.json from spec entities + code mapping
153+
```
154+
155+
### Stage 2b: /ddd:scan (no spec, has code)
156+
```
157+
Invoke /ddd:scan [-y]
158+
→ Output: doc-index.json from code analysis + inferred features
159+
```
160+
161+
### Skip When
162+
- `--skip-build` flag
163+
- `doc-index.json` exists AND NOT `--from-scratch`
164+
- In this case, suggest `/ddd:update` for incremental refresh
165+
166+
## Stage 3: Planning (always runs)
167+
168+
### Execution
169+
170+
```
171+
Invoke /ddd:plan [-y] "task description"
172+
```
173+
174+
The enhanced `/ddd:plan` now performs:
175+
1. Doc-index query (instant context from features, requirements, components, ADRs)
176+
2. Doc-index-guided exploration (1-4 angles based on affected features)
177+
3. Clarification (aggregate ambiguities from exploration + doc-index gaps)
178+
4. Task planning (plan.json + TASK-*.json with doc_context traceability)
179+
5. Handoff selection
180+
181+
Output:
182+
- `plan.json` — plan overview with doc_context
183+
- `.task/TASK-*.json` — individual tasks with doc_context
184+
- `exploration-{angle}.json` — exploration results (if Phase 2 ran)
185+
- `planning-context.md` — legacy context package
186+
187+
### Handoff Decision
188+
189+
After planning, `/ddd:plan` presents execution options:
190+
191+
| Option | Description | Auto-Select When |
192+
|--------|-------------|-----------------|
193+
| **ddd:execute** | Document-aware execution (recommended) | Default in ddd workflow |
194+
| **lite-execute** | Standard execution (no doc awareness) | When doc traceability not needed |
195+
| **direct** | Start coding with context | User prefers manual |
196+
| **stop** | Just the plan context | Planning/research only |
197+
198+
With `-y`: Auto-select `ddd:execute`.
199+
200+
## Stage 4: Execution
201+
202+
Based on Stage 3 handoff decision:
203+
204+
| Mode | Delegates To |
205+
|------|-------------|
206+
| **ddd:execute** | `/ddd:execute --in-memory` with plan.json + doc-index enrichment |
207+
| lite-execute | `/workflow:lite-execute` with plan.json path |
208+
| direct | Output context package, developer works manually |
209+
| stop | End here, no execution |
210+
211+
### ddd:execute Features (when selected)
212+
- Doc-enriched task prompts (feature context + component docs + ADR constraints)
213+
- Per-batch impact verification (changes stay within planned scope)
214+
- Result persistence (`TASK-*.result.json` per task, `execution-manifest.json` per session)
215+
- Post-execution verify gate (Stage 4.5, unless `--skip-verify`)
216+
- Post-completion auto-sync with manifest (Stage 5 triggered automatically)
217+
218+
**Note**: When using `ddd:execute`, Stage 4.5 and Stage 5 are auto-triggered. For other modes, run Stage 5 manually.
219+
220+
## Stage 4.5: Verify Gate
221+
222+
Embedded within `ddd:execute` (Step 4.5). Runs after all batches complete, before doc sync.
223+
224+
### Purpose
225+
226+
Quality gate ensuring execution output is correct before committing to documentation updates. Prevents bad code from being "blessed" into the doc-index.
227+
228+
### Checks Performed
229+
230+
| Check | Description | Gate Behavior |
231+
|-------|-------------|---------------|
232+
| **Convergence** | Run `task.convergence.verification` for each task | FAIL if any critical task fails |
233+
| **Build** | Run project build command (`tsc --noEmit`, etc.) | FAIL on build errors |
234+
| **Lint** | Run project linter (`eslint`, etc.) | WARN only (non-blocking) |
235+
| **Regression** | Run full test suite, compare to baseline | FAIL on new test failures |
236+
237+
### Gate Results
238+
239+
| Result | Action |
240+
|--------|--------|
241+
| **PASS** | All checks passed → proceed to Stage 5 |
242+
| **WARN** | Non-critical issues (lint warnings) → proceed with warnings logged |
243+
| **FAIL** | Critical issues → ask user: fix now / skip sync / abort |
244+
| **FAIL + `-y`** | Log failures, set `error_state` in session, stop |
245+
246+
### Output
247+
248+
- `execution-manifest.json` — persisted to session folder, consumed by Stage 5
249+
- Contains: task results, files_modified (with task attribution), verify gate results
250+
251+
## Stage 5: Post-Task Sync
252+
253+
### Trigger
254+
- **Auto**: `/ddd:execute` triggers `/ddd:sync --from-manifest` automatically after verify gate passes
255+
- **Manual**: User runs `/ddd:sync` after completing work in direct/lite-execute mode
256+
- **Resume**: `/ddd:auto --resume` after task completion
257+
258+
### Execution
259+
```
260+
# Auto mode (from ddd:execute): uses manifest for precise change tracking
261+
Invoke /ddd:sync [-y] --task-id <id> --from-manifest {session}/execution-manifest.json "task summary"
262+
263+
# Manual mode (from direct/lite-execute): falls back to git diff
264+
Invoke /ddd:sync [-y] [--task-id <id>] "task summary"
265+
266+
→ Updates: doc-index.json, feature-maps/, tech-registry/, action-logs/
267+
```
268+
269+
## State Tracking
270+
271+
### Session File: `.workflow/.doc-index/.auto-session.json`
272+
273+
```json
274+
{
275+
"session_id": "DAUTO-{timestamp}",
276+
"input": "user's original input",
277+
"detected_state": {
278+
"has_codebase": true,
279+
"has_spec": false,
280+
"has_index": false,
281+
"build_path": "code-first"
282+
},
283+
"stages_completed": ["detect", "index-build", "plan"],
284+
"current_stage": "execute",
285+
"spec_session": "SPEC-{slug}-{date}|null",
286+
"plan_session": "planning/{task-slug}-{date}/",
287+
"plan_context": "planning/{task-slug}-{date}/plan.json",
288+
"execution_mode": "ddd:execute|lite-execute|direct|stop",
289+
"execution_manifest": "planning/{task-slug}-{date}/execution-manifest.json|null",
290+
"verify_gate": "PASS|WARN|FAIL|null",
291+
"error_state": null,
292+
"last_error": {
293+
"stage": "execute",
294+
"message": "Task TASK-002 failed: compilation error",
295+
"timestamp": "ISO8601",
296+
"recoverable": true
297+
},
298+
"created_at": "ISO8601",
299+
"last_updated": "ISO8601"
300+
}
301+
```
302+
303+
### Resume
304+
```
305+
/ddd:auto --resume → Resume from current_stage in .auto-session.json
306+
```
307+
308+
### Error Recovery
309+
```
310+
/ddd:auto --resume
311+
IF error_state is set:
312+
Display last error context
313+
Ask: retry current stage / skip to next / abort
314+
ELSE:
315+
Resume from current_stage normally
316+
```
317+
318+
## Example Workflows
319+
320+
### New Project (Full Flow)
321+
```
322+
/ddd:auto "Build a task management API with user auth and team features"
323+
→ Stage 0: No code, no spec → need spec-gen
324+
→ Stage 1: spec-generator produces full spec
325+
→ Stage 2: index-build creates index from spec + empty codebase
326+
→ Stage 3: ddd:plan produces plan.json + TASK-*.json with doc_context
327+
→ Stage 4: ddd:execute runs tasks with feature context enrichment
328+
→ Stage 4.5: verify gate — convergence ✓, build ✓, tests ✓ → PASS
329+
→ Stage 5: ddd:sync --from-manifest auto-triggered, updates index
330+
```
331+
332+
### Existing Project, No Spec (Code-First)
333+
```
334+
/ddd:auto "Add rate limiting to API endpoints"
335+
→ Stage 0: Has code, no spec, no index
336+
→ Stage 2b: ddd:scan analyzes code, infers features from codebase
337+
→ Stage 3: ddd:plan queries index, explores with security + patterns angles
338+
→ Stage 4: ddd:execute runs with rate-limit component docs as context
339+
→ Stage 4.5: verify gate — convergence ✓, tests 41/42 (1 regression) → WARN
340+
→ Stage 5: ddd:sync --from-manifest, registers new rate-limit component
341+
```
342+
343+
### Existing Project with Index (Incremental)
344+
```
345+
/ddd:auto "Fix auth token expiration bug"
346+
→ Stage 0: Has code, has index → skip to plan
347+
→ Stage 3: ddd:plan finds feat-auth, REQ-002, tech-auth-service (Low complexity, skip exploration)
348+
→ Stage 4: ddd:execute runs single task with auth feature context
349+
→ Stage 4.5: verify gate — convergence ✓, build ✓, tests ✓ → PASS
350+
→ Stage 5: ddd:sync --from-manifest, updates tech-auth-service code locations
351+
```
352+
353+
### Planning Only
354+
```
355+
/ddd:auto "Investigate payment module architecture"
356+
→ Stage 0-2: (as needed)
357+
→ Stage 3: ddd:plan shows full context with exploration results
358+
→ Stage 4: user selects "stop" → gets plan.json + context package only
359+
```

0 commit comments

Comments
 (0)