🔁 Awesome Autoloop

An opinionated 5-agent pipeline + enforcement-hook framework for Claude Code.

It blocks some of your actions on purpose — and documents every single one.

 ·   ·  version 1.0.0  ·  for Claude Code (Agent Teams)

---

Awesome Autoloop turns Claude Code into a disciplined software team. Work flows through a fixed 5-agent pipeline, and a layer of enforcement hooks holds the line — blocking a Co-Authored-By commit, an unreviewed merge, a developer dispatched before a spec exists, and ~30 other footguns. The gates are honest: every action a hook can block is in the trust table, and every gate no-ops in any repo that isn't an autoloop project — your unrelated work is never touched.

What you get

• 🤖 A 5-agent pipeline — planner → plan-reviewer → architect → developer → code-reviewer — wired as Claude Code Agent Teams, with role gates that keep the order honest.
• 🛡️ ~30 enforcement hooks in 5 toggleable groups — commit hygiene, pipeline roles, merge gates, ledger hygiene, and post-merge "definition of done" walks. Deny-gates fail closed; nag-gates fail open.
• 🧩 Yours to adapt — the hooks + agents mount read-only from the plugin; an interactive installer copies an editable CLAUDE.md framework + rules + a task-board template into your own .claude/.

   you ─▶ planner ─▶ plan-reviewer ─▶ architect ─▶ developer ─▶ code-reviewer ─▶ merge
            │            (Mode A)         │            │            (Mode B)        │
            └──────────────────── enforcement hooks gate every step ───────────────┘
              commit-hygiene · pipeline-roles · merge-gates · ledger-hygiene · dod-walk

🚀 Install

/plugin marketplace add suhang56/awesome-autoloop
/plugin install awesome-autoloop@awesome-autoloop
/awesome-autoloop:install

1. registers this repo as a marketplace · 2. installs the plugin (hooks + agents + skills mount automatically) · 3. runs the interactive installer that copies the editable framework templates into your .claude/ and lets you choose which gate groups to enable. The third command is idempotent — re-run it any time.

Prerequisite — Agent Teams. The 5-agent pipeline needs Claude Code Agent Teams. The installer sets CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your settings.json env on --apply (set it by hand if you skip the installer). You pass any team_name string in the Agent() call — there is no separate TeamCreate step (TeamCreate was removed in Claude Code v2.1.178). Without the env var, teammate dispatch fails and the block-bare-agent gate dead-ends every spawn.

Two halves to turn it on. The installer wires the gate half (hooks + the activation marker). You turn on the drive half: the Agent-Teams env var above plus an autonomous/auto driving posture (a standing goal + non-per-action permission) so the pipeline actually loops. Agent Teams alone leaves the team idle — see docs/QUICKSTART.md.

Every enforcement hook is a .sh script, so it needs bash. Install Git for Windows before anything else — without git-bash, bash itself is absent and every hook is silently inactive, and no hook can warn you (bash can't run to detect its own absence). This is the one degradation the plugin can't surface at runtime. On macOS/Linux bash is native — skip this.

▶️ Run your first wave. The installer drops an empty .autoloop marker in your .claude/ (the activation anchor) and copies the editable templates. For a spec-to-merge walkthrough of one wave through the gates, read docs/QUICKSTART.md.

🛡️ The trust model

This framework can block your tool calls. That power is the point — and so is the honesty about it. Three things make it safe to install:

1. Every blockable action is documented. The full per-hook table is below. deny = the hook blocks the call (fail-closed); warn = it only emits a message, never blocks (fail-open).
2. It no-ops outside your autoloop projects. Hooks mount globally, but a node-free guard runs first in every gate and exit 0s unless the repo is autoloop-managed (see activation model). A git commit in an unrelated repo is never touched.
3. You choose what's on. The 5 gate groups are toggled at install (and via the AAL_GATES env var after). Don't use GitHub PRs? Deselect merge-gates.

⚠️ Two hooks delete directories. roster-tripwire and block-spawn-over-roster-cap prune harness team dirs under ~/.claude/teams/ that are untouched for >2 days (to clear stale-roster false-positives) — only dirs that look like a dead harness team (a config.json + mtime >2d), and only inside an autoloop project. They never touch your files.

Stop tier runs through one mount. Every Stop row is invoked by the single stop-dispatcher mount, which runs them in one process, merges all block reasons + all warns into ONE turn-end block message, and fails OPEN if node is absent. The per-check behaviors are unchanged — only the delivery is consolidated.

commit-hygiene · needs: bash, node, git · ON by default · fail-closed (these BLOCK a bad commit)

Hook	Event / matcher	Fail mode	Denies / warns	Deps
block-coauthor-commit	PreToolUse / Bash	deny	Blocks a git commit whose message contains a Co-Authored-By trailer. Parses the full command via node so a quoted/heredoc message can't smuggle the line past a naive grep.	bash, node
enforce-conventional-commit	PreToolUse / Bash	deny	Blocks a git commit whose message isn't type(scope)!: description (feat|fix|refactor|docs|test|chore|perf|ci|build|style). Parses the command via node (sources lib/parse-json.sh); skips messages built via $(...)/heredoc it can't introspect.	bash, node
block-claude-dir-commit	PreToolUse / Bash	deny	Blocks a git commit/push while .claude/ is staged — keeps your private config out of git. Parses the full command via node and honors the last cd <dir> anywhere in the command (resolves the right repo for compound/worktree forms).	bash, node, git
block-compound-commit-push	PreToolUse / Bash	deny (fail-OPEN)	Blocks one Bash call that compounds git add/git commit with git push/gh pr merge (via &&/;/|). If the gated push/merge is later denied, the WHOLE compound fails and the earlier commit silently doesn't run — so split them. A footgun-preventer, not a security gate: node-absent → no-op (allow).	bash, node
block-pnpm-install-in-main	PreToolUse / Bash	deny	Blocks a pnpm install/i/add/up/update targeting the shared main checkout (an aborted install there wipes node_modules/.pnpm + bins). No-ops unless AAL_MAIN_REPO is set; a worktree install (AAL_WORKTREE_ROOT) is allowed; append # ALLOW_MAIN_INSTALL for a deliberate lead recovery.	bash, node
block-cleaned-data-commit

pipeline-roles · needs: bash, node, git · ON by default · mixed (deny for role gates, warn for reminders)

Hook	Event / matcher	Fail mode	Denies / warns	Deps
stop-dispatcher	Stop	warn	The single Stop mount. Runs every consolidated Stop check (the 9 Stop rows across the groups) in one process: drains stdin once + feeds each, isolates a crashing check, normalizes both block wire-forms, and merges all reasons + warns into ONE decision:block Stop JSON (warns folded into the reason). Always emits + exit 0; node-absent → every child no-ops (fails OPEN). Edit its one-line CHECKS=( … ) registry to add/remove a check.	bash, node
block-bare-agent	PreToolUse / Agent	deny	Blocks a bare Agent spawn without a team_name, and a pipeline-role spawn missing a name or set run_in_background:true (a mailbox-less one-shot).	bash, node
validate-agent-type	PreToolUse / Agent	deny	Blocks a subagent_type outside the allowed set (the 5 pipeline roles + Explore/general-purpose).	bash, node
block-non-codereviewer-mode-b	PreToolUse / Agent	deny (default-allow)	Blocks a Mode-B / PR code-review dispatched to anything other than code-reviewer. Narrow trigger; default allow.	bash, node
block-spawn-over-roster-cap	PreToolUse / Agent	deny	Blocks a new teammate spawn once the live roster hits the cap (AAL_ROSTER_CAP, default 16) — forces shutdown-of-done before spawn.	bash, node
enforce-planner-first	PreToolUse / Agent	deny	Blocks a developer spawn for feature work when no recent spec exists in docs/product-specs/. Bug-fix team names (fix/bug) skip it.	bash, git
block-backlog-status-drift	PreToolUse / Write|Edit|MultiEdit	deny	Blocks writing a non-whitelisted ### [STATUS] (or a bare ✅/DONE/MERGED badge) onto an active ; a done card belongs in . Fail-OPEN on a parse error.