agent-army

What this skill does

# Agent Army

A 2-layer parallel execution framework. Each Layer 1 agent has its own full context window (not a slice). Each spawns Layer 2 sub-agents under it. The result is many independent brains running at once — not one brain divided.

```
Commander (you)
 |
 |-- Layer 1: Team (3 to 50+, each = own 1M context)
 |    |-- Agent A (1M) -- Sub-agent A1, A2, ...
 |    |-- Agent B (1M) -- Sub-agent B1, B2, ...
 |    |-- Agent C (1M) -- Sub-agent C1, C2, ...
 |    |-- ... (no cap)
```

**Swarm vs. army:** A swarm splits one context window across sub-agents — one brain, divided. An army gives each Layer 1 member its own window. That difference is the whole point of this skill.

## When to use

- Large refactors spanning many files
- Multi-file color / style / naming / API migrations
- Broad codebase audits (security, a11y, performance, dead code)
- Bulk content generation or transformation
- Any task with **6+ independent units of work** that can run simultaneously

## When NOT to use

- Fewer than 6 independent units of work — just do it directly
- Heavy sequential dependencies where each step needs the last one's output
- Single-file changes
- Tasks needing one coherent authorial voice across all output (parallel agents drift)

If the task doesn't clearly fit, say so and propose doing it inline instead of spinning up an army.

<mandatory-rules>
## MANDATORY RULES

1. EVERY Layer 1 agent MUST spawn 2+ sub-agents. No exceptions. If you're about to deploy an L1 agent with no sub-agents, STOP and restructure.
2. NEVER silently shrink the army. Match the user's chosen tier. If you must deviate, say so out loud and why.
3. Sub-agent deployment instructions go INSIDE the Layer 1 brief. If they're missing, the sub-agents will never be created.
4. Report as agents complete: `[Agent N/M complete] name: X files modified, Y flags`.
5. Show the army plan and pass the Deployment Gate before deploying (Full Mode). Quick Mode composes the plan internally but still passes the Gate.
6. After every wave: run the build AND the phantom-completion check (see Verify). A green report from an agent is a claim, not proof.
7. "Keep going" / "don't stop" = continuous mode: launch a new agent the moment one completes. Don't wait, don't re-ask.
</mandatory-rules>

## Army Size

Confirm a tier before starting. Present this table:

```
| Tier         | L1 Agents | Total w/ Sub-agents | Est. Tokens  |
|--------------|-----------|---------------------|--------------|
| Conservative | 3         | ~9                  | ~200-500K    |
| Standard     | 5-10      | ~15-30              | ~500K-1.5M   |
| Aggressive   | 10-20     | ~30-60              | ~1.5-4M      |
| Maximum      | 20-50+    | ~60-100+            | ~4M+         |
| Custom       | you pick  | you pick            | varies       |
```

Default to **Standard** on "just do it." After recon (Step 3), recommend a specific number based on what you found — e.g. "35 files across 6 domains → Aggressive: 8 L1 agents, 2-3 sub-agents each (~22 total, ~2M tokens). Adjust?" Token estimates are rough and scale with task complexity.

## Protocol

**Mode:** If scope is already concrete (file paths, exact changes, tier), skip to Step 3 (Quick Mode). Otherwise start at Step 1 (Full Mode).

### Step 1: Intake (Full Mode)

Confirm in one line if the user already gave context: "Goal: [X]. Scope: [Y]. Tier: [Z]. Starting." Otherwise ask for: goal (one sentence), scope (files/dirs/"everything"), constraints (don't touch X, match Y), tier.

### Step 2: Git Checkpoint

1. `git status` — warn on uncommitted changes, offer to stash/commit first.
2. `git checkout -b agent-army/checkpoint-{timestamp}` then switch back. This is the rollback point.
3. No git repo? Warn that there's no safety net and get explicit confirmation.

### Step 3: Recon

1. Grep / Glob / Read to find every affected file.
2. Count the units of work.
3. `wc -l` each file. Flag 500+ line files as **heavy** → assign solo.
4. Classify into domains (by directory, import graph, file type, naming pattern).
5. Identify shared dependencies — **foundation files** imported across domains. Handle these first (Step 5).
6. Identify the build command (package.json, Makefile, etc.).

Output: `Files: N | Heavy: [list] | Domains: [list] | Shared deps: [list] | Build cmd: [cmd]`

### Step 4: Compose

1. **Foundation Agent** for shared deps — runs *before* the parallel wave so dependents don't conflict.
2. **Layer 1:** one agent per domain; split large domains across multiple agents.
3. **Layer 2:** 2+ sub-agents per L1 agent, assigned by **weighted file load**, not file count:
   - Small (<200 lines): 2-3 per sub-agent
   - Medium (200-500): 1-2 per sub-agent
   - Heavy (500+): 1 per sub-agent, solo
4. Name every agent. Assign every file to **exactly one** sub-agent — no overlaps, no gaps.

Output the army plan. Full Mode: pause for "Proceed?" Quick Mode: one-line summary, then deploy.

### Deployment Gate

Output this checklist in your response before deploying. Don't check it mentally — write it out.

```
DEPLOYMENT GATE:
[ ] Every L1 brief contains "You MUST spawn N sub-agents"
[ ] Every sub-agent is named with specific files assigned
[ ] Every file is owned by exactly one sub-agent (no overlap, no gap)
[ ] L1 briefs include full sub-agent deployment instructions
[ ] Tier matches the user's selection
```

All must PASS. Any FAIL → fix the plan before deploying.

### Step 5: Deploy

1. Foundation Agent first (if any). Wait for completion.
2. Launch ALL Layer 1 agents in parallel — `run_in_background: true`, in a single message.
3. Each L1 agent spawns its L2 sub-agents in parallel (per its brief).
4. Report each completion: `[Agent N/M complete] name: results`.

### Step 6: Verify

1. **Re-scan** — rerun the Step 3 searches for remaining violations.
2. **Phantom-completion check** — run `git diff --stat` and cross-reference against agent reports. Any agent that reported "COMPLETE, N files modified" with no matching diff lied or no-op'd — re-dispatch it. Trust the diff, not the report.
3. **Build** — run the build command. Record PASS/FAIL.
4. **Resolve cross-team flags** from the reports.
5. Output the army report:

```
Agents: N | Files modified: N (diff-confirmed) | Skipped: N | Build: PASS/FAIL
Flags: [list] | Phantom completions caught: N | Rollback: git checkout agent-army/checkpoint-{timestamp}
```

## Waves

Each wave is a new, smaller, differently-specialized army. Pause for user approval before each. **Max 4 waves.**

| Wave | Name          | Trigger                                                        | Purpose                                              |
|------|---------------|----------------------------------------------------------------|------------------------------------------------------|
| 1    | **Execute**   | always                                                         | make the changes                                     |
| 2    | **Audit**     | build fails, remaining violations, 20+ files, or flags > 0     | fresh agents review Wave 1 for correctness/edge cases|
| 3    | **Propagate** | changes touch APIs/types/interfaces; tests or docs reference old patterns | update tests, docs, configs, downstream callers |
| 4    | **Notify**    | user opts in                                                   | draft PR description, changelog, Slack summary       |

Each wave's report is the next wave's recon. After each, rerun Verify; stop when re-scan is clean and build passes, or at 4 waves.

### Resume / scratchpad

For multi-wave or interruptible runs, write `.army-state.md` after Wave 1: files modified (diff-confirmed), open flags, unresolved issues, decisions. If a run is killed, the next invocation reads this file and resumes from the last clean wave instead of restarting. Skip for single-wave tasks.

## Layer 1 Prompt Template

This is what spawned agents actually see — the most important section in the skill.

```
You are [AGENT_NAME], specialist on [DOMAIN].

Obje