essentials-claude-code

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)