You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
FEAT-96: update plan-with-codex syntax and add prompt refactoring guide (#26)
* feat(code,platform): update plan-with-codex syntax and add prompt refactoring guide
Update plan-with-codex argument-hint to positional syntax. Add
"Refactoring Existing Prompts" section to context-engineering skill.
Fix stale skill count in platform README. Update changelogs.
* fix(code): use Write tool for plan-with-codex state persistence
Replace inline Bash printf/grep commands with Write and Read tool calls
in the plan-with-codex slash command. This makes state file operations
deterministic so users can approve the permission once instead of
re-approving every debate round.
* feat(code): add feedback-explorer agent to speed up plan revisions
Add a haiku-powered feedback-explorer agent that pre-fetches codebase
context referenced in Codex feedback before plan-agent revises. This
front-loads mechanical file discovery so opus can focus on judgment,
cutting revision time from ~6 minutes to ~2-3 minutes.
* fix(code): use fully qualified agent name for feedback-explorer
* add write tool
Copy file name to clipboardExpand all lines: CHANGELOG.md
+10Lines changed: 10 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,6 +6,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
6
6
7
7
## [Unreleased]
8
8
9
+
### code v1.2.2
10
+
11
+
#### Changed
12
+
- Updated `plan-with-codex` command argument-hint to use positional syntax instead of optional bracket notation
13
+
14
+
### platform v1.0.2
15
+
16
+
#### Added
17
+
- New "Refactoring Existing Prompts" section in `context-engineering` skill covering pitfalls for stale cross-references, over-abstraction, lost preconditions, and silent behavior changes
-`feedback-explorer` agent (haiku): pre-fetches codebase context referenced in reviewer feedback before plan-agent revises, cutting revision time from ~6 minutes to ~2-3 minutes.
8
+
-`plan-with-codex` Step 2e now spawns feedback-explorer before resuming plan-agent, writing a `{stem}.context` brief with pre-fetched code snippets.
9
+
10
+
### Fixed
11
+
12
+
-`plan-with-codex`: Replace inline Bash `printf` state writes with Write tool calls so the user only approves the file path once instead of re-approving every round.
13
+
-`plan-with-codex`: Replace Bash `grep`/`cut` state reads with a single Read tool call; explicitly ignore unknown keys for cross-flow compatibility with `debate-loop.sh`.
description: Haiku agent that pre-fetches codebase context referenced in reviewer feedback, so the plan-agent can skip mechanical exploration during revision.
4
+
model: haiku
5
+
tools: Read, Write, Glob, Grep
6
+
---
7
+
8
+
# Feedback Explorer
9
+
10
+
You do fast, mechanical codebase exploration to gather context for reviewer feedback. Your output is a context file that the plan-agent reads before revising, so it can focus on judgment instead of file discovery.
11
+
12
+
## Input
13
+
14
+
Your prompt will include:
15
+
-**feedback file path** -- the reviewer's findings
16
+
-**plan file path** -- the current plan
17
+
-**context output path** -- where to write results
18
+
19
+
## Process
20
+
21
+
1.**Read the feedback file and the plan file.**
22
+
23
+
2.**Extract references from the feedback.** For each finding, collect:
- Pattern keywords to search for (e.g., `redirect_uri`, `SetCookie`)
27
+
- Test file references
28
+
29
+
3.**Also extract references from the plan's Critical Files section** -- these are files the plan-agent already identified as relevant.
30
+
31
+
4.**Locate and fetch each reference.** For each:
32
+
- If it's a file path: Read it (or the relevant line range if a line number is given)
33
+
- If it's a function/type name: `Grep` for its definition, then Read the surrounding context (30 lines)
34
+
- If it's a keyword pattern: `Grep` for occurrences, Read the top 3 matches
35
+
- If a file path doesn't exist: try `Glob` with `**/{filename}` to find it
36
+
37
+
5.**Write the context file** using the format below. Use the `Write` tool.
38
+
39
+
## Output Format
40
+
41
+
```markdown
42
+
# Feedback Context Brief
43
+
44
+
## Finding 1: [title from feedback]
45
+
46
+
### [path/to/file.go:100-130]
47
+
```
48
+
[code snippet]
49
+
```
50
+
51
+
### [path/to/other_file.go:40-70]
52
+
```
53
+
[code snippet]
54
+
```
55
+
56
+
## Finding 2: [title from feedback]
57
+
58
+
### [path/to/file.tsx:1-50]
59
+
```
60
+
[code snippet]
61
+
```
62
+
63
+
## Plan Critical Files
64
+
65
+
### [path/to/critical_file.go:1-80]
66
+
```
67
+
[code snippet]
68
+
```
69
+
70
+
## Additional Discoveries
71
+
- [any relevant files found during search that weren't explicitly referenced]
72
+
```
73
+
74
+
## Rules
75
+
76
+
-**Speed over completeness.** Fetch what's explicitly referenced. Don't explore tangentially.
77
+
-**Include line numbers** in every section header so the plan-agent can verify without re-reading.
78
+
-**If a reference can't be found**, note it: `[NOT FOUND: path/to/missing.go -- searched with Glob **/{filename}]`
79
+
-**Do not analyze or judge the findings.** That's the plan-agent's job. You just gather code.
80
+
-**Keep snippets focused.** If a finding references a specific function, include that function plus ~10 lines of surrounding context, not the entire file.
Copy file name to clipboardExpand all lines: plugins/code/agents/plan-agent.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -87,8 +87,8 @@ Structure plans with these sections:
87
87
88
88
When given feedback to address:
89
89
90
-
1. Read the current plan file and the feedback file
91
-
2.**Verify each finding against the codebase before acting on it.** Use `Grep`, `Glob`, and `Read`to check whether the reviewer's claims are accurate (e.g., does the file/function they reference actually exist? Is the behavior they describe real?). Reviewers can hallucinate or misunderstand the codebase.
90
+
1. Read the current plan file and the feedback file. **If a context brief file is provided**, read it first -- it contains pre-fetched code snippets for the files and symbols referenced in the feedback, so you can skip most exploration.
91
+
2.**Verify each finding against the codebase before acting on it.**Start with the context brief if available. Use `Grep`, `Glob`, and `Read`for anything not covered by the brief or when you need additional context beyond what was pre-fetched. Reviewers can hallucinate or misunderstand the codebase.
92
92
3. For verified findings: address the concern. If the reviewer proposed a concrete fix, adopt it directly unless you have a strong reason not to.
93
93
4. For findings that don't hold up: reject them with a brief explanation and evidence (e.g., "Finding 2 claims X is missing, but `path/to/file:42` already implements it").
94
94
5. Write the updated plan back to the same file path using the `Write` tool
Check if `{stem}.state` exists (`test -f`). If yes, Read the state file and extract values by key name: `ROUND`, `PHASE`, `CODEX_SESSION_ID`, `LOG_ID`. Ignore any unknown keys (the shell-based debate-loop.sh writes an extra `SESSION_ID` field -- skip it).
90
88
91
89
**Validate preconditions:**
92
90
@@ -211,11 +209,27 @@ Read the feedback file and display full Codex feedback to the user.
**First, launch the `code:feedback-explorer`** (haiku) to pre-fetch codebase context referenced in the feedback:
215
+
216
+
```
217
+
Agent(
218
+
subagent_type="code:feedback-explorer",
219
+
name="feedback-explorer",
220
+
model="haiku",
221
+
mode="bypassPermissions",
222
+
run_in_background=false,
223
+
description="Pre-fetch context for round {N} feedback",
224
+
prompt="Read the feedback at {feedback-file-abs} and the plan at {plan-file-abs}. For every file path, function name, and code pattern referenced in the findings, locate and fetch the relevant code snippets. Write the context brief to {context-file-abs}."
**Then resume the plan-agent** with the pre-fetched context:
217
231
- description: "Revise plan based on Codex feedback"
218
-
- prompt: "Revise the plan at {plan-file-abs} based on feedback at {feedback-file-abs}. Verify each finding against the codebase before acting on it -- reject any that don't hold up. After updating the plan, write a revision summary to {revisions-file-abs}."
232
+
- prompt: "A context brief with pre-fetched code snippets is available at {context-file-abs} -- read it first to avoid redundant exploration. Then revise the plan at {plan-file-abs} based on feedback at {feedback-file-abs}. Verify each finding against the codebase before acting on it -- reject any that don't hold up. If the context brief is missing a file you need, use your own tools to fetch it. After updating the plan, write a revision summary to {revisions-file-abs}."
219
233
220
234
Verify plan was updated. Write state: `ROUND={N+1}, PHASE=codex_review`, preserve current `CODEX_SESSION_ID` and `LOG_ID`. Continue to next round.
221
235
@@ -228,7 +242,7 @@ Report outcome:
228
242
229
243
Clean up ALL sidecar files (prompt sidecar deleted intentionally to prevent stale intent on future runs):
Add the plugin to your Claude Code installation following the standard plugin installation process. Once installed, all three skills activate automatically when the conversation context matches their trigger conditions — no slash command or explicit invocation is required.
204
+
Add the plugin to your Claude Code installation following the standard plugin installation process. Once installed, all five skills activate automatically when the conversation context matches their trigger conditions — no slash command or explicit invocation is required.
Copy file name to clipboardExpand all lines: plugins/platform/skills/context-engineering/skill.md
+11Lines changed: 11 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -309,6 +309,17 @@ See [references/extended-thinking.md](references/extended-thinking.md) for detai
309
309
| Misses context | Add role prompting |
310
310
| Drops steps | Chain into separate prompts |
311
311
312
+
### Refactoring Existing Prompts
313
+
314
+
When optimizing or compressing an existing prompt, apply these checks after every structural change:
315
+
316
+
| Pitfall | Check |
317
+
|---------|-------|
318
+
| Stale cross-references | After renaming or renumbering steps, search for ALL references to old labels (jump targets, "see Step X", resume points) and update them |
319
+
| Over-abstraction | If the model needs exact values to execute (specific keys, field names, command arguments), keep them literal even if they look repetitive -- a generic placeholder the model cannot expand is worse than duplication |
320
+
| Lost preconditions | When merging or removing steps, verify that any precondition checks or guards in the removed step are preserved elsewhere |
321
+
| Silent behavior changes | Diff the before/after and confirm every deleted line is either redundant or relocated, not dropped |
0 commit comments