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..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.1", + "version": "1.3.0", "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..f92babc2 --- /dev/null +++ b/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`. diff --git a/plugins/code/agents/feedback-explorer.md b/plugins/code/agents/feedback-explorer.md new file mode 100644 index 00000000..44a71be2 --- /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, Write, 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 6fe3edde..2d712e79 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 @@ -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. 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 |