agent-teams-simplify-and-harden

What this skill does

# Agent Teams Simplify & Harden

## Install

```bash
npx skills add pskoett/pskoett-ai-skills/agent-teams-simplify-and-harden
```

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

```
┌──────────────────────────────────────────────────────────┐
│                  TEAM LEAD (you)                          │
│                                                           │
│  Phase 1: IMPLEMENT (+ document pass on fix rounds)       │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐                 │
│  │ impl-1   │ │ impl-2   │ │ impl-3   │  ...            │
│  │ (general │ │ (general │ │ (general │                 │
│  │ purpose) │ │ purpose) │ │ purpose) │                 │
│  └──────────┘ └──────────┘ └──────────┘                 │
│       │             │            │                        │
│       ▼             ▼            ▼                        │
│  ┌─────────────────────────────────────┐                 │
│  │  Verify: compile + tests            │                 │
│  └─────────────────────────────────────┘                 │
│       │                                                   │
│  Phase 2: SIMPLIFY & HARDEN AUDIT                         │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐                 │
│  │ simplify │ │ harden   │ │ spec     │  ...            │
│  │ auditor  │ │ auditor  │ │ auditor  │                 │
│  │ (Explore)│ │ (Explore)│ │ (Explore)│                 │
│  └──────────┘ └──────────┘ └──────────┘                 │
│       │             │            │                        │
│       ▼             ▼            ▼                        │
│  Exit conditions met?                                     │
│    YES → Produce summary. Ship it.                        │
│    NO  → back to Phase 1 with findings as tasks           │
│          (max 3 audit rounds)                             │
└──────────────────────────────────────────────────────────┘
```

## Loop Limits and Exit Conditions

The loop exits when ANY of these are true:

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

```
TeamCreate:
  team_name: "<project>-harden"
  description: "Implement and harden <description>"
```

### 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.

```
TaskCreate for each unit of work:
  subject: "Implement <specific thing>"
  description: "Detailed requirements, file paths, acceptance criteria"
  activeForm: "Implementing <thing>"
```

Set up dependencies if needed:
```
TaskUpdate: { taskId: "2", addBlockedBy: ["1"] }
```

### 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**.

```
Task tool (spawn teammate):
  subagent_type: general-purpose
  team_name: "<project>-harden"
  name: "impl-<area>"
  mode: bypassPermissions
  prompt: |
    You are an implementation agent on the <project>-harden team.
    Your name is impl-<area>.

    Check TaskList for your assigned tasks and complete them.
    After completing each task, mark it completed and check for more.

    Quality gates:
    - Code must compile cleanly (substitute your project's compile
      command, e.g. bunx tsc --noEmit, cargo build, go build ./...)
    - Tests must pass (substitute your project's test command,
      e.g. bun test, pytest, go test ./...)
    - Follow existing code patterns and conventions

    When all your tasks are done, notify the team lead.
```

### 4. Wait for Implementation to Complete

Monitor agent messages. When all implementation agents report done:

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:
```bash
git diff --name-only <base-branch>  # or: git diff --name-only HEAD~N
```
You will pass this file list to each auditor.

### 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:**

| Auditor | Focus | Mindset |
|---------|-------|---------|
| **simplify-auditor** | Code clarity and unnecessary complexity | "Is there a simpler way to express this?" |
| **harden-auditor** | Security and resilience gaps | "If someone malicious saw this, what would they try?" |
| **spec-auditor** | Implementation vs spec/plan completeness | "Does the code match what was asked for?" |

#### Simplify Auditor

```
Task tool (spawn teammate):
  subagent_type: Explore
  team_name: "<project>-harden"
  name: "simplify-auditor"
  prompt: |
    You are a simplify auditor on the <project>-harden team.
    Your name is simplify-auditor.

    Your job is to find unnecessary complexity -- NOT fix it. You are
    read-only.

    SCOPE: Only review the following files (modified in this session).
    Do NOT flag issues in other files, even if you notice them.
    Files to review:
    <paste file list here>

    Fresh-eyes start (mandatory): Before reporting findings, re-read all
    listed changed code with "fresh eyes" and actively look for obvious
    bugs, errors, confusing logic, brittle assumptions, naming issues,
    and missed hardening opportunities.

    Review each file and check for:

    1. Dead code and scaffolding -- debug logs, commented-out attempts,
       unused imports, temporary variables left from iteration
    2. Naming clarity -- function names, variables, and parameters that
       don't read clearly when seen fresh
    3. Control flow -- nested conditionals that could be flattened, early
       returns that could replace deep nesting, boolean expressions that
       could be simplified
    4. API surface -- public methods/functions that should be private,
       more exposure than necessary
    5. Over-abstraction -- classes, interfaces, or wrapper functions not
       justified by current scope. Agents tend to over-engineer.
    6. Consolidation -- logic spread across multiple functions/files that
       could live in one place

    For each finding, categorize as:
    - **Cosmetic** (dead code, unused imports, naming, control flow,
      visibility reduction) -- low risk, easy fix
    - **Refactor** (consolidation, restructuring, abstraction changes)
      -- only flag when genuinely necessary, not just "slightly better."
      The bar: would a senior engineer say the current state is clearly
      wrong, not just imperfect?

    For each finding report:
    1. File and line number
    2. Category (cosmetic or refactor)
    3. What's wrong
    4. What it should be (specific fix, not vague)
    5. Severity: high / medium / low

    If you notice issues outside the scoped files, list them separately
    under "Out-o