@undeemed/get-shit-done-codex 1.20.8 → 1.20.10
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.
- package/AGENTS.md +29 -29
- package/README.md +102 -30
- package/agents/gsd-debugger.md +53 -8
- package/agents/gsd-planner.md +86 -5
- package/agents/gsd-verifier.md +15 -0
- package/bin/install.js +524 -37
- package/commands/gsd/add-tests.md +41 -0
- package/commands/gsd/debug.md +3 -0
- package/commands/gsd/join-discord.md +1 -1
- package/commands/gsd/plan-phase.md +2 -1
- package/get-shit-done/bin/gsd-tools.cjs +39 -4
- package/get-shit-done/bin/lib/commands.cjs +5 -8
- package/get-shit-done/bin/lib/core.cjs +22 -9
- package/get-shit-done/bin/lib/init.cjs +17 -1
- package/get-shit-done/bin/lib/milestone.cjs +2 -1
- package/get-shit-done/bin/lib/phase.cjs +18 -20
- package/get-shit-done/bin/lib/roadmap.cjs +7 -7
- package/get-shit-done/bin/lib/state.cjs +216 -27
- package/get-shit-done/bin/lib/verify.cjs +9 -8
- package/get-shit-done/templates/DEBUG.md +7 -2
- package/get-shit-done/templates/VALIDATION.md +18 -46
- package/get-shit-done/templates/retrospective.md +54 -0
- package/get-shit-done/workflows/add-tests.md +350 -0
- package/get-shit-done/workflows/complete-milestone.md +63 -0
- package/get-shit-done/workflows/discuss-phase.md +2 -0
- package/get-shit-done/workflows/help.md +3 -0
- package/package.json +2 -1
package/AGENTS.md
CHANGED
|
@@ -81,49 +81,49 @@ Each task gets its own commit immediately after completion:
|
|
|
81
81
|
|
|
82
82
|
## Commands
|
|
83
83
|
|
|
84
|
-
The following commands are available. Invoke them with
|
|
84
|
+
The following commands are available. Invoke them with `$gsd-command-name`:
|
|
85
85
|
|
|
86
86
|
| Command | Description |
|
|
87
87
|
| --------------------------------- | ------------------------------------------- |
|
|
88
|
-
|
|
|
89
|
-
|
|
|
90
|
-
|
|
|
91
|
-
|
|
|
92
|
-
|
|
|
93
|
-
|
|
|
94
|
-
|
|
|
95
|
-
|
|
|
96
|
-
|
|
|
97
|
-
|
|
|
98
|
-
|
|
|
99
|
-
|
|
|
100
|
-
|
|
|
101
|
-
|
|
|
102
|
-
|
|
|
103
|
-
|
|
|
104
|
-
|
|
|
105
|
-
|
|
|
106
|
-
|
|
|
107
|
-
|
|
|
108
|
-
|
|
|
88
|
+
| `$gsd-new-project` | Initialize project through deep questioning |
|
|
89
|
+
| `$gsd-create-roadmap` | Create roadmap and state tracking |
|
|
90
|
+
| `$gsd-map-codebase` | Map existing codebase (brownfield projects) |
|
|
91
|
+
| `$gsd-plan-phase [N]` | Generate task plans for phase N |
|
|
92
|
+
| `$gsd-execute-plan [path]` | Execute a PLAN.md file |
|
|
93
|
+
| `$gsd-progress` | Show current position and what's next |
|
|
94
|
+
| `$gsd-verify-work [N]` | User acceptance testing |
|
|
95
|
+
| `$gsd-plan-fix [plan]` | Plan fixes for UAT issues |
|
|
96
|
+
| `$gsd-complete-milestone` | Archive milestone, prep next version |
|
|
97
|
+
| `$gsd-discuss-milestone` | Gather context for next milestone |
|
|
98
|
+
| `$gsd-new-milestone [name]` | Create new milestone with phases |
|
|
99
|
+
| `$gsd-add-phase` | Append phase to roadmap |
|
|
100
|
+
| `$gsd-insert-phase [N]` | Insert urgent work |
|
|
101
|
+
| `$gsd-remove-phase [N]` | Remove future phase |
|
|
102
|
+
| `$gsd-discuss-phase [N]` | Gather context before planning |
|
|
103
|
+
| `$gsd-research-phase [N]` | Deep ecosystem research |
|
|
104
|
+
| `$gsd-list-phase-assumptions [N]` | Review assumptions before planning |
|
|
105
|
+
| `$gsd-pause-work` | Create handoff when stopping mid-phase |
|
|
106
|
+
| `$gsd-resume-work` | Restore from last session |
|
|
107
|
+
| `$gsd-consider-issues` | Review deferred issues |
|
|
108
|
+
| `$gsd-help` | Show all commands |
|
|
109
109
|
|
|
110
110
|
## Workflow
|
|
111
111
|
|
|
112
112
|
### New Projects (Greenfield)
|
|
113
113
|
|
|
114
114
|
```bash
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
115
|
+
$gsd-new-project # Deep questioning → PROJECT.md
|
|
116
|
+
$gsd-create-roadmap # Create ROADMAP.md and STATE.md
|
|
117
|
+
$gsd-plan-phase 1 # Create atomic task plans
|
|
118
|
+
$gsd-execute-plan # Subagent executes autonomously
|
|
119
119
|
```
|
|
120
120
|
|
|
121
121
|
### Existing Projects (Brownfield)
|
|
122
122
|
|
|
123
123
|
```bash
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
124
|
+
$gsd-map-codebase # Analyze existing code → codebase/
|
|
125
|
+
$gsd-new-project # Questioning with codebase context
|
|
126
|
+
$gsd-create-roadmap # Continue as normal
|
|
127
127
|
```
|
|
128
128
|
|
|
129
129
|
## File References
|
package/README.md
CHANGED
|
@@ -4,6 +4,9 @@ A meta-prompting, context engineering and spec-driven development system for [Op
|
|
|
4
4
|
|
|
5
5
|
Fork of [get-shit-done](https://github.com/taches/get-shit-done) by TÂCHES, adapted for Codex CLI by [undeemed](https://github.com/undeemed).
|
|
6
6
|
|
|
7
|
+
> [!CAUTION]
|
|
8
|
+
> As of February 25, 2026, Codex is supported upstream. This fork remains focused on Codex-specific UX and compatibility with extra goodies.
|
|
9
|
+
|
|
7
10
|
[](https://www.npmjs.com/package/@undeemed/get-shit-done-codex)
|
|
8
11
|
[](LICENSE)
|
|
9
12
|

|
|
@@ -16,34 +19,106 @@ get-shit-done-codex (GSD) solves context rot — the quality degradation that ha
|
|
|
16
19
|
|
|
17
20
|
**The solution:** Hierarchical planning with fresh context windows. Each task runs in isolation with exactly the context it needs—no degradation from accumulated garbage.
|
|
18
21
|
|
|
22
|
+
## What Changed In This Fork
|
|
23
|
+
|
|
24
|
+
- **AGENTS-first for Codex:** `AGENTS.md` is the primary behavior contract . [Agent.md > Skills.md](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals)
|
|
25
|
+
- **Two command surfaces:** choose native skills (`$gsd-*`) or prompt aliases (`/prompts:gsd-*`).
|
|
26
|
+
- **Installer integrity checks:** `--verify` audits installation health, `--repair` restores missing artifacts.
|
|
27
|
+
- **Mode-aware installs:** installer adapts `AGENTS.md` and command guidance to your chosen mode.
|
|
28
|
+
|
|
19
29
|
## Installation
|
|
20
30
|
|
|
21
31
|
```bash
|
|
22
32
|
npx @undeemed/get-shit-done-codex@latest
|
|
23
33
|
```
|
|
24
34
|
|
|
25
|
-
You
|
|
35
|
+
You can install globally (`~/.codex/`) or locally (`./`).
|
|
36
|
+
|
|
37
|
+
### Recommended
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
npx @undeemed/get-shit-done-codex --global
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
If you run this in an interactive terminal, the installer will prompt you to choose `skills` (`$`) or `prompts` (`/prompts`).
|
|
44
|
+
In non-interactive runs, default is `skills` mode.
|
|
26
45
|
|
|
27
46
|
For non-interactive installs:
|
|
28
47
|
|
|
29
48
|
```bash
|
|
30
49
|
npx @undeemed/get-shit-done-codex --global # Install to ~/.codex/
|
|
31
50
|
npx @undeemed/get-shit-done-codex --local # Install to current directory
|
|
51
|
+
npx @undeemed/get-shit-done-codex --global --codex-mode skills # Native skills only
|
|
52
|
+
npx @undeemed/get-shit-done-codex --global --codex-mode prompts # Prompt aliases only
|
|
53
|
+
npx @undeemed/get-shit-done-codex --global --migrate # Apply detected migration cleanup
|
|
54
|
+
npx @undeemed/get-shit-done-codex --global --skip-migrate # Keep legacy surface files
|
|
55
|
+
npx @undeemed/get-shit-done-codex --verify --global # Check install integrity
|
|
56
|
+
npx @undeemed/get-shit-done-codex --verify --repair --global # Auto-repair
|
|
32
57
|
```
|
|
33
58
|
|
|
34
|
-
|
|
59
|
+
### Codex Modes
|
|
60
|
+
|
|
61
|
+
| Mode | Installs | Use Commands Like |
|
|
62
|
+
| --------- | ---------------------------- | --------------------------- |
|
|
63
|
+
| `skills` (default) | `skills/gsd-*/SKILL.md` | `$gsd-help`, `$gsd-plan-phase 1` |
|
|
64
|
+
| `prompts` | `prompts/gsd-*.md` | `/prompts:gsd-help` |
|
|
65
|
+
|
|
66
|
+
After installation, run `codex` (CLI) or `codex app` (Desktop), then run `$gsd-help` (or `/prompts:gsd-help` in prompts mode).
|
|
67
|
+
Single-surface policy: mixed `skills/` + `prompts/` installs are treated as drift and fail `--verify`.
|
|
68
|
+
|
|
69
|
+
### Installed File Structure
|
|
70
|
+
|
|
71
|
+
`$` skills mode (`--codex-mode skills`, default):
|
|
72
|
+
|
|
73
|
+
```text
|
|
74
|
+
~/.codex/
|
|
75
|
+
├── AGENTS.md
|
|
76
|
+
├── skills/
|
|
77
|
+
│ └── gsd-*/SKILL.md
|
|
78
|
+
└── get-shit-done/
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
`/prompts` mode (`--codex-mode prompts`):
|
|
82
|
+
|
|
83
|
+
```text
|
|
84
|
+
~/.codex/
|
|
85
|
+
├── AGENTS.md
|
|
86
|
+
├── prompts/
|
|
87
|
+
│ └── gsd-*.md
|
|
88
|
+
└── get-shit-done/
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
For local installs, replace `~/.codex/` with `./`.
|
|
92
|
+
|
|
93
|
+
### Verify And Repair
|
|
94
|
+
|
|
95
|
+
- `--verify`: checks `AGENTS.md`, command surfaces, workflow assets, and version metadata.
|
|
96
|
+
- `--verify --repair`: reinstalls missing/broken artifacts and verifies again.
|
|
97
|
+
- Migration is **detect-then-confirm**, not automatic:
|
|
98
|
+
- Interactive install asks before removing legacy surface files
|
|
99
|
+
- Non-interactive install skips cleanup unless `--migrate` is passed
|
|
100
|
+
- `--skip-migrate` keeps legacy files explicitly
|
|
101
|
+
|
|
102
|
+
### AGENTS-First Reliability
|
|
103
|
+
|
|
104
|
+
This fork is intentionally **AGENTS.md-first** for Codex reliability:
|
|
105
|
+
|
|
106
|
+
- `AGENTS.md` is the source of truth for behavior and workflow constraints
|
|
107
|
+
- `$gsd-*` skills are lightweight command wrappers around the same workflow docs
|
|
108
|
+
- `/prompts:gsd-*` are optional compatibility aliases (prompts mode)
|
|
35
109
|
|
|
36
110
|
## Staying Updated
|
|
37
111
|
|
|
38
112
|
```bash
|
|
39
113
|
# Check for updates from inside Codex
|
|
40
|
-
|
|
114
|
+
$gsd-update
|
|
115
|
+
# or: /prompts:gsd-update
|
|
41
116
|
|
|
42
117
|
# Update from terminal
|
|
43
118
|
npx @undeemed/get-shit-done-codex@latest --global
|
|
44
119
|
```
|
|
45
120
|
|
|
46
|
-
The installer
|
|
121
|
+
The installer writes a `get-shit-done/VERSION` file so `$gsd-update` (or `/prompts:gsd-update`) can detect installed vs latest and show changelog before updating.
|
|
47
122
|
|
|
48
123
|
## npm Trusted Publisher (OIDC)
|
|
49
124
|
|
|
@@ -63,16 +138,16 @@ When setting up npm Trusted Publisher for this package, use:
|
|
|
63
138
|
|
|
64
139
|
```bash
|
|
65
140
|
# 1. Initialize project (questions → research → requirements → roadmap)
|
|
66
|
-
|
|
141
|
+
$gsd-new-project
|
|
67
142
|
|
|
68
143
|
# 2. Plan the first phase
|
|
69
|
-
|
|
144
|
+
$gsd-plan-phase 1
|
|
70
145
|
|
|
71
146
|
# 3. Execute the phase
|
|
72
|
-
|
|
147
|
+
$gsd-execute-phase 1
|
|
73
148
|
|
|
74
149
|
# 4. Verify it works
|
|
75
|
-
|
|
150
|
+
$gsd-verify-work 1
|
|
76
151
|
```
|
|
77
152
|
|
|
78
153
|
## How It Works
|
|
@@ -80,7 +155,7 @@ When setting up npm Trusted Publisher for this package, use:
|
|
|
80
155
|
### 1. Initialize Project
|
|
81
156
|
|
|
82
157
|
```
|
|
83
|
-
|
|
158
|
+
$gsd-new-project
|
|
84
159
|
```
|
|
85
160
|
|
|
86
161
|
One command takes you from idea to ready-for-planning:
|
|
@@ -95,7 +170,7 @@ One command takes you from idea to ready-for-planning:
|
|
|
95
170
|
### 2. Plan Phase
|
|
96
171
|
|
|
97
172
|
```
|
|
98
|
-
|
|
173
|
+
$gsd-plan-phase 1
|
|
99
174
|
```
|
|
100
175
|
|
|
101
176
|
The system researches how to implement the phase, creates 2-3 atomic task plans, and verifies them against requirements.
|
|
@@ -105,7 +180,7 @@ The system researches how to implement the phase, creates 2-3 atomic task plans,
|
|
|
105
180
|
### 3. Execute Phase
|
|
106
181
|
|
|
107
182
|
```
|
|
108
|
-
|
|
183
|
+
$gsd-execute-phase 1
|
|
109
184
|
```
|
|
110
185
|
|
|
111
186
|
Runs all plans in parallel waves. Each plan executes in a fresh 200k context window. Every task gets its own atomic commit.
|
|
@@ -115,26 +190,22 @@ Runs all plans in parallel waves. Each plan executes in a fresh 200k context win
|
|
|
115
190
|
### 4. Verify Work
|
|
116
191
|
|
|
117
192
|
```
|
|
118
|
-
|
|
193
|
+
$gsd-verify-work 1
|
|
119
194
|
```
|
|
120
195
|
|
|
121
196
|
Manual user acceptance testing. The system walks you through testable deliverables and creates fix plans if issues are found.
|
|
122
197
|
|
|
123
198
|
## Commands
|
|
124
199
|
|
|
125
|
-
| Command
|
|
126
|
-
|
|
|
127
|
-
|
|
|
128
|
-
|
|
|
129
|
-
|
|
|
130
|
-
|
|
|
131
|
-
|
|
|
132
|
-
| `/prompts:gsd-new-milestone [name]` | Start next version |
|
|
133
|
-
| `/prompts:gsd-progress` | Show current status and what's next |
|
|
134
|
-
| `/prompts:gsd-update` | Check npm for a newer release and apply update |
|
|
135
|
-
| `/prompts:gsd-help` | Show all commands |
|
|
200
|
+
| Command | Description |
|
|
201
|
+
| ------------------------ | ----------------------------------------------------------------- |
|
|
202
|
+
| `$gsd-new-project` | Initialize project: questions → research → requirements → roadmap |
|
|
203
|
+
| `$gsd-plan-phase [N]` | Research + plan + verify for a phase |
|
|
204
|
+
| `$gsd-execute-phase <N>` | Execute all plans in parallel waves |
|
|
205
|
+
| `$gsd-verify-work [N]` | Manual user acceptance testing |
|
|
206
|
+
| `$gsd-help` | Show all commands |
|
|
136
207
|
|
|
137
|
-
|
|
208
|
+
Use `/prompts:gsd-*` aliases when installed with `--codex-mode prompts`.
|
|
138
209
|
|
|
139
210
|
## Why It Works
|
|
140
211
|
|
|
@@ -176,8 +247,9 @@ Git bisect finds exact failing task. Each task independently revertable.
|
|
|
176
247
|
|
|
177
248
|
**Commands not found?**
|
|
178
249
|
|
|
179
|
-
- Restart Codex
|
|
180
|
-
- Check `~/.codex/
|
|
250
|
+
- Restart Codex to reload installed command surfaces
|
|
251
|
+
- Check `~/.codex/skills/gsd-*/SKILL.md` (global) or `./skills/gsd-*/SKILL.md` (local)
|
|
252
|
+
- If using prompt aliases, check `~/.codex/prompts/gsd-*.md` (global) or `./prompts/gsd-*.md` (local)
|
|
181
253
|
|
|
182
254
|
**Update to latest:**
|
|
183
255
|
|
|
@@ -188,7 +260,7 @@ npx @undeemed/get-shit-done-codex@latest
|
|
|
188
260
|
**Can users be notified when an update is available?**
|
|
189
261
|
|
|
190
262
|
- Yes. The installer prints an update notice if a newer npm version exists.
|
|
191
|
-
- In-Codex update checks are available via `/prompts:gsd-update
|
|
263
|
+
- In-Codex update checks are available via `$gsd-update` (or `/prompts:gsd-update`).
|
|
192
264
|
- For release notifications outside the CLI, enable GitHub release watching on this repo.
|
|
193
265
|
|
|
194
266
|
## More Documentation
|
|
@@ -205,9 +277,9 @@ The original repository contains:
|
|
|
205
277
|
|
|
206
278
|
**Note:** The original README is written for Codex Code. When following it, remember that this fork uses:
|
|
207
279
|
|
|
208
|
-
-
|
|
209
|
-
-
|
|
210
|
-
-
|
|
280
|
+
- Codex-native skills (`$gsd-*`) by default
|
|
281
|
+
- Optional prompt aliases (`/prompts:gsd-*`) via `--codex-mode prompts`
|
|
282
|
+
- OpenAI Codex CLI & Desktop
|
|
211
283
|
|
|
212
284
|
## Keywords
|
|
213
285
|
|
package/agents/gsd-debugger.md
CHANGED
|
@@ -740,7 +740,7 @@ DEBUG_RESOLVED_DIR=.planning/debug/resolved
|
|
|
740
740
|
|
|
741
741
|
```markdown
|
|
742
742
|
---
|
|
743
|
-
status: gathering | investigating | fixing | verifying | resolved
|
|
743
|
+
status: gathering | investigating | fixing | verifying | awaiting_human_verify | resolved
|
|
744
744
|
trigger: "[verbatim user input]"
|
|
745
745
|
created: [ISO timestamp]
|
|
746
746
|
updated: [ISO timestamp]
|
|
@@ -804,10 +804,10 @@ files_changed: []
|
|
|
804
804
|
## Status Transitions
|
|
805
805
|
|
|
806
806
|
```
|
|
807
|
-
gathering -> investigating -> fixing -> verifying -> resolved
|
|
808
|
-
^ | |
|
|
809
|
-
|____________|___________|
|
|
810
|
-
(if verification fails)
|
|
807
|
+
gathering -> investigating -> fixing -> verifying -> awaiting_human_verify -> resolved
|
|
808
|
+
^ | | |
|
|
809
|
+
|____________|___________|_________________|
|
|
810
|
+
(if verification fails or user reports issue)
|
|
811
811
|
```
|
|
812
812
|
|
|
813
813
|
## Resume Behavior
|
|
@@ -910,6 +910,7 @@ Based on status:
|
|
|
910
910
|
- "investigating" -> Continue investigation_loop from Current Focus
|
|
911
911
|
- "fixing" -> Continue fix_and_verify
|
|
912
912
|
- "verifying" -> Continue verification
|
|
913
|
+
- "awaiting_human_verify" -> Wait for checkpoint response and either finalize or continue investigation
|
|
913
914
|
</step>
|
|
914
915
|
|
|
915
916
|
<step name="return_diagnosis">
|
|
@@ -969,11 +970,52 @@ Update status to "fixing".
|
|
|
969
970
|
- Update status to "verifying"
|
|
970
971
|
- Test against original Symptoms
|
|
971
972
|
- If verification FAILS: status -> "investigating", return to investigation_loop
|
|
972
|
-
- If verification PASSES: Update Resolution.verification, proceed to
|
|
973
|
+
- If verification PASSES: Update Resolution.verification, proceed to request_human_verification
|
|
974
|
+
</step>
|
|
975
|
+
|
|
976
|
+
<step name="request_human_verification">
|
|
977
|
+
**Require user confirmation before marking resolved.**
|
|
978
|
+
|
|
979
|
+
Update status to "awaiting_human_verify".
|
|
980
|
+
|
|
981
|
+
Return:
|
|
982
|
+
|
|
983
|
+
```markdown
|
|
984
|
+
## CHECKPOINT REACHED
|
|
985
|
+
|
|
986
|
+
**Type:** human-verify
|
|
987
|
+
**Debug Session:** .planning/debug/{slug}.md
|
|
988
|
+
**Progress:** {evidence_count} evidence entries, {eliminated_count} hypotheses eliminated
|
|
989
|
+
|
|
990
|
+
### Investigation State
|
|
991
|
+
|
|
992
|
+
**Current Hypothesis:** {from Current Focus}
|
|
993
|
+
**Evidence So Far:**
|
|
994
|
+
- {key finding 1}
|
|
995
|
+
- {key finding 2}
|
|
996
|
+
|
|
997
|
+
### Checkpoint Details
|
|
998
|
+
|
|
999
|
+
**Need verification:** confirm the original issue is resolved in your real workflow/environment
|
|
1000
|
+
|
|
1001
|
+
**Self-verified checks:**
|
|
1002
|
+
- {check 1}
|
|
1003
|
+
- {check 2}
|
|
1004
|
+
|
|
1005
|
+
**How to check:**
|
|
1006
|
+
1. {step 1}
|
|
1007
|
+
2. {step 2}
|
|
1008
|
+
|
|
1009
|
+
**Tell me:** "confirmed fixed" OR what's still failing
|
|
1010
|
+
```
|
|
1011
|
+
|
|
1012
|
+
Do NOT move file to `resolved/` in this step.
|
|
973
1013
|
</step>
|
|
974
1014
|
|
|
975
1015
|
<step name="archive_session">
|
|
976
|
-
**Archive resolved debug session.**
|
|
1016
|
+
**Archive resolved debug session after human confirmation.**
|
|
1017
|
+
|
|
1018
|
+
Only run this step when checkpoint response confirms the fix works end-to-end.
|
|
977
1019
|
|
|
978
1020
|
Update status to "resolved".
|
|
979
1021
|
|
|
@@ -1130,6 +1172,8 @@ Orchestrator presents checkpoint to user, gets response, spawns fresh continuati
|
|
|
1130
1172
|
**Commit:** {hash}
|
|
1131
1173
|
```
|
|
1132
1174
|
|
|
1175
|
+
Only return this after human verification confirms the fix.
|
|
1176
|
+
|
|
1133
1177
|
## INVESTIGATION INCONCLUSIVE
|
|
1134
1178
|
|
|
1135
1179
|
```markdown
|
|
@@ -1179,7 +1223,8 @@ Check for mode flags in prompt context:
|
|
|
1179
1223
|
**goal: find_and_fix** (default)
|
|
1180
1224
|
- Find root cause, then fix and verify
|
|
1181
1225
|
- Complete full debugging cycle
|
|
1182
|
-
-
|
|
1226
|
+
- Require human-verify checkpoint after self-verification
|
|
1227
|
+
- Archive session only after user confirmation
|
|
1183
1228
|
|
|
1184
1229
|
**Default mode (no flags):**
|
|
1185
1230
|
- Interactive debugging with user
|
package/agents/gsd-planner.md
CHANGED
|
@@ -157,21 +157,19 @@ Every task has four required fields:
|
|
|
157
157
|
- Good: "Create POST endpoint accepting {email, password}, validates using bcrypt against User table, returns JWT in httpOnly cookie with 15-min expiry. Use jose library (not jsonwebtoken - CommonJS issues with Edge runtime)."
|
|
158
158
|
- Bad: "Add authentication", "Make login work"
|
|
159
159
|
|
|
160
|
-
**<verify>:** How to prove the task is complete.
|
|
160
|
+
**<verify>:** How to prove the task is complete.
|
|
161
161
|
|
|
162
162
|
```xml
|
|
163
163
|
<verify>
|
|
164
164
|
<automated>pytest tests/test_module.py::test_behavior -x</automated>
|
|
165
|
-
<manual>Optional: human-readable description of what to check</manual>
|
|
166
|
-
<sampling_rate>run after this task commits, before next task begins</sampling_rate>
|
|
167
165
|
</verify>
|
|
168
166
|
```
|
|
169
167
|
|
|
170
168
|
- Good: Specific automated command that runs in < 60 seconds
|
|
171
169
|
- Bad: "It works", "Looks good", manual-only verification
|
|
172
|
-
- Simple format also accepted: `npm test` passes, `curl -X POST /api/auth/login` returns 200
|
|
170
|
+
- Simple format also accepted: `npm test` passes, `curl -X POST /api/auth/login` returns 200
|
|
173
171
|
|
|
174
|
-
**Nyquist Rule:** Every `<verify>` must include an `<automated>` command. If no test exists yet
|
|
172
|
+
**Nyquist Rule:** Every `<verify>` must include an `<automated>` command. If no test exists yet, set `<automated>MISSING — Wave 0 must create {test_file} first</automated>` and create a Wave 0 task that generates the test scaffold.
|
|
175
173
|
|
|
176
174
|
**<done>:** Acceptance criteria - measurable state of completion.
|
|
177
175
|
- Good: "Valid credentials return 200 + JWT cookie, invalid credentials return 401"
|
|
@@ -202,6 +200,16 @@ Each task: **15-60 minutes** Codex execution time.
|
|
|
202
200
|
|
|
203
201
|
**Combine signals:** One task sets up for the next, separate tasks touch same file, neither meaningful alone.
|
|
204
202
|
|
|
203
|
+
## Interface-First Task Ordering
|
|
204
|
+
|
|
205
|
+
When a plan creates new interfaces consumed by subsequent tasks:
|
|
206
|
+
|
|
207
|
+
1. **First task: Define contracts** — Create type files, interfaces, exports
|
|
208
|
+
2. **Middle tasks: Implement** — Build against the defined contracts
|
|
209
|
+
3. **Last task: Wire** — Connect implementations to consumers
|
|
210
|
+
|
|
211
|
+
This prevents the "scavenger hunt" anti-pattern where executors explore the codebase to understand contracts. They receive the contracts in the plan itself.
|
|
212
|
+
|
|
205
213
|
## Specificity Examples
|
|
206
214
|
|
|
207
215
|
| TOO VAGUE | JUST RIGHT |
|
|
@@ -447,6 +455,69 @@ After completion, create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
|
|
|
447
455
|
|
|
448
456
|
Wave numbers are pre-computed during planning. Execute-phase reads `wave` directly from frontmatter.
|
|
449
457
|
|
|
458
|
+
## Interface Context for Executors
|
|
459
|
+
|
|
460
|
+
**Key insight:** "The difference between handing a contractor blueprints versus telling them 'build me a house.'"
|
|
461
|
+
|
|
462
|
+
When creating plans that depend on existing code or create new interfaces consumed by other plans:
|
|
463
|
+
|
|
464
|
+
### For plans that USE existing code:
|
|
465
|
+
After determining `files_modified`, extract the key interfaces/types/exports from the codebase that executors will need:
|
|
466
|
+
|
|
467
|
+
```bash
|
|
468
|
+
# Extract type definitions, interfaces, and exports from relevant files
|
|
469
|
+
grep -n "export\|interface\|type\|class\|function" {relevant_source_files} 2>/dev/null | head -50
|
|
470
|
+
```
|
|
471
|
+
|
|
472
|
+
Embed these in the plan's `<context>` section as an `<interfaces>` block:
|
|
473
|
+
|
|
474
|
+
```xml
|
|
475
|
+
<interfaces>
|
|
476
|
+
<!-- Key types and contracts the executor needs. Extracted from codebase. -->
|
|
477
|
+
<!-- Executor should use these directly — no codebase exploration needed. -->
|
|
478
|
+
|
|
479
|
+
From src/types/user.ts:
|
|
480
|
+
```typescript
|
|
481
|
+
export interface User {
|
|
482
|
+
id: string;
|
|
483
|
+
email: string;
|
|
484
|
+
name: string;
|
|
485
|
+
createdAt: Date;
|
|
486
|
+
}
|
|
487
|
+
```
|
|
488
|
+
|
|
489
|
+
From src/api/auth.ts:
|
|
490
|
+
```typescript
|
|
491
|
+
export function validateToken(token: string): Promise<User | null>;
|
|
492
|
+
export function createSession(user: User): Promise<SessionToken>;
|
|
493
|
+
```
|
|
494
|
+
</interfaces>
|
|
495
|
+
```
|
|
496
|
+
|
|
497
|
+
### For plans that CREATE new interfaces:
|
|
498
|
+
If this plan creates types/interfaces that later plans depend on, include a "Wave 0" skeleton step:
|
|
499
|
+
|
|
500
|
+
```xml
|
|
501
|
+
<task type="auto">
|
|
502
|
+
<name>Task 0: Write interface contracts</name>
|
|
503
|
+
<files>src/types/newFeature.ts</files>
|
|
504
|
+
<action>Create type definitions that downstream plans will implement against. These are the contracts — implementation comes in later tasks.</action>
|
|
505
|
+
<verify>File exists with exported types, no implementation</verify>
|
|
506
|
+
<done>Interface file committed, types exported</done>
|
|
507
|
+
</task>
|
|
508
|
+
```
|
|
509
|
+
|
|
510
|
+
### When to include interfaces:
|
|
511
|
+
- Plan touches files that import from other modules → extract those module's exports
|
|
512
|
+
- Plan creates a new API endpoint → extract the request/response types
|
|
513
|
+
- Plan modifies a component → extract its props interface
|
|
514
|
+
- Plan depends on a previous plan's output → extract the types from that plan's files_modified
|
|
515
|
+
|
|
516
|
+
### When to skip:
|
|
517
|
+
- Plan is self-contained (creates everything from scratch, no imports)
|
|
518
|
+
- Plan is pure configuration (no code interfaces involved)
|
|
519
|
+
- Level 0 discovery (all patterns already established)
|
|
520
|
+
|
|
450
521
|
## Context Section Rules
|
|
451
522
|
|
|
452
523
|
Only include prior plan SUMMARY references if genuinely needed (uses types/exports from prior plan, or prior plan made decision affecting this one).
|
|
@@ -956,6 +1027,16 @@ For phases not selected, retain from digest:
|
|
|
956
1027
|
- `patterns`: Conventions to follow
|
|
957
1028
|
|
|
958
1029
|
**From STATE.md:** Decisions → constrain approach. Pending todos → candidates.
|
|
1030
|
+
|
|
1031
|
+
**From RETROSPECTIVE.md (if exists):**
|
|
1032
|
+
```bash
|
|
1033
|
+
cat .planning/RETROSPECTIVE.md 2>/dev/null | tail -100
|
|
1034
|
+
```
|
|
1035
|
+
|
|
1036
|
+
Read the most recent milestone retrospective and cross-milestone trends. Extract:
|
|
1037
|
+
- **Patterns to follow** from "What Worked" and "Patterns Established"
|
|
1038
|
+
- **Patterns to avoid** from "What Was Inefficient" and "Key Lessons"
|
|
1039
|
+
- **Cost patterns** to inform model selection and agent strategy
|
|
959
1040
|
</step>
|
|
960
1041
|
|
|
961
1042
|
<step name="gather_phase_context">
|
package/agents/gsd-verifier.md
CHANGED
|
@@ -16,6 +16,21 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool t
|
|
|
16
16
|
**Critical mindset:** Do NOT trust SUMMARY.md claims. SUMMARYs document what Codex SAID it did. You verify what ACTUALLY exists in the code. These often differ.
|
|
17
17
|
</role>
|
|
18
18
|
|
|
19
|
+
<project_context>
|
|
20
|
+
Before verifying, discover project context:
|
|
21
|
+
|
|
22
|
+
**Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
|
|
23
|
+
|
|
24
|
+
**Project skills:** Check `.agents/skills/` directory if it exists:
|
|
25
|
+
1. List available skills (subdirectories)
|
|
26
|
+
2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
|
|
27
|
+
3. Load specific `rules/*.md` files as needed during verification
|
|
28
|
+
4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
|
|
29
|
+
5. Apply skill rules when scanning for anti-patterns and verifying quality
|
|
30
|
+
|
|
31
|
+
This ensures project-specific patterns, conventions, and best practices are applied during verification.
|
|
32
|
+
</project_context>
|
|
33
|
+
|
|
19
34
|
<core_principle>
|
|
20
35
|
**Task completion ≠ Goal achievement**
|
|
21
36
|
|