Skip to content

AGENTS.md

Latest commit

 

History

History
52 lines (39 loc) · 2.65 KB

AGENTS.md

File metadata and controls

52 lines (39 loc) · 2.65 KB
Raw

loop-lab

Sandbox for the Finn loop — a spec/build/review AI software factory. Every feature here is built BY the loop (human-gated), never hand-coded. This repo is the testbed that graduates the loop into real repos later.

Stack: Next.js 16 App Router · TS · Tailwind · bun. Commands: bun run typecheck / bun run build / bun run dev.

The loop contract

Flow: idea → /finn-spec interviews you and files a GitHub issue → a HUMAN applies the agent-ready label → /loop /finn-build claims it (self-assigns @me) and opens a PR → /loop /finn-review posts a Finn-loop review of <SHA> verdict + labels → a HUMAN merges in the GitHub UI (issue auto-closes via Closes #N).

Labels (the whole state machine):

Scope Label Meaning
Issue agent-ready human-approved, ready to build (humans-only apply)
Issue blocked builder hit an open question; unassigned + comment
PR loop-approved review passed
PR loop-changes-requested review found fixable issues
PR needs-human-review review needs a human call

Hard rules:

  • Humans merge, always. Skills never run gh pr merge.
  • Only humans apply agent-ready. /finn-spec files the issue unlabeled.
  • One pass = one unit of work. Don't batch issues or bundle scope.
  • Specs carry AC-N (observable acceptance criteria) + NG-N (binding non-goals).
  • Branch naming issue-NNN-slug; PR bodies carry the scope ledger incl. the literal line Other behavior changes: None.
  • Only ONE builder loop at a time — never run parallel /finn-build.

Slack lane

Notify-only to #loop-lab (merge-ready PRs + blocked questions), best-effort. When the Slack MCP is absent (headless), skills print [slack-degraded] and continue — merge-ready discovery falls back to gh pr list --label loop-approved. Slack is a control surface, never state.

Operating rules

  • Loop sessions run on Opus — Gian sets /model opus before /loop; skills don't pin models.
  • No secret values in any file — .env.local (gitignored) + the Keychain rail only.
  • Loop labels are factory state, not personal tasks — no ClickUp coupling.

Graduation checklist (installing the loop into a real repo)

  1. Acceptance test passed here (specced → built → reviewed → merged with zero manual edits).
  2. Target repo has the required CI check on its default branch; the 5 labels created there.
  3. settings.json allowlist + Stop hook adapted to the target's script names.
  4. Loop section APPENDED to the target's existing AGENTS.md (never replace).
  5. One watched build+review pass observed before any unattended /loop.