loopd-probe

   ▄▄▄▄
◀━▐    ▌   loopd — the loop, running
  ▝▄▄▄▄▘

You steer. They build. Two gates stay yours.

A control panel for running a small team of AI agents on your repositories.

You describe the work. A project-manager agent breaks it into tasks. You approve. Engineer agents build it in the background, open pull requests, and get reviewed. You merge.

You act like an engineering manager, not a pair programmer.

This repo is the template. You stamp out one instance per group of repos (work, a side project, a client). Each instance is its own small git repo that sits beside those repos and holds only the state of the work — never application code.

Two colours, wherever loopd renders. Blue #5ea2ff is the machine's — agents, code, refs, running state. Pink #ff7ac2 is yours — gates, decisions, anything waiting on a person. No third accent, no status rainbow.

Contents

Normative contracts live in the machinery itself: plugin/seed/SCHEMA.md (document types, the verification predicate) and plugin-yolo/companion/AUTONOMY.md (the delegated-autonomy modes, shipped by the loopd-yolo companion plugin).

Install

Two halves, on two clocks. The plugin carries every slash command, the two enforcement hooks and the eight role agents, and is installed once per machine; the bundle carries the scripts, the SessionStart hook and the root documents, and is stamped once per instance. A machine with only the plugin has commands and nothing to read; a bundle with only the stamp has the data and no way to drive it, and every /loopd:… reports unknown command. Do the plugin first — it is one line, and it is what step 7 needs. (docs/operations.md § 1)

1. Install the plugin — once per machine

This repo is its own marketplace. In any Claude Code session:

/plugin marketplace add cbmono/loopd
/plugin install loopd@loopd

That is the minimal install — core alone. For core plus the autonomy companion and the mods in one command, install the bundle instead: /plugin install loopd-all@loopd (plugin-all/README.md — it ships nothing of its own, so turning a mod off later never touches loopd).

Or add a mod on its own — a hooks module Claude Code runs inside every session that loads it, each doing one thing and nothing else, each off by uninstalling it:

/plugin install loopd-mod-usage@loopd

Every command is namespaced: /loopd:dispatch, /loopd:new-project, and the rest of the table below; so is every role agent — loopd:software-engineer and the rest — because a bare agent name does not resolve. See plugin/README.md.

Installed as ai-bridge@ai-bridge before the rename? MIGRATION.md moves the machine and each bundle over, in order.

Already on ai-bridge-v2? That name is gone in 1.0.0 — the swap.

2. Make the bundle directory

Name it _loopd-<group>, inside the group folder, beside that group's repos.

mkdir -p ~/workspace/<group>/_loopd-<group>

• The leading underscore pins it to the top of the group folder and keeps it visible (unlike a dotfile).
• The -<group> suffix distinguishes it from other groups' bundles.
• The group folder itself is not a repo — just a plain directory holding this bundle plus the group's repos, side by side, each its own repo.
• A bundle created before the rename keeps its _ai-bridge-<group> name: that prefix is still recognised wherever the directory name is read (plugin/scripts/bundle-paths.sh), so nothing has to move.

No clone of this repo is needed. The installer ships in the plugin. /loopd:init creates the directory too, so this step is optional — it is here because naming it right is the part worth doing deliberately.

3. Stamp it

/loopd:init ~/workspace/<group>/_loopd-<group>

It does three things, and none of them is a symlink into a checkout:

It is idempotent. It backs up any conflicting real file as <name>.bak.<epoch>. --refresh-seeds additionally 3-way merges a seed change this repo has made since the bundle was stamped; without it that drift is reported and nothing is written.

This replaced install.sh, and the reason is structural. A plugin-shipped installer cannot stamp absolute symlinks into a plugin cache whose path changes on every update — every one of them would dangle. The symlinks existed so a git pull of this repo propagated into every bundle; claude plugin update gives that property for the whole tree, so they lost their reason to exist. The replaced install.sh and upgrade.sh ship for one version as stubs that print the command to run instead.

It also asks who the team is — once

On a first stamp, at a terminal, it offers to collect the roster: one line per person, <github-login> <commit-email>, yourself first. That fills in the tracked people map and defaultOwner, plus this clone's gitignored instance.config.local.json — the three values a shared bundle needs, which used to be hand-edited afterwards. See docs/sharing.md.

• Nothing is written until you confirm it. ctrl-C, ctrl-D and an empty first line all write nothing at all, and say so — a half-answered roster is never left behind.
• It never asks on a refresh, and never when stdin is not a terminal (a script, a background agent). It prints what to edit by hand instead.
• It never overwrites a value that is already there.
• Skipping costs nothing: fill the same three values in by hand whenever you like.

4. Configure it

cd ~/workspace/<group>/_loopd-<group>
$EDITOR instance.config.json      # org, reposRoot, worktreeRoot, authorEmail

5. Give it a remote

git init && git add -A && git commit -m "chore: bootstrap control panel"
gh repo create <user>/_loopd-<group> --private --source=. --push

Keep the leading underscore in the repo name, so a fresh git clone lands a _loopd-<group>/ directory that matches the convention.

6. Run your first loop

cd ~/workspace/<group>/_loopd-<group>   # this matters — see below
claude

Then, inside the session:

/loopd:new-project add rate limiting to the public API

Answer its questions. Review the draft tasks. Promote the ones you want (draft → ready). Then:

/loop 10m /loopd:dispatch

/loop is Claude Code's own repeat-a-slash-command primitive, and it is the standard way to run the cadence: one pass every ten minutes, in the session you are already in, with nothing installed to drive it. Omit the interval (/loop /loopd:dispatch) on a quiet bundle and the model paces itself. A pass that fires while a tick is still running prints one line and skips — the dispatch lock refuses it, so a clock can never start a second orchestrator. docs/operations.md → "Running the loop on a cadence" has the reasoning.

Always launch Claude from inside the instance directory. The bundle's linked role agents, its SessionStart banner and this panel's CLAUDE.md load from the instance's .claude/, and that is chosen by the working directory — not by what your editor has open. Everything the plugin carries is per machine and resolves anywhere.

The core loop

/loopd:new-project  →  you promote draft → ready  →  /loopd:dispatch  →  you merge the PR

/loopd:dispatch is serial and completion-gated — one tick at a time. Run one per instance. The launcher takes a per-clone lock (.tick-lock) immediately before each dispatch, and the tick runs the same check on entry — a resumed tick never passes through the launcher, so one that finds no lock is refused rather than allowed to run. That guarantee survives a compaction instead of resting on the session remembering it dispatched — →.

Two gates stay yours by default:

1. Promote a task from draft to ready.
2. Merge the PR (build projects) or approve the deliverable (research projects).

The idea is to steer, not watch. Role agents run in the background and bubble up results and questions, not every step.

Both gates can be delegated — see docs/autonomy.md. That capability is off unless installed, literally: it lives entirely in the separate loopd-yolo companion plugin, and uninstalling that plugin makes every project gated again with no other edits.

Who runs what, end to end

One kind: build project, from /loopd:new-project to merge. Every step links to the document that owns its rule; nothing here restates one. Tiers are the seed defaults — each instance sets its own in roleTiers/models (model routing).

HUMAN GATE 1 — you promote the task draft → ready

Nothing is dispatched until you do. The PM refines and critiques a draft but never sets ready (two human authorities).

HUMAN GATE 2 — you merge the PR

One ✗ in that criteria table blocks it, however green CI is (SCHEMA.md).

The next tick reflects the merge — status: done, and the task's worktree is reclaimed.

Commands

Run these inside an instance.

Flags /loopd:new-project accepts: kind=research, autonomy=<mode>, clis="…", browser=off|claude-for-chrome (default off), /yolo, /cli …, /claudeforchrome, --no-commit.

The team

All eight ship in the plugin and are dispatched namespaced — loopd:software-engineer, loopd:qa-reviewer, and so on. A bare agent name does not resolve (measured 2026-09-02). A task's assignee: field stays bare; the PM adds the namespace when it spawns.

Role dispatches are routed to a cost-appropriate model per tier (docs/operations.md § model routing).

Where the work lives

_loopd-<group>/
├── objectives/        OPTIONAL — goals that outlive one project (`/loopd:init <dir> --with-objectives`)
├── projects/<slug>/
│   ├── project.md     kind, status, autonomy, owner, target_repo
│   ├── phases/        ordered stages
│   ├── tasks/         the unit an agent is dispatched on
│   └── deliverables/  research output (no repo, no PR)
├── knowledge/         services, findings, teams, runbooks, references
├── repos/             symlinks to the group's repos (gitignored)
├── AWAITING.md        what needs you (derived, gitignored)
├── SNAPSHOT.json      board input (derived, gitignored)
└── instance.config.json

Document types and their fields: docs/schema.md.

Two kinds of project

A research project is asked less on purpose. Each dropped question describes machinery a research project never runs, so offering it would ask you to authorise tools nothing will use. Don't restore a question for symmetry — docs/conventions.md invariant 5.

Answering the PM's questions

When a draft is blocked it lists numbered open_questions (Q1:, Q2:, …).

1. Open the task doc.
2. Append --- <answer> to the question line: `` Q1: which region should we default to? --- eu-central-1 ``
3. The next tick treats everything after the --- as your answer, folds it into the task, and clears the question.
4. The draft becomes promotable once the list empties.

Answering in chat during a session works too (/loopd:answer).

The cleared entry is moved, not deleted — it lands in answered_questions as one flat line, <ISO 8601> by <login> · <the entry verbatim>. It is a human audit record: nothing reads it and no gate consults it. No customer PII in an answer — unlike the question you clear, this list persists for the life of the repo.

What needs you

AWAITING.md is the instance's one status artifact: a queue of just the items a human decision unblocks.

Each item carries a real link. Every /loopd:dispatch tick rewrites the file, and a SessionStart hook injects its items at launch.

In-flight and upcoming work is deliberately excluded — it needs no decision, and a queue you scroll past is a queue you stop reading. There is no /status command and no full board; don't reintroduce one.

On by default, off by deletion.

Derived and gitignored; never hand-edit it. Reasoning: docs/conventions.md invariant 3.

A cross-instance board is available too, on the same off-by-deletion rule (docs/operations.md § the board). Read the field list before you carry one off the machine — nothing publishes it, but a rendered file is still a file.

Three ways to see the board

One snapshot, four renderers. scripts/write-snapshot.sh derives each instance's SNAPSHOT.json; all four read it and none of them reads the bundle. Pick by what you are doing, not by which is newest.

scripts/print-board.sh                      # columns: instance, project, phases, tasks, awaiting
scripts/build-board.sh --standalone .       # ./board.html — THIS instance only, openable in a browser
scripts/build-board.sh --standalone         # the same, but every instance in boardInstances (see below)
scripts/build-board.sh                      # the same page as a BODY — no <html> wrapper, for embedding
scripts/watch-board.sh                      # ./.board-live/board.html, re-rendered on every change
scripts/board-serve.sh                      # http://localhost:<boardPort> — the same page, served and auto-reloading

The page keeps itself current, locally. Every /loopd:dispatch tick re-renders it to .board-live/board.html — gitignored, on this machine — and reports the path; a SessionStart hook prints the same path when a session starts. board: false in instance.config.json turns that off; absent or true leaves it on, which is the seeded default ([docs/operations.md § rendering it from each tick](docs/operations.