FEAT-96: update plan-with-codex syntax and add prompt refactoring guide

CHANGELOG.md

@@ -6,6 +6,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+### code v1.2.2
+
+#### Changed
+- Updated `plan-with-codex` command argument-hint to use positional syntax instead of optional bracket notation
+
+### platform v1.0.2
+
+#### Added
+- New "Refactoring Existing Prompts" section in `context-engineering` skill covering pitfalls for stale cross-references, over-abstraction, lost preconditions, and silent behavior changes
+
 ### code v1.2.1
 
 #### Changed

plugins/code/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "code",
   "description": "Code and planning framework plugin",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "author": {
     "name": "ClosedLoop",
     "email": "support@closedloop.ai"

plugins/code/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## [1.3.0] - 2026-03-22
+
+### Added
+
+- `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.
+- `plan-with-codex` Step 2e now spawns feedback-explorer before resuming plan-agent, writing a `{stem}.context` brief with pre-fetched code snippets.
+
+### Fixed
+
+- `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.
+- `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`.

plugins/code/agents/feedback-explorer.md

@@ -0,0 +1,80 @@
+---
+name: feedback-explorer
+description: Haiku agent that pre-fetches codebase context referenced in reviewer feedback, so the plan-agent can skip mechanical exploration during revision.
+model: haiku
+tools: Read, Glob, Grep
+---
+
+# Feedback Explorer
+
+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.
+
+## Input
+
+Your prompt will include:
+- **feedback file path** -- the reviewer's findings
+- **plan file path** -- the current plan
+- **context output path** -- where to write results
+
+## Process
+
+1. **Read the feedback file and the plan file.**
+
+2. **Extract references from the feedback.** For each finding, collect:
+   - Explicit file paths (e.g., `src/auth/handler.go`, `main.go:1100`)
+   - Function/type/variable names (e.g., `NewWebHandlers`, `AuthCode struct`)
+   - Pattern keywords to search for (e.g., `redirect_uri`, `SetCookie`)
+   - Test file references
+
+3. **Also extract references from the plan's Critical Files section** -- these are files the plan-agent already identified as relevant.
+
+4. **Locate and fetch each reference.** For each:
+   - If it's a file path: Read it (or the relevant line range if a line number is given)
+   - If it's a function/type name: `Grep` for its definition, then Read the surrounding context (30 lines)
+   - If it's a keyword pattern: `Grep` for occurrences, Read the top 3 matches
+   - If a file path doesn't exist: try `Glob` with `**/{filename}` to find it
+
+5. **Write the context file** using the format below. Use the `Write` tool.
+
+## Output Format
+
+```markdown
+# Feedback Context Brief
+
+## Finding 1: [title from feedback]
+
+### [path/to/file.go:100-130]
+```
+[code snippet]
+```
+
+### [path/to/other_file.go:40-70]
+```
+[code snippet]
+```
+
+## Finding 2: [title from feedback]
+
+### [path/to/file.tsx:1-50]
+```
+[code snippet]
+```
+
+## Plan Critical Files
+
+### [path/to/critical_file.go:1-80]
+```
+[code snippet]
+```
+
+## Additional Discoveries
+- [any relevant files found during search that weren't explicitly referenced]
+```
+
+## Rules
+
+- **Speed over completeness.** Fetch what's explicitly referenced. Don't explore tangentially.
+- **Include line numbers** in every section header so the plan-agent can verify without re-reading.
+- **If a reference can't be found**, note it: `[NOT FOUND: path/to/missing.go -- searched with Glob **/{filename}]`
+- **Do not analyze or judge the findings.** That's the plan-agent's job. You just gather code.
+- **Keep snippets focused.** If a finding references a specific function, include that function plus ~10 lines of surrounding context, not the entire file.

plugins/code/agents/plan-agent.md

@@ -87,8 +87,8 @@ Structure plans with these sections:
 
 When given feedback to address:
 
-1. Read the current plan file and the feedback file
-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.
+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.
+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.
 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.
 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").
 5. Write the updated plan back to the same file path using the `Write` tool

plugins/code/commands/plan-with-codex.md

@@ -1,6 +1,6 @@
 ---
 description: "Iterative plan refinement debate between Claude and Codex"
-argument-hint: [--max-rounds N] [--plan-file PATH] [--codex-model MODEL] <prompt>
+argument-hint: --max-rounds N --plan-file PATH --codex-model MODEL <prompt>
 allowed-tools: Bash, Read, Write, Glob, Grep, TodoWrite, Task, AskUserQuestion
 skills: code:codex-review
 effort: max
@@ -39,9 +39,12 @@ Agent(
 
 ### State Write
 
-All state updates use:
-```bash
-printf 'ROUND=%s\nPHASE=%s\nCODEX_SESSION_ID=%s\nLOG_ID=%s\n' '{round}' '{phase}' '{codex_session_id}' '{log_id}' > {state_file}
+All state updates use the Write tool (not Bash), so the user only approves the file path once:
+```
+Write(
+  file_path="{state_file}",
+  content="ROUND={round}\nPHASE={phase}\nCODEX_SESSION_ID={codex_session_id}\nLOG_ID={log_id}\n"
+)
 ```
 
 Valid phases: `user_review`, `codex_review`, `claude_revision`
@@ -62,6 +65,7 @@ Arguments: $ARGUMENTS
 Derive sidecar paths from the plan file stem (e.g., for `debate-plan.md`):
 - `{stem}.feedback` -- Codex feedback text
 - `{stem}.revisions` -- Claude's revision summary (changes made + pushback on rejected findings)
+- `{stem}.context` -- pre-fetched codebase snippets for the current revision round
 - `{stem}.state` -- phase/round/session state
 - `{stem}.prompt` -- original prompt (plain text)
 
@@ -80,13 +84,7 @@ TodoWrite([
 
 ## Step 0.5: Check for Resume
 
-Check if `{stem}.state` exists (`test -f`). If yes, read all four values:
-```bash
-grep "^ROUND=" {state_file} | cut -d= -f2-
-grep "^PHASE=" {state_file} | cut -d= -f2-
-grep "^CODEX_SESSION_ID=" {state_file} | cut -d= -f2-
-grep "^LOG_ID=" {state_file} | cut -d= -f2-
-```
+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).
 
 **Validate preconditions:**
 
@@ -211,11 +209,27 @@ Read the feedback file and display full Codex feedback to the user.
 
 ### 2e. Claude Revision
 
+Update TodoWrite: "Round {N}/{max}: Gathering context..."
+
+**First, launch the `code:feedback-explorer`** (haiku) to pre-fetch codebase context referenced in the feedback:
+
+```
+Agent(
+  subagent_type="code:feedback-explorer",
+  name="feedback-explorer",
+  model="haiku",
+  mode="bypassPermissions",
+  run_in_background=false,
+  description="Pre-fetch context for round {N} feedback",
+  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}."
+)
+```
+
 Update TodoWrite: "Round {N}/{max}: Revising plan..."
 
-Resume the plan-agent:
+**Then resume the plan-agent** with the pre-fetched context:
 - description: "Revise plan based on Codex feedback"
-- 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}."
+- 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}."
 
 Verify plan was updated. Write state: `ROUND={N+1}, PHASE=codex_review`, preserve current `CODEX_SESSION_ID` and `LOG_ID`. Continue to next round.
 
@@ -228,7 +242,7 @@ Report outcome:
 
 Clean up ALL sidecar files (prompt sidecar deleted intentionally to prevent stale intent on future runs):
 ```bash
-rm -f {state_file} {feedback_file} {revisions_file} {prompt_file}
+rm -f {state_file} {feedback_file} {revisions_file} {context_file} {prompt_file}
 ```
 
 Update TodoWrite: mark all remaining items completed.

plugins/platform/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "platform",
   "description": "ClosedLoop Platform plugin",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "author": {
     "name": "ClosedLoop",
     "email": "support@closedloop.ai"

plugins/platform/README.md

@@ -201,7 +201,7 @@ Covers skill anatomy (SKILL.md frontmatter, scripts/, references/, assets/), the
 
 ### Installing the Plugin
 
-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.
+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.
 
 ### Using claude-code-expert
 

plugins/platform/skills/context-engineering/skill.md

@@ -309,6 +309,17 @@ See [references/extended-thinking.md](references/extended-thinking.md) for detai
 | Misses context | Add role prompting |
 | Drops steps | Chain into separate prompts |
 
+### Refactoring Existing Prompts
+
+When optimizing or compressing an existing prompt, apply these checks after every structural change:
+
+| Pitfall | Check |
+|---------|-------|
+| 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 |
+| 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 |
+| Lost preconditions | When merging or removing steps, verify that any precondition checks or guards in the removed step are preserved elsewhere |
+| Silent behavior changes | Diff the before/after and confirm every deleted line is either redundant or relocated, not dropped |
+
 ### Common Tag Names
 
 | Tag | Purpose |