@undeemed/get-shit-done-codex 1.20.9 → 1.21.0
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/.codex/config.toml +77 -0
- package/README.md +125 -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 +634 -50
- 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/{AGENTS.md → get-shit-done/AGENTS.md} +30 -30
- 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 -2
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
:schema https://developers.openai.com/codex/config-schema.json
|
|
2
|
+
|
|
3
|
+
# Project-scoped Codex config for get-shit-done-codex.
|
|
4
|
+
# Loaded only when this project is trusted.
|
|
5
|
+
# Docs:
|
|
6
|
+
# - https://developers.openai.com/codex/config-basic
|
|
7
|
+
# - https://developers.openai.com/codex/config-reference
|
|
8
|
+
# - https://developers.openai.com/codex/multi-agent
|
|
9
|
+
|
|
10
|
+
web_search = "live"
|
|
11
|
+
|
|
12
|
+
[features]
|
|
13
|
+
multi_agent = true
|
|
14
|
+
collaboration_modes = true
|
|
15
|
+
shell_tool = true
|
|
16
|
+
shell_snapshot = true
|
|
17
|
+
unified_exec = true
|
|
18
|
+
apply_patch_freeform = true
|
|
19
|
+
personality = true
|
|
20
|
+
request_rule = true
|
|
21
|
+
|
|
22
|
+
[agents]
|
|
23
|
+
max_threads = 12
|
|
24
|
+
max_depth = 3
|
|
25
|
+
|
|
26
|
+
[agents."general-purpose"]
|
|
27
|
+
description = "General fallback role for GSD orchestration and ad-hoc subtasks."
|
|
28
|
+
|
|
29
|
+
[agents."gsd-codebase-mapper"]
|
|
30
|
+
description = "Map stack, architecture, conventions, testing, and concerns into .planning/codebase docs."
|
|
31
|
+
developer_instructions = "Read and follow agents/gsd-codebase-mapper.md for your complete role definition."
|
|
32
|
+
|
|
33
|
+
[agents."gsd-debugger"]
|
|
34
|
+
description = "Investigate regressions with hypothesis testing, isolate root cause, and propose or apply fixes."
|
|
35
|
+
developer_instructions = "Read and follow agents/gsd-debugger.md for your complete role definition."
|
|
36
|
+
|
|
37
|
+
[agents."gsd-executor"]
|
|
38
|
+
description = "Execute PLAN.md tasks with atomic commits, verification, and summary updates."
|
|
39
|
+
developer_instructions = "Read and follow agents/gsd-executor.md for your complete role definition."
|
|
40
|
+
|
|
41
|
+
[agents."gsd-integration-checker"]
|
|
42
|
+
description = "Verify cross-phase wiring and end-to-end behavior across delivered milestones."
|
|
43
|
+
developer_instructions = "Read and follow agents/gsd-integration-checker.md for your complete role definition."
|
|
44
|
+
|
|
45
|
+
[agents."gsd-phase-researcher"]
|
|
46
|
+
description = "Research phase implementation patterns and write RESEARCH.md artifacts for planners."
|
|
47
|
+
developer_instructions = "Read and follow agents/gsd-phase-researcher.md for your complete role definition."
|
|
48
|
+
|
|
49
|
+
[agents."gsd-plan-checker"]
|
|
50
|
+
description = "Stress-test plan quality and requirement coverage before execution."
|
|
51
|
+
developer_instructions = "Read and follow agents/gsd-plan-checker.md for your complete role definition."
|
|
52
|
+
|
|
53
|
+
[agents."gsd-planner"]
|
|
54
|
+
description = "Draft atomic PLAN.md files with objective, context, tasks, and success criteria."
|
|
55
|
+
developer_instructions = "Read and follow agents/gsd-planner.md for your complete role definition."
|
|
56
|
+
|
|
57
|
+
[agents."gsd-project-researcher"]
|
|
58
|
+
description = "Research ecosystem and produce project-level research docs for roadmap creation."
|
|
59
|
+
developer_instructions = "Read and follow agents/gsd-project-researcher.md for your complete role definition."
|
|
60
|
+
|
|
61
|
+
[agents."gsd-research-synthesizer"]
|
|
62
|
+
description = "Synthesize parallel research artifacts into actionable roadmap inputs."
|
|
63
|
+
developer_instructions = "Read and follow agents/gsd-research-synthesizer.md for your complete role definition."
|
|
64
|
+
|
|
65
|
+
[agents."gsd-roadmapper"]
|
|
66
|
+
description = "Turn requirements into phased ROADMAP.md structure with clear success criteria."
|
|
67
|
+
developer_instructions = "Read and follow agents/gsd-roadmapper.md for your complete role definition."
|
|
68
|
+
|
|
69
|
+
[agents."gsd-verifier"]
|
|
70
|
+
description = "Perform goal-backward verification that outcomes are actually delivered in code."
|
|
71
|
+
developer_instructions = "Read and follow agents/gsd-verifier.md for your complete role definition."
|
|
72
|
+
|
|
73
|
+
[mcp_servers.context7]
|
|
74
|
+
url = "https://mcp.context7.com/mcp"
|
|
75
|
+
|
|
76
|
+
[mcp_servers.context7.env_http_headers]
|
|
77
|
+
CONTEXT7_API_KEY = "CONTEXT7_API_KEY"
|
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,123 @@ 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
|
|
57
|
+
```
|
|
58
|
+
|
|
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
|
+
### What Gets Installed
|
|
70
|
+
|
|
71
|
+
The installer distributes everything GSD needs:
|
|
72
|
+
|
|
73
|
+
- **`AGENTS.md`** — behavior contract and command reference for Codex
|
|
74
|
+
- **`.codex/config.toml`** — multi-agent mode, feature flags, agent role registry, MCP servers
|
|
75
|
+
- **`agents/gsd-*.md`** — rich agent definitions (700+ lines each) for sub-agent orchestration
|
|
76
|
+
- **`skills/gsd-*/SKILL.md`** or **`prompts/gsd-*.md`** — command surfaces
|
|
77
|
+
- **`get-shit-done/`** — workflow files, templates, and references
|
|
78
|
+
|
|
79
|
+
On first run, Codex will prompt you to **trust the project** so the config takes effect (one-time, one-click).
|
|
80
|
+
|
|
81
|
+
> [!NOTE]
|
|
82
|
+
> `.codex/config.toml` is non-destructive — the installer skips it if you already have one, so your customizations are preserved on updates.
|
|
83
|
+
|
|
84
|
+
### Installed File Structure
|
|
85
|
+
|
|
86
|
+
`$` skills mode (`--codex-mode skills`, default):
|
|
87
|
+
|
|
88
|
+
```text
|
|
89
|
+
~/.codex/
|
|
90
|
+
├── AGENTS.md
|
|
91
|
+
├── .codex/config.toml
|
|
92
|
+
├── agents/gsd-*.md
|
|
93
|
+
├── skills/gsd-*/SKILL.md
|
|
94
|
+
└── get-shit-done/
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
`/prompts` mode (`--codex-mode prompts`):
|
|
98
|
+
|
|
99
|
+
```text
|
|
100
|
+
~/.codex/
|
|
101
|
+
├── AGENTS.md
|
|
102
|
+
├── .codex/config.toml
|
|
103
|
+
├── agents/gsd-*.md
|
|
104
|
+
├── prompts/gsd-*.md
|
|
105
|
+
└── get-shit-done/
|
|
32
106
|
```
|
|
33
107
|
|
|
34
|
-
|
|
108
|
+
For local installs, replace `~/.codex/` with `./`.
|
|
109
|
+
|
|
110
|
+
### Verify And Repair
|
|
111
|
+
|
|
112
|
+
- `--verify`: checks `AGENTS.md`, `config.toml`, agent definitions, command surfaces, workflow assets, and version metadata.
|
|
113
|
+
- `--verify --repair`: reinstalls missing/broken artifacts and verifies again.
|
|
114
|
+
- Migration is **detect-then-confirm**, not automatic:
|
|
115
|
+
- Interactive install asks before removing legacy surface files
|
|
116
|
+
- Non-interactive install skips cleanup unless `--migrate` is passed
|
|
117
|
+
- `--skip-migrate` keeps legacy files explicitly
|
|
118
|
+
|
|
119
|
+
### AGENTS-First Reliability
|
|
120
|
+
|
|
121
|
+
This fork is intentionally **AGENTS.md-first** for Codex reliability:
|
|
122
|
+
|
|
123
|
+
- `AGENTS.md` is the source of truth for behavior and workflow constraints
|
|
124
|
+
- `$gsd-*` skills are lightweight command wrappers around the same workflow docs
|
|
125
|
+
- `/prompts:gsd-*` are optional compatibility aliases (prompts mode)
|
|
35
126
|
|
|
36
127
|
## Staying Updated
|
|
37
128
|
|
|
38
129
|
```bash
|
|
39
130
|
# Check for updates from inside Codex
|
|
40
|
-
|
|
131
|
+
$gsd-update
|
|
132
|
+
# or: /prompts:gsd-update
|
|
41
133
|
|
|
42
134
|
# Update from terminal
|
|
43
135
|
npx @undeemed/get-shit-done-codex@latest --global
|
|
44
136
|
```
|
|
45
137
|
|
|
46
|
-
The installer
|
|
138
|
+
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
139
|
|
|
48
140
|
## npm Trusted Publisher (OIDC)
|
|
49
141
|
|
|
@@ -63,16 +155,16 @@ When setting up npm Trusted Publisher for this package, use:
|
|
|
63
155
|
|
|
64
156
|
```bash
|
|
65
157
|
# 1. Initialize project (questions → research → requirements → roadmap)
|
|
66
|
-
|
|
158
|
+
$gsd-new-project
|
|
67
159
|
|
|
68
160
|
# 2. Plan the first phase
|
|
69
|
-
|
|
161
|
+
$gsd-plan-phase 1
|
|
70
162
|
|
|
71
163
|
# 3. Execute the phase
|
|
72
|
-
|
|
164
|
+
$gsd-execute-phase 1
|
|
73
165
|
|
|
74
166
|
# 4. Verify it works
|
|
75
|
-
|
|
167
|
+
$gsd-verify-work 1
|
|
76
168
|
```
|
|
77
169
|
|
|
78
170
|
## How It Works
|
|
@@ -80,7 +172,7 @@ When setting up npm Trusted Publisher for this package, use:
|
|
|
80
172
|
### 1. Initialize Project
|
|
81
173
|
|
|
82
174
|
```
|
|
83
|
-
|
|
175
|
+
$gsd-new-project
|
|
84
176
|
```
|
|
85
177
|
|
|
86
178
|
One command takes you from idea to ready-for-planning:
|
|
@@ -95,7 +187,7 @@ One command takes you from idea to ready-for-planning:
|
|
|
95
187
|
### 2. Plan Phase
|
|
96
188
|
|
|
97
189
|
```
|
|
98
|
-
|
|
190
|
+
$gsd-plan-phase 1
|
|
99
191
|
```
|
|
100
192
|
|
|
101
193
|
The system researches how to implement the phase, creates 2-3 atomic task plans, and verifies them against requirements.
|
|
@@ -105,7 +197,7 @@ The system researches how to implement the phase, creates 2-3 atomic task plans,
|
|
|
105
197
|
### 3. Execute Phase
|
|
106
198
|
|
|
107
199
|
```
|
|
108
|
-
|
|
200
|
+
$gsd-execute-phase 1
|
|
109
201
|
```
|
|
110
202
|
|
|
111
203
|
Runs all plans in parallel waves. Each plan executes in a fresh 200k context window. Every task gets its own atomic commit.
|
|
@@ -115,26 +207,22 @@ Runs all plans in parallel waves. Each plan executes in a fresh 200k context win
|
|
|
115
207
|
### 4. Verify Work
|
|
116
208
|
|
|
117
209
|
```
|
|
118
|
-
|
|
210
|
+
$gsd-verify-work 1
|
|
119
211
|
```
|
|
120
212
|
|
|
121
213
|
Manual user acceptance testing. The system walks you through testable deliverables and creates fix plans if issues are found.
|
|
122
214
|
|
|
123
215
|
## Commands
|
|
124
216
|
|
|
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 |
|
|
217
|
+
| Command | Description |
|
|
218
|
+
| ------------------------ | ----------------------------------------------------------------- |
|
|
219
|
+
| `$gsd-new-project` | Initialize project: questions → research → requirements → roadmap |
|
|
220
|
+
| `$gsd-plan-phase [N]` | Research + plan + verify for a phase |
|
|
221
|
+
| `$gsd-execute-phase <N>` | Execute all plans in parallel waves |
|
|
222
|
+
| `$gsd-verify-work [N]` | Manual user acceptance testing |
|
|
223
|
+
| `$gsd-help` | Show all commands |
|
|
136
224
|
|
|
137
|
-
|
|
225
|
+
Use `/prompts:gsd-*` aliases when installed with `--codex-mode prompts`.
|
|
138
226
|
|
|
139
227
|
## Why It Works
|
|
140
228
|
|
|
@@ -176,8 +264,15 @@ Git bisect finds exact failing task. Each task independently revertable.
|
|
|
176
264
|
|
|
177
265
|
**Commands not found?**
|
|
178
266
|
|
|
179
|
-
- Restart Codex
|
|
180
|
-
- Check `~/.codex/
|
|
267
|
+
- Restart Codex to reload installed command surfaces
|
|
268
|
+
- Check `~/.codex/skills/gsd-*/SKILL.md` (global) or `./skills/gsd-*/SKILL.md` (local)
|
|
269
|
+
- If using prompt aliases, check `~/.codex/prompts/gsd-*.md` (global) or `./prompts/gsd-*.md` (local)
|
|
270
|
+
|
|
271
|
+
**Multi-agent / sub-agents not working?**
|
|
272
|
+
|
|
273
|
+
- Check `.codex/config.toml` exists in your install directory
|
|
274
|
+
- Ensure the project is **trusted** in Codex (it prompts on first run)
|
|
275
|
+
- Run `--verify` to check all artifacts are present
|
|
181
276
|
|
|
182
277
|
**Update to latest:**
|
|
183
278
|
|
|
@@ -188,7 +283,7 @@ npx @undeemed/get-shit-done-codex@latest
|
|
|
188
283
|
**Can users be notified when an update is available?**
|
|
189
284
|
|
|
190
285
|
- Yes. The installer prints an update notice if a newer npm version exists.
|
|
191
|
-
- In-Codex update checks are available via `/prompts:gsd-update
|
|
286
|
+
- In-Codex update checks are available via `$gsd-update` (or `/prompts:gsd-update`).
|
|
192
287
|
- For release notifications outside the CLI, enable GitHub release watching on this repo.
|
|
193
288
|
|
|
194
289
|
## More Documentation
|
|
@@ -205,9 +300,9 @@ The original repository contains:
|
|
|
205
300
|
|
|
206
301
|
**Note:** The original README is written for Codex Code. When following it, remember that this fork uses:
|
|
207
302
|
|
|
208
|
-
-
|
|
209
|
-
-
|
|
210
|
-
-
|
|
303
|
+
- Codex-native skills (`$gsd-*`) by default
|
|
304
|
+
- Optional prompt aliases (`/prompts:gsd-*`) via `--codex-mode prompts`
|
|
305
|
+
- OpenAI Codex CLI & Desktop
|
|
211
306
|
|
|
212
307
|
## Keywords
|
|
213
308
|
|
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
|
|