swarm-from-markdown

Swarm from Markdown

Converts a markdown checklist file into a self-organizing Claude Code swarm. Each unchecked - [ ] item becomes a TaskCreate call and a spawned worker agent. Checked items (- [x], - [X]) are skipped automatically.

When to Use This Skill

Use when:

• You have a todo.md, checklist.md, or any markdown file with - [ ] checkbox items
• You want to dispatch independent checklist items as parallel swarm tasks
• You need to avoid hand-expanding long task lists into manual TaskCreate loops
• Your task list changes over time and you want stable worker IDs for resumption

Quick Start (Worked Example)

Given tasks.md:

- [ ] Implement the login endpoint
- [x] Already done — skip this
- [ ] Write unit tests for auth
- [ ] Update API documentation

Run the parser:

uv run scripts/markdown_to_task_pool.py tasks.md --json

Output:

{
  "team_name": "swarm-tasks",
  "items": [
    {"index": 0, "worker_id": "worker-0", "text": "Implement the login endpoint"},
    {"index": 1, "worker_id": "worker-1", "text": "Write unit tests for auth"},
    {"index": 2, "worker_id": "worker-2", "text": "Update API documentation"}
  ],
  "worker_count": 3
}

Then orchestrate the swarm:

// Step 1 — Create team
TeamCreate({ team_name: "swarm-tasks" })

// Step 2 — Create one task per unchecked item (checked item is excluded)
TaskCreate({ subject: "Implement the login endpoint", description: "Implement the login endpoint", activeForm: "Working on Implement the login endpoint..." })
TaskCreate({ subject: "Write unit tests for auth", description: "Write unit tests for auth", activeForm: "Working on Write unit tests for auth..." })
TaskCreate({ subject: "Update API documentation", description: "Update API documentation", activeForm: "Working on Update API documentation..." })

// Step 3 — Spawn one worker per task (or use --workers N to cap concurrency)
Agent({ team_name: "swarm-tasks", name: "worker-0", subagent_type: "general-purpose", prompt: "...", run_in_background: true })
Agent({ team_name: "swarm-tasks", name: "worker-1", subagent_type: "general-purpose", prompt: "...", run_in_background: true })
Agent({ team_name: "swarm-tasks", name: "worker-2", subagent_type: "general-purpose", prompt: "...", run_in_background: true })

// Step 4 — Observe pool state
TaskList()