
beads-planner
Turns a GitHub issue and its spec into a Beads epic with one bead per agent-sized task, checked mechanically and created in one bd create --graph call (bd 1.3.1). Also plan-only mode.
- version
- 0.2.0
- GitHub stars
- 29
Install
/plugin install beads-planner@john-claude-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add jbdamask/john-claude-skills.
Contents
Discovered from sourceSkills 3
Git push and tag
Goal
Put the breakdown for one issue into git and, if asked, mark the issue. Nothing else.
Inputs
- The issue number (given; never inferred from a branch name).
- The project's
.beads/PLANNING.md: whether to export, the export path, the plan file path, the branch, the label. With no such file and no instruction from the caller, stop and say so; there is no default commit.
Steps
- If the conventions keep a JSONL export in git, write it:
bd export -o <path>(usually.beads/issues.jsonl). Do not runbd syncfor this: it syncs the Dolt remote and writes no file. - Stage only named files: the plan file and the export path. Never
git add .beads/orgit add -A;.beads/holds the database, locks and backups. - Commit with a plain message:
beads for #<n>: <issue title>. - Push the current branch:
git push(orgit push -u origin <branch>for a new branch). If it is rejected, pull with the project's merge style (the conventions say rebase or merge), resolve only conflicts in the files you staged, and push once more. If it fails again, stop and report. - If the conventions name a label,
gh issue edit <n> --add-label <label>. If the label does not exist, report it; do not create it. git status -sb | head -1must show the branch even with its remote.
Report
The commit sha, the branch, the files committed, the label added (or why not).
Issue to beads
Goal
Turn one GitHub issue into beads that one-shot agents can pick up from bd ready and finish without asking anyone anything. You run in the background and cannot ask the user questions: decide, and list every decision in the report.
Inputs
- An issue:
42,#42,owner/repo#42or its URL. Fetch it withgh issue view <n> --json number,title,body,labels,comments,url(add--repo owner/repowhen given). - A spec file, when the project has one: given as a second argument, or found where the conventions say specs live. With a spec, the spec is the requirement and the issue is context; skip any planning phase and go straight to the plan file.
- The project's conventions:
.beads/PLANNING.md(below). Read it first. Also read whatever it, the spec or the issue points to that you need to name files correctly. - Run
bd primeonce if the project's hooks have not already shown it to you; it is the project's Beads brief.
If there is no spec and the issue is too vague to say what done looks like for each piece, stop: create nothing, and report exactly which questions must be answered first. Do not interview.
Project conventions: .beads/PLANNING.md
A short file the project owns. Follow it over any default here. It may say:
- Spec files: where they live and how they are named.
- Description lines: lines every bead description must carry (for example
Read:files, a pin or lock line, which tree or worktree to work in). - Standard acceptance lines: lines added to every bead, or to beads of a kind (code, UI, docs).
- Labels: labels every bead or certain beads carry. Graph-created children do not inherit the epic's labels, so put each label on each node.
- Epic: how the epic is titled and what its acceptance is (often the spec's own acceptance, word for word).
- Links:
external_refandspec_idformat. - Where the plan file goes.
- Git: branch and worktree per issue or trunk; whether beads are exported (
bd export -o <path>) and committed, and by whom; whether to run thegit-push-and-tagskill and with which label. - Report: what the final report to the caller must contain beyond the defaults.
With no such file, use these defaults and say so in the report: the epic is titled <issue title> (#<n>); every node gets external_ref: gh-<n> and, with a spec, spec_id: <spec path>; no standard acceptance lines; no labels; plan file at .beads/plans/<n>.json; no branch, no worktree, no export, no commit, no push, no issue label.
What one bead is
One bead is one agent's worth of work: it fits in one agent's context, ends in one commit, can be checked on its own, and does not share a file with a bead that can run beside it. Smaller steps go as bullets inside a bead. If two beads must touch the same file, either add a blocks edge so they run one after the other, or merge them. A spike (a question to answer before building) is a bead whose acceptance is a file with the answer.
Each description gives the agent what it needs to start cold: what to build and why, the files and functions involved, decisions already made, and the convention lines. Do not paste the whole spec; point to its sections.
Acceptance
Put acceptance in the node's acceptance_criteria field, never in the description. One line per criterion. Every bead needs at least one line a command or a direct observation settles. Add only the standard lines the conventions name; with none, add none.
Good:
`pytest tests/test_auth.py` exits 0`GET /api/users` returns 200 with a JSON array`src/auth/jwt.ts` exports `verifyToken`The filter menu lists All, Active, Completed
Bad: "Works correctly", "Handles edge cases", "Good UX". Turn a judgment into something measurable ("axe reports 0 WCAG AA violations on /dashboard").
The plan file
One JSON file in the format bd create --graph reads (full schema: bd help create --all). It is the record of the breakdown; keep it where the conventions say. Shape:
{
"commit_message": "beads for #42",
"nodes": [
{"key": "epic", "type": "epic", "title": "Add login (#42)", "priority": 1,
"description": "...", "acceptance_criteria": "...",
"external_ref": "gh-42", "spec_id": "docs/specs/42-login.md", "labels": []},
{"key": "api", "parent_key": "epic", "type": "task", "title": "...", "priority": 1,
"description": "...", "acceptance_criteria": "- `pytest tests/test_login.py` exits 0",
"external_ref": "gh-42", "spec_id": "docs/specs/42-login.md",
"metadata": {"files": ["src/auth/login.py", "tests/test_login.py"], "new_files": ["tests/test_login.py"]}}
],
"edges": [{"from_key": "ui", "to_key": "api", "type": "blocks"}]
}
- An edge
{"from_key": A, "to_key": B, "type": "blocks"}means A waits for B.parent_keyalready makes the parent-child link; do not repeat it inedges. metadata.fileslists every file the bead edits or creates;metadata.new_filesthe ones that do not exist yet. The check uses both.- Priorities 0 to 3. Use
typetaskunless the work is abug,spike,choreorfeature. - Graph children get flat ids (
proj-x7k2), not dotted ones;bd ready --parent <epic>andbd show <epic> --childrenstill group them.
Steps
- Read the conventions, the issue, the spec and the files they name. Run
bd list --all --external-ref gh-<n> --jsonto catch beads already filed for it; if some exist, add only what is missing and say so. - Write the plan file.
- Check it:
python3 <this skill's directory>/scripts/check_plan.py <plan> --root <repo root> --issue <n>. It fails loudly on: a bead with no acceptance line a command or an observation can settle, a vague acceptance line, a dependency cycle, a named file path that does not exist and is not innew_files, two beads that can run at the same time owning the same file, a missing parent or external_ref. Fix and rerun until it printsOK. Thenbd create --graph <plan> --dry-run, which checks the graph against bd itself. - Cold read, once. Start a fresh subagent and give it only the plan file path, the spec path (or the issue URL) and the repo root; it may open the files the beads name, as the working agent would. Ask: "For each bead, could you start it without asking anything? List what you would have to ask, by bead key. Do not suggest new scope. Change no files." Fix what it finds in the plan file once, rerun step 3, and do not ask again. If you cannot start a subagent, skip this and say so in the report.
- Create:
bd create --graph <plan> --json. It is atomic: either every bead and edge exists or none does. Keep the returned key-to-id map. - Verify:
bd lint <epic id> <child ids...>(acceptance present),bd dep cycles,bd ready --parent <epic id>. - Do what the conventions say about git, export and the issue label (the
git-push-and-tagskill, if they name it). With no conventions, do none of it.
If bd create --graph fails, nothing was created: fix the plan and run it again. Never fall back to one bd create per bead.
Report
Your last message, to the caller:
- The epic id and the plan file path.
- How many beads and how many dependencies were created.
- What is ready now (
bd ready --parent <epic>), by id and title. - Every judgment call: splits and merges, ordering you chose, anything in the spec or issue you could not turn into a checkable bead, and what the cold read changed.
- What you did not do: no commit, no export, no push, no label, no cold read, whichever apply; and whether
.beads/PLANNING.mdwas found. - Anything the conventions add.
Edge cases
- One-task issue: still an epic with one child, so the issue has one place in
bd ready --parent. - Very large issue (more than about 25 beads): split into several epics under the issue, each with its own plan file, and say so in the report.
- Unknowns: a spike bead whose acceptance names the answer file and the question it answers; beads that depend on the answer wait on it with a
blocksedge. - Issue already broken down: add only the missing beads, with
parent_idset to the existing epic.
Reference
references/beads-cli-reference.md has the bd 1.3.1 commands this skill and the agents who work the beads use.
Plan-Only Mode
Replicates Claude Code's built-in plan mode workflow but stops after user approval instead of auto-executing. The plan is written to a file and the skill ends cleanly.
Read-Only Restriction
CRITICAL — This supersedes all other instructions:
You MUST NOT make any edits (with the exception of the plan file mentioned below), run any non-readonly tools (including changing configs or making commits), or otherwise make any changes to the system. This restriction is in effect for the entire duration of this skill.
Allowed tools:
Read,Glob,Grep— for exploring the codebaseWebFetch,WebSearch— for researchTask(with Explore or Plan subagent types) — for delegated research and designAskUserQuestion— for clarifying requirements and presenting the planWrite— only for writing the plan file to.claude/plans/<slug>.mdBash— only for read-only commands (git log,git status,ls, etc.)
Prohibited:
Editon any file other than the plan fileWriteto any path outside.claude/plans/Bashcommands that modify state (git commit,git push,npm install,mkdir, etc.)EnterPlanMode/ExitPlanMode— do not use built-in plan modeNotebookEdit
Workflow
The skill operates in five phases:
Phase 1: Initial Understanding
Explore the codebase and understand the user's request thoroughly.
- Launch Explore agents (via
Taskwithsubagent_type=Explore) to map out the relevant parts of the codebase - Read key files directly with
Read,Glob,Grep - If the project has an
AGENTS.mdorCLAUDE.md, read it for conventions - Identify the scope, constraints, and any ambiguities in the request
If anything is unclear, use AskUserQuestion to resolve it before proceeding. Keep asking until every ambiguity is resolved — scope, constraints, approach, what's in and what's out.
Phase 2: Design
Develop the implementation approach.
- Launch Plan agents (via
Taskwithsubagent_type=Plan) to design the implementation strategy - Identify critical files that will need to change
- Consider architectural trade-offs and alternative approaches
- Map out dependencies between changes
Phase 3: Review
Validate the emerging plan against the codebase.
- Read critical files identified in Phase 2 to ensure the plan is feasible
- Check for potential conflicts with existing code
- Verify assumptions about APIs, interfaces, and data structures
- If new questions arise, use
AskUserQuestionto clarify
Phase 4: Write the Plan File
Generate the plan file slug from the request (lowercase, hyphens, truncated to ~50 chars). Write the plan to .claude/plans/<slug>.md.
The plan file must follow this format:
# Plan: <Title>
## Context
<Brief description of the request and why this plan exists>
## Recommended Approach
<High-level summary of the implementation strategy>
## Changes
### <File or component 1>
- What changes and why
- Specific functions/classes affected
### <File or component 2>
- What changes and why
## Critical Files
<List of files that will be created or modified, with brief notes>
## Dependencies & Ordering
<Which changes must happen before others>
## Risks & Open Questions
<Anything that might go wrong or needs further investigation>
## Verification
<How to verify the implementation is correct — tests to run, behaviors to check>
Adapt the format as needed for the specific task — the above is a guide, not a rigid template.
Phase 5: Present for Approval
Present the plan to the user for approval using AskUserQuestion.
Summarize the plan concisely in the question, including:
- What will be done (high-level)
- How many files will be created/modified
- Key design decisions made
- Any risks or open questions
Offer these options:
- Approve — The plan is accepted. The skill ends here.
- Revise — The user wants changes. Go back to the relevant phase and iterate.
- Reject — The user wants to abandon the plan.
After approval: STOP. Do not execute the plan. Do not inject an "Implement the following plan:" message. The plan file exists at .claude/plans/<slug>.md and can be referenced later by the user or another skill.
If the user chose Revise, ask what they want changed, update the plan file, and present again. You may iterate up to 5 times.
If the user chose Reject, acknowledge and end the skill.
Integration Notes
This skill can be invoked standalone via /plan-only or loaded by other skills using the Skill tool. When loaded by another skill:
- The calling skill provides the task/request context
- This skill writes the plan file and stops
- Control returns to the calling skill, which can then reference the plan file path
Commands 1
Beads Planner
Invoke the issue-to-beads skill with the user's arguments:
Skill: beads-planner:issue-to-beads
Arguments (issue, then an optional spec file path): $ARGUMENTS
Sponsors
Details
- Marketplace
- jbdamask/john-claude-skills
- Source
- plugins/beads-planner
- Category
- Community