agent-teams-simplify-and-harden

What this skill does

# Agent Teams Simplify & Harden

## Install

```bash
gh skill install pskoett/pskoett-skills agent-teams-simplify-and-harden
```

Fallback using the Agent Skills CLI:

```bash
npx skills add pskoett/pskoett-skills/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

## Pipeline Integration

This skill replaces stages 2–4 of the standard pipeline (execution, review, learning) with a team-based loop. It can follow `plan-interview` or run standalone — every upstream artifact is optional.

```
[plan-interview] → [agent-teams-simplify-and-harden] → [self-improvement]
                    ├─ intent frame (team lead)
                    ├─ implement (parallel agents)
                    ├─ audit (parallel agents)
                    ├─ drift check (team lead, between rounds)
                    └─ learning loop output → self-improvement
```

When a plan file from `plan-interview` exists, the skill extracts tasks from it. When no plan exists, the team lead runs a brief inline planning phase. Context-surfing runs as a lightweight drift check for the team lead between loop rounds — sub-agents are short-lived and don't need it.

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

### 0. Plan and Frame

**If a plan file exists** (from `plan-interview` at `docs/plans/plan-NNN-<slug>.md` or user-provided): read it, extract the implementation checklist, and use those as the task list for step 2.

**If no plan exists**, run a brief inline planning interview:

1. What needs to be built, fixed, or hardened? (features, bugs, targets)
2. What's the spec or source of truth? (doc, issue, PR, or verbal description)
3. What are the acceptance criteria?

Turn the answers into a concrete task list. This is not a full `plan-interview` — just enough to break the work into parallelizable units.

**Intent frame:** Before creating the team, the team lead emits:

```markdown
## Intent Frame #1

**Outcome:** [What the team session will deliver]
**Approach:** [Team structure, number of agents, audit dimensions]
**Constraints:** [Scope boundaries, loop cap, budget limits]
**Success criteria:** [Clean audit or loop cap with all critical/high resolved]
**Estimated complexity:** [Small / Medium / Large — based on task count and file count]
```

Confirm with the user before proceeding. This anchors all subsequent drift checks.

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

> Optional: delegate this compile/test step to the `verify-gate` skill instead of running ad-hoc commands, for consistency with the inner-loop pipeline. verify-gate runs the project's compile/test/lint and returns a pass/fail signal with diagnostics.

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?" |
| **