loopd

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

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:

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

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:

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