---
name: readiness-check
description: Decide whether a repo is ready to run two or more AI coding agents in parallel, before spending a day on setup. Five hard prerequisites, three anti-patterns that look ready but are not, and a GREEN/YELLOW/RED verdict. Use when asked "should I run multiple agents on this codebase", "is this repo ready for a swarm", or "why did my parallel agents stall".
version: 1.1.0
license: CC-BY-4.0
tags: [agents, parallel, swarm, setup, decision-framework, prerequisites, claude-code, cursor, codex]
---

# Skill — Readiness Check

## When to use this skill

Use this skill **before** running `swarm-init` on any repo. The full PAL setup is reversible but not free — you'll write at least 2,000 lines across CLAUDE.md, AGENTS.md, task specs, swarm.toml, and CI wiring. If the repo isn't ready, those lines are wasted and the agents will spin without shipping.

Trigger phrases that should call this skill:
- "Should I set up parallel agent lanes here?"
- "Is this repo ready for a swarm?"
- "Can I run two coding agents on this codebase?"
- "Why did my swarm stall on day one?"

Run it once per repo before init. Run it again if you've shipped a significant restructure (new monorepo split, new CI system, new auth model).

## Prerequisites — all five must clear

The swarm assumes five things about your repo. If any of them fails, the swarm will either not start or will fail in confusing ways. Check all five before init.

### 1. A clearly splittable lane boundary

You can name two (or three) discrete lanes of work where each lane mostly touches different files. The canonical splits that work:

- Frontend ↔ backend (Next.js pages and components vs API routes and server code)
- Web ↔ worker (the web app vs a Python or Node worker process)
- Schema ↔ code (Prisma/DB migrations vs application code that uses them)
- Build ↔ tests (production code vs test files and harnesses)

A split works when 80%+ of typical PRs touch only one side.

Do not eyeball this. Measure it. Define your two lanes as path prefixes, then run:

```bash
# Edit LANE_A and LANE_B to match your repo, then run from the repo root.
LANE_A='^(src/app|src/components|app/)'
LANE_B='^(server/|api/|worker/)'

git log -50 --format='%H' | while read -r sha; do
  files=$(git show --name-only --format='' "$sha" | grep -v '^$')
  a=$(echo "$files" | grep -Ec "$LANE_A" || true)
  b=$(echo "$files" | grep -Ec "$LANE_B" || true)
  if   [ "$a" -gt 0 ] && [ "$b" -eq 0 ]; then echo "A-only"
  elif [ "$b" -gt 0 ] && [ "$a" -eq 0 ]; then echo "B-only"
  elif [ "$a" -gt 0 ] && [ "$b" -gt 0 ]; then echo "BOTH"
  else echo "neither"; fi
done | sort | uniq -c | sort -rn
```

Read the output. `A-only` plus `B-only` as a share of the commits that touched either lane is your clustering score. At or above 80%, the boundary is real. Between 60% and 80%, the boundary is fuzzy and you will need per-task file guardrails to compensate. Below 60%, you do not have two lanes, you have one.

A large `neither` count is not a problem. It usually means config, docs, and lockfiles, which belong on the shared-file blocklist anyway.

### 2. CI that runs locally in under 10 minutes

The drain daemon runs your local CI script on every clean PR before merging. If CI takes 30 minutes, the daemon can't keep up with two parallel lanes shipping multiple PRs an hour. Under 10 minutes is the soft cap; under 5 is ideal.

If your CI today is 20+ minutes and you can't trim it, this is a prerequisite gap to fix before swarm init. Common trims: parallelize test runners, skip expensive integration tests on per-PR runs (run them on main only), cache dependency installs.

The whole contract is a script that exits `0` on pass and non-zero on fail. That is all an autonomous merge gate needs:

```bash
#!/usr/bin/env bash
# scripts/local_ci.sh — exit 0 = safe to merge, non-zero = do not merge.
set -euo pipefail

start=$(date +%s)
pnpm install --frozen-lockfile
pnpm typecheck
pnpm lint
pnpm test -- --run          # unit + component tests only; no cloud deps
echo "local CI passed in $(( $(date +%s) - start ))s"
```

Time it before you trust it: `time bash scripts/local_ci.sh`. If that number is over 10 minutes, no amount of orchestration will save you, because the gate is the bottleneck.

### 3. A backlog of at least 10 typed task specs you can write upfront

The agents pull from a task backlog in `docs/agent-tasks/`. Each task is a structured markdown file (lane, priority, effort, status, files-to-touch, files-not-to-touch, acceptance criteria). If you can't write 10 of these upfront, the agents will run out of work in the first session and you'll spend the session writing more specs by hand — which defeats the point.

If you have ideas but they're not specced yet, that's normal. Allocate a focused half-day to write 10–15 task specs *before* you start.

A task spec is a markdown file with a small, fixed header. The two fields that matter most for parallel work are the file guardrails, because they are what keep two agents out of each other's way:

```markdown
---
id: WEB-01
lane: frontend
priority: 2
effort: M
status: todo
files-to-touch:
  - src/components/ConversionToast.tsx
  - src/lib/toast-store.ts
files-not-to-touch:
  - src/lib/api-client.ts   # backend lane owns this
---

## Goal
One sentence describing the observable outcome.

## Acceptance criteria
- [ ] A specific, checkable statement
- [ ] Another one
- [ ] `pnpm test` passes
```

The test of a good spec: an agent can finish it without asking you a question, and you can verify it without reading the diff.

If you can't articulate 10 discrete tasks at this level, the project isn't scoped enough to run agents in parallel yet. Spend a day on planning first.

### 4. You control at least one git remote

The drain daemon uses `gh` CLI to poll PRs and squash-merge. You need:
- A GitHub repo you can push to (or a self-hosted equivalent the `gh` CLI can target)
- Push and merge permissions on the default branch
- Either `gh auth login` set up as your user, or a bot identity (advanced, see `swarm-init.md`)

A repo where you can only file PRs but not merge them won't run the swarm — there's nowhere for the daemon to land work.

### 5. You can accept the blast radius

The swarm auto-merges its own PRs when they pass CI and clear the autonomy guardrails (diff cap, lane match, shared-file blocklist). That means code lands on `main` without you reviewing every PR in real time.

If you're not comfortable with that — production deploy hooks, regulated codebase, customer-facing migrations — the swarm isn't right yet, OR you need to set the autonomy guardrails much tighter.

Three guardrails do most of the work, whatever tooling you wire them into:

- **Diff cap.** Refuse to auto-merge any PR above N changed lines. Start at 150. A large diff is where an agent's confident wrongness hides.
- **Shared-file blocklist.** Any PR touching a path on the list requires a human. Seed it with lockfiles, CI config, auth, migrations, and payment code.
- **Lane match.** Refuse to auto-merge a PR whose changed files fall outside the lane the agent was assigned. This catches drift early, and it is the single highest-value check of the three.

Set all three tight, watch for a week, then loosen the diff cap first.

The defaults in `swarm.toml` are tuned for indie projects with a real CI and rollback story, not for production systems where a bad merge causes outages.

## Anti-patterns — situations that look ready but aren't

### Anti-pattern 1: "Every change touches every file"

If your repo's commits routinely touch frontend, backend, schema, AND tests in the same PR, the lane boundary is fuzzy and the agents will merge-conflict constantly on shared files. The fix is either (a) restructure to enforce cleaner boundaries before swarming, or (b) accept that you can only run one agent at a time on this codebase — single-lane PAL works fine too.

Symptom: `git log --name-only --pretty=format: -50` shows most commits touching 5+ file types.

### Anti-pattern 2: "We have CI but it lives in GitHub Actions only"

The drain daemon runs CI **locally** on the host machine via `scripts/local_ci.sh`. GitHub Actions CI runs in the cloud and the daemon can't replicate it locally. If your only test suite is `gh workflow run`, the daemon can't gate merges on it.

The fix is to write a `scripts/local_ci.sh` that runs the same test suite locally (or a meaningful subset). If your tests genuinely cannot run locally — they require cloud-only secrets, GPU runners, etc. — the swarm isn't right for this repo without restructuring.

### Anti-pattern 3: "Solo dev, no other commits expected, just me and the agents"

Counter-intuitively, the swarm works best when there's a human committing alongside the agents — because the human catches drift and posts course-corrections via `AGENT_CHAT.md`. A pure-agent loop with zero human oversight tends to drift over a week as the agents reinforce each other's blind spots. The pattern is "human + N agents," not "N agents alone."

If you're planning to walk away for a week and let the agents run, dial autonomy way down (low diff cap, expansive blocklist) and check in daily.

## Decision output

After running through the five prerequisites and three anti-patterns, end with one of three decisions:

1. **GREEN — run swarm-init now.** All five prerequisites cleared, no anti-patterns triggered. Proceed to the `swarm-init` skill.

2. **YELLOW — fix the listed gap, then re-run this check.** One or two prerequisites have specific gaps that can be closed in a focused half-day or less (e.g., CI is slow, need to trim it; task backlog needs to be written). List the gaps explicitly.

3. **RED — this repo isn't a swarm candidate right now.** A prerequisite gap that takes weeks to close (fundamental restructure for lane boundaries; no CI at all yet), or an anti-pattern that's structural to how the repo is shaped. Document why so the decision can be revisited later when the project shape changes.

For RED decisions, the next step is **not** "force the swarm anyway." Run single-lane Claude Code or Codex directly without the swarm machinery; you get most of the value with none of the setup tax.

## Worked example 1 — GREEN

Repo: indie SaaS, Next.js + Python worker, Prisma schema, ~3,000 lines of test code, 2-month commit history.

- Lane boundary: frontend (Next.js app and components) vs backend (Python worker + API routes). 87% of last 50 commits touched only one side. ✓
- CI: `pnpm test && pnpm worker:test` runs in 4 minutes locally. ✓
- Backlog: 14 tasks specced upfront across both lanes. ✓
- Remote: own the GitHub repo, `gh auth login` set up. ✓
- Blast radius: indie project, no production users, willing to ship and revert. ✓
- Anti-patterns: none triggered.

**Decision: GREEN. Run swarm-init.**

## Worked example 2 — YELLOW

Repo: solo dev tooling, single Next.js app, ~1,500 lines.

- Lane boundary: backend (API routes) vs frontend (pages and components). Marginal — 65% of commits touched only one side, 35% touched both. ⚠
- CI: `pnpm test` runs in 90 seconds. ✓
- Backlog: 3 tasks specced. ✗
- Remote: own the GitHub repo. ✓
- Blast radius: indie, accepted. ✓
- Anti-patterns: borderline anti-pattern 1 (fuzzy boundary).

**Decision: YELLOW. Spend half a day writing 7+ more task specs to hit the backlog floor. The lane-boundary fuzziness is acceptable if task specs explicitly call out files-to-touch / files-not-to-touch per task — that compensates for the structural blurriness.**

## Worked example 3 — RED

Repo: pre-launch e-commerce platform with payment integration, customer data, no test suite yet.

- Lane boundary: would be storefront vs admin vs payment service — clear if test coverage existed. ⚠
- CI: no test suite. ✗
- Backlog: 20+ ideas but none specced. ⚠
- Remote: own the GitHub repo. ✓
- Blast radius: pre-launch payment integration — cannot accept auto-merge of agent PRs to main. ✗

**Decision: RED. Fix the test suite first (3–6 weeks of work depending on coverage target). Then revisit. In the meantime, use single-lane Claude Code with manual PR review; do not run the swarm.**

## Output format

Use this checklist when running the skill against a target repo:

```
Repo: <path>
Date: <YYYY-MM-DD>

Prerequisite 1 — Splittable lane boundary: [✓ / ⚠ / ✗]
  Notes: <one line>
Prerequisite 2 — CI under 10 min locally: [✓ / ⚠ / ✗]
  Notes: <one line>
Prerequisite 3 — 10+ task specs writable upfront: [✓ / ⚠ / ✗]
  Notes: <one line>
Prerequisite 4 — Own at least one git remote: [✓ / ⚠ / ✗]
  Notes: <one line>
Prerequisite 5 — Accept the blast radius: [✓ / ⚠ / ✗]
  Notes: <one line>

Anti-pattern 1 — Every change touches every file: [Not triggered / Borderline / Triggered]
Anti-pattern 2 — CI only in GitHub Actions: [Not triggered / Borderline / Triggered]
Anti-pattern 3 — Pure agent loop with no human oversight: [Not triggered / Borderline / Triggered]

Decision: [GREEN / YELLOW / RED]
Next step: <one line>
```

## Using this check on its own

This file is self-contained. The lane-boundary measurement, the CI contract, the task-spec shape, and the three autonomy guardrails above are everything you need to run the check and act on a YELLOW.

A GREEN verdict means the next problem is mechanical: scaffolding worktrees, wiring a merge daemon, writing the boot prompts, and handling cross-lane conflicts when they land. None of that is hard, but there is a lot of it, and getting the order wrong wastes a day.

That machinery is what the full Parallel Agent Lanes pack covers, in twelve further skills: `swarm-init`, `task-spec-author`, `local-ci-configure`, `autonomy-tuning`, `lane-boundary-design`, `agent-brief-author`, `agent-chat-protocol`, `drain-daemon-operations`, `lane-nudge-protocol`, `conflict-resolution`, `plan-for-goal-author`, and `scaling-beyond-two-lanes`, plus nine worked artifacts from a real setup. It is at `lonelybrewclub.com`.

If a RED verdict sent you here, you do not need the pack. You need a test suite. Come back after.

---

## About this file

This is `readiness-check`, skill 1 of 13 from the **Parallel Agent Lanes** pack by Lonely Brew Club. It is published free and complete, exactly as it ships to buyers.

Licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Use it, adapt it, quote it. Keep this attribution.

The full pack is at <https://lonelybrewclub.com/#pal>. Questions: support@lonelybrewclub.com