THE AGENTIC FLOW (fork from https://github.com/AvivK5498/The-Claude-Protocol)

Enforcement-first orchestration for Claude Code. Every agent tracked. Every decision logged. Nothing gets lost.

Claude Code plans great. Without structure, nothing survives past one session.

npx skills add AvivK5498/The-Claude-Protocol

macOS, Linux, and Windows.

Why This Exists · How It Works · Getting Started · Hooks

Why This Exists

Claude Code is the best coding agent out there. But let it run unsupervised and you get agents editing main, commits without PRs, lost context every session, and zero traceability on what was done and why.

Plan mode helps — until you need to coordinate across files, track what was planned vs what shipped, or pick up a task three sessions later. Plans vanish. Context resets. Investigation gets redone from scratch.

The Claude Protocol is the enforcement layer. It wraps Claude Code with 13 hooks that physically block bad actions, isolates every task in its own git worktree, and documents everything automatically — dispatch prompts, agent knowledge, decisions, all of it. Beads (git-native tickets) track every unit of work from creation to merge.

The complexity is in the system. What you see: Claude plans with you, you approve, agents execute in isolation, PRs get merged. Done.

How It Works

┌─────────────────────────────────────────┐
│         ORCHESTRATOR (Co-Pilot)         │
│  Plans with you (Plan mode)            │
│  Investigates with Grep/Read/Glob       │
│  Delegates implementation via Task()    │
└──────────────────┬──────────────────────┘
                   │
       ┌───────────┼───────────┐
       ▼           ▼           ▼
  ┌─────────┐ ┌─────────┐ ┌─────────┐
  │ react-  │ │ python- │ │ nextjs- │
  │supervisor│ │supervisor│ │supervisor│
  └────┬────┘ └────┬────┘ └────┬────┘
       │           │           │
  .worktrees/ .worktrees/ .worktrees/
  bd-BD-001   bd-BD-002   bd-BD-003

The orchestrator investigates, discusses with you, and plans. It never writes code. Dispatch prompts are auto-logged to the bead so nothing gets lost.

Supervisors are created automatically based on your tech stack. They read bead comments for full context, work in isolated worktrees, and push clean PRs.

Beads are git-native tickets. Every task, every epic, every dependency — tracked in your repo, not a third-party service. One bead = one unit of work = one worktree = one PR.

Workflow

Standalone — Investigate → plan → approve → create bead → dispatch supervisor → worktree → PR → merge.

Epics — Cross-domain work (DB + API + frontend) becomes an epic with enforced child dependencies. Each child gets its own worktree. Dependencies prevent dispatching out of order.

Every task goes through beads. No exceptions.

Kanban UI

The Claude Protocol pairs with the Beads Kanban UI for visual task management and GitOps directly from the browser. Track epics, subtasks, dependencies, and PR status across columns — without leaving the board.

Architecture: How Agents Work Together

Task Ownership & Responsibilities

| Role | Creates Tasks? | Works on Tasks? | Creates Dependencies? | |------|----------------|-----------------|----------------------| | Orchestrator (Claude) | ✅ Yes (via bd create) | ❌ Never | ✅ Yes (via --deps) | | Supervisors | ❌ Never | ✅ Yes (in worktrees) | ❌ Never | | Detectives/Scout | ❌ Never | ❌ Never | ❌ Never |

The orchestrator is the only agent that creates beads and manages dependencies. Supervisors only work on assigned tasks in isolated worktrees.

Agent Types

| Agent | Type | Purpose | When Used | |-------|------|---------|-----------| | scout | Read-only | Quick reconnaissance | "What files relate to X?" | | detective | Read-only | Deep investigation | "Why is X broken?" | | architect | Read-only | Design docs for epics | Cross-domain features | | scribe | Read-only | Documentation generation | Doc updates | | security-detective | Read-only | Vulnerability scanning | Security audits | | {tech}-supervisor | Implementation | Actual code changes | Per-task execution | | security-supervisor | Implementation | Security fixes | Vulnerability remediation | | code-reviewer | Verification | 3-phase review | Optional review gate |

Bead Task Lifecycle

User Request
    ↓
Orchestrator investigates (Grep, Read, Glob)
    ↓
Plan with user (optional: Plan mode)
    ↓
User confirms approach
    ↓
**Interactive agent selection:**
  - Orchestrator lists available agents
  - Recommends best agent for each task
  - User accepts or specifies different agents
  - Final "go" confirmation
    ↓
Orchestrator creates bead(s)
    ↓
Orchestrator dispatches supervisor with BEAD_ID
    ↓
Supervisor works in .worktrees/bd-{BEAD_ID}/
    ↓
Supervisor commits, pushes, marks `inreview`
    ↓
Orchestrator prompts: /review, /merge, or /continue
    ↓
User merges PR
    ↓
bd close {ID}

Auto-Pilot Mode (Generalized Loop)

Enable autonomous task execution with automatic testing and retry logic.

How to Activate

Say to Claude: "auto-pilot", "watch mode", or "run the loop"

The Loop

1. Run `bd ready` to find unblocked tasks
2. For each ready task:
   - Determine type from bead title (Implement, Test, Scan, Fix, etc.)
   - Dispatch appropriate agent
3. Wait for completion → agent marks `inreview`
4. Auto-create test bead (if implementation task)
5. If test fails:
   - Create fix bead with dependency
   - Loop continues
6. If test passes:
   - Notify user "Task BD-XXX complete, tests passing"
7. Run `bd ready` again → repeat until empty

Agent Routing

Auto-pilot automatically selects agents based on bead title:

| Bead Title Pattern | Agent Dispatched | |-------------------|------------------| | "Implement...", "Add...", "Create..." | {tech}-supervisor | | "Test...", "Verify..." | Built-in test mode OR code-reviewer | | "Scan...", "Audit...", "Security..." | security-detective | | "Fix...", "Resolve..." | {tech}-supervisor | | "Investigate...", "Debug..." | detective |

Safety Rails

• Max 3 retries per original task (prevents infinite loops)
• User can interrupt anytime with "stop" or "pause"
• Full traceability: Each iteration creates new beads
• Retry tracking: Stored in bead comments (RETRY: 1/3)

Resume After Stop

When you say "stop", the currently running agent completes its work gracefully (no mid-task termination), then the loop pauses.

Resume commands:

• "continue" or "resume" → Picks up where it left off
• "continue BD-XXX" → Resume specific task
• "skip BD-XXX" → Mark task as skipped, continue with next

Works across sessions: The .beads/ database persists all state. You can:

1. Stop auto-pilot
2. Close Claude entirely
3. Reopen later
4. Say "continue"
5. Loop resumes from where it stopped

Custom Agents

Want to add your own specialized agents? Just drop them in .claude/agents/.

Requirements

1. Filename: Must end with -supervisor for implementation agents
2. Format: Markdown with YAML frontmatter
3. Workflow: Must include beads workflow (copy from .claude/beads-workflow-injection.md)

Example

---
name: my-custom-supervisor
description: Handles custom domain logic
model: sonnet
tools: *
---

# My Custom Supervisor: "Name"

[Include beads workflow here]

[Your custom instructions]

The orchestrator will automatically detect and offer your custom agent when appropriate.

Getting Started

npx skills add AvivK5498/The-Claude-Protocol

Or via npm:

npm install -g @apapacho/the-agentic-flow

Then in any Claude Code session:

/create-beads-orchestration

The skill walks you through setup, scans your tech stack, and creates supervisors with best practices injected.

Requirements

• Claude Code with hooks support
• Node.js (for npx)
• Python 3 (for bootstrap)
• beads CLI (installed automatically)

Antigravity Support

This repo also supports Google's Antigravity agent.

Setup

npx @apapacho/the-agentic-flow bootstrap --antigravity

This creates an .agent/skills/beads-orchestration directory containing the keys to the kingdom: a SKILL.md that teaches Antigravity how to use the bd CLI.

How It Works

Antigravity automatically detects skills in the .agent/skills directory. You don't need to "install" it further. When you ask Antigravity to "check the tasks" or "create a task", it will find this skill, read the instructions, and know how to call bd list or bd create.

Coexistence with Claude

Yes, they play nicely together. Both agents share the same source of truth: the .beads directory.

• Claude uses .claude/agents and .worktrees/.
• Antigravity uses .agent/skills and the same .beads database.
• You can start a task in Claude, and Antigravity can see it via bd list.
• You can create a task in Antigravity, and Claude can pick it up.

What Makes This Different

Enforcement, Not Suggestions

13 hooks across 5 lifecycle events. They don't warn — they block. The orchestrator can't edit code. Supervisors can't skip beads. Epics can't close with open children. PRs must be merged before a bead is closed.

Documentation That Writes Itself

Every supervisor dispatch prompt is automatically captured as a bead comment. Agents voluntarily log conventions and gotchas into a persistent knowledge base. Session start surfaces recent knowledge so agents don't re-investigate solved problems.

# Agent captures an insight
bd comment BD-001 "LEARNED: TaskGroup requires @Sendable closures in strict concurrency mode."

# Search the knowledge base
.beads/memory/recall.sh "concurrency"

Follow-Up Traceability

Closed beads are immutable. Bug fixes become new beads linked via bd dep relate — full history, no reopening. Merged branches don't get reused. Each fix gets its own worktree and PR.

What Gets Installed

.claude/
├── agents/           # Supervisors (auto-created for your tech stack)
├── hooks/            # Workflow enforcement (13 hooks)
├── skills/           # subagents-discipline, react-best-practices
└── settings.json
CLAUDE.md             # Orchestrator instructions
.beads/               # Task database
  memory/             # Knowledge base (knowledge.jsonl + recall.sh)
.worktrees/           # Isolated worktrees per task (created dynamically)

Hooks

13 hooks enforce every workflow step. They block before bad actions happen, auto-log after good ones, and validate before supervisors exit.

PreToolUse (7 hooks) — Block orchestrator from writing code. Require beads for supervisor dispatch. Enforce worktree isolation. Block closing epics with open children. Enforce sequential dependency dispatch.

PostToolUse (3 hooks) — Auto-log dispatch prompts as bead comments. Capture knowledge base entries. Enforce concise supervisor responses.

SubagentStop (1 hook) — Verify worktree exists, code is pushed, bead status is updated.

SessionStart (1 hook) — Surface task status, recent knowledge, and cleanup suggestions.

UserPromptSubmit (1 hook) — Prompt for clarification on ambiguous requests.

Advanced: External Providers

By default, all agents run via Claude's Task(). To delegate read-only agents (scout, detective, etc.) to Codex/Gemini:

/create-beads-orchestration --external-providers

Requires Codex CLI (codex login), optionally Gemini CLI, and uv.

License

MIT

Credits

• beads — Git-native task tracking by Steve Yegge
• sub-agents.directory — External agent templates