autonomous-claude-agent-team
This is a specific, working example — not a flexible framework. It is a Claude Code plugin that implements one concrete workflow for building features with a team of AI agents. This is an example to show how you can build your own hook-driven workflow-as-code.
A hook-driven state machine for orchestrating three Claude Code agents — a lead, a developer, and a reviewer — through a structured feature development cycle.
What it is
Three agents work through a fixed cycle:
- Lead coordinates. Never writes or reviews code. Can only stop in BLOCKED or COMPLETE.
- Developer implements via TDD, runs strict lint, and signals done by writing to a state file. Cannot go idle without signalling.
- Reviewer runs
git diff on uncommitted changes, runs typecheck/build/tests/lint, and returns APPROVED or REJECTED.
Every session is tracked by a GitHub issue. The PR is always created as a draft — this workflow never opens it. CodeRabbit reviews before humans do.
Hooks enforce the rules mechanically. The lead can't skip states, the developer can't commit before review, and no agent can stop at the wrong moment. This matters because LLMs are unreliable self-enforcers — hooks are code and can't be argued with.
How it works
flowchart LR
SPAWN --> PLANNING
PLANNING --> RESPAWN
RESPAWN --> DEVELOPING
DEVELOPING --> REVIEWING
REVIEWING -->|approved| COMMITTING
REVIEWING -->|rejected| DEVELOPING
COMMITTING -->|next iteration| RESPAWN
COMMITTING -->|done| CR_REVIEW
CR_REVIEW --> PR_CREATION
PR_CREATION --> FEEDBACK
FEEDBACK -->|iterate| RESPAWN
FEEDBACK --> COMPLETE
RESPAWN happens at the start of every iteration. It shuts down the existing developer and reviewer and spawns fresh agents with only the plan and iteration context. This clears their context windows deliberately — accumulated noise from earlier iterations pollutes decisions in later ones.
State file at /tmp/feature-team-state-${CLAUDE_SESSION_ID}.json is the source of truth:
{
"state": "DEVELOPING",
"iteration": 1,
"iterations": [
{
"task": "Add PDF rendering for line items",
"developerDone": false,
"developingHeadCommit": "abc123",
"reviewApproved": false,
"reviewRejected": false,
"coderabbitFeedbackAddressed": false,
"coderabbitFeedbackIgnored": false,
"lintedFiles": ["src/invoice/pdf-renderer.ts"],
"lintRanIteration": true
}
],
"githubIssue": 42,
"featureBranch": "feature/my-feature",
"prNumber": null,
"userApprovedPlan": true,
"activeAgents": ["feature-team-developer", "feature-team-reviewer"],
"eventLog": [
{ "op": "transition", "at": "2024-01-15T10:00:00Z", "detail": { "from": "PLANNING", "to": "RESPAWN" } }
]
}
/autonomous-claude-agent-team:workflow transition <STATE> is the only way the lead changes state. Each state's transitions and guards are defined in src/workflow-definition/domain/states/. Example — committing.ts:
// committing.ts (abbreviated)
export const committingState: ConcreteStateDefinition = {
emoji: '💾',
canTransitionTo: ['RESPAWN', 'CR_REVIEW', 'BLOCKED'],
transitionGuard: (ctx) => {
if (!ctx.gitInfo.workingTreeClean)
return fail('Uncommitted changes detected.')
const currentIteration = ctx.state.iterations[ctx.state.iteration]
if (!currentIteration?.lintRanIteration)
return fail('Lint not run this iteration.')
if (!ctx.gitInfo.hasCommitsVsDefault)
return fail('No commits beyond default branch.')
return pass()
},
}
Guards are pure functions that inspect git state and workflow state, returning pass() or fail('reason'). Every state follows this pattern.
Hooks:
SessionStart — persists CLAUDE_SESSION_ID to envPreToolUse — blocks plugin reads; blocks writes during RESPAWN; blocks commits during DEVELOPING/REVIEWING; validates lead identity and re-injects state procedure if lostSubagentStart — injects iteration, issue, and state context into spawned agents at startup; registers agent in active agents listTeammateIdle — blocks developer going idle in DEVELOPING without signalling done; blocks lead going idle in any state except BLOCKED or COMPLETE
The state procedure is injected in three moments only: successful transition (new state's procedure), failed transition (current state's procedure as a reminder), and identity loss recovery. Not on every tool call.
What you need to know
Starting a session:
/autonomous-claude-agent-team:start-feature-team
What the lead will ask you for:
- Reference documents (spec, existing code pointers, architecture notes)
- Plan approval before any code is written
- Decisions when the team is BLOCKED
Signals you'll see:
