@dotdotgod/claude-code 0.1.47 → 0.1.48
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Create a durable staged plan using dotdotgod 5-stage pipeline
|
|
3
|
+
argument-hint: <task or change request>
|
|
4
|
+
allowed-tools: [Read, Glob, Grep, Bash, Write, Edit]
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
<!-- Generated from packages/shared resources by scripts/generate-adapters.mjs. Do not edit this file directly; edit the shared source and run `pnpm run generate`. -->
|
|
8
|
+
|
|
9
|
+
# /dd:plan-goal - Staged Planning
|
|
10
|
+
|
|
11
|
+
Run the dotdotgod 5-stage planning pipeline.
|
|
12
|
+
|
|
13
|
+
Task request: `$ARGUMENTS`
|
|
14
|
+
|
|
15
|
+
## Goal
|
|
16
|
+
|
|
17
|
+
Create a durable staged plan using the dotdotgod 5-stage pipeline before changing source or config files. Each stage produces a checkpoint file under `.dotdotgod-plan/` and updates the durable plan artifact at `docs/plan/<task>/README.md`.
|
|
18
|
+
|
|
19
|
+
Tip: set `/goal "docs/plan/<task>/.dotdotgod-plan/05_WORKSTREAM_HANDOFF.md Status: completed"` before running this command to let Claude track completion automatically across turns. Omit `/goal` when you want to review and approve each stage manually.
|
|
20
|
+
|
|
21
|
+
## Pipeline Overview
|
|
22
|
+
|
|
23
|
+
| Stage | ID | Checkpoint | Required Sections |
|
|
24
|
+
|-------|----|------------|------------------|
|
|
25
|
+
| Intake | `01-intake` | `01_INTAKE.md` | Request Summary, Goal, Scope, Non-goals, Constraints, Assumptions |
|
|
26
|
+
| Context Load | `02-context-load` | `02_CONTEXT_LOAD.md` | Memory Reads, Impact Candidates, Related Files |
|
|
27
|
+
| Discovery | `03-discovery` | `03_DISCOVERY.md` | Findings, Risks, Open Questions |
|
|
28
|
+
| Plan | `04-plan` | `04_PLAN.md` | Implementation Design, Code Touchpoints, Data/State Flow, Edge Cases, Atomic Tasks, Test Design, Validation Plan, Resume Point |
|
|
29
|
+
| Workstream Handoff | `05-workstream-handoff` | `05_WORKSTREAM_HANDOFF.md` | Workstream Handoff, Workstream Map, Shared Context, Workstreams, Integration Sequence, Todo Contract |
|
|
30
|
+
|
|
31
|
+
## Checkpoint Format
|
|
32
|
+
|
|
33
|
+
Write each checkpoint to `docs/plan/<task>/.dotdotgod-plan/NN_STAGE_NAME.md`:
|
|
34
|
+
|
|
35
|
+
```
|
|
36
|
+
Stage: <stage-id>
|
|
37
|
+
Status: completed
|
|
38
|
+
Updated: <ISO timestamp>
|
|
39
|
+
|
|
40
|
+
## <Required Section 1>
|
|
41
|
+
[content]
|
|
42
|
+
|
|
43
|
+
## Stage 0N Construction Checklist
|
|
44
|
+
- [x] Category: evidence
|
|
45
|
+
- [x] Category: evidence description
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Use `Status: blocked` when a user decision blocks the stage. Use only canonical checklist rows: `- [x] Category: evidence`. Do not use tables, `completed - [x]`, or `Category: completed - [x]` shorthand.
|
|
49
|
+
|
|
50
|
+
## Resume Logic
|
|
51
|
+
|
|
52
|
+
When the argument is a task path such as `docs/plan/<task>/README.md` or a task slug:
|
|
53
|
+
|
|
54
|
+
1. Resolve the README path from the argument.
|
|
55
|
+
2. Scan `.dotdotgod-plan/` for existing checkpoint files.
|
|
56
|
+
3. Reverse-scan to find the last checkpoint where `Status:` is not `completed`.
|
|
57
|
+
4. Resume from that stage. If all checkpoints show `Status: completed`, report the plan as already complete and stop.
|
|
58
|
+
5. If no checkpoints exist, start from Stage 01.
|
|
59
|
+
6. Load the found checkpoint content as stage context before generating the next stage message.
|
|
60
|
+
|
|
61
|
+
## Stage Instructions
|
|
62
|
+
|
|
63
|
+
### Stage 01: Intake
|
|
64
|
+
|
|
65
|
+
Create the initial planning context for the durable plan request.
|
|
66
|
+
|
|
67
|
+
Include in the durable plan and checkpoint:
|
|
68
|
+
- **Request Summary** — restate the user's request in your own words.
|
|
69
|
+
- **Goal** — the intended durable plan goal.
|
|
70
|
+
- **Scope** — what is in scope.
|
|
71
|
+
- **Non-goals** — what is explicitly out of scope.
|
|
72
|
+
- **Constraints** — known constraints and guardrails.
|
|
73
|
+
- **Assumptions** — assumptions made where information is incomplete.
|
|
74
|
+
|
|
75
|
+
Construction checklist categories: Requirements, Constraints, Failure paths, Data shape, Verification, Integration impact.
|
|
76
|
+
|
|
77
|
+
Do not edit source code. Do not advance beyond Stage 01.
|
|
78
|
+
|
|
79
|
+
### Stage 02: Context Load
|
|
80
|
+
|
|
81
|
+
Use the Stage 01 context, then update the durable plan artifact and checkpoint.
|
|
82
|
+
|
|
83
|
+
Include in the durable plan and checkpoint:
|
|
84
|
+
- **Memory Reads** — agent docs, README indexes, specs, architecture notes, test docs, and active plans consulted. Use `dotdotgod expand <root> "<request>" --json` when the request contains `[[...]]` refs; use `--fuzzy` for high-signal doc names before broad grep/find.
|
|
85
|
+
- **Impact Candidates** — for each likely target file, run `dotdotgod graph impact <root> --changed <path> --compact` and record related specs, tests, scores, and reasons. Fall back to README indexes and traceability blocks when the CLI is unavailable.
|
|
86
|
+
- **Related Files** — source, config, and doc files identified as relevant.
|
|
87
|
+
|
|
88
|
+
Construction checklist categories: Memory reads, Impact candidates, Related files, Boundary risk.
|
|
89
|
+
|
|
90
|
+
Do not edit source code. Do not advance beyond Stage 02.
|
|
91
|
+
|
|
92
|
+
### Stage 03: Discovery
|
|
93
|
+
|
|
94
|
+
Use the Stage 02 context, then update the durable plan artifact and checkpoint with actual findings from inspected code and docs — not just a list of files to inspect.
|
|
95
|
+
|
|
96
|
+
Include in the durable plan and checkpoint:
|
|
97
|
+
- **Findings** — concrete observations from reading source, config, and docs.
|
|
98
|
+
- **Risks** — identified risks and failure paths.
|
|
99
|
+
- **Open Questions** — research gaps the agent can resolve by reading project context. Do not silently carry unresolved user decisions forward. If a missing choice requires the user to decide scope, behavior, product policy, risk acceptance, or implementation direction, stop and ask the user a concrete question with options. Record machine-readable blockers with `DecisionOwner: user` and `DecisionState: unresolved`, or `BlockerType: user-decision` and `Status: blocked`. Do not use prose keywords such as "TBD" or "undecided" as machine-readable state.
|
|
100
|
+
|
|
101
|
+
Construction checklist categories: Findings, Risks, Open questions, Extension points.
|
|
102
|
+
|
|
103
|
+
Do not edit source code. Do not advance beyond Stage 03.
|
|
104
|
+
|
|
105
|
+
### Stage 04: Plan
|
|
106
|
+
|
|
107
|
+
Use the Stage 03 context, then update the durable plan artifact and checkpoint with an implementation design — not a generic project plan.
|
|
108
|
+
|
|
109
|
+
Include in the durable plan and checkpoint:
|
|
110
|
+
- **Implementation Design** — design overview.
|
|
111
|
+
- **Code Touchpoints** — exact files, functions, types, classes, and commands to change.
|
|
112
|
+
- **Data/State Flow** — how data and state change through the implementation.
|
|
113
|
+
- **Edge Cases** — failure paths, empty/missing data, invalid input, interrupted/resumed state, idempotency, retry behavior, and integration boundaries.
|
|
114
|
+
- **Atomic Tasks** — each task must name concrete code touchpoints; no vague verbs such as "update logic" without a named target. A different agent must be able to implement the task without this chat history.
|
|
115
|
+
- **Test Design** — unit, integration, or E2E tests for each atomic task.
|
|
116
|
+
- **Validation Plan** — verification commands and review checks.
|
|
117
|
+
- **Resume Point** — current resume state for long-running tasks.
|
|
118
|
+
|
|
119
|
+
When the implementation design has multiple independent parts, split the durable plan into task-local support markdown files under `docs/plan/<task>/`. Keep `README.md` as the overview/index, and link each support file with a one-line purpose. Use support files for implementation-part detail such as CLI changes, extension or runtime changes, tests, docs, migration, or rollout. Do not put final user-facing plan content only in `.dotdotgod-plan/`.
|
|
120
|
+
|
|
121
|
+
Apply `dotdotgod graph impact` evidence from Stage 02 to strengthen Code Touchpoints, Edge Cases, and Validation Plan. For Claude Code and Codex plans, include a concrete `dd:impact` or `impact-review` step before broad verification or final handoff when source, config, or docs files will change.
|
|
122
|
+
|
|
123
|
+
Do not silently carry unresolved user decisions forward. Stop and ask if scope, behavior, risk acceptance, or implementation direction is missing.
|
|
124
|
+
|
|
125
|
+
Construction checklist categories: Implementation design, Code touchpoints, Data/State flow, Edge cases, Atomic tasks, Test design, Validation plan, Resume point.
|
|
126
|
+
|
|
127
|
+
Do not edit source code. Do not advance beyond Stage 04.
|
|
128
|
+
|
|
129
|
+
### Stage 05: Workstream Handoff
|
|
130
|
+
|
|
131
|
+
Use the Stage 04 context, then update the durable plan artifact and checkpoint with a phase-based, subagent-ready Workstream Handoff Contract.
|
|
132
|
+
|
|
133
|
+
Include in the durable plan and checkpoint:
|
|
134
|
+
- **Workstream Handoff** — state `Split decision: yes` or `Split decision: no`. When no split is needed, include `No-split rationale:` and a concrete Todo Contract as the implementation handoff contract.
|
|
135
|
+
- **Workstream Map** — when split is needed: at least two `Workstream ID:` entries, each with owner or role, exact primary handoff file, target files and functions, dependencies, and whether it can run in parallel. Include an execution phase map with phase names, dependency gates, sequencing constraints, and parallelization notes.
|
|
136
|
+
- **Shared Context** — everything every downstream agent needs to work without this chat history.
|
|
137
|
+
- **Workstreams** — per-workstream contracts with structured fields: `Workstream ID:`, `Purpose:`, `Required context:`, `Allowed edits:`, `Forbidden edits:`, `Tasks:`, `Validation:`, `Handoff output:`, `Dependencies:`. Each split-workstream subagent must receive exactly one primary handoff file and be able to work from that file alone. Each primary handoff file must include role, phase, dependency gates, summarized context, exact target files and functions, allowed edits, forbidden edits, tasks, validation, expected handoff output, dependencies, and integration notes. Use UPPER_SNAKE_CASE markdown files under the task directory and README index links for large split contracts.
|
|
138
|
+
- **Integration Sequence** — how to combine workstream outputs after phase gates pass: `Step:`, `Validation:`, `Handoff:`.
|
|
139
|
+
- **Todo Contract** — aggregated implementation todos across workstreams and phases.
|
|
140
|
+
|
|
141
|
+
The `.dotdotgod-plan/05_WORKSTREAM_HANDOFF.md` file is internal stage state context and validation evidence. Write final user-facing handoff instructions to `README.md` or task-local support files outside `.dotdotgod-plan/`.
|
|
142
|
+
|
|
143
|
+
Construction checklist categories: Handoffs, Do-not rules, Focused verification, Chat-independent context.
|
|
144
|
+
|
|
145
|
+
Do not edit source code. Do not advance beyond Stage 05.
|
|
146
|
+
|
|
147
|
+
## Stage Evaluation
|
|
148
|
+
|
|
149
|
+
After writing each stage output, self-evaluate before advancing:
|
|
150
|
+
|
|
151
|
+
- **pass** — the durable plan artifact has enough human-readable content and the matching checkpoint has all required sections, a completed construction checklist, and no unresolved user decisions. Advance to the next stage.
|
|
152
|
+
- **retry** — the output is repairable without user input. Rewrite the stage (maximum 5 retries). Repair the durable plan artifact as well as the checkpoint.
|
|
153
|
+
- **blocked** — a user decision about scope, behavior, risk acceptance, or implementation direction is required. Stop, surface the concrete question with options, and wait for user input before proceeding. Do not pass a stage that records unresolved choices as "TBD" or "undecided".
|
|
154
|
+
|
|
155
|
+
## Completion: Document Clarify
|
|
156
|
+
|
|
157
|
+
After Stage 05 passes, run a final `document-clarify` pass before implementation:
|
|
158
|
+
|
|
159
|
+
- Use the `document-clarify` skill.
|
|
160
|
+
- Clarify `docs/plan/<task>/README.md` and any task-local support or workstream handoff markdown files referenced by that README.
|
|
161
|
+
- Preserve scope, user decisions, validation requirements, workstream dependencies, Todo Contract, and handoff contracts.
|
|
162
|
+
- Do not execute implementation work. Do not edit source or config files.
|
|
163
|
+
- Treat `docs/plan/<task>/.dotdotgod-plan/*.md` files as internal checkpoint state and validation evidence, not user-facing documentation to polish.
|
|
164
|
+
- Do not weaken acceptance criteria, verification commands, do-not rules, or blocker descriptions.
|
|
165
|
+
- Stop after reporting the clarified plan path and any remaining blockers.
|
|
166
|
+
|
|
167
|
+
## Quality Rules
|
|
168
|
+
|
|
169
|
+
- Prefer documented facts over inference; label inference explicitly.
|
|
170
|
+
- Checkpoint files are internal validation evidence; final plan content belongs in `README.md` or task-local support files.
|
|
171
|
+
- Validation steps must be executable commands or concrete review checks.
|
|
172
|
+
- Do not silently carry unresolved user decisions across stages.
|
|
173
|
+
- Do not begin source or config implementation until the user explicitly asks to execute the plan.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@dotdotgod/claude-code",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.48",
|
|
4
4
|
"description": "Claude Code adapter for dotdotgod project memory workflows.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "Elastic-2.0",
|
|
@@ -38,7 +38,7 @@
|
|
|
38
38
|
"url": "https://github.com/dotdotgod/dotdotgod-kit/issues"
|
|
39
39
|
},
|
|
40
40
|
"scripts": {
|
|
41
|
-
"verify": "node -e \"const fs=require('fs'); const req=['.claude-plugin/plugin.json','commands/dd/load.md','commands/dd/plan.md','commands/dd/init.md','commands/dd/impact.md','skills/project-load/SKILL.md','skills/doc-first-planning/SKILL.md','skills/project-initializer/SKILL.md','skills/impact-review/SKILL.md','skills/document-clarify/SKILL.md','skills/document-clarify/agents/openai.yaml','skills/project-initializer/scripts/init_project.sh','hooks/README.md']; JSON.parse(fs.readFileSync('.claude-plugin/plugin.json','utf8')); for (const f of req) { if (!fs.existsSync(f)) throw new Error('missing '+f); } console.log('claude-code adapter ok')\"",
|
|
41
|
+
"verify": "node -e \"const fs=require('fs'); const req=['.claude-plugin/plugin.json','commands/dd/load.md','commands/dd/plan.md','commands/dd/plan-goal.md','commands/dd/init.md','commands/dd/impact.md','skills/project-load/SKILL.md','skills/doc-first-planning/SKILL.md','skills/plan-goal/SKILL.md','skills/plan-goal/agents/openai.yaml','skills/project-initializer/SKILL.md','skills/impact-review/SKILL.md','skills/document-clarify/SKILL.md','skills/document-clarify/agents/openai.yaml','skills/project-initializer/scripts/init_project.sh','hooks/README.md']; JSON.parse(fs.readFileSync('.claude-plugin/plugin.json','utf8')); for (const f of req) { if (!fs.existsSync(f)) throw new Error('missing '+f); } console.log('claude-code adapter ok')\"",
|
|
42
42
|
"pack:dry-run": "pnpm pack --dry-run --json"
|
|
43
43
|
}
|
|
44
44
|
}
|
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: plan-goal
|
|
3
|
+
description: Use this skill when the user asks Claude Code to run a staged planning pipeline, create a durable plan with checkpoint files, or use dotdotgod plan-goal stages (intake, context-load, discovery, plan, workstream-handoff); when dd:plan-goal or staged planning is mentioned.
|
|
4
|
+
version: 1.0.0
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
<!-- Generated from packages/shared resources by scripts/generate-adapters.mjs. Do not edit this file directly; edit the shared source and run `pnpm run generate`. -->
|
|
8
|
+
|
|
9
|
+
# Staged Planning
|
|
10
|
+
|
|
11
|
+
## Goal
|
|
12
|
+
|
|
13
|
+
Create a durable staged plan using the dotdotgod 5-stage pipeline before changing source or config files. Each stage produces a checkpoint file under `.dotdotgod-plan/` and updates the durable plan artifact at `docs/plan/<task>/README.md`.
|
|
14
|
+
|
|
15
|
+
Tip: set `/goal "docs/plan/<task>/.dotdotgod-plan/05_WORKSTREAM_HANDOFF.md Status: completed"` before running this command to let Claude track completion automatically across turns. Omit `/goal` when you want to review and approve each stage manually.
|
|
16
|
+
|
|
17
|
+
## Pipeline Overview
|
|
18
|
+
|
|
19
|
+
| Stage | ID | Checkpoint | Required Sections |
|
|
20
|
+
|-------|----|------------|------------------|
|
|
21
|
+
| Intake | `01-intake` | `01_INTAKE.md` | Request Summary, Goal, Scope, Non-goals, Constraints, Assumptions |
|
|
22
|
+
| Context Load | `02-context-load` | `02_CONTEXT_LOAD.md` | Memory Reads, Impact Candidates, Related Files |
|
|
23
|
+
| Discovery | `03-discovery` | `03_DISCOVERY.md` | Findings, Risks, Open Questions |
|
|
24
|
+
| Plan | `04-plan` | `04_PLAN.md` | Implementation Design, Code Touchpoints, Data/State Flow, Edge Cases, Atomic Tasks, Test Design, Validation Plan, Resume Point |
|
|
25
|
+
| Workstream Handoff | `05-workstream-handoff` | `05_WORKSTREAM_HANDOFF.md` | Workstream Handoff, Workstream Map, Shared Context, Workstreams, Integration Sequence, Todo Contract |
|
|
26
|
+
|
|
27
|
+
## Checkpoint Format
|
|
28
|
+
|
|
29
|
+
Write each checkpoint to `docs/plan/<task>/.dotdotgod-plan/NN_STAGE_NAME.md`:
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
Stage: <stage-id>
|
|
33
|
+
Status: completed
|
|
34
|
+
Updated: <ISO timestamp>
|
|
35
|
+
|
|
36
|
+
## <Required Section 1>
|
|
37
|
+
[content]
|
|
38
|
+
|
|
39
|
+
## Stage 0N Construction Checklist
|
|
40
|
+
- [x] Category: evidence
|
|
41
|
+
- [x] Category: evidence description
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Use `Status: blocked` when a user decision blocks the stage. Use only canonical checklist rows: `- [x] Category: evidence`. Do not use tables, `completed - [x]`, or `Category: completed - [x]` shorthand.
|
|
45
|
+
|
|
46
|
+
## Resume Logic
|
|
47
|
+
|
|
48
|
+
When the argument is a task path such as `docs/plan/<task>/README.md` or a task slug:
|
|
49
|
+
|
|
50
|
+
1. Resolve the README path from the argument.
|
|
51
|
+
2. Scan `.dotdotgod-plan/` for existing checkpoint files.
|
|
52
|
+
3. Reverse-scan to find the last checkpoint where `Status:` is not `completed`.
|
|
53
|
+
4. Resume from that stage. If all checkpoints show `Status: completed`, report the plan as already complete and stop.
|
|
54
|
+
5. If no checkpoints exist, start from Stage 01.
|
|
55
|
+
6. Load the found checkpoint content as stage context before generating the next stage message.
|
|
56
|
+
|
|
57
|
+
## Stage Instructions
|
|
58
|
+
|
|
59
|
+
### Stage 01: Intake
|
|
60
|
+
|
|
61
|
+
Create the initial planning context for the durable plan request.
|
|
62
|
+
|
|
63
|
+
Include in the durable plan and checkpoint:
|
|
64
|
+
- **Request Summary** — restate the user's request in your own words.
|
|
65
|
+
- **Goal** — the intended durable plan goal.
|
|
66
|
+
- **Scope** — what is in scope.
|
|
67
|
+
- **Non-goals** — what is explicitly out of scope.
|
|
68
|
+
- **Constraints** — known constraints and guardrails.
|
|
69
|
+
- **Assumptions** — assumptions made where information is incomplete.
|
|
70
|
+
|
|
71
|
+
Construction checklist categories: Requirements, Constraints, Failure paths, Data shape, Verification, Integration impact.
|
|
72
|
+
|
|
73
|
+
Do not edit source code. Do not advance beyond Stage 01.
|
|
74
|
+
|
|
75
|
+
### Stage 02: Context Load
|
|
76
|
+
|
|
77
|
+
Use the Stage 01 context, then update the durable plan artifact and checkpoint.
|
|
78
|
+
|
|
79
|
+
Include in the durable plan and checkpoint:
|
|
80
|
+
- **Memory Reads** — agent docs, README indexes, specs, architecture notes, test docs, and active plans consulted. Use `dotdotgod expand <root> "<request>" --json` when the request contains `[[...]]` refs; use `--fuzzy` for high-signal doc names before broad grep/find.
|
|
81
|
+
- **Impact Candidates** — for each likely target file, run `dotdotgod graph impact <root> --changed <path> --compact` and record related specs, tests, scores, and reasons. Fall back to README indexes and traceability blocks when the CLI is unavailable.
|
|
82
|
+
- **Related Files** — source, config, and doc files identified as relevant.
|
|
83
|
+
|
|
84
|
+
Construction checklist categories: Memory reads, Impact candidates, Related files, Boundary risk.
|
|
85
|
+
|
|
86
|
+
Do not edit source code. Do not advance beyond Stage 02.
|
|
87
|
+
|
|
88
|
+
### Stage 03: Discovery
|
|
89
|
+
|
|
90
|
+
Use the Stage 02 context, then update the durable plan artifact and checkpoint with actual findings from inspected code and docs — not just a list of files to inspect.
|
|
91
|
+
|
|
92
|
+
Include in the durable plan and checkpoint:
|
|
93
|
+
- **Findings** — concrete observations from reading source, config, and docs.
|
|
94
|
+
- **Risks** — identified risks and failure paths.
|
|
95
|
+
- **Open Questions** — research gaps the agent can resolve by reading project context. Do not silently carry unresolved user decisions forward. If a missing choice requires the user to decide scope, behavior, product policy, risk acceptance, or implementation direction, stop and ask the user a concrete question with options. Record machine-readable blockers with `DecisionOwner: user` and `DecisionState: unresolved`, or `BlockerType: user-decision` and `Status: blocked`. Do not use prose keywords such as "TBD" or "undecided" as machine-readable state.
|
|
96
|
+
|
|
97
|
+
Construction checklist categories: Findings, Risks, Open questions, Extension points.
|
|
98
|
+
|
|
99
|
+
Do not edit source code. Do not advance beyond Stage 03.
|
|
100
|
+
|
|
101
|
+
### Stage 04: Plan
|
|
102
|
+
|
|
103
|
+
Use the Stage 03 context, then update the durable plan artifact and checkpoint with an implementation design — not a generic project plan.
|
|
104
|
+
|
|
105
|
+
Include in the durable plan and checkpoint:
|
|
106
|
+
- **Implementation Design** — design overview.
|
|
107
|
+
- **Code Touchpoints** — exact files, functions, types, classes, and commands to change.
|
|
108
|
+
- **Data/State Flow** — how data and state change through the implementation.
|
|
109
|
+
- **Edge Cases** — failure paths, empty/missing data, invalid input, interrupted/resumed state, idempotency, retry behavior, and integration boundaries.
|
|
110
|
+
- **Atomic Tasks** — each task must name concrete code touchpoints; no vague verbs such as "update logic" without a named target. A different agent must be able to implement the task without this chat history.
|
|
111
|
+
- **Test Design** — unit, integration, or E2E tests for each atomic task.
|
|
112
|
+
- **Validation Plan** — verification commands and review checks.
|
|
113
|
+
- **Resume Point** — current resume state for long-running tasks.
|
|
114
|
+
|
|
115
|
+
When the implementation design has multiple independent parts, split the durable plan into task-local support markdown files under `docs/plan/<task>/`. Keep `README.md` as the overview/index, and link each support file with a one-line purpose. Use support files for implementation-part detail such as CLI changes, extension or runtime changes, tests, docs, migration, or rollout. Do not put final user-facing plan content only in `.dotdotgod-plan/`.
|
|
116
|
+
|
|
117
|
+
Apply `dotdotgod graph impact` evidence from Stage 02 to strengthen Code Touchpoints, Edge Cases, and Validation Plan. For Claude Code and Codex plans, include a concrete `dd:impact` or `impact-review` step before broad verification or final handoff when source, config, or docs files will change.
|
|
118
|
+
|
|
119
|
+
Do not silently carry unresolved user decisions forward. Stop and ask if scope, behavior, risk acceptance, or implementation direction is missing.
|
|
120
|
+
|
|
121
|
+
Construction checklist categories: Implementation design, Code touchpoints, Data/State flow, Edge cases, Atomic tasks, Test design, Validation plan, Resume point.
|
|
122
|
+
|
|
123
|
+
Do not edit source code. Do not advance beyond Stage 04.
|
|
124
|
+
|
|
125
|
+
### Stage 05: Workstream Handoff
|
|
126
|
+
|
|
127
|
+
Use the Stage 04 context, then update the durable plan artifact and checkpoint with a phase-based, subagent-ready Workstream Handoff Contract.
|
|
128
|
+
|
|
129
|
+
Include in the durable plan and checkpoint:
|
|
130
|
+
- **Workstream Handoff** — state `Split decision: yes` or `Split decision: no`. When no split is needed, include `No-split rationale:` and a concrete Todo Contract as the implementation handoff contract.
|
|
131
|
+
- **Workstream Map** — when split is needed: at least two `Workstream ID:` entries, each with owner or role, exact primary handoff file, target files and functions, dependencies, and whether it can run in parallel. Include an execution phase map with phase names, dependency gates, sequencing constraints, and parallelization notes.
|
|
132
|
+
- **Shared Context** — everything every downstream agent needs to work without this chat history.
|
|
133
|
+
- **Workstreams** — per-workstream contracts with structured fields: `Workstream ID:`, `Purpose:`, `Required context:`, `Allowed edits:`, `Forbidden edits:`, `Tasks:`, `Validation:`, `Handoff output:`, `Dependencies:`. Each split-workstream subagent must receive exactly one primary handoff file and be able to work from that file alone. Each primary handoff file must include role, phase, dependency gates, summarized context, exact target files and functions, allowed edits, forbidden edits, tasks, validation, expected handoff output, dependencies, and integration notes. Use UPPER_SNAKE_CASE markdown files under the task directory and README index links for large split contracts.
|
|
134
|
+
- **Integration Sequence** — how to combine workstream outputs after phase gates pass: `Step:`, `Validation:`, `Handoff:`.
|
|
135
|
+
- **Todo Contract** — aggregated implementation todos across workstreams and phases.
|
|
136
|
+
|
|
137
|
+
The `.dotdotgod-plan/05_WORKSTREAM_HANDOFF.md` file is internal stage state context and validation evidence. Write final user-facing handoff instructions to `README.md` or task-local support files outside `.dotdotgod-plan/`.
|
|
138
|
+
|
|
139
|
+
Construction checklist categories: Handoffs, Do-not rules, Focused verification, Chat-independent context.
|
|
140
|
+
|
|
141
|
+
Do not edit source code. Do not advance beyond Stage 05.
|
|
142
|
+
|
|
143
|
+
## Stage Evaluation
|
|
144
|
+
|
|
145
|
+
After writing each stage output, self-evaluate before advancing:
|
|
146
|
+
|
|
147
|
+
- **pass** — the durable plan artifact has enough human-readable content and the matching checkpoint has all required sections, a completed construction checklist, and no unresolved user decisions. Advance to the next stage.
|
|
148
|
+
- **retry** — the output is repairable without user input. Rewrite the stage (maximum 5 retries). Repair the durable plan artifact as well as the checkpoint.
|
|
149
|
+
- **blocked** — a user decision about scope, behavior, risk acceptance, or implementation direction is required. Stop, surface the concrete question with options, and wait for user input before proceeding. Do not pass a stage that records unresolved choices as "TBD" or "undecided".
|
|
150
|
+
|
|
151
|
+
## Completion: Document Clarify
|
|
152
|
+
|
|
153
|
+
After Stage 05 passes, run a final `document-clarify` pass before implementation:
|
|
154
|
+
|
|
155
|
+
- Use the `document-clarify` skill.
|
|
156
|
+
- Clarify `docs/plan/<task>/README.md` and any task-local support or workstream handoff markdown files referenced by that README.
|
|
157
|
+
- Preserve scope, user decisions, validation requirements, workstream dependencies, Todo Contract, and handoff contracts.
|
|
158
|
+
- Do not execute implementation work. Do not edit source or config files.
|
|
159
|
+
- Treat `docs/plan/<task>/.dotdotgod-plan/*.md` files as internal checkpoint state and validation evidence, not user-facing documentation to polish.
|
|
160
|
+
- Do not weaken acceptance criteria, verification commands, do-not rules, or blocker descriptions.
|
|
161
|
+
- Stop after reporting the clarified plan path and any remaining blockers.
|
|
162
|
+
|
|
163
|
+
## Quality Rules
|
|
164
|
+
|
|
165
|
+
- Prefer documented facts over inference; label inference explicitly.
|
|
166
|
+
- Checkpoint files are internal validation evidence; final plan content belongs in `README.md` or task-local support files.
|
|
167
|
+
- Validation steps must be executable commands or concrete review checks.
|
|
168
|
+
- Do not silently carry unresolved user decisions across stages.
|
|
169
|
+
- Do not begin source or config implementation until the user explicitly asks to execute the plan.
|