autonomous-claude-agent-team

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 env
• PreToolUse — blocks plugin reads; blocks writes during RESPAWN; blocks commits during DEVELOPING/REVIEWING; validates lead identity and re-injects state procedure if lost
• SubagentStart — injects iteration, issue, and state context into spawned agents at startup; registers agent in active agents list
• TeammateIdle — 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: