agent-loops

# Agent Workflow Loops This skill defines the operational loops that implementer agents follow when making code changes and writing tests. Each loop has explicit entry criteria, exit criteria, and escalation rules. If you are an agent, follow these loops exactly. **You do not review your own work.** All reviews are performed by an independent reviewer. Prefer Claude via the bundled scripts. If Claude is unavailable, use a different model before asking your own model family to review. Same-model shell-outs are the last resort. You never grade your own homework. **Bundled references:** - `references/testing-standards.md` — Test quality standards (how to write tests) - `references/audit-workflow.md` — Test gap discovery (how to find what's missing) - `references/perspective-catalog.md` — Review perspective selection (used by primary and fallback code review) - `references/review-prompt.md` — Code review prompt template for fallback reviewers - `references/audit-prompt.md` — Test audit prompt template for module-scope (full-contract) audits - `references/diff-audit-prompt.md` — Test audit prompt template for diff-scope (per-commit) audits; used by `diff-test-audit.sh` when `--git` is active **Bundled scripts:** - `$SKILL_DIR/scripts/specialist-review.sh` — Provider-aware Claude/Gemini/Codex CLI path for code review - `$SKILL_DIR/scripts/diff-test-audit.sh` — Provider-aware Claude/Gemini/Codex CLI path for test audit ### Locate Scripts The bundled scripts live inside the installed skill directory, not the project tree. Before invoking any script, resolve `SKILL_DIR` so paths work regardless of install scope: ```bash SKILL_DIR="$(ls -d ~/.codex/skills/agent-loops 2>/dev/null || ls -d .codex/skills/agent-loops 2>/dev/null)" ``` All script invocations below use `"$SKILL_DIR/scripts/..."`. Run the snippet above once at the start of your session and reuse the variable. --- ## Architecture: Who Does What | Role | Agent | How | |------|-------|-----| | **Implementer** | Codex or Gemini | Writes code changes and test code | | **Code Reviewer** | Claude preferred; non-self scripted fallback next; same-model provider last; fresh-context Codex final fallback | `specialist-review` keeps same-model shell-outs last; fallback reviewer uses bundled prompts and produces a review artifact | | **Test Auditor** | Claude preferred; non-self scripted fallback next; same-model provider last; fresh-context Codex final fallback | `diff-test-audit` keeps same-model shell-outs last; fallback auditor uses bundled prompts and produces an audit artifact | | **Remediator** | Codex or Gemini | Fixes findings from the independent review/audit artifact | **Critical rule:** Codex and Gemini NEVER self-review unless every independent provider path has already failed. Every review step must be performed by an independent reviewer using this selection order: 1. Bundled script with automatic Claude-first, self-last provider selection 2. A fresh-context Codex reviewer that did not implement the change If neither path is available, stop and escalate to the user. ## Why Shell-Based Review (Even for Claude) The bundled scripts aren't a Codex/Gemini accommodation — they exist to enable **cross-model independent review**, which every agent benefits from. The provider rotation explicitly keeps the current agent's own model family last, so a Claude agent invoking `specialist-review.sh` gets its review from Gemini or Codex first, not another Claude instance. Two kinds of reviewer independence are in play: - **Cross-model independence** (shell scripts): reviewer is a *different model family* with different training data and alignment. Catches blind spots inherent to the current model. Requires shelling out to a different provider. - **Fresh-context independence** (sub-agents): reviewer is the *same model family* but with no prior context. Catches local anchoring bias. Cheap to obtain via Task-tool sub-agents in Claude Code. Agent-loops uses the first mechanism as its baseline because cross-model is a stronger guarantee than fresh-context alone. Claude-native sub-agent flows (like `multi-specialist-review`) add within-model multi-perspective diversity on top of the shell-based baseline when warranted — they don't replace it. ## Reviewer Selection Order When a review or audit is required, use this exact fallback chain: 1. **Bundled script first.** Let the bundled script try Claude, then another model family, and keep the current model family last. The script validates the artifact contract before accepting the generated artifact. 2. **Fresh-context Codex next.** Spawn a reviewer agent with fresh context. That agent must: - not have authored or edited the implementation under review - receive only the task spec, relevant diff/module/tests, and the bundled references - act only as reviewer/auditor, not as implementer - write its result to a markdown artifact under `.cortex/reviews/` 3. **Escalate** if no independent reviewer is available. Treat fallback artifacts exactly like script-generated `REVIEW_FILE` or `REPORT_FILE` outputs in the loops below. Call out fallback usage in the handoff so humans know whether the review came from Claude, Gemini, Codex, or fresh-context Codex. --- ## Skill Invocation Reference ### Pre-Review: Impact Analysis with Codanna (Optional) Before requesting code review, you can use codanna to understand the blast radius of your changes. This provides grounded structural data that helps scope the review and catch issues the diff alone won't reveal. ```bash # What calls the functions you changed? codanna mcp find_callers process_request --watch # What's the full impact if this symbol changes? codanna mcp analyze_impact DatabaseConnection --watch --json # Feed impact data into review context IMPACT=$(codanna mcp analyze_impact "$CHANGED_SYMBOL" --watch --json 2>/dev/null) ``` This is optional — agent-loops works without codanna. But when available, impact data makes reviews more precise and catches downstream breakage the diff doesn't show. ### `specialist-review` — Request Code Review **When:** After completing implementation, after each remediation cycle. **What you get back:** Findings with severity levels (P0-P3) and a verdict (BLOCKED / PASS WITH ISSUES / CLEAN). #### IMPORTANT: Source Files Only Scope `specialist-review` to **source files only**. Do NOT include test files (`*.test.*`, `*.spec.*`, `__tests__/`) in the path filter — tests are reviewed separately in **Loop 2** via `diff-test-audit`. #### IMPORTANT: Do Not Review the Code Yourself Your ONLY job is to invoke an independent reviewer and read the output artifact. Do NOT analyze the diff as the reviewer. Do NOT write review comments yourself. Do NOT adopt perspectives yourself. Route the review to Claude first, then fallback if needed. Claude is still the preferred reviewer because it can load domain-specific skills such as `owasp-top-10`, `secure-coding-practices`, and `python-testing-patterns`. The bundled script now tries Claude first, then a different model family, and keeps same-model shell-outs for last resort. Codex and Gemini are both available as explicit providers. If the automated providers are unavailable or fail, continue with a fresh-context Codex reviewer instead of reviewing the code yourself. #### Automated Path: Provider-Aware Script > **LONG-RUNNING CALL — USE THE POLLING PATTERN BELOW.** > This script invokes an external LLM and takes **3-5 minutes for larger diffs**. > Do NOT start remediation, tests, or commits while the review is in progress. > When calling from a Bash tool, set `timeout: 600000` (10 min) — the default > 120-second timeout will kill the subprocess before the reviewer finishes. > The review is only done when you have a `REVIEW_FILE` path in hand. **Polling invocation (REQUIRED)** — run the review in the background and poll so the Bash tool receives periodic output and does not time out: ```bash # Start review in background, capture stdout (the result file path) separately REVIEW_TMP=$(mktemp /tmp/review-out.XXXXXX) "$SKILL_DIR/scripts/specialist-review.sh" --git -- src/parser/ src/auth.rs \ >"$REVIEW_TMP" & REVIEW_PID=$! # Poll every 15s — each echo keeps the Bash tool connection alive while kill -0 "$REVIEW_PID" 2>/dev/null; do sleep 15 echo "[poll] Review still running (pid $REVIEW_PID)..." done # Collect exit code and read result wait "$REVIEW_PID" REVIEW_EXIT=$? if [[ $REVIEW_EXIT -eq 0 ]]; then REVIEW_FILE=$(cat "$REVIEW_TMP") echo "Review complete: $REVIEW_FILE" cat "$REVIEW_FILE" else echo "Review failed (exit $REVIEW_EXIT):" cat "$REVIEW_TMP" # contains failure summary with stderr paths and debug info fi rm -f "$REVIEW_TMP" ``` The script emits heartbeat lines to stderr every 15 seconds during provider execution. Combined with the poll loop above, this ensures continuous output. Additional invocation forms (wrap any of these in the polling pattern above): ```bash # Review changes since a specific ref, scoped to a directory "$SKILL_DIR/scripts/specialist-review.sh" --git origin/main -- claude_ctx_py/ # Review all changes vs last commit (use sparingly in monorepos) "$SKILL_DIR/scripts/specialist-review.sh" --git # Pipe in a pre-filtered diff git diff HEAD~3..HEAD -- src/ | "$SKILL_DIR/scripts/specialist-review.sh" - # Review a diff file "$SKILL_DIR/scripts/specialist-review.sh" /path/to/changes.diff # Custom output directory "$SKILL_DIR/scripts/specialist-review.sh" --git --output ./my-reviews -- src/ # Force a specific provider "$SKILL_DIR/scripts/specialist-review.sh" --provider gemini --git -- src/parser/ "$SKILL_DIR/scripts/specialist-review.sh" --provider codex --git -- src/parser/ ``` **Always scope to the files you touched.** In a monorepo, an unscoped `--git` sends the entire repo diff to the reviewer, wasting tokens and risking timeouts. Provider selection: - Default is `auto`, which tries Claude first, keeps the current agent's own model family last, and uses the remaining provider in between. - Override per run with `--provider auto|claude|gemini|codex`. - Override by environment with `AGENT_LOOPS_LLM_PROVIDER` or `SPECIALIST_REVIEW_PROVIDER`. - Override provider models with `CLAUDE_MODEL`, `GEMINI_MODEL`, or `CODEX_MODEL`. - Enable a second reviewer with `AGENT_LOOPS_SECONDARY_PROVIDER=claude|gemini|codex` and optionally `AGENT_LOOPS_SECONDARY_MODEL=<model>`. Use `SPECIALIST_REVIEW_SECONDARY_PROVIDER` / `SPECIALIST_REVIEW_SECONDARY_MODEL` for code-review only, or `TEST_REVIEW_SECONDARY_PROVIDER` / `TEST_REVIEW_SECONDARY_MODEL` for test-audit only. The script preserves both raw artifacts and emits one synthesized final artifact. - To conserve Claude usage while keeping a second signal, use: `CLAUDE_MODEL=sonnet AGENT_LOOPS_SECONDARY_PROVIDER=codex` or `CLAUDE_MODEL=sonnet AGENT_LOOPS_SECONDARY_PROVIDER=gemini`. - Set `AGENT_LOOPS_SELF_PROVIDER=claude|gemini|codex` when the current agent is not auto-detected. Codex, Gemini, and Claude sessions auto-detect themselves when their standard session markers are present. - The script validates the review artifact shape before accepting it; invalid provider output is rejected and the next fallback is tried. - If both CLIs are unavailable or fail, use the fresh-context Codex fallback below. #### Manual Fallback: Fresh-Context Codex If the bundled script cannot get a usable artifact from any scripted provider: 1. Generate the same scoped diff you would have sent to the script. 2. Provide the reviewer: - `references/review-prompt.md` - `references/perspective-catalog.md` - the scoped diff - the prior review artifact, if this is a remediation cycle 3. Require the reviewer to emit markdown that follows the `Review Output Format` documented later in this skill. 4. Save that output under `.cortex/reviews/review-<timestamp>-fallback.md` and treat the saved path as `REVIEW_FILE`. #### Size Guards and `--jumbo` Both `specialist-review.sh` and `diff-test-audit.sh` enforce a **soft size guard** before sending content to the reviewer: | Script | Default limit | Env override | |--------------------------|------------------------|---------------------------------------| | `specialist-review.sh` | 3000 diff lines | `AGENT_LOOPS_MAX_DIFF_LINES` | | `diff-test-audit.sh` | 500 KB source + tests | `AGENT_LOOPS_MAX_CONTENT_BYTES` | The guard behaves as a two-step decision gate, not a hard cap: 1. **First run aborts on oversize.** The abort is deliberate: it forces you to consider whether the change can be split before sending a large payload to the reviewer. The error message lists concrete split strategies (by path filter, by ref range, by sub-module, by logical scope). Try those first. 2. **If splitting doesn't make sense, rerun with `--jumbo`.** Use this flag when the change is genuinely cohesive and decomposing it would fragment a single logical unit — a refactor that only reads correctly as a whole, generated code, or a single-commit feature whose parts don't stand alone. `--jumbo` sends the full content to the reviewer (no truncation). ```bash # First run aborts with splitting guidance "$SKILL_DIR/scripts/specialist-review.sh" --git -- src/big-refactor/ # After deciding the change can't be split, retry with --jumbo "$SKILL_DIR/scripts/specialist-review.sh" --jumbo --git -- src/big-refactor/ ``` `--jumbo` is a considered override, not a default. Use it only after the abort made you think about splitting. Modern provider context windows (Claude Opus/Sonnet 4.x, Gemini 2.5 Pro, GPT-5) can absorb the full payload, but reviewers do their best work on focused diffs — so prefer splitting when it's natural, and reach for `--jumbo` when it isn't. `AGENT_LOOPS_ALLOW_TRUNCATION=1` still exists for backward compatibility but silently truncates, which produces partial reviews. Prefer `--jumbo` over truncation in nearly every case. #### Anti-Patterns - **Performing the review yourself** — Use an independent reviewer, never the implementer. - **Summarizing the diff before invoking the script** — Unnecessary. The script reads the diff directly. - **Ignoring the output artifact** — The review is written to a file. Read it. - **Using a same-context Codex agent as reviewer** — If Codex is the fallback reviewer, it must have fresh context and no implementation authorship. - **Stopping at the first Claude failure** — Let the script try the non-self provider before the same-model last resort and fresh-context Codex. - **Skipping the polling pattern** — Use the polling invocation from the section above. The review takes 3-5 minutes; without the poll loop the Bash tool will time out or the agent will lose track of the process. Set `timeout: 600000` on the Bash call. - **Moving on before you have `REVIEW_FILE`** — The review is a gate. Do not proceed to findings triage, remediation, tests, or commit until the poll loop exits and you have a file path. - **Reaching for `--jumbo` before considering a split** — The first-run abort is a forcing function. Use `--jumbo` only after you've decided the change is cohesive; don't paper over a legitimately splittable diff. ### `diff-test-audit` — Request Test Audit **When:** Per-commit test coverage check — verifies the files your diff touched have adequate tests. **What you get back:** A gap report covering both missing coverage AND test quality issues (mirror tests, flaky assertions, etc.) scoped to your changed files, with P0/P1/P2 severity. #### Scope: Default to Diff, Not Module This audit is a per-commit completeness check — did your change get tested — not a module-level survey. Default to scoping by files the diff touched (`--git` filters the audit to changed files; add `-- <paths>` to narrow further): ```bash "$SKILL_DIR/scripts/diff-test-audit.sh" <module> --git "$SKILL_DIR/scripts/diff-test-audit.sh" <module> --git -- <touched-files> ``` When `--git` is active, the script uses a **diff-focused prompt** (`references/diff-audit-prompt.md`) that explicitly scopes findings to behaviors introduced or modified by the diff. Pre-existing untested code in touched files is **out of scope** — those gaps are not reported. This prevents the "audit surfaces noise in neighboring code" problem a full-contract prompt would produce even at file scope. For full module audits (mapping a module's public contract and surveying coverage across unmodified code), use the **`test-review` skill** instead. It uses parallel Haiku sub-agents with synthesis — better suited to exhaustive module work. The full-contract prompt (`audit-prompt.md`) is still used by this script when invoked without `--git`, but that path is legacy — module audits belong in `test-review`. #### IMPORTANT: Do Not Audit the Tests Yourself Your ONLY job is to invoke an independent auditor and read the output artifact. Do NOT map behaviors yourself. Do NOT classify test coverage yourself. Do NOT produce the gap report yourself. Route the audit to Claude first, then fallback if needed. Claude is still the preferred auditor because it can apply the testing standards and audit workflow with project-aware skill support. The bundled script now tries Claude first, then a different model family, and keeps same-model shell-outs for last resort. Codex and Gemini are both available as explicit providers. If the automated providers are unavailable or fail, continue with a fresh-context Codex auditor instead of skipping the audit. #### Automated Path: Provider-Aware Script > **LONG-RUNNING CALL — USE THE POLLING PATTERN BELOW.** > This script invokes an external LLM and takes **3-5 minutes for larger modules**. > Do NOT start writing tests or commits while the audit is in progress. > When calling from a Bash tool, set `timeout: 600000` (10 min) — the default > 120-second timeout will kill the subprocess before the auditor finishes. > The audit is only done when you have a `REPORT_FILE` path in hand. **Polling invocation (REQUIRED)** — run the audit in the background and poll so the Bash tool receives periodic output and does not time out: ```bash # Start audit in background, capture stdout (the result file path) separately # Default scope: --git filters to files the current diff touched