From cae78fc24bb02da7195c960a725b8c8f9a2631ba Mon Sep 17 00:00:00 2001 From: "daniel.ochoa" Date: Fri, 20 Mar 2026 17:12:55 -0500 Subject: [PATCH 1/5] 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. --- CHANGELOG.md | 10 ++++++++++ plugins/code/.claude-plugin/plugin.json | 2 +- plugins/code/commands/plan-with-codex.md | 2 +- plugins/platform/.claude-plugin/plugin.json | 2 +- plugins/platform/README.md | 2 +- plugins/platform/skills/context-engineering/skill.md | 11 +++++++++++ 6 files changed, 25 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 18607554..23eeb25e 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/plugins/code/.claude-plugin/plugin.json b/plugins/code/.claude-plugin/plugin.json index 525d490d..4dc222c5 100644 --- a/plugins/code/.claude-plugin/plugin.json +++ b/plugins/code/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "code", "description": "Code and planning framework plugin", - "version": "1.2.1", + "version": "1.2.2", "author": { "name": "ClosedLoop", "email": "support@closedloop.ai" diff --git a/plugins/code/commands/plan-with-codex.md b/plugins/code/commands/plan-with-codex.md index 6fe3edde..c547abb2 100644 --- a/plugins/code/commands/plan-with-codex.md +++ b/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] +argument-hint: --max-rounds N --plan-file PATH --codex-model MODEL allowed-tools: Bash, Read, Write, Glob, Grep, TodoWrite, Task, AskUserQuestion skills: code:codex-review effort: max diff --git a/plugins/platform/.claude-plugin/plugin.json b/plugins/platform/.claude-plugin/plugin.json index 99b6e42f..522b4b9e 100644 --- a/plugins/platform/.claude-plugin/plugin.json +++ b/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" diff --git a/plugins/platform/README.md b/plugins/platform/README.md index 97d5483e..159224db 100644 --- a/plugins/platform/README.md +++ b/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 diff --git a/plugins/platform/skills/context-engineering/skill.md b/plugins/platform/skills/context-engineering/skill.md index 1894fa1b..725abf34 100644 --- a/plugins/platform/skills/context-engineering/skill.md +++ b/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 | From 0cb3c7f2b8974a378c4b8246531034453df48a5e Mon Sep 17 00:00:00 2001 From: "daniel.ochoa" Date: Sun, 22 Mar 2026 11:41:07 -0500 Subject: [PATCH 2/5] 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. --- plugins/code/.claude-plugin/plugin.json | 2 +- plugins/code/CHANGELOG.md | 8 ++++++++ plugins/code/commands/plan-with-codex.md | 17 +++++++---------- 3 files changed, 16 insertions(+), 11 deletions(-) create mode 100644 plugins/code/CHANGELOG.md diff --git a/plugins/code/.claude-plugin/plugin.json b/plugins/code/.claude-plugin/plugin.json index 4dc222c5..bf1e0a29 100644 --- a/plugins/code/.claude-plugin/plugin.json +++ b/plugins/code/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "code", "description": "Code and planning framework plugin", - "version": "1.2.2", + "version": "1.2.3", "author": { "name": "ClosedLoop", "email": "support@closedloop.ai" diff --git a/plugins/code/CHANGELOG.md b/plugins/code/CHANGELOG.md new file mode 100644 index 00000000..fff68e9b --- /dev/null +++ b/plugins/code/CHANGELOG.md @@ -0,0 +1,8 @@ +# Changelog + +## [1.2.3] - 2026-03-22 + +### 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`. diff --git a/plugins/code/commands/plan-with-codex.md b/plugins/code/commands/plan-with-codex.md index c547abb2..d80bda2f 100644 --- a/plugins/code/commands/plan-with-codex.md +++ b/plugins/code/commands/plan-with-codex.md @@ -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` @@ -80,13 +83,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:** From 27939ca79d5b5c0fa049ebac1b77f49912f44c0e Mon Sep 17 00:00:00 2001 From: "daniel.ochoa" Date: Sun, 22 Mar 2026 11:51:26 -0500 Subject: [PATCH 3/5] 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. --- plugins/code/.claude-plugin/plugin.json | 2 +- plugins/code/CHANGELOG.md | 7 ++- plugins/code/agents/feedback-explorer.md | 80 ++++++++++++++++++++++++ plugins/code/agents/plan-agent.md | 4 +- plugins/code/commands/plan-with-codex.md | 23 ++++++- 5 files changed, 109 insertions(+), 7 deletions(-) create mode 100644 plugins/code/agents/feedback-explorer.md diff --git a/plugins/code/.claude-plugin/plugin.json b/plugins/code/.claude-plugin/plugin.json index bf1e0a29..072de698 100644 --- a/plugins/code/.claude-plugin/plugin.json +++ b/plugins/code/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "code", "description": "Code and planning framework plugin", - "version": "1.2.3", + "version": "1.3.0", "author": { "name": "ClosedLoop", "email": "support@closedloop.ai" diff --git a/plugins/code/CHANGELOG.md b/plugins/code/CHANGELOG.md index fff68e9b..f92babc2 100644 --- a/plugins/code/CHANGELOG.md +++ b/plugins/code/CHANGELOG.md @@ -1,6 +1,11 @@ # Changelog -## [1.2.3] - 2026-03-22 +## [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 diff --git a/plugins/code/agents/feedback-explorer.md b/plugins/code/agents/feedback-explorer.md new file mode 100644 index 00000000..d8275fc5 --- /dev/null +++ b/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. diff --git a/plugins/code/agents/plan-agent.md b/plugins/code/agents/plan-agent.md index f53ef481..a1e964b3 100644 --- a/plugins/code/agents/plan-agent.md +++ b/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 diff --git a/plugins/code/commands/plan-with-codex.md b/plugins/code/commands/plan-with-codex.md index d80bda2f..fdc5f16a 100644 --- a/plugins/code/commands/plan-with-codex.md +++ b/plugins/code/commands/plan-with-codex.md @@ -65,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) @@ -208,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 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. @@ -225,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. From 02e0087c63e1237182ff9e4cdcd8300d6c3ccf20 Mon Sep 17 00:00:00 2001 From: "daniel.ochoa" Date: Sun, 22 Mar 2026 11:52:53 -0500 Subject: [PATCH 4/5] fix(code): use fully qualified agent name for feedback-explorer --- plugins/code/commands/plan-with-codex.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/code/commands/plan-with-codex.md b/plugins/code/commands/plan-with-codex.md index fdc5f16a..2d712e79 100644 --- a/plugins/code/commands/plan-with-codex.md +++ b/plugins/code/commands/plan-with-codex.md @@ -211,7 +211,7 @@ Read the feedback file and display full Codex feedback to the user. Update TodoWrite: "Round {N}/{max}: Gathering context..." -**First, launch the feedback-explorer** (haiku) to pre-fetch codebase context referenced in the feedback: +**First, launch the `code:feedback-explorer`** (haiku) to pre-fetch codebase context referenced in the feedback: ``` Agent( From b41bd1aa5dc7169368bf8b190f15a904cf067729 Mon Sep 17 00:00:00 2001 From: "daniel.ochoa" Date: Mon, 23 Mar 2026 10:40:22 -0500 Subject: [PATCH 5/5] add write tool --- plugins/code/agents/feedback-explorer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/code/agents/feedback-explorer.md b/plugins/code/agents/feedback-explorer.md index d8275fc5..44a71be2 100644 --- a/plugins/code/agents/feedback-explorer.md +++ b/plugins/code/agents/feedback-explorer.md @@ -2,7 +2,7 @@ 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 +tools: Read, Write, Glob, Grep --- # Feedback Explorer