Agent Loop

A portable, high-bar loop for agentic engineering. Playbooks are copied verbatim. The author of the code does not grade it. Done means correct, maintainable, and verified — not “it compiles,” not “symptom gone,” and not “every step was ticked.”

Inspired by pstack. This is the methodology only: no product repos, no eval catalog, no company branding. Clone it, install it, use it on whatever you are building.

What you get

1. loop-mode — match a playbook (intake, loop, frontend, backend, bug-fix, review, open-pr, …) and copy its steps into todos.
2. Independence — spawn loop-planner, loop-implementer, loop-tester, loop-reviewer. No agent grades its own homework.
3. Proof — a driven page or a real HTTP path, outlined in the reply, bound to the code state you ship.

Install

This machine, every Cursor workspace

git clone https://github.com/Bsoong/agent-loop.git
cd agent-loop
./scripts/install-user.sh

That symlinks this repo to ~/.cursor/plugins/local/agent-loop. Reload the window. Skills, agents, the always-on rule, and the evidence stop hook then apply in whatever you open.

Into one product repo (teammates / cloud agents)

./scripts/install-into-repo.sh /path/to/your-app

That copies skills, agents, hooks, and the always-on rule into your-app/.cursor/. Commit that if the team should share it.

Daily use

/loop-mode fix the empty state on the settings page

Or just start a ticket. The always-on rule routes into loop-mode. Work with real risk (shared contracts, auth, migrations, money, concurrency, broad config) runs the full loop: plan → implement one step → verify → review.

Map your product’s important routes in skills/loop-mode/features/ so verify-frontend has somewhere to look. A template lives there.

Local Chromium

Doctor the origin, sign in once, then screenshot a named route. The CLI lives in this clone — not in the product repo.

pnpm install
pnpm chromium doctor --origin http://localhost:3000
pnpm chromium login  --origin http://localhost:3000 --headed   # wait; you sign in
pnpm chromium shot   --origin http://localhost:3000 --url /settings \
  --out ~/.agent-loop/shots/after.png

scripts/chromium.sh does the same from any cwd. Drive localhost, not 127.0.0.1 — host-only cookies stay on the hostname they were set for. --login-path / AGENT_LOOP_LOGIN_PATH defaults to /login. --session-cookie / AGENT_LOOP_SESSION_COOKIE waits for a named cookie.

Do not run ./scripts/install-user.sh on a machine that already has a differently named company loop plugin if you intend that plugin to stay the only always-on loop. This installer only links ~/.cursor/plugins/local/agent-loop and does not overwrite a sibling plugin directory.

Layout

cli/chromium.ts            generic doctor → login → shot / hover / click
skills/loop-mode/          router + playbooks + quality refs
skills/prove-it/           done-gate
skills/verify-frontend/
skills/verify-backend/
skills/control-ui/         local browser proof (screenshots to ~/.agent-loop/shots)
scripts/chromium.sh        doctor → login → shot / hover / click
skills/split-pr/
skills/review-pr/
skills/pre-pr-review/      Bugbot + Security Review + review-pr before submit
skills/capture-thread-learning/
skills/loop-standards/     quality bar + independence rules
agents/                    planner, implementer, tester, reviewer
docs/                      code-quality, loop-learnings, lifecycle, measurement template
hooks/                     worktree seed + stop hook (outline proof; never write evidence.json)
scripts/                   install-user / install-into-repo / local git hooks

Principles (always on)

• Risk, not file count, selects the ceremony. Low / Moderate / High by affected consumers, behavioral impact, uncertainty, reversibility. A one-line config or authorization change is never Low.
• Verify the contract before depending on it. Read the actual props, signatures, callers, and the resolved package version. Never invent a prop, API, default, or fallback.
• Ask before widening behavior, a public contract, a dependency, or architecture — before the edit.
• Every finding ends fixed, disproven with evidence, deferred with your explicit acceptance, or open. A promised follow-up PR is not a fix.
• PRs ≤500 changed lines (excluding generated, lockfiles, vendored), measured against each PR’s own base. Mergeability outranks the cap for a genuinely atomic change.
• Never write .agent-loop/evidence.json (or any evidence file) into a product repo. Outline proof in the reply. Screenshots go to ~/.agent-loop/shots/ or the chat.

Env

Variable	Role
AGENT_LOOP_ROOT	Override the clone path if it is not where the plugin symlink points
AGENT_LOOP_ORIGIN	Default origin for pnpm chromium (default http://localhost:3000)
AGENT_LOOP_SHOTS_DIR	Where browser screenshots go (default ~/.agent-loop/shots)
AGENT_LOOP_CHROMIUM_PROFILE	Persistent Chrome profile for local Playwright
AGENT_LOOP_STORAGE_STATE	Playwright storage-state JSON after login
AGENT_LOOP_SESSION_COOKIE	Optional cookie name that login waits for
AGENT_LOOP_LOGIN_PATH	Path treated as the auth wall (default /login)

License

MIT. Use it wherever.