Declarative, Claims-Driven Agent Harness & Verification FSM for Autonomous Software Engineering.
Band is a lightweight, zero-dependency execution harness and external verification engine. It drives AI agents through arbitrary, declarative multi-stage pipelines (TDD, mutation analysis, adversarial audits, multi-tier quality gates) with deterministic state machines and external Stop-hook enforcement.
flowchart LR
A["π‘ <b>Feature Request</b>"] --> B["π― <b>1. Intent Discovery</b><br/><code>/intent</code>"] --> C["π <b>2. Spec & Contract</b><br/><code>/spec</code>"] --> D["π₯ <b>3. Autonomous FSM</b><br/><code>/band</code>"] --> E["π <b>Verified Code</b>"]
Band structures autonomous software engineering into three strictly gated phases:
- Problem Solved: Prevents context pollution and goal drift (Anthropic Research, 2024) where AI models jump into premature code assumptions before understanding the business domain.
- 5-Lens Interview: Clarifies JTBD, Adversarial edge cases, Non-Goals, Pre-Mortem failure modes, and Business Invariants.
- Anti-Pollution Rule: Strictly forbids technical design, file paths, or code snippets in the intent document.
- Artifact & Gate:
.agents/tasks/<slug>/intent.mdverified viash .agents/bin/band --validate-intent
- Problem Solved: Prevents hallucinatory API design and blast-radius regressions (SWE-bench / Jimenez et al., 2024) by requiring codebase reconnaissance before coding.
- Blast Radius Matrix: Explicitly maps affected packages, modified files, and downstream consumers.
- Contract Generation: Creates
.agents/tasks/<slug>/done.yamlwith declarative verification claims. - Artifact & Gate:
.agents/tasks/<slug>/done.yamlverified viash .agents/bin/band --validate
- Problem Solved: Eliminates premature task completion and self-correction failure (Huang et al., 2023) by intercepting agent exits with a deterministic FSM and external Stop-hook.
- Stage Boundaries: Enforces
allow(whitelist) anddeny(blacklist) file boundaries per stage at the Git level. - Stop-Hook Interception: Intercepts agent exit attempts, verifies claims with real compilers and test runners, and feeds back failure traces.
- Artifact & Gate: Automated Multi-Agent Pipeline driven by
.agents/settings.json(Claude Code, via.claude -> .agents) or.agents/hooks.json
flowchart LR
Dispatch["1. Stage Dispatch<br/>(Role & Directive)"] --> Guard["2. Git Boundary<br/>(allow / deny)"] --> Agent["3. Agent Execution"] --> Hook{"4. Stop-Hook<br/>Claims Passed?"}
Hook -- "No" --> Retry["Circuit Breaker & Feedback"] --> Agent
Hook -- "Yes" --> Next["Advance to Stage N+1"]
- Declarative Stages (
pipelines/*.yaml): Ordered steps (e.g. Red β Green β Mutation β Review β Gate). - Subagent Scoping: Subagents are given minimal directives with strict file boundaries (
allow/deny). - External Stop-Hook: When an agent attempts to stop or complete, the hook intercepts and evaluates stage claims.
- Circuit Breaker: Trips if identical failures repeat across consecutive attempts, preventing infinite hallucination loops.
- Zero External Dependencies: Built on the Python 3 standard library (
subprocess,json,hashlib,unittest).
Autonomous LLM agents deployed on real-world codebases exhibit predictable failure modes when left unconstrained. Band's architecture directly solves these empirical problems:
- The Problem: When an AI agent is asked to simultaneously understand business requirements and write technical code, it suffers from severe context pollution and goal drift (Anthropic Research, 2024): the model jumps to premature technical assumptions (e.g. ad-hoc database schemas), skips critical business edge cases, and loses sight of non-goals without structured decomposition (Wei et al., 2022).
- Band Solution: Two-phase decoupling via
/intentand/spec. Phase 1 captures human intent, user journeys, invariants, and strict non-goals in pure natural language (zero code). Phase 2 takes the validated intent, conducts codebase reconnaissance, and outputs an exact architectural blueprint and verification contract (done.yaml).
- The Problem: Empirical research shows that LLMs cannot reliably self-evaluate or self-correct generated code through intrinsic reflection (Huang et al., 2023). Without external feedback loops like executable test oracles (Shinn et al., 2023), agents experience confirmation bias and falsely declare broken solutions correct.
- Band Solution: External Stop-hook executing real compilers, linters, test harnesses, and typecheckers to intercept exit attempts and return exact execution traces.
- The Problem: In unconstrained monolithic prompts, AI agents frequently game evaluations by weakening, altering, or deleting failing tests (SWE-bench / Jimenez et al., 2024) to force broken implementations to pass.
- Band Solution: Git-level
allow(whitelist) anddeny(blacklist) boundaries per stage. A Test Author agent is isolated to test files, while an Implementer agent is strictly blocked from altering test suites during the Green phase.
- The Problem: Monolithic single-agent contexts experience rapid reasoning degradation due to context overload and loss of operational discipline (MetaGPT / Hong et al., 2023); multi-agent orchestration with dedicated roles is required to sustain long-horizon execution (AutoGen / Wu et al., 2023).
- Band Solution: Explicit multi-agent decomposition where each stage defines a specialized role (
Test Author,Code Implementer,Mutation Runner,Adversarial Reviewer,Gatekeeper) with minimal, scoped context.
- The Problem: High test coverage frequently hides vacuous assertions: tests can execute code paths without verifying critical business invariants, leaving silent logic bugs undetected (Jia & Harman, 2011).
- Band Solution: First-class
mutationclaim adapter running diff-scoped mutation testing (e.g., Stryker/PIT) to prove test suites actively catch logic mutations before code is accepted.
| Pipeline | Target Use Case | Stages Executed |
|---|---|---|
hardened |
Mission-critical core domain logic & security features | red-phase β green-phase β mutation-gate β adversarial-review β gatekeeper |
standard |
Regular product features and component development | red-phase β green-phase β gatekeeper |
fast |
Quick hotfixes, CSS styling, and minor UI tweaks | implementation β gatekeeper |
docs |
Technical documentation, architecture guides, schemas | authoring β critic β gatekeeper |
A Task Contract (done.yaml) is the single source of truth for task completion:
slug: feat-user-auth
target: "services/auth"
pipeline: "hardened"
claims:
# L1: Build & Unit Tests
- id: l1-build
kind: make
target: check-package
params:
PKG: "@services/auth"
# L2: Mutation Testing (Stryker diff against modified files)
- id: l2-mutation
kind: mutation
target: "@services/auth"
mode: diff
# L3: AI Adversarial Critic Review
- id: l3-critic
kind: critic
checks:
- "No unhandled nulls or security bypasses"
- "Follows intent.md non-goals"
# L4: Clean Diff Hygiene
- id: l4-hygiene
kind: hygiene
no_stubs: true
no_skipped_tests: trueInstall Band into the root of any repository:
curl -fsSL https://raw.githubusercontent.com/jiva-studio/band/main/install.sh | bash
sh .agents/bin/band --init # wire hooks, link .claude -> .agents
sh .agents/bin/band --doctor # verify interpreter, hooks, Makefile targetsThis installs the clean .agents/ structure:
.agents/
βββ bin/band # Launcher: sh .agents/bin/band <args> (works from any directory)
βββ settings.json # Claude Code settings incl. Band hooks (seen as .claude/settings.json)
βββ .gitignore # settings.local.json, worktrees/ (harness-local state)
βββ hooks.json # Stop-hook and PreToolUse guard configuration (non-Claude harnesses)
βββ pipelines/ # Declarative pipeline definitions (standard, hardened, fast, docs)
βββ band/ # Python FSM verification engine & zero-dependency YAML loader
βββ skills/ # Agent skills (/band-install, /intent, /spec, /band, /coder)
βββ agents/ # Subagent definitions (optional)
βββ tasks/ # Task folders with intent.md, spec.md, done.yaml
Always invoke Band through the launcher, never with a bare python3 -m band (the package lives in .agents/, so it is not importable from the repository root):
sh .agents/bin/band --statusThe launcher adds .agents/ to PYTHONPATH and picks the interpreter in this order: $BAND_PYTHON (may contain arguments, e.g. BAND_PYTHON="uv run --no-project python"), python3, python (>= 3.8), then uv run --no-project python. This makes it work on hosts such as NixOS where python3 is not on PATH but uv is.
.agents/ is the only canonical agent directory. band --init makes .claude a symlink to it (.claude -> .agents), so Claude Code reads .agents/settings.json, .agents/skills/, .agents/agents/ and .agents/commands/ directly:
- If
.claudedoes not exist, the symlink is created. - If a real
.claude/directory exists, its contents are migrated into.agents/first:settings.jsonis deep-merged (lists unioned),skills/,agents/andcommands/entries and other files are moved. Existing.agentsentries are never overwritten. Migration is all-or-nothing: on any conflict (same entry with different content, a differing scalar setting, invalid JSON) nothing is changed and--initreportsSKIPPEDwith the reasons;band --doctorkeeps warning until it is resolved. .agents/.gitignoreignores harness-local state arriving through the link (settings.local.json,worktrees/).
Band's hooks are merged into .agents/settings.json (existing settings and hooks are preserved; re-running is idempotent). The guard also protects this file (and .claude/settings.json, the same file) from agent edits; ~/.claude/settings.json and settings.local.json are not affected:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write|MultiEdit|NotebookEdit|Bash",
"hooks": [{ "type": "command", "command": "sh \"${CLAUDE_PROJECT_DIR}/.agents/bin/band\" --guard --harness claude-code", "timeout": 30 }]
}
],
"Stop": [
{
"hooks": [{ "type": "command", "command": "sh \"${CLAUDE_PROJECT_DIR}/.agents/bin/band\" --hook --harness claude-code", "timeout": 600 }]
}
]
}
}- PreToolUse guard reads Claude Code's stdin payload (
tool_name,tool_input.file_path/notebook_path/command). A protected write is denied with exit code 2 andhookSpecificOutput.permissionDecision: "deny"; allowed calls exit 0 silently, so Claude Code's own permission prompts still apply. - Stop hook blocks with exit code 2 (reason on stderr, plus
hookSpecificOutput{"hookEventName": "Stop", "decision": "continue", "reason": ...}on stdout) while stage claims fail, and exits 0 when the pipeline passes, is paused, or no task is active. An internal Band error never traps the agent: the stop is allowed and asystemMessageis shown. .agents/hooks.jsonkeeps the original dialect ({"decision": "allow" | "deny" | "continue"}) for other harnesses;--harness auto(the default) detects Claude Code payloads byhook_event_name.
The critic claim reviews the complete task diff β committed, uncommitted and untracked changes against the merge-base of the task's base branch (claim base > done.yaml base_branch > $BAND_BASE_BRANCH > origin/HEAD > main > master). It never reviews truncated input: if the diff exceeds max_diff_chars (default 200000) or intent.md exceeds max_intent_chars (default 50000), the claim fails with an explicit message. The CLI timeout defaults to 300 s (timeout on the claim or BAND_CRITIC_TIMEOUT).
Developers trigger the workflow directly through chat slash commands:
> /band-install # 0. Auto-configures Makefile, mutation testing & doctor
> /intent Add course cover image picker # 1. Runs 5-lens interview & locks intent.md
> /spec # 2. Explores codebase, spins worktree & generates done.yaml
> /band # 3. Runs autonomous multi-agent FSM pipeline
/band-installβ Inspects repository stack, generates tailoredMakefileverification targets and mutation test configurations, and runsband --doctor./intent <feature>β Conducts the 5-lens interview and produces.agents/tasks/<slug>/intent.md./specβ Creates an isolated Git Worktree (.agents/worktrees/<slug>), conducts codebase reconnaissance, maps blast radius, and generates a validateddone.yaml./bandβ Spawns specialized subagents through the FSM pipeline under external Stop-hook supervision until 100% verified./coderβ Implementation agent for single-agent tasks and subagent coding phases.
MIT Β© Jiva Studio