Agent Teams Simplify & Harden

Install

CODEBLOCK0

A two-phase team loop that produces production-quality code: implement, then audit using simplify + harden passes, then fix audit findings, then re-audit, repeating until the codebase is solid or the loop cap is reached.

When to Use

• - Implementing multiple features from a spec or plan
• Hardening a codebase after a batch of changes
• Fixing a list of issues or gaps identified in a review
• Any task touching 5+ files where quality gates matter

The Pattern

CODEBLOCK1

Loop Limits and Exit Conditions

The loop exits when ANY of these are true:

1. 1. Clean audit: All auditors report zero findings
2. Low-only round: All findings in a round are severity low -- fix them inline (team lead or a single impl agent) and exit without re-auditing
3. Loop cap reached: 3 audit rounds have completed. After the third round, fix remaining critical/high findings inline and exit. Log any unresolved medium/low findings in the final summary.

Budget guidance: Track the cumulative diff growth across rounds. If fix rounds have added more than 30% on top of the original implementation diff, tighten the scope: skip medium/low simplify findings and focus only on harden patches and spec gaps.

Step-by-Step Procedure

1. Create the Team

CODEBLOCK2

2. Create Tasks

Break the work into discrete, parallelizable tasks. Each task should be independent enough for one agent to complete without blocking on others.

CODEBLOCK3

Set up dependencies if needed:
CODEBLOCK4

3. Spawn Implementation Agents

Spawn general-purpose agents (they can read, write, and edit files). One per task or one per logical group. Run them in parallel.

CODEBLOCK5

4. Wait for Implementation to Complete

Monitor agent messages. When all implementation agents report done:

1. 1. Run compile/type checks to verify clean build
2. Run tests to verify all pass
3. If either fails, fix or assign fixes before proceeding

Before spawning auditors, collect the list of files modified in this session:

git diff --name-only <base-branch>  # or: git diff --name-only HEAD~N

5. Spawn Audit Agents

Spawn Explore agents (read-only -- they cannot edit files, which prevents them from "fixing" issues silently). Each auditor covers a different concern using the Simplify & Harden methodology.

Recommended audit dimensions:

Simplify Auditor

CODEBLOCK7

Harden Auditor

CODEBLOCK8

Spec Auditor

CODEBLOCK9

6. Process Audit Findings

Collect findings from all auditors. For each finding:

• - Critical/High: Create a task and assign to an implementation agent
• Medium: Create a task, include in next implementation round
• Low/Cosmetic: Include in next round only if trivial to fix; otherwise note in the final summary and skip

Refactor gate: For findings categorized as refactor or security refactor, evaluate whether the refactor is genuinely necessary before creating a task. The bar: "Would a senior engineer say the current state is clearly wrong, not just imperfect?" Reject refactor proposals that are style preferences or marginal improvements.

Exit check: If all findings in this round are severity low, fix them inline and skip re-auditing (see Loop Limits).

When creating fix tasks, bundle a document pass into each implementation agent's work:

After fixing your assigned issues, add up to 5 single-line comments
across the files you touched on non-obvious decisions:

• - Logic that needs more than 5 seconds of "why does this exist?" thought
• Workarounds or hacks, with context and a TODO for removal conditions
• Performance choices and why the current approach was picked

Do NOT comment on the audit fixes themselves -- only on decisions
from the original implementation that lack explanation.

This keeps the document pass lightweight and scoped. Auditors in subsequent rounds should not flag these comments as findings.

7. Loop

If there are findings to fix:

1. 1. Create tasks from findings (include document pass instructions)
2. Spawn implementation agents (or reuse idle ones via SendMessage)
3. Wait for fixes
4. Run compile + test verification
5. Check loop limits (see "Loop Limits and Exit Conditions")
6. If not exiting: spawn audit agents again (fresh agents, not reused -- clean context)
7. Repeat

8. Final Verification and Summary

When exit conditions are met:

1. 1. Compile / type check -- must be clean
2. Tests -- must all pass
3. No // TODO or // FIXME comments introduced without corresponding tasks

Produce a final summary for the session:

CODEBLOCK10

Adapt the format to your context. The goal is a clear record of what was found, what was fixed, what was skipped and why, and what remains.

9. Cleanup

Send shutdown requests to all agents, then delete the team:

CODEBLOCK11

Agent Sizing Guide

More agents = more parallelism but more coordination overhead. For most tasks, 2-3 implementation agents and 2-3 auditors is the sweet spot.

Tips

• - Implementation agents should be general-purpose -- they need write access
• Audit agents should be Explore -- read-only prevents them from silently "fixing" things, which defeats the purpose of auditing
• Fresh audit agents each round -- don't reuse auditors from previous rounds; they carry context that biases them toward "already checked" areas
• Task descriptions must be specific -- include file paths, function names, exact behavior expected. Vague tasks produce vague implementations.
• Run compile + tests between phases -- don't spawn auditors on broken code; fix compilation/test errors first
• Keep the loop tight -- if auditors find only 1-2 low-severity cosmetic issues, fix them yourself instead of spawning a full implementation round
• Assign tasks before spawning -- set owner on tasks via TaskUpdate so agents know what to work on immediately
• Simplify-first posture -- when processing audit findings, prioritize cosmetic cleanups that reduce noise before tackling refactors. Cleanup is the default, refactoring is the exception
• Security over style -- when budget or time is constrained, prioritize harden findings over simplify findings
• Pass the file list -- always give auditors the explicit list of modified files. Don't rely on them figuring out scope on their own.

Example: Implementing Spec Features

CODEBLOCK12

Quality Gates (Non-Negotiable)

These must pass before the loop can exit:

1. 1. Clean compile / type check -- zero errors
2. Tests -- zero failures
3. Exit condition met (clean audit, low-only round, or loop cap reached with critical/high findings resolved)
4. No // TODO or // FIXME comments introduced without corresponding tasks