@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 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 `/gsd:command-name`:
84
+ The following commands are available. Invoke them with `$gsd-command-name`:
85
85
 
86
86
  | Command | Description |
87
87
  | --------------------------------- | ------------------------------------------- |
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 |
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
- /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
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
- /gsd:map-codebase # Analyze existing code → codebase/
125
- /gsd:new-project # Questioning with codebase context
126
- /gsd:create-roadmap # Continue as normal
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
  [![npm version](https://img.shields.io/npm/v/%40undeemed%2Fget-shit-done-codex?style=flat-square)](https://www.npmjs.com/package/@undeemed/get-shit-done-codex)
8
11
  [![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)
9
12
  ![npm Downloads](https://img.shields.io/npm/dt/@undeemed/get-shit-done-codex?style=flat-square)
@@ -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'll be prompted to install globally (`~/.codex/`) or locally (`./`).
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
- After installation, run `codex` (CLI) or `codex app` (Desktop), then use `/prompts:gsd-help` to see all commands.
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
- /prompts:gsd-update
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 now writes a `get-shit-done/VERSION` file so `/prompts:gsd-update` can detect installed vs latest and show changelog before updating.
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
- /prompts:gsd-new-project
141
+ $gsd-new-project
67
142
 
68
143
  # 2. Plan the first phase
69
- /prompts:gsd-plan-phase 1
144
+ $gsd-plan-phase 1
70
145
 
71
146
  # 3. Execute the phase
72
- /prompts:gsd-execute-phase 1
147
+ $gsd-execute-phase 1
73
148
 
74
149
  # 4. Verify it works
75
- /prompts:gsd-verify-work 1
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
- /prompts:gsd-new-project
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
- /prompts:gsd-plan-phase 1
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
- /prompts:gsd-execute-phase 1
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
- /prompts:gsd-verify-work 1
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 | Description |
126
- | ----------------------------------- | ----------------------------------------------------------------- |
127
- | `/prompts:gsd-new-project` | Initialize project: questions → research → requirements → roadmap |
128
- | `/prompts:gsd-plan-phase [N]` | Research + plan + verify for a phase |
129
- | `/prompts:gsd-execute-phase <N>` | Execute all plans in parallel waves |
130
- | `/prompts:gsd-verify-work [N]` | Manual user acceptance testing |
131
- | `/prompts:gsd-complete-milestone` | Archive milestone, tag release |
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
- See `/prompts:gsd-help` for the complete command reference.
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 CLI to reload prompts
180
- - Check `~/.codex/prompts/gsd-*.md` (global) or `./prompts/gsd-*.md` (local)
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
- - `/prompts:gsd-*` command format (instead of `/gsd:*`)
209
- - OpenAI Codex CLI & Desktop (instead of Codex Code)
210
- - `~/.codex/` directory (instead of `~/.codex/`)
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
 
@@ -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 archive_session
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
- - Archive session when verified
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
@@ -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. Supports structured format:
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 with Set-Cookie header
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 for this behavior, set `<automated>MISSING — Wave 0 must create {test_file} first</automated>` and create a Wave 0 task that generates the test scaffold.
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">
@@ -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