Skip to content
Back to search

essentials-claude-code

All-in-one workflow plugin—loops, swarms, and teams on Claude Code's Task System. All enforce exit criteria—swarm is faster with parallel queue execution, teams add contract-first coordination. Plan your way, execute your way. Optional: Beads for persistent memory, Ralph TUI for dashboard.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gantisstorm--essentials-claude-code/badge.svg)](/listings/gantisstorm--essentials-claude-code)

HTML

<a href="/listings/gantisstorm--essentials-claude-code"><img src="/api/listings/gantisstorm--essentials-claude-code/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 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`.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 18 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "essentials-claude-code",
  3. "version": "3.43.0",
  4. "description": "Loops, swarms, and teams powered by Claude Code's built-in Task System. Plans define exit criteria. Executors run until tests pass. Done means actually done.",
  5. "author": "GantisStorm",
  6. "owner": {
  7. "name": "GantisStorm"
  8. },
  9. "homepage": "https://github.com/GantisStorm/essentials-claude-code",
  10. "plugins": [
  11. {
  12. "name": "essentials",
  13. "version": "3.43.0",
  14. "description": "24 commands, 8 agents. Loops, swarms, and teams powered by Claude Code's built-in Task System. Native task dependencies, ctrl+t progress, automatic persistence.",
  15. "source": "./essentials"
  16. }
  17. ]
  18. }
README.md · README · 728 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <img src="logo.png" alt="Essentials for Claude Code" width="450"/>
  3. # Essentials for Claude Code
  4. [![Unlicense](https://img.shields.io/badge/license-Unlicense-blue.svg)](https://unlicense.org/)
  5. [![Claude Code](https://img.shields.io/badge/Built%20for-Claude%20Code-blueviolet)](https://claude.ai/code)
  6. [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)
  7. **Loops, swarms, and teams powered by Claude Code's built-in Task System.**
  8. 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](https://www.anthropic.com/news/claude-opus-4-6). All use Claude's native task dependencies, `ctrl+t` progress, and automatic persistence.
  9. Plans define exit criteria. Loops run until tests pass. Done means actually done.
  10. </div>
  11. ---
  12. ## The Problem
  13. ```
  14. You: "Add authentication"
  15. AI: *writes code* "Done!"
  16. You: *runs tests* — 3 failing
  17. You: "Fix these"
  18. AI: "Fixed!"
  19. You: *runs tests* — still failing
  20. [repeat until you give up]
  21. ```
  22. ## The Solution
  23. ```
  24. # Option A: Discuss in chat, then execute from context
  25. You: "I need to fix this auth bug..." [back and forth discussion]
  26. You: /implement-loop fix the auth bug we discussed
  27. AI: *implements, tests fail, fixes, tests fail, fixes...*
  28. AI: "Exit criteria passed" ✓
  29. # Option B: Create plan first, then execute
  30. You: /plan-creator Add authentication
  31. You: /plan-loop .claude/plans/auth-plan.md # Sequential
  32. You: /plan-swarm .claude/plans/auth-plan.md # Parallel subagents
  33. You: /plan-team .claude/plans/auth-plan.md # Agent Teams with contracts
  34. AI: "Exit criteria passed" ✓
  35. ```
  36. ---
  37. ## Quick Start
  38. ```bash
  39. # Install
  40. /plugin marketplace add GantisStorm/essentials-claude-code
  41. /plugin install essentials@essentials-claude-code
  42. mkdir -p .claude/plans .claude/prompts .claude/prd
  43. # Option A: From conversation (after discussing a bug/feature)
  44. /implement-loop fix the auth bug we discussed # Sequential
  45. /implement-swarm refactor the API handlers # Parallel subagents
  46. /implement-team build the full-stack feature # Agent Teams with contracts
  47. # Option B: With plan file
  48. /plan-creator Add user authentication with JWT
  49. /plan-loop .claude/plans/user-auth-3k7f2-plan.md # Sequential
  50. /plan-swarm .claude/plans/user-auth-3k7f2-plan.md # Parallel subagents
  51. /plan-team .claude/plans/user-auth-3k7f2-plan.md # Agent Teams with contracts
  52. # Visual progress
  53. ctrl+t # Toggle task tree view
  54. ```
  55. **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`.
  56. ---
  57. ## Powered by Claude Code's Task System
  58. Our loop, swarm, and team commands use Claude Code's **built-in Task Management System** (v2.1.19+).
  59. > **Ralph TUI and Beads integrate seamlessly.** Use [Ralph TUI](https://github.com/subsy/ralph-tui) for dashboard visualization. Use [Beads](https://github.com/steveyegge/beads) for persistent task tracking across sessions.
  60. ### What We Used Before
  61. The community built Ralph Wiggum loops with workarounds:
  62. - **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
  63. - **External plan files**: Markdown files tracking task state since Claude had no built-in persistence
  64. - **TodoWrite**: Flat task lists with no dependency ordering — tasks could run out of order
  65. - **Fresh sessions**: Starting new conversations to fight context rot, manually re-establishing state each time
  66. ### What We Use Now
  67. Claude Code v2.1.19+ provides native tools that replace all of this:
  68. | Old Workaround | Native Replacement | Why It's Better |
  69. |----------------|-------------------|-----------------|
  70. | Stop hooks (shell scripts) | `TaskUpdate({ status: "completed" })` | No external scripts, status is structured data |
  71. | External plan.md for state | `~/.claude/tasks/` storage | Survives context compaction automatically |
  72. | TodoWrite flat lists | `TaskUpdate({ addBlockedBy: [...] })` | Dependencies enforced — tasks can't run out of order |
  73. | Manual session coordination | `CLAUDE_CODE_TASK_LIST_ID` env var | Same task list across sessions |
  74. | Single agent | `TaskList` + parallel workers | Multiple agents coordinate via shared state |
  75. **The core loop is unchanged:** Plan → Implement → Verify → Loop if fail → Done when pass.
  76. ### What Tasks Do Well
  77. - **Dependency management**: Task #3 blocked by #1 and #2 literally cannot start until both complete
  78. - **Visual progress**: Press `ctrl+t` to see live task tree with status
  79. - **Parallel coordination**: Multiple workers share one task list, no conflicts
  80. - **Persistence**: Survives context compaction, stored in `~/.claude/tasks/`
  81. ### What Tasks Don't Do
  82. `TaskList` shows ID, subject, status, and blockedBy — **but NOT description**. To see implementation details, you must call `TaskGet` for each task individually.
  83. **This is why we still use plan files.** Tasks track status. Plans hold implementation details.
  84. ```
  85. Plan file (.claude/plans/) → Full implementation code (50-200+ lines per task)
  86. Task System (~/.claude/tasks/) → Status tracking, dependencies, parallel coordination
  87. ```
  88. ### The Four Core Tools
  89. | Tool | Purpose |
  90. |------|---------|
  91. | `TaskCreate` | Create task with subject, description, activeForm |
  92. | `TaskUpdate` | Change status, set owner, add `blockedBy` dependencies |
  93. | `TaskGet` | Get full details of ONE task (including description) |
  94. | `TaskList` | See ALL tasks (but only subject, status, blockedBy) |
  95. ### How Dependencies Work
  96. Dependencies flow through the entire pipeline:
  97. ```
  98. Plan Creator Converter Executor
  99. ┌──────────────┐ ┌─────────────────────────┐ ┌──────────────────────┐
  100. │ Dependency │ → │ dependsOn (prd.json) │ → │ addBlockedBy (task │
  101. │ Graph │ │ depends_on (beads) │ │ primitive) │
  102. │ │ │ │ │ │
  103. │ Phase 1: A,B │ │ US-003: ["US-001","002"]│ │ taskId "3": │
  104. │ Phase 2: C │ │ │ │ blockedBy: ["1","2"]│
  105. └──────────────┘ └─────────────────────────┘ └──────────────────────┘
  106. ```
  107. 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.
  108. **Task lifecycle**: `pending` → (blocked until deps complete) → `in_progress` → `completed`
  109. 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.
  110. ```
  111. TaskCreate({ subject: "Set up database" }) // → task "1"
  112. TaskCreate({ subject: "Create auth middleware" }) // → task "2"
  113. TaskUpdate({ taskId: "2", addBlockedBy: ["1"] }) // #2 waits for #1
  114. ```
  115. Task #2 **cannot start** until #1 completes. The system enforces this.
  116. ### Visual Progress (`ctrl+t`)
  117. ```
  118. Tasks (2 done, 1 in progress, 3 open)
  119. ✓ #1 Set up database schema
  120. ■ #2 Create auth middleware (Worker-1)
  121. □ #3 Add login routes > blocked by #2
  122. □ #4 Write tests > blocked by #3
  123. ```
  124. ### Queue-Based Swarm Coordination
  125. Main agent controls a queue of background agents:
  126. ```
  127. Main: Mark #1-3 in_progress → Spawn Agent-1, Agent-2, Agent-3
  128. ↓
  129. Main: Stop and wait — background agents notify on completion
  130. ↓
  131. Agent-1: Completes Task #1 → notifies main → exits
  132. ↓
  133. Main: Woken → Mark #1 completed → TaskList → #4 unblocked → Mark #4 in_progress → Spawn Agent-4
  134. ↓
  135. Main: Stop and wait — next notification
  136. ... repeat until all tasks complete ...
  137. ```
  138. Each agent does ONE task then exits. No racing. No stuck loops.
  139. Main agent marks tasks in_progress on spawn, completed on return, and refills queue as slots open.
  140. ### Multi-Session Persistence
  141. Tasks persist across sessions with `CLAUDE_CODE_TASK_LIST_ID`:
  142. ```bash
  143. # Per terminal session
  144. CLAUDE_CODE_TASK_LIST_ID="my-project" claude
  145. # Or in .claude/settings.json
  146. { "env": { "CLAUDE_CODE_TASK_LIST_ID": "my-project" } }
  147. ```
  148. Start a new session tomorrow — your task list is still there.
  149. ---
  150. ## Workflows
  151. | Workflow | Best For | Converter | Loop | Swarm | Team |
  152. |----------|----------|-----------|------|-------|------|
  153. | **Simple** | 80% of tasks | — | `/implement-loop`, `/plan-loop` | `/implement-swarm`, `/plan-swarm` | `/implement-team`, `/plan-team` |
  154. | **Tasks** | prd.json format | `/tasks-converter` | `/tasks-loop` | `/tasks-swarm` | — |
  155. | **Beads** | Persistent memory | `/beads-converter` | `/beads-loop` | `/beads-swarm` | — |
  156. **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.
  157. **All use Claude Code's built-in Task System** for dependencies, `ctrl+t` progress, and persistence.
  158. **Alternative executor:** [Ralph TUI](https://github.com/subsy/ralph-tui) runs Tasks/Beads with the classic Ralph Wiggum loop style (community approach before Claude Code had native tasks).
  159. ### Loop vs Swarm vs Team
  160. | Aspect | Loop | Swarm | Team |
  161. |--------|------|-------|------|
  162. | **Executor** | Main agent (foreground) | Background subagents | Full Claude Code instances (tmux panes) |
  163. | **Concurrency** | 1 task at a time | Up to N tasks (`--workers`) | All agents in parallel |
  164. | **Context** | Full conversation history | Each agent gets task description only | Each agent gets contracts + ownership scope |
  165. | **Communication** | N/A (single agent) | Workers isolated | Agents message each other via lead |
  166. | **Lead role** | Implements directly | Queue manager | Contract author + coordinator (no coding) |
  167. | **Pre-work** | Parse plan, create tasks | Parse plan, create tasks | Parse plan, **define contracts**, create tasks |
  168. | **Visibility** | See work live | Check with `ctrl+t` or TaskList | Each agent visible in tmux pane |
  169. | **Best for** | Sequential tasks | Independent parallel tasks | Multi-component builds requiring integration |
  170. | **Task system** | Same | Same | Same |
  171. | **Dependencies** | Same | Same | Same |
  172. **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).
  173. ### Simple (Start Here)
  174. ```bash
  175. # From conversation context (after discussing)
  176. /implement-loop fix the auth bug # Sequential
  177. /implement-swarm refactor API handlers # Parallel subagents
  178. /implement-team build the dashboard # Agent Teams with contracts
  179. # Or with plan file
  180. /plan-creator Add JWT authentication
  181. /plan-loop .claude/plans/jwt-auth-plan.md # Sequential
  182. /plan-swarm .claude/plans/jwt-auth-plan.md # Parallel subagents
  183. /plan-team .claude/plans/jwt-auth-plan.md # Agent Teams with contracts
  184. ```
  185. ### Tasks (prd.json Format)
  186. ```bash
  187. /plan-creator Add JWT authentication
  188. /tasks-converter .claude/plans/jwt-auth-plan.md
  189. # Execute with Claude Code's Task System (recommended)
  190. /tasks-loop .claude/prd/jwt-auth.json # Sequential
  191. /tasks-swarm .claude/prd/jwt-auth.json # Parallel
  192. # Or execute with Ralph TUI (classic Ralph loop)
  193. ralph-tui run --prd .claude/prd/jwt-auth.json
  194. ```
  195. ### Beads (Persistent Memory)
  196. ```bash
  197. bd init
  198. /plan-creator Add JWT authentication
  199. /beads-converter .claude/plans/jwt-auth-plan.md
  200. # Execute with Claude Code's Task System (recommended)
  201. /beads-loop # Sequential
  202. /beads-swarm # Parallel
  203. # Or execute with Ralph TUI (classic Ralph loop)
  204. ralph-tui run --tracker beads --epic <epic-id>
  205. ```
  206. ---
  207. ## How Loops Work
  208. ```
  209. ┌─────────────────┐
  210. │ Read Source │
  211. │ (plan/context) │
  212. └────────┬────────┘
  213. │
  214. ▼
  215. ┌─────────────────┐
  216. │ Create Tasks │
  217. │ + Dependencies │
  218. │ (from Dep Graph)│
  219. └────────┬────────┘
  220. │
  221. ┌────────────────────┴────────────────────┐
  222. │ MAIN AGENT │
  223. │ │
  224. │ ┌─────────────────┐ │
  225. │ │ TaskList │◄──────┐ │
  226. │ │ (find unblocked)│ │ │
  227. │ └────────┬────────┘ │ │
  228. │ │ │ │
  229. │ ▼ │ │
  230. │ ┌─────────────────┐ │ │
  231. │ │ Mark task │ │ │
  232. │ │ in_progress │ │ │
  233. │ └────────┬────────┘ │ │
  234. │ │ │ │
  235. │ ▼ │ │
  236. │ ┌─────────────────┐ │ │
  237. │ │ Implement │ │ │
  238. │ │ (read, edit) │ │ │
  239. │ └────────┬────────┘ │ │
  240. │ │ │ │
  241. │ ▼ │ │
  242. │ ┌─────────────────┐ │ │
  243. │ │ Mark task │ │ │
  244. │ │ completed │ │ │
  245. │ └────────┬────────┘ │ │
  246. │ │ │ │
  247. │ ┌─────┴─────┐ │ │
  248. │ │ │ │ │
  249. │ More tasks All done │ │
  250. │ │ │ │ │
  251. │ └───────────┼──────────┘ │
  252. │ │ │
  253. └──────────────────┼──────────────────────┘
  254. │
  255. ▼
  256. ┌─────────────────┐
  257. │ Run Exit │
  258. │ Criteria │
  259. └────────┬────────┘
  260. │
  261. ┌─────┴─────┐
  262. │ │
  263. FAIL PASS
  264. │ │
  265. │ ▼
  266. │ ┌─────────────────┐
  267. │ │ Loop complete ✓ │
  268. │ └─────────────────┘
  269. │
  270. ▼
  271. ┌─────────────────┐
  272. │ Fix issues │
  273. │ (loop back) │
  274. └─────────────────┘
  275. ```
  276. **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.
  277. ---
  278. ## How Swarms Work
  279. ```
  280. ┌─────────────────┐
  281. │ Read Source │
  282. │ (plan/context) │
  283. └────────┬────────┘
  284. │
  285. ▼
  286. ┌─────────────────┐
  287. │ Create Tasks │
  288. │ + Dependencies │
  289. │ (from Dep Graph)│
  290. └────────┬────────┘
  291. │
  292. ▼
  293. ┌─────────────────┐
  294. │ Spawn up to N │
  295. │ background agents│
  296. │ (ready tasks) │
  297. └────────┬────────┘
  298. │
  299. ┌───────────────────┼───────────────────┐
  300. │ │ │
  301. ▼ ▼ ▼
  302. ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
  303. │ Agent 1 │ │ Agent 2 │ │ Agent N │
  304. │─────────────│ │─────────────│ │─────────────│
  305. │ implement │ │ implement │ │ implement │
  306. │ EXIT │ │ EXIT │ │ EXIT │
  307. └──────┬──────┘ └──────┬──────┘ └──────┬──────┘
  308. │ │ │
  309. └───────────────────┼───────────────────┘
  310. │
  311. ┌────────────────────┴────────────────────┐
  312. │ MAIN AGENT │
  313. │ │
  314. │ ┌─────────────────┐ │
  315. │ │ Stop & wait │◄──────┐ │
  316. │ │ (notification) │ │ │
  317. │ └────────┬────────┘ │ │
  318. │ │ │ │
  319. │ ▼ │ │
  320. │ ┌─────────────────┐ │ │
  321. │ │ Agent done │ │ │
  322. │ │ Mark completed │ │ │
  323. │ └────────┬────────┘ │ │
  324. │ │ │ │
  325. │ ▼ │ │
  326. │ ┌─────────────────┐ │ │
  327. │ │ Find ready │ │ │
  328. │ │ (pending+empty │ │ │
  329. │ │ blockedBy) │ │ │
  330. │ │ Mark in_progress│ │ │
  331. │ │ Spawn workers │ │ │
  332. │ └────────┬────────┘ │ │
  333. │ │ │ │
  334. │ ┌─────┴─────┐ │ │
  335. │ │ │ │ │
  336. │ More tasks All done │ │
  337. │ │ │ │ │
  338. │ └───────────┼──────────┘ │
  339. │ │ │
  340. └──────────────────┼──────────────────────┘
  341. │
  342. ▼
  343. ┌─────────────────┐
  344. │ Swarm complete ✓│
  345. └─────────────────┘
  346. ```
  347. **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.
  348. ---
  349. ## How Teams Work
  350. ```
  351. ┌─────────────────┐
  352. │ Read Source │
  353. │ (plan/context) │
  354. └────────┬────────┘
  355. │
  356. ▼
  357. ┌─────────────────┐
  358. │ Determine Team │
  359. │ Structure │
  360. │ (2-5+ agents) │
  361. └────────┬────────┘
  362. │
  363. ▼
  364. ┌─────────────────┐
  365. │ Define Contracts│
  366. │ (exact URLs, │
  367. │ JSON shapes, │
  368. │ status codes) │
  369. └────────┬────────┘
  370. │
  371. ▼
  372. ┌─────────────────┐
  373. │ Enter Delegate │
  374. │ Mode + Spawn │
  375. │ all agents │
  376. └────────┬────────┘
  377. │
  378. ┌───────────────────┼───────────────────┐
  379. │ │ │
  380. ▼ ▼ ▼
  381. ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
  382. │ Agent 1 │ │ Agent 2 │ │ Agent N │
  383. │ (Backend) │ │ (Database) │ │ (Frontend) │
  384. │─────────────│ │─────────────│ │─────────────│
  385. │ contracts + │ │ contracts + │ │ contracts + │
  386. │ ownership │◄───►│ ownership │◄───►│ ownership │
  387. │ scope │relay│ scope │relay│ scope │
  388. └──────┬──────┘ └──────┬──────┘ └──────┬──────┘
  389. │ │ │
  390. └───────────────────┼───────────────────┘
  391. │
  392. ┌────────────────────┴────────────────────┐
  393. │ LEAD AGENT │
  394. │ (Delegate Mode) │
  395. │ │
  396. │ ┌─────────────────┐ │
  397. │ │ Relay messages │ │
  398. │ │ Mediate changes │ │
  399. │ │ Resolve conflicts│ │
  400. │ └────────┬────────┘ │
  401. │ │ │
  402. │ ▼ │
  403. │ ┌─────────────────┐ │
  404. │ │ Contract diff │ │
  405. │ │ (built vs spec) │ │
  406. │ └────────┬────────┘ │
  407. │ │ │
  408. └────────────┼────────────────────────────┘
  409. │
  410. ▼
  411. ┌─────────────────┐
  412. │ End-to-end │
  413. │ validation │
  414. └────────┬────────┘
  415. │
  416. ┌─────┴─────┐
  417. │ │
  418. FAIL PASS
  419. │ │
  420. │ ▼
  421. │ ┌─────────────────┐
  422. │ │ Team complete ✓ │
  423. │ └─────────────────┘
  424. │
  425. ▼
  426. ┌─────────────────┐
  427. │ Re-spawn agent │
  428. │ with fix │
  429. └─────────────────┘
  430. ```
  431. **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.
  432. **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.
  433. ---
  434. ## Commands
  435. ### Plan Creators
  436. | Command | Use For |
  437. |---------|---------|
  438. | `/plan-creator <feature>` | New features (brownfield development) |
  439. | `/bug-plan-creator <error> <desc>` | Bug fixes, root cause analysis |
  440. | `/code-quality-plan-creator <files>` | Refactoring, dead code, security |
  441. 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`.
  442. ### Execute Loops (Sequential)
  443. | Command | Source |
  444. |---------|--------|
  445. | `/implement-loop <task>` | Conversation context |
  446. | `/plan-loop <plan>` | Plan file (required) |
  447. | `/tasks-loop [prd.json]` | prd.json |
  448. | `/beads-loop [--label]` | Beads DB |
  449. Cancel any loop: `/cancel-loop`
  450. ### Execute Swarms (Parallel)
  451. | Command | Source |
  452. |---------|--------|
  453. | `/implement-swarm <task>` | Conversation context |
  454. | `/plan-swarm <plan>` | Plan file (required) |
  455. | `/tasks-swarm [prd.json]` | prd.json |
  456. | `/beads-swarm [--epic]` | Beads DB |
  457. Cancel any swarm: `/cancel-swarm`
  458. ### Execute Teams (Agent Teams)
  459. | Command | Source |
  460. |---------|--------|
  461. | `/implement-team <task>` | Conversation context |
  462. | `/plan-team <plan>` | Plan file (required) |
  463. Cancel any team: `/cancel-team`
  464. **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](https://github.com/coleam00/context-engineering-intro/tree/main/use-cases/build-with-agent-team).
  465. ### Convert Formats
  466. | Command | Output | Dependency Source |
  467. |---------|--------|-------------------|
  468. | `/tasks-converter <plan>` | prd.json with `dependsOn` arrays | Plan's `## Dependency Graph` table |
  469. | `/beads-converter <plan>` | Beads issues with `bd dep add` | Plan's `## Dependency Graph` table |
  470. 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.
  471. ### Schema References
  472. | Command | Purpose |
  473. |---------|---------|
  474. | `/plan-schema [validate <path>]` | Plan file format — sections, per-file format, dependency graph rules |
  475. | `/prd-schema [validate <path>]` | prd.json schema — required fields, rejected fields, examples |
  476. | `/beads-schema [validate]` | Beads CLI — issue types, statuses, priorities, commands |
  477. Invoke without arguments for a quick reference. Invoke with `validate` to check an existing file against the schema.
  478. ### Utilities
  479. | Command | Purpose |
  480. |---------|---------|
  481. | `/codemap-creator <dir>` | Create JSON code map via LSP |
  482. | `/codemap-creator --update <map> [--diff\|--mr\|--pr]` | Update existing codemap with changed files |
  483. | `/document-creator <dir>` | DEVGUIDE.md generation |
  484. | `/mr-description-creator` | PR/MR descriptions via gh/glab |
  485. | `/show-status <json\|beads> [path\|epic-id]` | Task/bead status dashboard |
  486. | `/reset-prd <path>` | Reset prd.json to initial state |
  487. | `/reset-beads <epic-id>` | Reopen all tasks in a beads epic |
  488. | `/ralph-config <json\|beads>` | Write RalphTUI config for workflow |
  489. ---
  490. ## What's In A Plan?
  491. Plans are markdown files in `.claude/plans/` with structured sections:
  492. ```markdown
  493. ## Implementation Plan
  494. ### src/types/auth.ts [create]
  495. [Complete code — not pseudocode]
  496. Dependencies: —
  497. Provides: AuthToken type, validateToken() function
  498. ### src/services/auth.ts [create]
  499. [Complete code]
  500. Dependencies: src/types/auth.ts
  501. Provides: AuthService class
  502. ## Dependency Graph
  503. | Phase | File | Action | Depends On |
  504. |-------|-------------------------|--------|-------------------------|
  505. | 1 | `src/types/auth.ts` | create | — |
  506. | 2 | `src/services/auth.ts` | create | `src/types/auth.ts` |
  507. ## Exit Criteria
  508. npm test -- auth && npm run typecheck
  509. ```
  510. **Self-Contained Rule:** Each task must be implementable with ONLY its description. No "see design.md" allowed.
  511. **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.
  512. ---
  513. ## Project Structure
  514. ```
  515. your-project/
  516. ├── .claude/
  517. │ ├── plans/ # Source of truth (plan files with Dependency Graphs)
  518. │ ├── prd/ # prd.json files (from /tasks-converter)
  519. │ ├── maps/ # Code maps (from /codemap-creator)
  520. │ └── prompts/ # Generated prompts
  521. ├── .ralph-tui/ # RalphTUI config (if using)
  522. │ └── config.toml # Tracker, agent settings
  523. └── .beads/ # Beads DB (if using)
  524. ```
  525. **RalphTUI setup:** Run `ralph-tui setup` per project. See [Managing .ralph-tui/](WORKFLOW-TASKS.md#managing-ralph-tui-folder) for config details and switching trackers.
  526. ---
  527. ## Requirements
  528. | Tool | Required? | Purpose |
  529. |------|-----------|---------|
  530. | None | — | Simple workflow (loop/swarm) works out of the box |
  531. | tmux | For Team mode | Agent Teams use tmux for split-pane visualization |
  532. | [Beads CLI](https://github.com/steveyegge/beads) | For Beads workflow | Persistent memory across sessions |
  533. | [Ralph TUI](https://github.com/subsy/ralph-tui) | Optional | Classic Ralph loop executor with TUI dashboard |
  534. **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.
  535. ---
  536. ## Model Configuration
  537. Edit YAML frontmatter in `essentials/commands/*.md` or `essentials/agents/*.md`:
  538. ```yaml
  539. ---
  540. model: opus # opus | sonnet | haiku
  541. ---
  542. ```
  543. ---
  544. ## Troubleshooting
  545. | Problem | Solution |
  546. |---------|----------|
  547. | Loop won't stop | Exit criteria must return exit code 0 |
  548. | Wrong exit criteria | Edit plan directly, re-run loop |
  549. | Context filling up | Plans persist outside conversation |
  550. | prd.json not found | Use `userStories` and `passes` fields |
  551. | Beads CLI missing | `brew tap steveyegge/beads && brew install bd` |
  552. | Swarm runs sequentially | Check plan's Dependency Graph — every task chained to previous degrades swarm to sequential. Only declare real code dependencies. |
  553. ---
  554. ## Documentation
  555. - [WORKFLOW-SIMPLE.md](WORKFLOW-SIMPLE.md) — Default workflow, zero dependencies
  556. - [WORKFLOW-TASKS.md](WORKFLOW-TASKS.md) — Dashboard visualization with Ralph TUI
  557. - [WORKFLOW-BEADS.md](WORKFLOW-BEADS.md) — Persistent task tracking with Beads
  558. - [COMPARISON.md](COMPARISON.md) — Why verification-driven loops matter
  559. ---
  560. ## Contributing
  561. 1. Fork it
  562. 2. Create your branch (`git checkout -b feature/thing`)
  563. 3. Commit changes
  564. 4. Push and open a PR
  565. ---
  566. ## Credits
  567. - [Ralph Wiggum pattern](https://ghuntley.com/ralph/) by Geoffrey Huntley
  568. - [Beads](https://github.com/steveyegge/beads) by Steve Yegge — Persistent memory
  569. - [Ralph TUI](https://github.com/subsy/ralph-tui) by subsy — Classic Ralph loop executor
  570. - [build-with-agent-team](https://github.com/coleam00/context-engineering-intro/tree/main/use-cases/build-with-agent-team) by Cole Medin — Contract-first Agent Teams pattern
  571. - Built for [Claude Code](https://claude.ai/code)
  572. ---
  573. <div align="center">
  574. *Plans define exit criteria. Loops, swarms, and teams run until tests pass. Done means actually done.*
  575. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.