Essentials for Claude Code

Loops, swarms, and teams powered by Claude Code's built-in Task System.

Loop, swarm, and team are three execution modes. Loop runs sequentially. Swarm runs parallel subagents. Team spawns full Claude Code instances with shared contracts via Agent Teams. All use Claude's native task dependencies, ctrl+t progress, and automatic persistence.

Plans define exit criteria. Loops run until tests pass. Done means actually done.

---

The Problem

You: "Add authentication"
AI:  *writes code* "Done!"
You: *runs tests* — 3 failing
You: "Fix these"
AI:  "Fixed!"
You: *runs tests* — still failing
     [repeat until you give up]

The Solution

# Option A: Discuss in chat, then execute from context
You: "I need to fix this auth bug..." [back and forth discussion]
You: /implement-loop fix the auth bug we discussed
AI:  *implements, tests fail, fixes, tests fail, fixes...*
AI:  "Exit criteria passed" ✓

# Option B: Create plan first, then execute
You: /plan-creator Add authentication
You: /plan-loop .claude/plans/auth-plan.md       # Sequential
You: /plan-swarm .claude/plans/auth-plan.md      # Parallel subagents
You: /plan-team .claude/plans/auth-plan.md       # Agent Teams with contracts
AI:  "Exit criteria passed" ✓

---

Quick Start

# Install
/plugin marketplace add GantisStorm/essentials-claude-code
/plugin install essentials@essentials-claude-code
mkdir -p .claude/plans .claude/prompts .claude/prd

# Option A: From conversation (after discussing a bug/feature)
/implement-loop fix the auth bug we discussed    # Sequential
/implement-swarm refactor the API handlers       # Parallel subagents
/implement-team build the full-stack feature     # Agent Teams with contracts

# Option B: With plan file
/plan-creator Add user authentication with JWT
/plan-loop .claude/plans/user-auth-3k7f2-plan.md   # Sequential
/plan-swarm .claude/plans/user-auth-3k7f2-plan.md  # Parallel subagents
/plan-team .claude/plans/user-auth-3k7f2-plan.md   # Agent Teams with contracts

# Visual progress
ctrl+t   # Toggle task tree view

Zero external dependencies. All three modes enforce exit criteria. Swarm defaults to 3 concurrent workers. Team requires tmux and CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.

---

Powered by Claude Code's Task System

Our loop, swarm, and team commands use Claude Code's built-in Task Management System (v2.1.19+).

Ralph TUI and Beads integrate seamlessly. Use Ralph TUI for dashboard visualization. Use Beads for persistent task tracking across sessions.

What We Used Before

The community built Ralph Wiggum loops with workarounds:

• Stop hooks: Shell scripts (.sh files) that ran after each Claude response, grepping output for keywords like "complete" or "done" to decide whether to continue the loop
• External plan files: Markdown files tracking task state since Claude had no built-in persistence
• TodoWrite: Flat task lists with no dependency ordering — tasks could run out of order
• Fresh sessions: Starting new conversations to fight context rot, manually re-establishing state each time

What We Use Now

Claude Code v2.1.19+ provides native tools that replace all of this:

Old Workaround	Native Replacement	Why It's Better
Stop hooks (shell scripts)	TaskUpdate({ status: "completed" })	No external scripts, status is structured data
External plan.md for state	~/.claude/tasks/ storage	Survives context compaction automatically
TodoWrite flat lists	TaskUpdate({ addBlockedBy: [...] })	Dependencies enforced — tasks can't run out of order
Manual session coordination	CLAUDE_CODE_TASK_LIST_ID env var	Same task list across sessions
Single agent	TaskList + parallel workers	Multiple agents coordinate via shared state

The core loop is unchanged: Plan → Implement → Verify → Loop if fail → Done when pass.

What Tasks Do Well

• Dependency management: Task #3 blocked by #1 and #2 literally cannot start until both complete
• Visual progress: Press ctrl+t to see live task tree with status
• Parallel coordination: Multiple workers share one task list, no conflicts
• Persistence: Survives context compaction, stored in ~/.claude/tasks/

What Tasks Don't Do

TaskList shows ID, subject, status, and blockedBy — but NOT description. To see implementation details, you must call TaskGet for each task individually.

This is why we still use plan files. Tasks track status. Plans hold implementation details.

Plan file (.claude/plans/)     →  Full implementation code (50-200+ lines per task)
Task System (~/.claude/tasks/) →  Status tracking, dependencies, parallel coordination

The Four Core Tools

Tool	Purpose
TaskCreate	Create task with subject, description, activeForm
TaskUpdate	Change status, set owner, add blockedBy dependencies
TaskGet	Get full details of ONE task (including description)
TaskList	See ALL tasks (but only subject, status, blockedBy)

How Dependencies Work

Dependencies flow through the entire pipeline:

Plan Creator                    Converter                      Executor
┌──────────────┐    ┌─────────────────────────┐    ┌──────────────────────┐
│ Dependency   │ →  │ dependsOn (prd.json)    │ →  │ addBlockedBy (task   │
│ Graph        │    │ depends_on (beads)      │    │ primitive)           │
│              │    │                         │    │                      │
│ Phase 1: A,B │    │ US-003: ["US-001","002"]│    │ taskId "3":          │
│ Phase 2: C   │    │                         │    │  blockedBy: ["1","2"]│
└──────────────┘    └─────────────────────────┘    └──────────────────────┘

Plan creators write a ## Dependency Graph table. Converters read it to build dependsOn (prd.json) or depends_on (beads). Loop/swarm commands translate those to addBlockedBy using an ID map.

Task lifecycle: pending → (blocked until deps complete) → in_progress → completed

A task with non-empty blockedBy shows as blocked in ctrl+t. When a blocking task is marked completed, it's automatically removed from the blocked list. A task becomes ready (executable) when its blockedBy list is empty.

TaskCreate({ subject: "Set up database" })           // → task "1"
TaskCreate({ subject: "Create auth middleware" })     // → task "2"
TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })      // #2 waits for #1

Task #2 cannot start until #1 completes. The system enforces this.

Visual Progress (ctrl+t)

Tasks (2 done, 1 in progress, 3 open)
✓ #1 Set up database schema
■ #2 Create auth middleware (Worker-1)
□ #3 Add login routes > blocked by #2
□ #4 Write tests > blocked by #3

Queue-Based Swarm Coordination

Main agent controls a queue of background agents:

Main:    Mark #1-3 in_progress → Spawn Agent-1, Agent-2, Agent-3
         ↓
Main:    Stop and wait — background agents notify on completion
         ↓
Agent-1: Completes Task #1 → notifies main → exits
         ↓
Main:    Woken → Mark #1 completed → TaskList → #4 unblocked → Mark #4 in_progress → Spawn Agent-4
         ↓
Main:    Stop and wait — next notification
         ... repeat until all tasks complete ...

Each agent does ONE task then exits. No racing. No stuck loops. Main agent marks tasks in_progress on spawn, completed on return, and refills queue as slots open.

Multi-Session Persistence

Tasks persist across sessions with CLAUDE_CODE_TASK_LIST_ID:

# Per terminal session
CLAUDE_CODE_TASK_LIST_ID="my-project" claude

# Or in .claude/settings.json
{ "env": { "CLAUDE_CODE_TASK_LIST_ID": "my-project" } }

Start a new session tomorrow — your task list is still there.

---

Workflows

Workflow	Best For	Converter	Loop	Swarm	Team
Simple	80% of tasks	—	/implement-loop, /plan-loop	/implement-swarm, /plan-swarm	/implement-team, /plan-team
Tasks	prd.json format	/tasks-converter	/tasks-loop	/tasks-swarm	—
Beads	Persistent memory	/beads-converter	/beads-loop	/beads-swarm	—

Converters transform plans into executable formats. /tasks-converter creates prd.json files with dependsOn arrays. /beads-converter creates beads with epic→task hierarchy and depends_on via bd dep add. Both read the plan's ## Dependency Graph table to build dependencies that maximize parallel execution.

All use Claude Code's built-in Task System for dependencies, ctrl+t progress, and persistence.

Alternative executor: Ralph TUI runs Tasks/Beads with the classic Ralph Wiggum loop style (community approach before Claude Code had native tasks).

Loop vs Swarm vs Team

Aspect	Loop	Swarm	Team
Executor	Main agent (foreground)	Background subagents	Full Claude Code instances (tmux panes)
Concurrency	1 task at a time	Up to N tasks (--workers)	All agents in parallel
Context	Full conversation history	Each agent gets task description only	Each agent gets contracts + ownership scope
Communication	N/A (single agent)	Workers isolated	Agents message each other via lead
Lead role	Implements directly	Queue manager	Contract author + coordinator (no coding)
Pre-work	Parse plan, create tasks	Parse plan, create tasks	Parse plan, define contracts, create tasks
Visibility	See work live	Check with ctrl+t or TaskList	Each agent visible in tmux pane
Best for	Sequential tasks	Independent parallel tasks	Multi-component builds requiring integration
Task system	Same	Same	Same
Dependencies	Same	Same	Same

All three use the same task graph with dependencies. Loop executes sequentially. Swarm spawns isolated subagents for independent parallel work. Team defines integration contracts upfront and spawns full Claude Code instances that can communicate — use when components must agree on interfaces (frontend + backend + database).

Simple (Start Here)

# From conversation context (after discussing)
/implement-loop fix the auth bug       # Sequential
/implement-swarm refactor API handlers  # Parallel subagents
/implement-team build the dashboard    # Agent Teams with contracts

# Or with plan file
/plan-creator Add JWT authentication
/plan-loop .claude/plans/jwt-auth-plan.md    # Sequential
/plan-swarm .claude/plans/jwt-auth-plan.md   # Parallel subagents
/plan-team .claude/plans/jwt-auth-plan.md    # Agent Teams with contracts

Tasks (prd.json Format)

/plan-creator Add JWT authentication
/tasks-converter .claude/plans/jwt-auth-plan.md

# Execute with Claude Code's Task System (recommended)
/tasks-loop .claude/prd/jwt-auth.json             # Sequential
/tasks-swarm .claude/prd/jwt-auth.json            # Parallel

# Or execute with Ralph TUI (classic Ralph loop)
ralph-tui run --prd .claude/prd/jwt-auth.json

Beads (Persistent Memory)

bd init
/plan-creator Add JWT authentication
/beads-converter .claude/plans/jwt-auth-plan.md

# Execute with Claude Code's Task System (recommended)
/beads-loop                                        # Sequential
/beads-swarm                                       # Parallel

# Or execute with Ralph TUI (classic Ralph loop)
ralph-tui run --tracker beads --epic <epic-id>

---

How Loops Work

                    ┌─────────────────┐
                    │  Read Source    │
                    │ (plan/context)  │
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │  Create Tasks   │
                    │  + Dependencies │
                    │ (from Dep Graph)│
                    └────────┬────────┘
                             │
        ┌────────────────────┴────────────────────┐
        │              MAIN AGENT                 │
        │                                         │
        │   ┌─────────────────┐                   │
        │   │    TaskList     │◄──────┐           │
        │   │ (find unblocked)│       │           │
        │   └────────┬────────┘       │           │
        │            │                │           │
        │            ▼                │           │
        │   ┌─────────────────┐       │           │
        │   │  Mark task      │       │           │
        │   │  in_progress    │       │           │
        │   └────────┬────────┘       │           │
        │            │                │           │
        │            ▼                │           │
        │   ┌─────────────────┐       │           │
        │   │   Implement     │       │           │
        │   │   (read, edit)  │       │           │
        │   └────────┬────────┘       │           │
        │            │                │           │
        │            ▼                │           │
        │   ┌─────────────────┐       │           │
        │   │  Mark task      │       │           │
        │   │   completed     │       │           │
        │   └────────┬────────┘       │           │
        │            │                │           │
        │      ┌─────┴─────┐          │           │
        │      │           │          │           │
        │  More tasks   All done      │           │
        │      │           │          │           │
        │      └───────────┼──────────┘           │
        │                  │                      │
        └──────────────────┼──────────────────────┘
                           │
                           ▼
                    ┌─────────────────┐
                    │  Run Exit       │
                    │  Criteria       │
                    └────────┬────────┘
                             │
                       ┌─────┴─────┐
                       │           │
                     FAIL        PASS
                       │           │
                       │           ▼
                       │    ┌─────────────────┐
                       │    │ Loop complete ✓ │
                       │    └─────────────────┘
                       │
                       ▼
                ┌─────────────────┐
                │   Fix issues    │
                │   (loop back)   │
                └─────────────────┘

Sequential execution. Main agent works through tasks one at a time in dependency order. Blocked tasks wait until their dependencies complete. Exit criteria verified at end. Loops until all tests pass.

---

How Swarms Work

                    ┌─────────────────┐
                    │  Read Source    │
                    │ (plan/context)  │
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │  Create Tasks   │
                    │  + Dependencies │
                    │ (from Dep Graph)│
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │  Spawn up to N  │
                    │ background agents│
                    │ (ready tasks)   │
                    └────────┬────────┘
                             │
         ┌───────────────────┼───────────────────┐
         │                   │                   │
         ▼                   ▼                   ▼
  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
  │  Agent 1    │     │  Agent 2    │     │  Agent N    │
  │─────────────│     │─────────────│     │─────────────│
  │ implement   │     │ implement   │     │ implement   │
  │ EXIT        │     │ EXIT        │     │ EXIT        │
  └──────┬──────┘     └──────┬──────┘     └──────┬──────┘
         │                   │                   │
         └───────────────────┼───────────────────┘
                             │
        ┌────────────────────┴────────────────────┐
        │              MAIN AGENT                 │
        │                                         │
        │   ┌─────────────────┐                   │
        │   │  Stop & wait    │◄──────┐           │
        │   │  (notification) │       │           │
        │   └────────┬────────┘       │           │
        │            │                │           │
        │            ▼                │           │
        │   ┌─────────────────┐       │           │
        │   │  Agent done     │       │           │
        │   │  Mark completed │       │           │
        │   └────────┬────────┘       │           │
        │            │                │           │
        │            ▼                │           │
        │   ┌─────────────────┐       │           │
        │   │  Find ready     │       │           │
        │   │ (pending+empty  │       │           │
        │   │  blockedBy)     │       │           │
        │   │  Mark in_progress│      │           │
        │   │  Spawn workers  │       │           │
        │   └────────┬────────┘       │           │
        │            │                │           │
        │      ┌─────┴─────┐          │           │
        │      │           │          │           │
        │  More tasks   All done      │           │
        │      │           │          │           │
        │      └───────────┼──────────┘           │
        │                  │                      │
        └──────────────────┼──────────────────────┘
                           │
                           ▼
                    ┌─────────────────┐
                    │ Swarm complete ✓│
                    └─────────────────┘

Queue-based parallel execution (default: 3 workers). Main agent marks tasks in_progress and spawns up to N background agents. Each agent does ONE task then exits. On completion notification, main agent marks the task completed, checks TaskList for newly unblocked tasks (status=pending, empty blockedBy), marks them in_progress, and spawns workers. Dependencies enforced — blocked tasks wait until all their blockers complete.

---

How Teams Work

                    ┌─────────────────┐
                    │  Read Source    │
                    │ (plan/context)  │
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │ Determine Team  │
                    │ Structure       │
                    │ (2-5+ agents)   │
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │ Define Contracts│
                    │ (exact URLs,    │
                    │  JSON shapes,   │
                    │  status codes)  │
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │ Enter Delegate  │
                    │ Mode + Spawn    │
                    │ all agents      │
                    └────────┬────────┘
                             │
         ┌───────────────────┼───────────────────┐
         │                   │                   │
         ▼                   ▼                   ▼
  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
  │  Agent 1    │     │  Agent 2    │     │  Agent N    │
  │ (Backend)   │     │ (Database)  │     │ (Frontend)  │
  │─────────────│     │─────────────│     │─────────────│
  │ contracts + │     │ contracts + │     │ contracts + │
  │ ownership   │◄───►│ ownership   │◄───►│ ownership   │
  │ scope       │relay│ scope       │relay│ scope       │
  └──────┬──────┘     └──────┬──────┘     └──────┬──────┘
         │                   │                   │
         └───────────────────┼───────────────────┘
                             │
        ┌────────────────────┴────────────────────┐
        │              LEAD AGENT                 │
        │         (Delegate Mode)                 │
        │                                         │
        │   ┌─────────────────┐                   │
        │   │ Relay messages   │                   │
        │   │ Mediate changes  │                   │
        │   │ Resolve conflicts│                   │
        │   └────────┬────────┘                   │
        │            │                            │
        │            ▼                            │
        │   ┌─────────────────┐                   │
        │   │ Contract diff   │                   │
        │   │ (built vs spec) │                   │
        │   └────────┬────────┘                   │
        │            │                            │
        └────────────┼────────────────────────────┘
                     │
                     ▼
              ┌─────────────────┐
              │ End-to-end      │
              │ validation      │
              └────────┬────────┘
                       │
                 ┌─────┴─────┐
                 │           │
               FAIL        PASS
                 │           │
                 │           ▼
                 │    ┌─────────────────┐
                 │    │ Team complete ✓ │
                 │    └─────────────────┘
                 │
                 ▼
          ┌─────────────────┐
          │ Re-spawn agent  │
          │ with fix        │
          └─────────────────┘

Contract-first parallel execution. Lead agent reads the plan, defines exact integration contracts (API URLs, JSON shapes, status codes, SSE formats), then spawns full Claude Code instances in tmux panes via Delegate Mode. Each agent gets contracts it produces, contracts it consumes, and ownership boundaries. Agents communicate through the lead for contract changes. After all agents complete, lead runs a contract diff and end-to-end validation.

Key difference from swarms: Swarm workers are isolated — they can't talk to each other. Team agents share contracts and communicate through the lead, making teams ideal for multi-component builds where interfaces must align.

---

Commands

Plan Creators

Command	Use For
/plan-creator <feature>	New features (brownfield development)
/bug-plan-creator <error> <desc>	Bug fixes, root cause analysis
/code-quality-plan-creator <files>	Refactoring, dead code, security

All three produce plans with the same structure: per-file implementation details, ## Dependency Graph table, and exit criteria. Pass a code map, design doc, or any reference file as additional context. Any plan can be fed to any converter or executed directly via /plan-loop, /plan-swarm, or /plan-team.

Execute Loops (Sequential)

Command	Source
/implement-loop <task>	Conversation context
/plan-loop <plan>	Plan file (required)
/tasks-loop [prd.json]	prd.json
/beads-loop [--label]	Beads DB

Cancel any loop: /cancel-loop

Execute Swarms (Parallel)

Command	Source
/implement-swarm <task>	Conversation context
/plan-swarm <plan>	Plan file (required)
/tasks-swarm [prd.json]	prd.json
/beads-swarm [--epic]	Beads DB

Cancel any swarm: /cancel-swarm

Execute Teams (Agent Teams)

Command	Source
/implement-team <task>	Conversation context
/plan-team <plan>	Plan file (required)

Cancel any team: /cancel-team

Requires: tmux + CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Lead defines integration contracts, spawns full Claude Code instances in tmux panes via Delegate Mode. Agents communicate through the lead. Based on Cole Medin's build-with-agent-team pattern.

Convert Formats

Command	Output	Dependency Source
/tasks-converter <plan>	prd.json with dependsOn arrays	Plan's ## Dependency Graph table
/beads-converter <plan>	Beads issues with bd dep add	Plan's ## Dependency Graph table

Converters read the plan's ## Dependency Graph to build file→task/bead ID maps and translate file dependencies to task dependencies. Falls back to per-file Dependencies/Provides for older plans without a Dependency Graph.

Schema References

Command	Purpose
/plan-schema [validate <path>]	Plan file format — sections, per-file format, dependency graph rules
/prd-schema [validate <path>]	prd.json schema — required fields, rejected fields, examples
/beads-schema [validate]	Beads CLI — issue types, statuses, priorities, commands

Invoke without arguments for a quick reference. Invoke with validate to check an existing file against the schema.

Utilities

Command	Purpose
/codemap-creator <dir>	Create JSON code map via LSP
/codemap-creator --update <map> [--diff|--mr|--pr]	Update existing codemap with changed files
/document-creator <dir>	DEVGUIDE.md generation
/mr-description-creator	PR/MR descriptions via gh/glab
/show-status <json|beads> [path|epic-id]	Task/bead status dashboard
/reset-prd <path>	Reset prd.json to initial state
/reset-beads <epic-id>	Reopen all tasks in a beads epic
/ralph-config <json|beads>	Write RalphTUI config for workflow

---

What's In A Plan?

Plans are markdown files in .claude/plans/ with structured sections:

## Implementation Plan

### src/types/auth.ts [create]
[Complete code — not pseudocode]
Dependencies: —
Provides: AuthToken type, validateToken() function

### src/services/auth.ts [create]
[Complete code]
Dependencies: src/types/auth.ts
Provides: AuthService class

## Dependency Graph

| Phase | File                    | Action | Depends On              |
|-------|-------------------------|--------|-------------------------|
| 1     | `src/types/auth.ts`     | create | —                       |
| 2     | `src/services/auth.ts`  | create | `src/types/auth.ts`     |

## Exit Criteria
npm test -- auth && npm run typecheck

Self-Contained Rule: Each task must be implementable with ONLY its description. No "see design.md" allowed.

Dependency Graph Rule: The ## Dependency Graph table is the source of truth for execution order. Converters read it to build dependsOn/depends_on. Files in the same phase can execute in parallel. Only real code dependencies should create phase boundaries.

---

Project Structure

your-project/
├── .claude/
│   ├── plans/          # Source of truth (plan files with Dependency Graphs)
│   ├── prd/            # prd.json files (from /tasks-converter)
│   ├── maps/           # Code maps (from /codemap-creator)
│   └── prompts/        # Generated prompts
├── .ralph-tui/         # RalphTUI config (if using)
│   └── config.toml     # Tracker, agent settings
└── .beads/             # Beads DB (if using)

RalphTUI setup: Run ralph-tui setup per project. See Managing .ralph-tui/ for config details and switching trackers.

---

Requirements

Tool	Required?	Purpose
None	—	Simple workflow (loop/swarm) works out of the box
tmux	For Team mode	Agent Teams use tmux for split-pane visualization
Beads CLI	For Beads workflow	Persistent memory across sessions
Ralph TUI	Optional	Classic Ralph loop executor with TUI dashboard

Simple workflow has zero dependencies for loop and swarm. Team mode requires tmux and CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Add Beads for persistent memory. Add Ralph TUI if you prefer the classic Ralph Wiggum loop style.

---

Model Configuration

Edit YAML frontmatter in essentials/commands/*.md or essentials/agents/*.md:

---
model: opus    # opus | sonnet | haiku
---

---

Troubleshooting

Problem	Solution
Loop won't stop	Exit criteria must return exit code 0
Wrong exit criteria	Edit plan directly, re-run loop
Context filling up	Plans persist outside conversation
prd.json not found	Use userStories and passes fields
Beads CLI missing	brew tap steveyegge/beads && brew install bd
Swarm runs sequentially	Check plan's Dependency Graph — every task chained to previous degrades swarm to sequential. Only declare real code dependencies.

---

Documentation

• WORKFLOW-SIMPLE.md — Default workflow, zero dependencies
• WORKFLOW-TASKS.md — Dashboard visualization with Ralph TUI
• WORKFLOW-BEADS.md — Persistent task tracking with Beads
• COMPARISON.md — Why verification-driven loops matter

---

Contributing

1. Fork it
2. Create your branch (git checkout -b feature/thing)
3. Commit changes
4. Push and open a PR

---

Credits

• Ralph Wiggum pattern by Geoffrey Huntley
• Beads by Steve Yegge — Persistent memory
• Ralph TUI by subsy — Classic Ralph loop executor
• build-with-agent-team by Cole Medin — Contract-first Agent Teams pattern
• Built for Claude Code

---

Plans define exit criteria. Loops, swarms, and teams run until tests pass. Done means actually done.