agent-loop

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.

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 assigned work items, report progress, escalate blockers
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

6-Tier Prompt Hierarchy

Tier	Role	Scope	Default Model	Reference
0	Epic Author	Write machine-executable epics	human	references/epic-authoring.md
1	Team Leader	Decompose epic into issues, spawn agents	sonnet	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 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).

Core Skills (Mandatory)

Every agent at every tier loads these before any work:

/core:anti-fabrication
/core:git
/core:tdd
/core:twelve-factor
/core:security
/core:mise
/core:nushell

Domain-specific skills load based on issue/task labels.

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: mise run ci must pass before any PR or merge
• 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:

1. Create feature branch
2. Write tests first (TDD)
3. Implement
4. Run local CI (mise run ci) — fix until 0 failures
5. Commit without attribution
6. Run gitleaks scan on committed changes — fix if secrets detected
7. Push, create PR
8. Watch remote CI (gh pr checks --watch) — fix and push until passing
9. 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
/core:anti-fabrication
/core:git
/core:tdd
/core:security
/core:mise
/core:nushell
<domain-specific skills based on task>

## 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>

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.

Model Selection

Choose the initial model by task complexity:

Task Type	Model	Examples
Multi-file implementation, design decisions	sonnet	New API endpoint, adapter refactor
Simple ops, monitoring, status checks	haiku	Deploy monitor, log reader, port check
Research, codebase exploration	Explore subagent	Pattern discovery, ADR review
Architecture design	Plan subagent	API design, system integration

Default to haiku. Use sonnet when the task requires judgment across multiple files or architectural decisions. The escalation path (haiku → sonnet → opus) applies when an agent fails twice on the same work.

Secret Safety

Agents must NEVER read, print, or report actual secret values (API keys, tokens, passwords). Only confirm secrets exist and are non-empty:

# WRONG — exposes the secret
op item get "KEY" --vault Vault --fields credential --reveal

# RIGHT — confirms it's set without exposing
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: Runex workflows, 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

References

• references/team-leader.md -- Epic decomposition, team formation, orchestration
• references/sub-team-leader.md -- Issue decomposition, worker management, model escalation
• references/agent-worker.md -- Task execution with TDD, skill loading, reporting
• references/validator.md -- Strictest CI per language, structured failure reporting
• references/fix-agent.md -- CI failure remediation, test fixing, escalation
• references/epic-authoring.md -- User guide for writing machine-executable epics