---
name: loopd
description: Use when the user invokes `/loopd <name>` to start a loopd session. The argument is either `pm` (run the PM merge-orchestration round) or a worker name (run that worker's round in its worktree). Reads .loopd/LOOPD.md + .loopd/LOOP_<NAME>.md, runs the appropriate pre-round, picks a task from Active or Queue, delegates via parallel subagent dispatch, runs gates, commits, pushes, updates the tracker, schedules next wake.
---

# loopd — run a loopd round

You are starting a loopd session. The skill argument is either `pm` or a worker name. Find `.loopd/` via `git rev-parse --show-toplevel`/../.loopd or by searching upward.

## Step 0 — Verify loopd is installed

1. `git rev-parse --show-toplevel` succeeds.
2. `.loopd/config.sh` exists at the repo root.
3. `source .loopd/config.sh` (via a Bash tool call) — you now have `PROJECT`, `MAIN_BRANCH`, `PM_WORKTREE`, `WORKER_NAMES[]`, `WORKER_BRANCHES[]`, `WORKER_WORKTREES[]`.

If any of these fail, tell the user loopd isn't installed here and point them at `/loopd-init`.

## Step 1 — Dispatch on argument

Parse the skill argument. Valid values: `pm`, or any element of `WORKER_NAMES[]`. Anything else → error to user.

- `pm` → go to **PM round** section.
- worker name → go to **Worker round** section, resolving the worker's branch + worktree by index.

---

## PM round

You are the Project Manager. You never touch domain code; you only orchestrate.

### Pre-round
```bash
cd "$PM_WORKTREE"
bash .loopd/pm-round.sh
```

`pm-round.sh` does: fetch origin, FF-merge every `WORKER_BRANCHES[*]` into `MAIN_BRANCH`, cherry-pick + force-with-lease reset on divergence, log every action to `.loopd/pm-round.log`.

### Read state
- Read `.loopd/LOOPD.md` (charter) if you need protocol refresher.
- Read `.loopd/LOOP_PM.md` — your Roadmap, Blocker matrix, PM log.
- Read every `.loopd/LOOP_<WORKER>.md` — to confirm each worker's Queue depth ≥ 3, spot cross-loop conflicts, detect blockers.
- `git log --oneline -20` — see what each worker shipped this round.

### Delegate (parallel)

Dispatch investigation subagents in a single message with multiple Agent calls. Common PM investigations:
- Explore: find cross-cutting code that two workers might collide on.
- general-purpose: synthesize a roadmap update from the logs.

Codex: use `spawn_agent` per `references/codex-tools.md`.

### Update tracker

For each worker whose Queue is thin: specify a new task in their `## Queue` (with enough detail that they can pick it up without asking). Keep Queue ≥ 3.

Update `LOOP_PM.md`:
- Rewrite `## Roadmap` if priorities shifted.
- Update `## Blocker matrix` for cross-loop blockers.
- Append one-line entry to `## Log`.

### Commit + push

**Only PM pushes `main`.** If state changed:
```bash
git add .loopd/LOOP_*.md
git commit -m "pm(round): <summary>"
git push origin "$MAIN_BRANCH"
```

If nothing changed (quiet round), skip the commit.

### Schedule next wake

Use ScheduleWakeup (or Codex equivalent):
- If this round merged ≥1 worker commit or reconciled a divergence → 270s.
- If 2+ consecutive quiet rounds → 1500s.
- Default → 1200s.

Pass the same `/loopd pm` invocation as the wake prompt.

---

## Worker round

You are a worker. The skill argument was your name (e.g., `backend`). Resolve:
- `idx` = index of your name in `WORKER_NAMES`.
- `BRANCH` = `WORKER_BRANCHES[idx]`.
- `WORKTREE` = `WORKER_WORKTREES[idx]`.

### Pre-round — rebase on main
```bash
cd "$WORKTREE"
git fetch origin
git rebase "origin/$MAIN_BRANCH"
```

Conflicts in your domain → resolve. Conflicts outside your domain → stop, flag in `Blocked by` in your `LOOP_<NAME>.md`, let PM reconcile. Do not resolve other workers' code blindly.

### Read state
- `.loopd/LOOPD.md` if you need protocol refresher.
- `.loopd/LOOP_<YOUR_NAME_UPPER>.md` — your Active task, Queue, Blocked by, Backlog, PM log, Log. The header prose block tells you your Domain, Bar, and Gates.

### Pick task

Priority order:
1. If `## Active task` populated → work it.
2. Else promote top of `## Queue` into Active.
3. Else pull top of `## Backlog` into Active.
4. Else (no work available) — propose something from the domain, flag to PM.

Never wait for PM to populate Active — the Queue exists for exactly this reason.

### Delegate (parallel)

Single message, multiple Agent calls:
- Explore — survey current code state
- code-architect or backend-architect — sketch design
- code-reviewer (after implementation)

Codex: use `spawn_agent` per `references/codex-tools.md`.

### Gates

The `## Gates` prose in your `LOOP_<NAME>.md` lists the exact commands. Typically:
- Fast gates every round (unit tests + lint) — ~30s.
- Full gates every 3rd round (integration, feature-flag variants, smoke tests) — several minutes.

If gates fail, fix or roll back; do not ship red.

### Update tracker

Move completed item out of `## Active task`, append one-line entry to `## Log` (keep last 5 — older lives in `git log`), pull next task from `## Queue` into `## Active task`.

Do NOT maintain a Completed list. `git log --oneline --author=...` reconstructs it.

### Commit + push

Use the commit prefix convention from your `LOOP_<NAME>.md`:

```bash
git add <specific files>
git commit -m "<prefix>(<topic>): <one-liner>"
git push origin "$BRANCH"
```

**Never `git push origin $MAIN_BRANCH`.** The pre-push hook will reject it; do not bypass.

### Schedule next wake

Use ScheduleWakeup with the same `/loopd <your-name>` invocation. Typical: 270s if active round, 600s if quiet.

---

## Rules that apply to both PM and worker

- **Parallelism is the default for subagent dispatch.** Bad: three sequential Agent calls. Good: one message with three parallel Agent calls.
- **Related files ship in the same commit.** Schema + query, proto + handler, lockfile + manifest — atomic or not at all. Avoids cross-worker codegen breakage.
- **Review gate before ship on sensitive paths.** If your LOOP file's Bar prose calls for paranoid review (compliance, auth, money-handling), run `code-reviewer` before commit.
- **Never force-push `main`.** Ever.
- **Never push another worker's branch.** Ever.

## When things go wrong

- Worker pre-round rebase fails on your own domain → fix, continue.
- Rebase fails on another domain → stop, flag in `Blocked by`, wake PM.
- PM's `pm-round.sh` reports FF-fail → the script auto-handles it (cherry-pick + force-with-lease reset); read `.loopd/pm-round.log` to verify no surprises.
- Gates red → don't ship. Fix in the same round, or roll back Active.
- `.loopd/config.sh` sources with errors → likely typo; have the user inspect, or re-run `/loopd-init` with `--repair` (TBD).