From thrum
Converts plan files into beads epics, TDD-quality tasks, implementation prompts, and worktrees to structure projects before coding begins.
npx claudepluginhub leonletto/thrum --plugin thrumThis skill uses the workspace's default tool permissions.
Convert a plan file into beads epics and tasks with TDD-quality descriptions,
Current session: !`source "${CLAUDE_PLUGIN_ROOT}/scripts/state.sh" && get_current_session 2>/dev/null || echo "No active session"`
Use when you need to create an execution plan from a feature spec - handles worktree context, dispatches subagent for task decomposition, validates quality, analyzes dependencies, groups into phases, and commits the plan
Decomposes GitHub issues into structured Beads epics, tasks, and sub-tasks with objectively verifiable acceptance criteria and dependencies. Useful for planning actionable work in Beads projects.
Share bugs, ideas, or general feedback.
Convert a plan file into beads epics and tasks with TDD-quality descriptions, filled implementation prompts, and ready-to-use worktrees.
Core principle: Task descriptions are the source of truth. Each task is a self-contained implementation guide — detailed enough for an agent to work autonomously.
Announce at start: "I'm using the project-setup skill to decompose this plan into epics and tasks."
digraph when_to_use {
"Have a design doc?" [shape=diamond];
"Have a plan file?" [shape=diamond];
"Need epics & tasks?" [shape=diamond];
"Use brainstorming skill first" [shape=box];
"Use writing-plans skill first" [shape=box];
"Already have tasks in beads" [shape=box];
"Run project-setup" [shape=doublecircle];
"Have a design doc?" -> "Use brainstorming skill first" [label="no"];
"Have a design doc?" -> "Have a plan file?" [label="yes"];
"Have a plan file?" -> "Use writing-plans skill first" [label="no"];
"Have a plan file?" -> "Need epics & tasks?" [label="yes"];
"Need epics & tasks?" -> "Already have tasks in beads" [label="no"];
"Need epics & tasks?" -> "Run project-setup" [label="yes"];
}
Don't use when:
Before starting, verify beads is installed:
bd version
If bd is not found, stop and tell the user:
project-setup requires beads (
bd) for task tracking with dependencies. Install it:brew install dolt # required dependency brew install steveyegge/beads/bd # beads CLI bd init # initialize in your repoSee the beads repo for alternative install methods. Requires dolt v1.81.8+ and bd v0.59.0+.
Do not proceed without beads. Do not fall back to markdown task lists or TodoWrite.
Primary input: plan file path (output of writing-plans, e.g.
dev-docs/plans/2026-02-21-feature-plan.md). The plan references the design doc
— both are read in Phase 1.
Also needed from CLAUDE.md or conversation context:
make test && make lint)>80%)If any are missing, ask the user (prefer multiple choice when possible).
Read the plan file and the design doc it references. Identify major phases, components, data flow, and interfaces.
This skill produces two complementary artifacts per task:
| Artifact | Contains | Authoritative For |
|---|---|---|
| Beads task | Acceptance criteria, deps, status | What must be true to close the task |
| Plan file section | Step-by-step code, file paths, verify commands | How to implement the task |
Both are required. Agents read bd show {TASK_ID} first (what must be true),
then search the plan file for the matching ## Task: {BEAD_ID} section (how to
get there).
If the plan file lacks code for a task, the task description must be detailed enough to stand alone. Flag any plan tasks with vague or missing implementation code during this phase.
Use sub-agents to explore the codebase in parallel:
# All launched in ONE message for parallel execution
Task(subagent_type="Explore", run_in_background=true,
prompt="Explore {{PROJECT_ROOT}}. Map packages, interfaces, and patterns
relevant to: {{FEATURE_DESCRIPTION}}.
Write findings to output/planning/codebase-scan.md")
Task(subagent_type="general-purpose", model="haiku", run_in_background=true,
prompt="Run: bd list --status=open, bd ready, bd blocked.
Identify work related to {{FEATURE_DESCRIPTION}}.
Write to output/planning/beads-context.md")
After agents complete, read the output files. Check bd list / bd ready /
bd blocked for related or overlapping work.
Ask the user focused questions (prefer multiple choice) about anything the plan leaves ambiguous — constraints, scope boundaries, patterns to follow.
After reading the plan and design doc, check if the project has an implementation philosophy doc — a file defining anti-patterns, red flags, and non-negotiable criteria:
Check if the design doc references a philosophy doc (look for "philosophy", "anti-patterns", "implementation standards" keywords)
Search for existing files:
find . -name "*philosophy*" -o -name "*anti-pattern*" -o -name "*implementation-standards*" | head
If found: Read it and extract the key anti-patterns. These will be injected into each epic's prompt in Phase 4.
If not found: Offer to create one from the philosophy-template.md file
in this skill's resources/ directory. Use AskUserQuestion to ask whether
to create it now or skip.
This is the project's "rules of engagement" for implementation agents. Without it, agents can only verify "tests pass" — they can't verify architectural compliance.
Map each plan phase to a beads epic. Each epic should:
Naming: Imperative form — "Implement Sync Protocol", "Build Session Manager", "Create Filter Component".
Present the epic breakdown to the user for approval before creating anything.
Once the user approves the epic breakdown:
bd create "Epic Title" --type=epic --priority=1
# If epics have ordering dependencies:
bd dep add <later-epic-id> <earlier-epic-id>
When creating > 6 tasks, delegate to parallel sub-agents — one per epic:
Task(subagent_type="general-purpose", model="haiku",
prompt="Create these beads tasks under epic {{EPIC_1_ID}}:
1. bd create --title='...' --type=task --priority=2 --description='...'
2. bd create --title='...' --type=task --priority=1 --description='...'
Then set ordering: bd dep add <later_id> <earlier_id>
Return the created task IDs and their titles.")
Task(subagent_type="general-purpose", model="haiku",
prompt="Create these beads tasks under epic {{EPIC_2_ID}}:
...")
After sub-agents return IDs, set cross-epic dependencies directly (requires IDs from multiple sub-agents):
bd dep add <epic-2-id> <epic-1-id>
# Verify no circular dependencies
bd blocked
Every beads task description is a self-contained implementation guide:
Required sections:
## Files
- Create: `exact/path/to/new_file.go`
- Modify: `exact/path/to/existing.go` (add XyzService interface)
- Test: `exact/path/to/new_file_test.go`
## Steps
### Step 1: Write the failing test
```go
func TestSpecificBehavior(t *testing.T) {
result := Function(input)
assert.Equal(t, expected, result)
}
```
### Step 2: Implement
```go
func Function(input Type) ReturnType {
// implementation
}
```
### Step 3: Verify and commit
```bash
go test ./path/to/package/... -run TestSpecificBehavior -v
git commit -m "feat(module): add specific feature"
```
## Acceptance Criteria
- [ ] All tests pass
- [ ] Function handles edge case X
- [ ] Error returns are typed, not generic
Scale code detail to task type:
| Task Type | Code in Steps | Test Detail |
|---|---|---|
| API/Interface design | Full signatures + types | Contract tests, error case tests |
| Business logic | Full implementation code | TDD: failing test → implement → pass |
| Integration/Wiring | Connection code + config | Integration test against mock/real dependency |
| UI/Styling | Full CSS/component code | Visual verification steps, screenshot check |
| Testing-only | N/A | Full test code with scenarios and edge cases |
| Documentation | N/A (outline only) | Verification: doc renders, links work |
Granularity: Each task should be completable in one focused session (30-90 minutes). If a task has more than 5 steps, split it.
Implementation agents log DRY/refactoring opportunities they discover during feature work. These go into a persistent refactoring epic in beads. Check if one exists; if not, create it:
# Search for existing refactoring epic
bd list --type=epic | grep -i refactor
If found, note the epic ID — it will be referenced in the implementation template's "Logging Refactoring Opportunities" section.
If not found, create one:
bd create "Refactoring & DRY Opportunities" --type=epic --priority=3 \
--description="Persistent backlog for refactoring, DRY improvements, and code
organization opportunities discovered during feature work. Tasks are added by
implementation agents as they encounter opportunities. Reviewed and prioritized
by the coordinator periodically."
This epic is project-wide and long-lived — it persists across feature epics.
Do not close it when closing feature epics. Implementation agents find it via
bd list --type=epic | grep -i refactor and add tasks under it.
Before proceeding to Phase 3:
bd blocked should be clean)After creating all tasks, verify the plan file has a searchable anchor for each task. Implementation agents find their code by searching for:
## Task: {BEAD_ID} — {Title}
For each created task, grep the plan file:
grep "## Task:" {{PLAN_FILE}} | head -20
Cross-reference against the created bead IDs. If any task lacks a matching anchor, add it to the plan file at the corresponding section. This ensures agents can search for their section instead of reading the entire (potentially large) file.
After setting all dependencies, scan for tasks that depend on tasks in OTHER epics:
bd blocked
For each cross-epic dependency (where the blocker is in a different epic than the blocked task), record:
| Blocked Task | Blocked By | Blocker's Epic |
|---|
Save this map — it feeds Phase 4, where each implementation prompt will include its epic's cross-epic dependencies so agents know exactly which external tasks to check before starting blocked work.
If no cross-epic dependencies exist, note that and move on.
This phase is an interactive decision gate. You MUST ask the user which worktree and agent to use for each epic before generating prompts. Do not infer silently — present options and let the user choose.
Run these commands and present the results to the user:
# List all active worktrees with branches
git worktree list
# Check which worktrees have in-progress beads tasks
bd list --status=in_progress
# Check the CLAUDE.md worktree table for status info
# (read the "Worktree Layout" section from the project root CLAUDE.md)
For each epic, use AskUserQuestion to let the user choose a worktree. Build
the options from the gathered state:
Option types to present:
| Scenario | Option label |
|---|---|
| Existing idle worktree with related branch | "Reuse <path> (<branch>)" |
| Existing idle worktree, unrelated branch | "Reuse <path>, create new branch" |
| No suitable worktree exists | "Create new worktree" |
| Work is small enough for the current branch | "Use current worktree (<branch>)" |
Include in each option's description:
For "Create new worktree", suggest:
~/.workspaces/{repo}/{feature} (from CLAUDE.md convention)feature/{feature-name} (from thrum-dev)For agent names, suggest a name derived from the feature in each option
description (e.g., impl_{feature}). The user can override.
Based on the user's choice, execute the appropriate setup:
cd <worktree-path>
# Check if clean
git status
# Fast-forward or rebase to thrum-dev if behind
git fetch origin thrum-dev
git rebase origin/thrum-dev
# OR if branches diverged: ask user before rebasing
# Verify redirects are intact
cat .thrum/redirect # should point to <project-root>/.thrum
cat .beads/redirect # should point to <project-root>/.beads
# If redirects are missing or wrong, fix them:
# (from project root)
./scripts/setup-worktree-thrum.sh <worktree-path>
# Verify beads sees shared database
bd where # Should show <project-root>/.beads
bd ready # Should show issues from the shared database
# Register the agent (if not already registered with the right name)
thrum quickstart --name <agent-name> --role implementer \
--module <branch-name> --intent "Implementing <epic-id>"
# From the project root — MUST pass --base thrum-dev
./scripts/setup-worktree-thrum.sh \
<worktree-path> <branch-name> \
--identity <agent-name> --role implementer --base thrum-dev
The setup script handles: branch creation, worktree creation, thrum redirect,
beads redirect, and thrum quickstart registration.
# Just register the agent
thrum quickstart --name <agent-name> --role implementer \
--module <current-branch> --intent "Implementing <epic-id>"
# Verify beads
bd where
bd ready
Before proceeding to Phase 4, verify for each worktree:
cd <worktree-path>
# Beads sees shared database
bd where
# Expected: <project-root>/.beads
# Issues are visible
bd ready
# Thrum daemon reachable
thrum daemon status
# Redirects correct
cat .thrum/redirect
cat .beads/redirect
# Agent registered
thrum agent list --context
If a new worktree was created, update the worktree table in the project root CLAUDE.md. Use the existing table format:
| `<path>` | `<branch>` | <purpose> | active |
"not in a bd workspace" — The beads redirect file is missing or incorrect:
ls -la .beads/
cat .beads/redirect
bd where
# Fix: run setup-worktree-thrum.sh <path> (redirect-only mode)
Wrong database — bd where shows a local database instead of shared:
bd where
# Should show <project-root>/.beads, not a local database
# Fix: rm .beads/*.db && re-run setup script
Sync warnings in worktrees — Warnings about "snapshot validation failed" or "git status failed" are normal in worktrees. If the final output shows success, it's fine.
At the end of this phase, you should have a confirmed assignment for each epic:
| Epic | Worktree Path | Branch | Agent Name |
|---|---|---|---|
<epic-id> | <path> | <branch> | <agent-name> |
These values feed directly into the {{PLACEHOLDER}} resolution in Phase 4.
CRITICAL: You MUST generate prompts yourself. Do NOT delegate prompt generation to sub-agents. Sub-agents take shortcuts — they skip sections, leave template metadata in the output, fail to strip meta-sections, and produce prompts that confuse the implementation agent. The prompt is the most important artifact this skill produces. It defines how the implementation agent behaves for the entire epic. Treat it with the same care as writing code.
For each epic/worktree assignment, generate a filled prompt file.
Read the implementation-agent.md file from this skill's resources/
directory.
This is the source template. Do not work from memory — read the actual file every time.
For each epic's prompt, generate the {{ANTI_PATTERNS}} content:
display:none")AskUserQuestion before injecting into the promptWhy this matters: The verifier sub-agent pattern in the implementation template uses these red flags to check each task. Generic "tests pass" verification misses architectural violations that pass tests but violate design decisions.
Perform literal find-and-replace on every {{PLACEHOLDER}} in the template. All
worktree-related values come from the Phase 3 assignments:
| Placeholder | Source |
|---|---|
{{EPIC_ID}} | Beads epic ID from Phase 2 |
{{EPIC_TITLE}} | Epic title (used in commit messages) |
{{WORKTREE_PATH}} | From Phase 3 worktree assignment |
{{BRANCH_NAME}} | From Phase 3 worktree assignment |
{{PROJECT_ROOT}} | Absolute path to the project root |
{{DESIGN_DOC}} | Absolute path to the design spec |
{{REFERENCE_CODE}} | Relevant reference code paths (relative OK if committed) |
{{QUALITY_COMMANDS}} | Test/lint commands — scoped to packages this epic modifies. Avoid full-suite commands (e.g., go test ./...) that hit pre-existing failures. Example: go build ./... && go test ./internal/processing/localstore/ -v |
{{COVERAGE_TARGET}} | Coverage threshold (e.g., >80%) |
{{AGENT_NAME}} | From Phase 3 agent registration |
{{PLAN_FILE}} | Absolute path to the plan file (primary input) |
{{ANTI_PATTERNS}} | Generated in Step 1.5 from design doc + philosophy doc |
{{CROSS_EPIC_DEPS}} | From Phase 2 cross-epic dependency map. If no cross-epic deps, replace with "No cross-epic dependencies." |
IMPORTANT — Absolute paths for gitignored files: {{DESIGN_DOC}},
{{PLAN_FILE}}, and the saved prompt path (dev-docs/prompts/) are typically
gitignored. Agents in worktrees cannot resolve relative paths to these files
because worktrees only share committed content. Always resolve these to absolute
paths (e.g., /Users/you/project/dev-docs/plans/file.md, not
dev-docs/plans/file.md). This also applies to beads task descriptions — any
reference to a plan or design doc in a task description must be an absolute
path.
Strip template meta-sections. The following sections exist to document the template itself and MUST NOT appear in the filled prompt:
## Purpose — template description, not agent instructions## CRITICAL: Prompt Generation Rules — instructions for the coordinator
filling the template, not for the implementation agent## Inputs Required — placeholder documentation for the coordinator, not the
agent. Including this section confuses agents with {{PLACEHOLDER}}
descriptions alongside already-resolved values.<!-- STRIP ... --> HTML comment blocks — these are meta-instructions
that must be removed along with any text they annotateKeep all behavioral sections. The output must contain every behavioral section from the template — Sub-Agent Strategy, all 4 Phases (including the new Phase 3: Self-Review Gate), Resume Quick Reference, etc. — with placeholders replaced by resolved values. Do not omit, reorganize, or summarize behavioral sections.
Add a header before the filled template with quick context, task inventory, and architecture notes specific to this feature:
# Implementation Prompt: {{FEATURE_NAME}}
> Generated by project-setup on YYYY-MM-DD Plan: {{PLAN_FILE}} Design doc:
> {{DESIGN_DOC}} Epic: {{EPIC_ID}} (N tasks)
## Quick Context
<!-- 2-3 sentences about what this epic delivers and key decisions -->
<!-- Optional: task inventory table, architecture notes, suggested batches -->
## Worktree Setup
<!-- If worktree was already created in Phase 3, note that here: -->
Worktree ready at `{{WORKTREE_PATH}}` on branch `{{BRANCH_NAME}}`. Agent
`{{AGENT_NAME}}` registered.
<!-- If worktree needs to be created by the implementation agent: -->
./scripts/setup-worktree-thrum.sh {{WORKTREE_PATH}} {{BRANCH_NAME}} \
--identity {{AGENT_NAME}} --role implementer --base thrum-dev
---
<!-- PASTE the filled template below this line.
STRIP the "## Purpose" and "## Inputs Required" sections — those are
template meta-documentation, not agent instructions.
START from "## Sub-Agent Strategy" through "## Resume Quick Reference".
All behavioral sections must be present with placeholders resolved. -->
Save to dev-docs/prompts/{feature}.md, then commit:
git add dev-docs/prompts/
git commit -m "plan: add implementation prompts for {{FEATURE_NAME}}"
Too vague tasks: "Add validation" is not a step —
if err := validate(input); err != nil { return fmt.Errorf(...) } is. Prefer
complete code over pseudocode.
Too large tasks: If a task has more than 5 steps, split it. Each task = one focused session.
Missing dependencies: Forgetting cross-epic deps leads to agents starting
work they can't finish. Always run bd blocked to verify.
Skipping worktree selection: Always ask the user which worktree to use.
Check git worktree list and bd list --status=in_progress for idle worktrees
before proposing new ones. Never silently assign worktrees.
Wrong base branch: The setup script defaults --base to main. Always pass
--base thrum-dev explicitly since features branch from thrum-dev.
Generating prompts before worktree setup: Prompts embed the worktree path, branch, and agent name. These must be confirmed in Phase 3 before generating prompts in Phase 4.
Skipping the plan file: This skill reads the plan file (from writing-plans) as primary input. If you only have a design doc, use writing-plans first to produce the plan.
Delegating prompt generation to sub-agents: The filled implementation prompt
is the most critical artifact. Sub-agents take shortcuts: they leave template
meta-sections (## Inputs Required, ## Purpose) in the output, skip
behavioral sections, fail to properly resolve placeholders, and produce prompts
that confuse the implementation agent. Always generate prompts yourself in the
main context.
Leaving template meta-sections in filled prompts: The ## Purpose and
## Inputs Required sections are documentation ABOUT the template, not
instructions FOR the agent. Strip them. If they appear in the filled prompt,
agents see {{PLACEHOLDER}} descriptions alongside already-resolved values,
which is confusing and wasteful of context.
Using relative paths for gitignored files: Plan files, design docs, and
prompts live in gitignored directories (dev-docs/, docs/plans/). Agents in
worktrees can't see these via relative paths — the worktree only shares
committed files. Always use absolute paths (starting with /) when referencing
these files in: placeholder resolution, beads task descriptions, and the
generated implementation prompt. This is the most common source of "file not
found" errors for worktree agents.
When complete, you should have produced:
dev-docs/prompts/{feature}.mdAfter setup is complete, each epic is ready for an implementation agent. The
filled prompt at dev-docs/prompts/{feature}.md is the session start prompt —
give it directly to the implementing agent.