| name | agent-loop |
| description | Generic epic-to-PR agent workflow (codename Forge) with 4-phase execution, a 6-tier hierarchy, and paired-team fan-out. Use when coordinating any feature delivery, working an issue or epic ("work epic <id>", "work issue <id>", "use Forge on the next bees ready item", "forge <id>"), picking up an epic in a fresh session (decomposing path) or with pre-existing issues (dispatching path), implementing a multi-step task that benefits from plan→test→implement→review phases, asking clarifying questions before decomposing, forming a team and assigning models per tier, or orchestrating multi-agent workflows. Loads on casual feature requests too — not only when the word "epic" appears. |
| license | MIT |
Agent Loop
Defines the standard workflow for agents working epics, issues, and tasks through a 4-phase execution model with a 6-tier prompt hierarchy.
Forge — the default operating model
Forge is the name for how this skill works an issue: paired teams of strong-model principals and cheap read-only hands, fanned out across the issue's slices, with reviewers on the best-thinker model. Forge is the implied default for all work — the lead applies it without being told to "use the 5/6-tier system."
Activate Forge by work phrasing ("work epic/issue ", acting on bees ready), by forge <id> in a mission / spawn prompt, or by the /work command in an interactive session — all load this skill and run Forge on the target.
Two disciplines make Forge cheap and reliable:
- Hands do the searching. Principals (planners, reviewers) never run their own
Grep/Glob/large-Read sweeps. They spawn focused read-only hands on the smallest fast model, receive a file:line index, and Read only those lines. See references/researcher.md.
- Paired teams fan out. Every issue runs the same paired structure; fan-out width
N = the planner's slice count (N=1 for a small issue, same path). See references/forge.md.
Required plugins
Assumes both core@vinnie357 (this plugin) and claude-code@vinnie357 (agent/team file formats, referenced by name in spawning steps) are installed. Standalone core still describes the workflow, but cross-plugin skill names like /claude-code:claude-agents won't resolve until claude-code@vinnie357 is installed too — treat those references as procedural-only until then.
4-Phase Execution
Every agent, regardless of tier, follows these four phases:
| Phase | Name | Purpose |
|---|
| 1 | Pre-flight | Load skills, check tracker, verify branch, understand assignment |
| 2 | Working | Execute work items. Before any spawn: re-verify core skills loaded, load /claude-code:claude-agents always, load /claude-code:claude-teams for ≥2 parallel workers. |
| 3 | Validation | Run strictest CI suite, iterate with fix agent until clean |
| 4 | Submit | Create PR, wait for CI, report to upstream, clean up after merge |
Phase 1.5: Decomposition Gate
Between Phase 1 (pre-flight) and Phase 2 (spawn), the Team Leader checks two deterministic signals — no file searching:
- bees:
bees list --epic <slug> — does the epic already have issues?
DECOMPOSITION_PATH env var: is it set AND does the file it points at exist? This is the canonical signal an upstream process sets to hand off a pre-computed proposal.
| State | bees | DECOMPOSITION_PATH | Action |
|---|
| A | Has issues | Unset, OR set+missing | Skip Phase 1.5a. Spot-check each issue (AC, skill labels, dep edges). Flag gaps, proceed. |
| B | Empty | Unset, OR set+missing | Run Phase 1.5a — produce the decomposition from the epic objective + AC, record assumptions, decompose into bees. Ask only on a genuine fork or hard blocker. |
| C | Empty | Set + file exists | Consume the proposal verbatim — bees create one issue per proposed item with AC, skill labels, and dep edges as written. Topological order (deps before dependents); map depends_on titles to bee IDs returned by prior bees create calls as you go. If any cycle is detected in the dep graph (2-cycle X↔Y, 3-cycle A→B→C→A, or longer), halt and report all cycle members — create zero issues. No clarifying questions. Spot-check after, proceed. |
| D | Has issues | Set + file exists | Resume gap — diff proposal titles vs existing bees titles. Materialize each missing proposed item with the same rules as State C (topological order, cycle detection). Spot-check the complete set, proceed. Never re-ask, never re-decompose. |
Robustness:
- Empty string (
"") for DECOMPOSITION_PATH = unset — no log, proceed as State A or B per the bees-state column.
- Set but file missing: emit exactly one line —
agent-loop: DECOMPOSITION_PATH=<value> not found; proceeding as State <B|A> (B if bees empty, A if bees has issues). No retry, no search, no crash.
- Never search for proposal files outside
DECOMPOSITION_PATH. Unset or empty = no proposal, full stop.
Proposal file format: this skill mandates only the consumption rules above; the file's on-disk schema is defined by whatever upstream process produces it. A minimum interoperable shape is a JSON array of issues each carrying title, acceptance_criteria (list), labels (list), and depends_on (list of titles or stable local keys that resolve to other entries in the same file).
Phase 1.5a: Default to proceeding (State B only)
Plan presence, not who is at the keyboard, is the operative question. A plan is PRESENT when DECOMPOSITION_PATH is set and the file exists, OR bees already has issues, OR an upstream proposal exists. States A / C / D are plan-present — consume, spot-check, or resume and proceed; never ask clarifying questions there.
State B is plan-absent: the lead PRODUCES the decomposition from the epic objective and acceptance criteria, records assumptions as a bees comment (audit trail), and proceeds on the most reasonable interpretation.
Reserve AskUserQuestion for a genuine architectural fork the user owns that can't be responsibly defaulted, or a hard blocker: missing repository, missing credential, or contradictory acceptance criteria with no clear winner. A preference question — "approach A or B?" — is NOT a blocker; pick the reasonable default, record it, proceed.
When escalating, group related questions into a single AskUserQuestion call (max 4 questions, 2–4 options each) — never one at a time. Once a decision is judged a genuine fork the user owns, ask rather than guess. Doesn't apply to single-file mechanical refactors, status checks, or log diagnosis.
Applies in every context: a host running without a human supplies the plan (State C fires); with no plan, the default is still proceed-on-reasonable-default.
6-Tier Prompt Hierarchy
These six tiers describe authority — who reports to whom across an epic. For the orthogonal axis of how a single issue flows through staged agents, see "Five-Tier Decomposition Pipeline" below.
| Tier | Role | Scope | Default Model | Reference |
|---|
| 0 | Epic Author | Write machine-executable epics | human | references/epic-authoring.md |
| 1 | Team Leader | Four-state gate (spot-check / consume proposal / ask+decompose / resume gap); spawn agents | opus | references/team-leader.md |
| 2 | Sub-team Leader | Decompose issue into tasks, manage workers | sonnet | references/sub-team-leader.md |
| 3 | Agent Worker | Execute a single task with TDD | haiku | references/agent-worker.md |
| 4 | Validator | Run CI, report all failures, never fix | haiku | references/validator.md |
| 5 | Fix Agent | Receive failures, fix code, re-run tests | haiku | references/fix-agent.md |
Model overrides (env-var convention)
Model defaults per tier are exactly that — defaults. Each tier honors an env var so a deployment can swap models when a new family ships, without changing the spawn script (12-factor config):
| Tier | Env var | Default |
|---|
| 1 Team Leader | AGENT_LOOP_LEAD_MODEL | opus |
| 2 Sub-team Leader | AGENT_LOOP_SUBLEAD_MODEL | sonnet |
| 3 Agent Worker | AGENT_LOOP_WORKER_MODEL | haiku |
| 4 Validator | AGENT_LOOP_VALIDATOR_MODEL | haiku |
| 5 Fix Agent | AGENT_LOOP_FIX_MODEL | haiku |
| Research hands (text) | AGENT_LOOP_HANDS_MODEL | smallest fast model (Explore) |
| Research hands (vision) | AGENT_LOOP_HANDS_VISION_MODEL | a multimodal-capable model the harness offers |
The two hands vars follow the same contract as the tier vars: the launching process resolves them and passes the model to the spawn; no model name appears as a literal in the prompt body. The vision var is set by capability, not by a fixed name — the available multimodal model shifts with the harness and model family. See references/researcher.md.
Contract: whoever launches the spawning process (shell command, CI job, parent Claude session, external orchestrator) sets these env vars; the spawn script reads $AGENT_LOOP_* and passes the resolved model to the Task tool invocation (subagent_type/model argument) — never as a literal in the prompt body. An empty string (AGENT_LOOP_LEAD_MODEL="") is treated identically to unset, falling through to the default, so orchestrators can emit "" to mean "use default" without special-casing.
The escalation chain is also overridable: AGENT_LOOP_ESCALATION_CHAIN (comma-separated names; default haiku,sonnet,opus).
Model Escalation
Default assignment starts at haiku. On repeated failure (2 attempts on same work item):
haiku -> sonnet -> opus
Maximum 2 promotions per agent. If opus fails, escalate to the upstream tier (sub-lead to lead, lead to user).
Five-Tier Decomposition Pipeline
The 6-tier hierarchy above describes WHO reports to whom (authority). The five-tier pipeline below describes HOW one work item flows through five sequential agents (process). They are orthogonal: a Sub-team Leader (tier 2 authority) dispatches a pipeline (process) to deliver one issue.
The five roles below are the linear N=1 form; Forge (references/forge.md) is the canonical shape that generalizes them to paired teams and N-slice fan-out, with identical role-to-model defaults and adversarial separation.
For each issue, the Sub-team Leader spawns distinct Agent invocations in order. No shared context across stages — each stage is adversarial against the next.
| Pipeline Stage | Model | Responsibility | Forbidden |
|---|
| P1 Test Planner | opus | Translate acceptance criteria into ordered test list + edge cases | Writing code or tests |
| P2 Test Author | sonnet | Write failing tests against P1's spec | Reading impl source; modifying after handoff |
| P3 Implementer | sonnet | Make tests pass | Modifying test files; reading P2's chat context |
| P4 CI Runner | haiku | Run CI, capture verbatim output, report green/red | Judging correctness; touching code |
| P5 Reviewer | opus | Verify tests exercise AC, no overfit, no missed edges | Authoring fixes (sends back to P2 or P3 with findings) |
Each stage owes the restraint ladder its phase duty — see /core:restraint's agent-loop-phases reference for the row mapping (P1 → Test planning, P2 → Test authoring, P3 → Implementation, P5 → Review).
When to apply
Apply for multi-file changes, public API surfaces (HTTP/exported/schema), cross-repo work, or any issue carrying explicit acceptance criteria. Single-agent stays acceptable for one-liners, mechanical refactors, status checks, and log diagnosis. When in doubt, decompose.
Fan-out happens at the Sub-team Leader, not at the epic decomposer or the bees-worker. Decomposition produces one bees issue per slice; the leader picking up the issue is the one that spawns the five stages.
Orchestration rules
- Each stage is a separate Agent invocation (no SendMessage continuations between tiers).
- The leader verifies stage transitions before dispatching the next: test commit present before P3, test files unmodified before P5.
- P4 reports verbatim CI output; on red the leader dispatches a fresh P3 (no chat continuity).
- P5 reads
git diff main...HEAD, tests, and the acceptance criteria; approves with one line or rejects with a structured findings list. P5 reviews per /core:code-review, including its Restraint and Scope checklist item.
- bees issues carry a single
complexity:complex or complexity:trivial label, not tier labels. The Sub-team Leader picks up the issue, reads complexity, and (for complex) dispatches the five stages internally — each Task spawn prompt names its tier (team:opus-planner ... team:opus-review) as dispatch-time metadata. Tier labels never land on bees rows. See /core:bees.
- The five stages run as Task spawns by default. When Claude Code workflows are available and the operator opts in, encode them as one workflow script instead — the stage gates become deterministic assertions. See "Optional: workflow execution substrate" below and
references/workflows-execution.md.
Avoiding pipeline collapse
Single agents tend to merge planning + test-writing + implementation into one pass, defeating the adversarial separation. The leader prompt MUST explicitly name the stage (You are P2 — test author for issue <id>) and forbid out-of-stage activity.
Delegated research — the hands pattern
The costly principals (Test Planner, Test Reviewer, Reviewer, Final Reviewer) delegate all search to hands (see the Forge disciplines above). Select the hands model by capability, set in config — never a hardcoded name: text and code research use the smallest fast model (AGENT_LOOP_HANDS_MODEL); research that requires vision (images, screenshots, rendered web pages, visual PDFs, Playwright or visual MCP output) uses a multimodal-capable model the harness offers (AGENT_LOOP_HANDS_VISION_MODEL). Full contract in references/researcher.md; references/dispatch-discipline.md carries the delegate-before-you-search rule.
Core Skills (Mandatory)
Every agent at every tier loads these before any work:
/core:anti-fabrication
/core:git
/core:tdd
/core:twelve-factor
/core:restraint
/core:security
/core:mise
/core:nushell
/core:agent-loop
/core:bees
This block is the canonical copy. test/validate-core-list.nu drift-checks it against the eight sites it lists — this skill, four tier references, /core:work, the core session-start hook, and the operator CLAUDE.md template. Other files that enumerate core skills are not covered; add a site to that script when it starts carrying the full stack.
Domain-specific skills activate from their own Use when descriptions — that is the discovery mechanism at every tier. Two rules descriptions cannot express:
- Tracker state: a repo tracked by beads loads
/core:beads in place of /core:bees.
- Issue labels: load the domain-plugin skills named by the issue's labels, by exact name.
Enforcement, not description, carries a third rule: leaders name every skill explicitly in the spawn prompt's ## Load skills block — globs do not expand, and listed is not loaded.
Skills to load before spawning
When a leader (Tier 1 or Tier 2) prepares to spawn an agent, load these by exact name with the Skill tool:
/claude-code:claude-agents — always. Carries agent file format, tool allowlists, and model selection./claude-code:claude-teams — if forming a team or spawning ≥2 parallel workers. Carries peer-to-peer messaging, shared task list, Agent SDK patterns./claude-code:plugin-marketplace — when the spawned agent needs a skill not already in the team's load list.
Glob patterns like /core:* do not expand in Agent prompts. List skill names explicitly.
Key Conventions
- Tracker: Use bees (
bees ready, bees close) for issue management
- Commits: Conventional commits, no attribution, no Co-Authored-By
- PRs: Minimal format (title + bullet list), no templates, no attribution
- TDD: Code without tests is not complete
- CI (dual gate): Gate 1 — local
mise run ci green before every commit; Gate 2 — local + remote gh pr checks green before any squash merge (see /core:git Dual-Gate CI Policy)
- Branches: One feature branch per epic (
feature/<epic-slug>)
- Merge: Squash merge only, user approves
Agent Worker Execution Order
Every agent worker (Tier 3) follows these steps:
- Create feature branch
- Write tests first (TDD)
- Implement
- Gate 1 — Run local CI (
mise run ci) — fix until 0 failures
- Commit without attribution
- Run gitleaks scan on committed changes — fix if secrets detected
- Push, create PR
- Gate 2 — Watch remote CI (
gh pr checks --watch) — fix and push until local + remote are green (merge-ready)
- Close bees issue, notify leader of PR status and URL
Agents never merge — they report the PR URL to the team leader.
Agent Prompt Template
Team leaders structure agent prompts with these sections:
## Load skills
<every name from "Core Skills (Mandatory)", one per line — never this placeholder, never a glob>
<domain skills for this task, per the issue's labels and the tracker-state rule>
## Working directory
cd /path/to/repo
## Bees issue
<issue-id>: <title>
## Context
<what exists, what's needed, why>
## What to implement
<specific files, existing functions to reuse, code patterns>
## Rules
<project-specific constraints>
## Execution order
<the 9 steps above>
Canonical list: /core:agent-loop "Core Skills (Mandatory)"; drift-checked in CI.
Key: always reference existing code and functions to reuse. "Implement X" is vague — "add import/2 action to WorkflowController, reuse serialize_workflow/1 from line 28" is machine-executable.
Proof of loading
Require each spawned agent to quote one sentence from each loaded skill in its first response. Do not proceed with the agent's work until proof is received. Listing skill names in the prompt is not the same as the agent loading them — proof prevents skipped loads.
Leader spawn — concrete example
See references/leader-spawn-example.md for a worked Phoenix-endpoint Task-tool prompt. The mandatory /core:* skill list at the top of any spawn prompt is enumerated in "Core Skills (Mandatory)" above — never use globs in spawn prompts (they don't expand).
Model Selection
Scale the team to the work — choose by role, not by a trivial-vs-complex guess:
| Role | Model | Examples |
|---|
| Multi-file implementation | sonnet | New API endpoint, adapter refactor |
| Test planning, architecture design | opus (or Plan subagent) | Test-list design, system integration |
| Simple ops, monitoring, status checks | haiku | Deploy monitor, log reader, port check |
Hands and reviewer models follow the Forge convention — see "Model overrides" above and references/forge.md.
Secret Safety
Agents must NEVER read, print, or report actual secret values (API keys, tokens, passwords). Only confirm secrets exist and are non-empty:
op item get "KEY" --vault Vault --fields credential --reveal
test -n "$(op item get KEY --vault Vault --fields credential 2>/dev/null)" && echo "set" || echo "empty"
Tool Preferences
- JSON parsing: Use
jq, not python3 -c "import json..."
- Scripting: Nushell (
.nu), not bash — cross-platform, structured data
- Infrastructure: parameterized workflow tools, not direct SSH
- Tool management: mise, not brew — portable across macOS and Linux
- Issue tracking: bees, not beads
The Layered Model
- Epic -- what the user writes. Objective, skills, constraints. No implementation details.
- Issues -- created by team leader. Independently deliverable slices with acceptance criteria.
- Tasks -- created by agents. Granular implementation steps, invisible to the user.
Usage
Load the reference matching your assigned role:
Team Leader -> Read references/team-leader.md
Sub-team Leader -> Read references/sub-team-leader.md
Agent Worker -> Read references/agent-worker.md
Validator -> Read references/validator.md
Fix Agent -> Read references/fix-agent.md
Epic Author -> Read references/epic-authoring.md
Spec-Driven Epics (optional)
Epics may include a spec: field pointing to a .allium behavioral spec file (e.g., spec: docs/specs/<epic-slug>.allium). When present:
- The team leader checks for the spec in Phase 1. On a refactor epic without a
spec: field, run /allium:distill to derive a baseline spec from existing code before decomposition.
- Agent workers invoke
/allium:propagate to seed failing test skeletons before implementation.
- The validator invokes
/allium:weed after CI passes to flag spec/code divergence.
Epics WITHOUT a spec: field behave exactly as today — all spec-driven steps are no-ops. Requires the upstream allium plugin: /plugin install allium@juxt. See /allium:allium for full integration details.
Optional: workflow execution substrate
Claude Code dynamic workflows are an optional runtime for the five-tier pipeline. When available and opted-in, the Sub-team Leader encodes one issue's pipeline as a workflow script instead of dispatching five Task spawns — the adversarial separation and stage gates (test files unmodified before P5, mise run ci green before review) become deterministic script assertions, model escalation becomes a retry ladder, and the validator↔fix iteration becomes a bounded loop. isolation: 'worktree' gives each parallel implementer its own tree, replacing the shallow-clone workaround for working-tree contention.
The boundary: decomposition, any Phase 1.5a escalation (the rare fork-or-blocker AskUserQuestion), and merge approval stay in the interactive loop — a workflow has no mid-run user input. The workflow executes already-decomposed issues (gate States A/C/D); it never decomposes them.
The Forge shape encodes the same way at larger fan-out: templates/forge-issue.workflow.js is the runnable /forge-issue workflow — a startup-index hands pass per principal, planner slicing, dep-wave parallel() implementor + test-runner fan-out, and the remediation pair.
Workflows are a research preview on paid plans. When disabled, the default Task-spawn path applies unchanged. See references/workflows-execution.md and the /claude-code:claude-workflows skill.
References
references/forge.md -- The Forge operating model: paired teams (principal + cheap hands), implementation fan-out (N pairs by slice), reviewers as the best-thinker tier, startup-index handoff, gates between pairsreferences/researcher.md -- The hands pattern: read-only focused research, startup vs on-demand modes, the file:line index output contract, capability-based AGENT_LOOP_HANDS_MODEL / AGENT_LOOP_HANDS_VISION_MODEL selectionreferences/team-leader.md -- Epic decomposition, team formation, orchestrationreferences/sub-team-leader.md -- Issue decomposition, worker management, model escalationreferences/agent-worker.md -- Task execution with TDD, skill loading, reportingreferences/validator.md -- Strictest CI per language, structured failure reportingreferences/fix-agent.md -- CI failure remediation, test fixing, escalationreferences/epic-authoring.md -- User guide for writing machine-executable epicsreferences/leader-spawn-example.md -- Worked Phoenix-endpoint Team Leader spawn prompt with explicit /core:* + /elixir:* skill listreferences/dep-doc-introspection.md — Staged-pipeline prompts name the runtime-introspection tools AND the specific deps touched, never abstract "use the introspection tools"references/no-todos.md — Implementer prompts ban TODO/FIXME/XXX/HACK/KLUDGE/DEFERRED markers, enforced by pre-commit grep; tempted workers escalate-or-implement-now instead of punting scope via a commentreferences/dispatch-discipline.md — Spawn-prompt rules: explicit model, specialized subagent types, lead delegates all execution, fresh-main branch creation, no polling, host-inspection over claims, ADR search before proposing architecturereferences/secret-provisioning.md — Tier 1 plans include symmetric secret provisioning (generation, store creation, prod/dev deploy diffs); Tier 5 blocker checkreferences/workflows-execution.md — Optional workflow substrate for the five-tier pipeline: pipeline-as-script, stage gates, escalation ladder, teams-of-teams; decomposition/merge stay interactivetemplates/five-tier-issue.workflow.js — Runnable N=1 five-tier pipeline template: stage prompts, skillProof schemas, diff-boundary gate, escalation ladder, bounded fix looptemplates/forge-issue.workflow.js — Runnable Forge workflow: startup-index hands, planner slicing, dep-wave fan-out, opus reviewers with haiku hands, remediation pair
