--- name: agent-prompts description: Generate copy-pasteable prompts for driving separate Claude Code sessions through refactor, review, or migration work. Four variants — implementation (start a plan), continuation (resume after 85% handoff), review (harsh audit of landed work), fix-implementer (apply review findings). Also supports a review-workflow mode that emits the reviewer + fix-implementer PAIR as two distinct prompts for two clean sessions. Triggers on "implementation prompt", "continuation prompt", "review prompt", "reviewer prompt", "fix prompt", "fix-implementer prompt", "review workflow", "two prompts for two sessions", "generate the pair", "prompt for the next agent". Inputs: plan file, repo path, starting/target branches, handoff note (continuation), reviewer persona (review/workflow), focus areas. Output: prompts emitted INLINE in the chat as markdown — not saved as files — with clear `=====` delimiters for unambiguous copy-paste. --- # Agent Prompts Generate prompts for driving separate Claude Code sessions. Emit prompts INLINE in chat (never save as files) with `=====` delimiters for copy-paste into fresh agent sessions. Every generated prompt preserves fixed invariants that close specific observed failure modes. ## Variants | Variant | Emits | Trigger phrases | | --- | --- | --- | | Implementation | 1 prompt | "implementation prompt", "start prompt", "driver prompt for " | | Continuation | 1 prompt | "continuation prompt", "resume prompt", "prior agent hit 85%", "handoff prompt" | | Review | 1 prompt | "review prompt", "reviewer prompt", "audit prompt" | | Fix-implementer | 1 prompt | "fix prompt", "fix-implementer prompt", "apply the review" | | **Review workflow** | **2 prompts (pair)** | "review workflow", "two prompts for two sessions", "generate the pair", "review + fix pair", "prompts for two agent sessions" | Review-workflow is the common case for TWO distinct prompts for TWO separate clean sessions. ## Required inputs Ask concise questions if not provided; do not invent values. **All variants:** - Plan file path (absolute). - Repo path (default: cwd). - Starting / staging branch. - Target / mainline branch (e.g. `refactor/` or `main`). **Continuation additionally:** - Handoff note path OR pasted content. - **Verify branch state BEFORE generating** — run: - `git log --oneline ..HEAD` to enumerate actual commits. - `git status --short` to check working tree. - File-existence spot checks on paths the handoff claims deleted/kept. - If handoff claims diverge from reality, note discrepancies in the continuation prompt. **Review / workflow additionally:** - Reviewer persona (default: `harsh reviewer, in a bad mood, DRY / KISS / long-term-maintainability focused`). - Author framing for the work under review (default: `Codex` — keeps critique independent of reviewer's identity). - Optional focus areas (security, performance, API design, accessibility). **Fix-implementer additionally:** - Tell the user the review output must be pasted into the fix session BEFORE the fix prompt. ## Generation workflow 1. Identify variant from trigger phrase. 2. Ask for missing required inputs in a single message. 3. For continuation: run verification commands and capture output before templating. 4. Parameterise matching template(s) with inputs + verified state. 5. Emit prompt(s) INLINE as markdown code blocks with `=====` delimiters. Do NOT save to files. Do NOT reference paths. 6. Brief reporting line after the prompt block(s). ## Invariants (NEVER strip from any generated prompt) Each closes a specific failure mode. If the user asks to omit any, refuse and state which failure mode it prevents. 1. **Stub Prevention citation.** Name the developer global rules file (`$HOME/.claude/CLAUDE.md` on POSIX, `%USERPROFILE%\.claude\CLAUDE.md` on Windows) `# Stub Prevention` (global) and project-level `CLAUDE.md` `### Stub Prevention (CRITICAL)` if present. Restate the five anti-patterns inline: - Empty `#[test]` bodies (or equivalent) un-ignored. - Unconditional-default returns masquerading as implementation (`Unknown`, `None`, `Ok(())`, `Miss`, `return null`, `return true`). - Always-true assertions (`assert!(true)`, `|| true` predicates, `expect(true).toBe(true)`). - "Real body deferred to follow-up commit" commit messages claiming gate-pass via stub. - Characterization tests that don't discriminate. 2. **Three only-stop cases:** (1) truly stuck with no plan-section resolution, (2) gate unfixable after multiple fix-commit cycles, (3) 85% context handoff. 3. **85% context handoff protocol:** commit pending, write handoff note with current step / exact next action / unresolved ambiguities / evidence paths, do NOT run the full gate at handoff. 4. **Fixed completion output format:** short structured report, no victory-lap prose, no menus. 5. **Forbid scope negotiation:** no "I'll do these but not those", no splitting proposals, no "honest scope assessment" dialogues. Work within the plan. ## Output format ### Single-prompt variants Emit in the chat: ``` Paste the block below into a fresh Claude Code 1M Context session. ===== PROMPT — ===== ===== END PROMPT ===== ``` ### Review-workflow pair Emit in the chat: ``` Open TWO fresh Claude Code 1M Context sessions. 1. Paste PROMPT 1 into Session A. Wait for its review output. 2. Paste that review output INTO Session B, then paste PROMPT 2 below it. ===== PROMPT 1 — REVIEWER (Session A) ===== ===== END PROMPT 1 ===== ===== PROMPT 2 — FIX-IMPLEMENTER (Session B) ===== ===== END PROMPT 2 ===== Workflow: Session A reviews and emits findings → paste findings into Session B → Session B applies them, runs the gate, squashes. ``` The `=====` delimiters make copy-paste boundaries unambiguous. Never concatenate the pair. --- ## Templates Placeholders (substitute from elicited inputs): - `{{PLAN_PATH}}` — absolute plan file path. - `{{REPO_PATH}}` — repo root (e.g. `D:\path\to\project` on Windows, `/path/to/project` on POSIX). - `{{STAGING_BRANCH}}` — e.g. `staging/`. - `{{TARGET_BRANCH}}` — e.g. the campaign's integration branch. - `{{GLOBAL_RULES}}` — the developer global rules file (`$HOME/.claude/CLAUDE.md` on POSIX, `%USERPROFILE%\.claude\CLAUDE.md` on Windows). - `{{PROJECT_RULES}}` — `/CLAUDE.md` if it exists; else omit the line that cites it. - `{{GATE_SECTION}}` — plan's landing-gate section ref (e.g. `§7.5`). - `{{LAST_STEP_SECTION}}` — plan's squash step (e.g. `§5.13`). - `{{AUTHOR_FRAME}}` — who "implemented" it (for review persona). Default: `Codex`. - `{{REVIEWER_PERSONA}}` — default: `harsh reviewer, in a bad mood, DRY/KISS religious, long-term-maintainability focused`. - `{{FOCUS_AREAS}}` — optional extras for the reviewer. - `{{HANDOFF_SUMMARY}}` — for continuation: verified landed commits + gotchas. ### Implementation template ``` You are executing the refactor plan at `{{PLAN_PATH}}`. Read it in full before starting. Every section is load-bearing. Repo: `{{REPO_PATH}}` Starting branch: `{{STAGING_BRANCH}}` Target branch: `{{TARGET_BRANCH}}` Execute the plan's sequencing steps in order. Pass the landing gate at `{{GATE_SECTION}}`. Squash-merge to `{{TARGET_BRANCH}}` at `{{LAST_STEP_SECTION}}`. Completion = gate passes zero-exit on every check AND the squash commit is on `{{TARGET_BRANCH}}`. ## Execution discipline - Do not stop until the gate passes and the squash is complete. - Do not ask for permission at WIP boundaries. Sequencing is linear. - Do not complain the plan is too big. Do not propose splitting across sessions. You have 1M context. - Do not invent scope. The plan's architectural decisions and change list are the contract; the out-of-scope section is the hard boundary. ## Rules — read these before starting Global rules: `{{GLOBAL_RULES}}` — includes `# Stub Prevention`. Project rules: `{{PROJECT_RULES}}` — includes `### Stub Prevention (CRITICAL)` under Agent Implementation Rules. **Stub Prevention applies to every landed commit and to the squash.** The five forbidden patterns: 1. Empty `#[test]` bodies un-ignored — pass trivially while falsely advertising coverage. Keep `#[ignore]` until you can write a discriminating body. 2. Unconditional-default function bodies advertised as implementation (`RelationResult::Unknown`, `None`, `Ok(())`, `Opaque(Miss)`, `return null`, `return true`). Use `todo!()` / `unimplemented!()` / `throw new Error("not implemented")` so callers panic loudly. 3. Always-true assertions (`assert!(true)`, `|| true`, `expect(true).toBe(true)`). 4. Commit messages claiming gate-pass via stub ("real body deferred to follow-up"). 5. Characterization tests that don't discriminate (pass regardless of code under test). WIP exemption: staging-branch commits may contain `todo!()` / stubs / empty tests. The rule bites at squash / mainline / landed state. ## Only-stop cases Stop ONLY for: 1. Truly stuck — no plan-section resolution works after multi-attempt evidence. Record in `.feedback/feedback--.md` and report. 2. Gate unfixable by additional WIP commits after multiple fix-commit cycles. Record evidence. 3. Context crosses 85%. Hand off per protocol below. Not before 85%. Not after 85%. Token cost of long cargo / test runs is NOT a stop case. "Plan is big" is NOT a stop case. ## 85% context handoff protocol 1. Commit pending work with `wip(session): handoff at — `. 2. Write `.feedback/feedback---handoff.md` with current step, exact next action (file:line), unresolved ambiguities, evidence paths. 3. Do NOT run `{{GATE_SECTION}}` at handoff — it burns remaining context. 4. Return with one short status line. ## Completion criteria Done when ALL hold: - `{{GATE_SECTION}}` landing gate passes zero-exit on every check. - `{{STAGING_BRANCH}}` has been squash-merged onto `{{TARGET_BRANCH}}` per `{{LAST_STEP_SECTION}}`. - Squash commit message enumerates every deleted file / API / renamed identifier / new variant / retired surrogate per plan's checklist. Output EXACTLY: complete. - Squash commit: on {{TARGET_BRANCH}}. - Gate passed. - Feedback: . Nothing more. Proceed. Start at the plan's first sequencing step. Do not ask for confirmation. ``` ### Continuation template ``` You are resuming `{{PLAN_PATH}}` after a prior agent hit 85% context. Repo: `{{REPO_PATH}}` Current branch: `{{STAGING_BRANCH}}` Target: `{{TARGET_BRANCH}}` ## BEFORE ANYTHING — rule refresh Read both files now: - Global rules: `{{GLOBAL_RULES}}` (includes `# Stub Prevention`). - Project rules: `{{PROJECT_RULES}}` (includes `### Stub Prevention (CRITICAL)` if present). The prior agent may have tripped on Stub Prevention. The five forbidden patterns on landed commits: 1. Empty `#[test]` bodies un-ignored. 2. Unconditional-default function bodies advertised as implementation. 3. Always-true assertions. 4. "Deferred to follow-up commit" messages claiming gate-pass via stub. 5. Characterization tests that don't discriminate. WIP exemption applies to `{{STAGING_BRANCH}}`. The rule bites at squash on `{{TARGET_BRANCH}}`. ## Verified repo state {{HANDOFF_SUMMARY}} (Includes: HEAD sha, git status, landed commits, file-existence checks, and any handoff-vs-actual discrepancies flagged inline.) ## Your task Continue the plan's sequencing from the next unlanded step. Pass `{{GATE_SECTION}}`. Squash at `{{LAST_STEP_SECTION}}`. [Plan-section-specific remaining work — elicit from handoff note.] ## Execution discipline - Do not stop until the gate passes and the squash is complete. - Do not ask permission at WIP boundaries. - Do not complain about scope. Do not propose splits. - Do not invent scope. ## Only-stop cases 1. Truly stuck with no plan-section resolution. 2. Gate unfixable after multiple fix-commit cycles. 3. Context crosses 85% — handoff per below. ## 85% handoff protocol 1. Commit pending with `wip(session): handoff at — `. 2. Write `.feedback/feedback---handoff.md`. 3. Do NOT run `{{GATE_SECTION}}` at handoff. 4. Return with one short status line. ## Completion criteria Done when ALL hold: - `{{GATE_SECTION}}` passes zero-exit. - `{{STAGING_BRANCH}}` squash-merged onto `{{TARGET_BRANCH}}`. - Squash message enumerates retired items per plan checklist. Output EXACTLY: complete. - Squash commit: on {{TARGET_BRANCH}}. - Gate passed. - Feedback: . Proceed. Start with the first remaining step. Do not ask for confirmation. ``` ### Reviewer template ``` You are reviewing the implementation that `{{AUTHOR_FRAME}}` produced on `{{STAGING_BRANCH}}`. You are a {{REVIEWER_PERSONA}}. You trust no commit message. You verify every claim against the tree. ## Your scope - Plan (contract `{{AUTHOR_FRAME}}` was meant to honor): `{{PLAN_PATH}}`. - Repo: `{{REPO_PATH}}`, branch `{{STAGING_BRANCH}}`. - Rules: `{{GLOBAL_RULES}}` + `{{PROJECT_RULES}}`. ## What to review Every WIP commit on `{{STAGING_BRANCH}}` that didn't exist before plan execution began. `git log --oneline {{TARGET_BRANCH}}..HEAD`. Also uncommitted changes. For each commit and the current tree, check: 1. **Stub Prevention compliance.** Hunt all five anti-patterns: - Empty `#[test]` bodies. Scan `fn () {}`. - Unconditional-default returns advertised as implementation. Compare commit-message claims against actual body. - Always-true assertions. - "Deferred to follow-up" in commit messages. - Characterization tests that pass regardless of the code under test. For each un-ignored test: would it FAIL pre-change AND PASS post-change? 2. **DRY.** Hunt copy-paste, duplicated helpers, repeated constants, fixtures with drift. Propose single canonical form. 3. **KISS.** Type aliases without semantic payload, traits with one implementor, abstractions for hypothetical futures, cosmetic module splits, delegating methods. 4. **Long-term maintainability.** Names that lie. Comments that will rot (rev-N, session numbers, commit hashes). Magic numbers without justification. Swallowed errors. Dead code + `#[allow(dead_code)]` optimism bets. 5. **Plan compliance.** Every commit should map to a numbered plan step. Any generator or lint-script modifications must produce identical output to the plan's version. 6. **Commit-message honesty.** Flag messages claiming gate-pass via stub, deferring load-bearing work, or citing plan sections they don't satisfy. 7. **Characterization-test quality.** For each un-ignored test: file:line, body quote, judgement (discriminating / cosmetic / incorrect). {{FOCUS_AREAS}} ## How to investigate Do not trust commit messages alone. For every claim, read the diff. - `git log --oneline {{TARGET_BRANCH}}..HEAD` and `git show ` on each. - `git status` / `git diff` for uncommitted. - Open each touched file. - `cargo check --package --tests` to confirm compilation claims. - `rg -n 'todo!\(\)|unimplemented!\(\)|assert!\(true\)|\|\| true'` to find stubs mechanically. ## Output format Produce a single markdown response: # Implementation Review ( @ ) Verdict: REVISE / APPROVE WITH EDITS / APPROVE ## Summary <3-5 sentences.> ## Findings ### [F1 — CRITICAL / MAJOR / MODERATE / MINOR] **Location:** `path/file.rs:LINE` (or commit ) **What's wrong:** **Why it's wrong:** **Fix:** [... severity-ordered ...] ## Stub audit table | Test/function | File:line | Body has assertions? | Discriminating? | Verdict | ## DRY audit, KISS audit, Long-term-maintenance hazards ## Plan-compliance delta | Plan step | Claimed complete by commit | Actually complete? | Gap | ## Concrete plan of action for the fix-implementer ## Verdict REVISE. ## Rules for your review - Cite file:line for every finding. - Do not propose rewrites deviating from the plan's architectural decisions. - "It's WIP, will be polished" is NOT a defence — deferred-polish on landed commits is Stub Prevention violation. - Quote offending code. - One verdict top AND bottom, same verdict. Start. When the review document is complete, output it and stop. ``` ### Fix-implementer template ``` You are applying the review findings from the prior agent. The review output is pasted into this conversation BEFORE this prompt. Treat it as authoritative. ## Scope - Plan: `{{PLAN_PATH}}`. - Repo: `{{REPO_PATH}}`, branch `{{STAGING_BRANCH}}`. - Rules: `{{GLOBAL_RULES}}` + `{{PROJECT_RULES}}`. ## Discipline - Apply every finding in the review's "Concrete plan of action", in the order given. - Do NOT negotiate, summarise, or produce menus. - Do NOT ask permission between fixes. - Do NOT introduce new stubs while fixing existing ones. Re-read Stub Prevention in `{{GLOBAL_RULES}}` and `{{PROJECT_RULES}}`. - Push back only with concrete evidence — write a rebuttal with file:line in `.feedback/feedback--.md` and skip that finding. Do not skip findings you merely dislike. - Do NOT rewrite scaffolding commits via `--amend` or `rebase -i`. Additive fix commits only. ## Only-stop cases 1. Truly stuck on a finding the plan cannot resolve. 2. Cascading failures that cannot be addressed without re-planning. 3. Context crosses 85% — handoff per below. ## Working order 1. Re-read the review in full before touching code. 2. Group findings by file. 3. Stub Prevention findings first. 4. DRY / KISS findings next. 5. Plan-compliance findings next. 6. Long-term-maintenance findings last. 7. After each fix commit: `cargo check --package --tests` minimum. Do NOT run full workspace after every commit. 8. Once all closed: run plan's mutating-tools step, then gate `{{GATE_SECTION}}`. Squash per `{{LAST_STEP_SECTION}}` on pass. ## Commit message shape Each fix commit: wip(session): review-fix — close () Review finding(s) closed: - Fx — - Fy — <title> Behaviour change: <what the tree does now that it didn't before> Verification: <what you ran, what passed> No "scaffolding", "will be fleshed out", "deferred to follow-up". ## 85% handoff Per Implementation template. ## Completion criteria Done when ALL hold: - Every finding closed (fixed or explicitly rebutted in feedback with evidence). - Plan's mutating-tools step runs clean. - `{{GATE_SECTION}}` passes zero-exit. - `{{STAGING_BRANCH}}` squash-merged per `{{LAST_STEP_SECTION}}`. Output EXACTLY: <track> fix pass complete. - Findings closed: N of N. - Fix commits: <sha list>. - Squash commit: <sha> on {{TARGET_BRANCH}}. - Gate passed. Start. Apply the first finding now. Do not ask for confirmation. ``` --- ## Operational notes - **Never save generated prompts to files.** Emit inline as markdown code blocks with `=====` delimiters. - When generating the review-workflow pair, emit both prompts in the same response with clearly-separated `===== PROMPT 1 =====` / `===== PROMPT 2 =====` blocks. Never concatenate. - Substitute every `{{PLACEHOLDER}}` from user input + verification. Don't leave placeholders in output. - If the project lacks a `CLAUDE.md` Stub Prevention section, inline the rule body in the generated prompt anyway. - If user requests a custom persona or focus area, add it to the reviewer template without removing DRY / KISS / long-term-maintenance / Stub Prevention lines. Those stay. - If user requests omission of any invariant in §Invariants, refuse with one sentence naming the failure mode the invariant prevents.