loop-architect

Loop Architect

Design loops and goals the way Boris Cherny does: "Turn workflows into skills, then loop them." Output of this skill = a concrete, copy-pasteable setup (goal contract, loop prompt, or routine prompt) with verification and hard stops — not a vague plan.

Intake rule

Start with a short brief: repeated task, target repo/system/environment, gate command(s), state file/ledger, budget/cadence, tools available, and the stop/escalation condition. Ask one concise proactive question round (max 4 questions) when any of those missing pieces changes the primitive, safety, or verifiability. If enough context exists, proceed with explicit assumptions. If the user is also asking to create work for the factory, pair this skill with define-goal: design the repeat mechanism, then return to a real goal artifact (docs/goals/ entry or run-now command). Do not leave the user with loop advice only.

Step 1 — Qualify (the four-condition test)

A loop pays off only when ALL four hold. Check honestly; if one fails, recommend a plain one-shot prompt instead and say which condition failed.

1. Repeats — the task recurs at least ~weekly (or runs many iterations within one goal)
2. Automated gate — a test / typecheck / build / linter / benchmark can REJECT bad output without a human in the room
3. Budget — the user's plan can absorb retries and re-reads (loops explore and waste)
4. Tools — the agent can run what it changes and see what breaks (logs, dev server, browser extension, simulator, MCPs)

Closed first, open later. Default to the most bounded primitive and scope that still solves the task — a closed loop (defined steps, a gate after each, tight blast radius); widen to a broader open-ended goal only after the gate has demonstrably rejected bad output in practice. Every loop that fails dies one of four deaths — runaway cost, silent death (stands still, pretends alive), aimless drift, or shipping faster than you can review — and all four are cheaper to prevent in a bounded loop than to detect in an open one.

Step 2 — Pick the primitive

Anthropic's official loops guidance ("Getting started with loops") names four loop types; they map onto this table as: turn-based = a plain prompt + verification skills (no loop primitive — Step 1's one-shot answer), goal-based = /goal, time-based = /loop / routines via /schedule, proactive = the no-human-in-real-time compositions (the docs/goals queue + repeated /dispatch, routines/automations, channels — goals, skills, workflows, and auto mode composed in). A user asking for a "proactive loop" over a work stream (bug reports, triage) usually wants the queue row or a routine, not just a channel. (Workflows, agent teams, and Stop hooks below aren't loop types — they're building blocks a loop composes.)

Combos are normal: workflow + /goal for hard completion; skill + /loop for cadence; routine/automation + channel for laptop-closed with phone telemetry.

Workflow thresholds (per platform docs): >5 independent agents or a multi-stage find→verify→synthesize loop → workflow; 2–4 parallel lookups → plain subagents, cheaper and simpler; anything that must survive the session (cross-iteration implementers, multi-day queues) → the docs/goals/index.yaml ledger plus repeated one-goal dispatch runs, never workflow state — workflows are session-bound and don't resume across sessions. Dispatch implementers may use workflows only for bounded read-only fan-out or review inside that one goal, never as parallel code-writing lanes. Agent teams are interactive-session machinery, never a factory lane — dispatch implementers don't spawn teammates. The Workflow tool needs Claude Code ≥2.1.154 and can be disabled; design a plain-subagent fallback for when it's unavailable.

Step 3 — Write the contract

For /goal — six elements, one cap (condition max 4,000 chars)

CRITICAL CONSTRAINT: the /goal evaluator (Claude Code's configured small-fast model — default Haiku, a Claude Code setting) only reads the transcript. It cannot run commands or read files. Every clause must be demonstrable by output the agent prints (test results, exit codes, diffs, counts). Never write taste conditions ("clean", "better", "high quality").

/goal <end state> verified by <command + expected output the agent will print>
while preserving <what must not regress/change>.
Work only within <files/branches/tools boundaries>.
Between iterations, record what changed, what the check showed, and the next best action.
If blocked or no valid paths remain, stop and report attempted paths, evidence, the
blocker, and what would unlock progress.
If the same check fails the same way twice in a row, or after ~3 honest attempts the end
state can neither be reached nor shown measurable (a flaky, non-deterministic, or
contradictory check), declare GOAL_UNREACHABLE: <which clause, why unmeasurable, last
measurement> and stop — never retry the identical failing approach. Before stopping on
success, re-print the final check outputs. Stop after <N> turns.

• Evaluator mechanics that shape the condition (verified against the shipped CLI): the evaluator reads a RECENCY-truncated transcript (roughly the newest half of its context window) and answers "insufficient evidence" when proof may sit in the omitted prefix — hence the template's closing-turn recap of the final check outputs; long runs should also announce "turn N of cap M" so the turn cap stays provable. Its built-in impossible verdict is what honors GOAL_UNREACHABLE — but only with evidence attached (its prompt treats a bare "can't be done" as evidence, not proof). Evaluation is deferred while background tasks/workflows run — the workflow + /goal combo judges only after the fan-out settles.

• Reachability pre-check: before drafting the condition, confirm the end state is one the agent can drive to TRUE and MEASURE — a binary or a threshold it can print — not an asymptote ("every page < 50ms") or an unmeasurable absolute. An unreachable target spins forever; fix the target before writing the goal. Pair it with the GOAL_UNREACHABLE escape hatch above so the loop terminates even when a check turns out flaky in practice.

• Include an explicit outcome taxonomy for queue-like work ("every item ends as fixed | acknowledged-stale | abandoned | blocked-external; 0 items left unclassified") — a missing "blocked" bucket makes the goal bounce forever on reality.

• Prefer two small goals with a checkpoint over one mega-goal.

• Unattended runs: pair the goal with auto mode — auto mode removes per-tool permission prompts, /goal removes per-turn prompts (complementary, not redundant). /goal is a session-scoped Stop hook under the hood: it needs a trusted workspace with hooks enabled (disableAllHooks blocks it, and the command says why).

• If the user's ask is vague, run pre-goal calibration: ask what "done" means until it is specific and measurable, THEN draft the condition for approval. Keep the question round short; derive code-level detail from repo recon instead of asking the user to debug for you.

For /loop — skill-first

1. Confirm the task ran manually at least once reliably. If not, do that first.
2. Put the procedure in a skill (scope, exact checks, allowed actions, FORBIDDEN actions, state-file location, one-line status format per iteration). The loop body is then just /loop 10m /skill-name.
3. Fixed interval for predictable cadence — match it to how often the watched thing actually changes (don't poll a nightly job every 5 minutes); omit the interval to let the agent self-pace (1m–1h based on observed activity; it may switch to the Monitor tool and stream instead of polling); bare /loop uses loop.md if present — project .claude/loop.md beats user ~/.claude/loop.md.
4. Remember mechanics: fires between turns only, 7-day expiry, jitter up to 30m on recurring tasks, Esc cancels a pending iteration, restored on --resume.

For routines (cloud) — fully autonomous, no permission prompts exist

The prompt must be self-contained: what to read, what to do, how to verify, where to write results, what success means, what to escalate. Pushes only to claude/-prefixed branches unless unrestricted pushes were explicitly enabled. Scope repos, connectors

Content truncated.