improve

Improve Pipeline

Stateless iterative review-fix pipeline. Dispatches specialist sentinels (correctness, security, perf) in parallel, consolidates via review-arbiter, dispatches review-fixer to apply targeted fixes, then re-reviews. Loops until arbiter returns "clean" verdict (zero issues) or max iterations (5) reached. No state.json, no hooks, no Agent Teams -- follows the same stateless direct-dispatch model as the debug pipeline.

Key Architecture

• Stateless: No .agents/tmp/state.json is created or read during improve
• Direct dispatch: The improve command spawns agents via Agent tool, reads their output files, and proceeds
• No hooks: Because no ants state.json exists, check_ants_workflow() in every hook returns false (exits 0 immediately), so all hooks pass through without interfering
• Self-contained: All output files live under .agents/tmp/improve/
• Iterative: Loops up to 5 iterations with early termination on clean verdict

Pipeline

Phase I0  | REVIEW      | Adversarial Review     | 4x parallel sentinels + review-arbiter
Phase I1  | FIX         | Targeted Repair        | 1x review-fixer
[loop back to I0 if issues remain, up to 5 iterations]
Phase I2  | REPORT      | Summary                | Orchestrator displays results

Pipeline Diagram

Iteration 1:
    I0 Review (4x parallel sentinels)
       / | | \
correctness security perf testing
       \ | | /
    review-arbiter (consolidate)
       |
    verdict?
     /      \
  clean    issues_found
    |         |
  I2 Report  I1 Fix (review-fixer)
              |
            [loop -> I0 Review, iteration 2]

...repeat up to 5 iterations...

I2 Report (summary of all iterations)

Phase Details

Phase I0: Adversarial Review (REVIEW)

Four specialist sentinels dispatched in parallel: ants:sentinel-correctness, ants:sentinel-security, ants:sentinel-perf, ants:sentinel-testing. Each reviews all project files relevant to the task description. (sentinel-docs and sentinel-style are excluded from the improve pipeline — docs/style quality is out of scope for defect-focused improvement.)

After all four complete, ants:review-arbiter consolidates findings by cross-referencing, deduplicating, and resolving conflicts across all sentinel reports. The arbiter reports all issues by default -- no severity threshold override is needed, as the arbiter naturally captures all severities including info.

• Sentinel output: .agents/tmp/improve/iter-{N}/I0-review.sentinel-correctness.json, .agents/tmp/improve/iter-{N}/I0-review.sentinel-security.json, .agents/tmp/improve/iter-{N}/I0-review.sentinel-perf.json, .agents/tmp/improve/iter-{N}/I0-review.sentinel-testing.json
• Arbiter output: .agents/tmp/improve/iter-{N}/I0-quality.json
• Verdict: clean (zero issues) terminates loop; issues_found (any severity) triggers I1

Phase I1: Targeted Repair (FIX)

Single ants:review-fixer agent reads issues from .agents/tmp/improve/iter-{N}/I0-quality.json. The dispatch prompt overrides the fixer's default state.json input -- since the improve pipeline is stateless, there is no state file. Instead, the fixer is pointed directly to the arbiter's quality file.

Fixer processes issues in severity order: critical first, then warning, then info. ALL severities are fixed (info and above) -- this is the key differentiator from the swarm pipeline.

• Output: .agents/tmp/improve/iter-{N}/I1-fix.json
• After fix completes: Loop back to I0 for re-review

Phase I2: Summary Report (REPORT)

No agent dispatched -- the orchestrator reads all iteration outputs and displays a summary. Shows: iteration count, issues found per iteration, issues fixed per iteration, final verdict. Displayed directly to the user.

Severity Policy

• Fix ALL issues: critical, warning, AND info
• This distinguishes improve from swarm (which only blocks on critical/warning)
• The improve pipeline is explicitly for thoroughness
• No configurable threshold -- always fixes everything

Iteration Control

• Max iterations: 5 (hardcoded in command, not configurable)
• Early termination: Arbiter returns clean verdict (zero issues at any severity)
• No circuit breaker: Stateless pipeline uses simple iteration counter
• If 5 iterations cannot resolve all issues, the remaining issues likely need human judgment

Phase-Agent Mapping

Phase	Agent	Model	Reused	Count	Execution
I0	ants:sentinel-correctness	sonnet	Yes	1	Parallel
I0	ants:sentinel-security	sonnet	Yes	1	Parallel
I0	ants:sentinel-perf	sonnet	Yes	1	Parallel
I0	ants:sentinel-testing	sonnet	Yes	1	Parallel
I0	ants:review-arbiter	sonnet	Yes	1	Sequential (after sentinels)
I1	ants:review-fixer	inherit	Yes	1	Single

Total: 6 reused agents, 0 new agents

Output File Layout

All output files live under .agents/tmp/improve/ with per-iteration subdirectories:

Phase	File	Format	Description
I0 sentinel	.agents/tmp/improve/iter-{N}/I0-review.sentinel-correctness.json	JSON	Correctness findings
I0 sentinel	.agents/tmp/improve/iter-{N}/I0-review.sentinel-security.json	JSON	Security findings
I0 sentinel	.agents/tmp/improve/iter-{N}/I0-review.sentinel-perf.json	JSON	Performance findings
I0 sentinel	.agents/tmp/improve/iter-{N}/I0-review.sentinel-testing.json	JSON	Test quality findings
I0 arbiter	.agents/tmp/improve/iter-{N}/I0-quality.json	JSON	Consolidated verdict
I1 fixer	.agents/tmp/improve/iter-{N}/I1-fix.json	JSON	Fix report

Orchestration Model

The improve pipeline uses stateless direct dispatch -- the same model as the debug pipeline, fundamentally different from the swarm pipeline's hook-driven Agent Teams orchestration.

• No state.json -- iteration progress is tracked in the command's conversation context, not .agents/tmp/state.json. Because no state file exists, all ants hooks (check_ants_workflow()) exit 0 immediately as no-ops.
• Direct dispatch -- the command spawns agents via Agent tool, reads their output files, evaluates verdicts, and loops. No hooks, no Agent Teams.
• Review-fixer edits freely -- the edit gate imposes no restrictions since there is no active swarm state.