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-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add jbdamask/john-claude-skills.

Contents

Discovered from source

Skills 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

  1. If the conventions keep a JSONL export in git, write it: bd export -o <path> (usually .beads/issues.jsonl). Do not run bd sync for this: it syncs the Dolt remote and writes no file.
  2. Stage only named files: the plan file and the export path. Never git add .beads/ or git add -A; .beads/ holds the database, locks and backups.
  3. Commit with a plain message: beads for #<n>: <issue title>.
  4. Push the current branch: git push (or git 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.
  5. 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.
  6. git status -sb | head -1 must 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#42 or its URL. Fetch it with gh issue view <n> --json number,title,body,labels,comments,url (add --repo owner/repo when 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 prime once 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_ref and spec_id format.
  • 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 the git-push-and-tag skill 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_key already makes the parent-child link; do not repeat it in edges.
  • metadata.files lists every file the bead edits or creates; metadata.new_files the ones that do not exist yet. The check uses both.
  • Priorities 0 to 3. Use type task unless the work is a bug, spike, chore or feature.
  • Graph children get flat ids (proj-x7k2), not dotted ones; bd ready --parent <epic> and bd show <epic> --children still group them.

Steps

  1. Read the conventions, the issue, the spec and the files they name. Run bd list --all --external-ref gh-<n> --json to catch beads already filed for it; if some exist, add only what is missing and say so.
  2. Write the plan file.
  3. 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 in new_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 prints OK. Then bd create --graph <plan> --dry-run, which checks the graph against bd itself.
  4. 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.
  5. 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.
  6. Verify: bd lint <epic id> <child ids...> (acceptance present), bd dep cycles, bd ready --parent <epic id>.
  7. Do what the conventions say about git, export and the issue label (the git-push-and-tag skill, 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.md was 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 blocks edge.
  • Issue already broken down: add only the missing beads, with parent_id set 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 codebase
  • WebFetch, WebSearch — for research
  • Task (with Explore or Plan subagent types) — for delegated research and design
  • AskUserQuestion — for clarifying requirements and presenting the plan
  • Write — only for writing the plan file to .claude/plans/<slug>.md
  • Bash — only for read-only commands (git log, git status, ls, etc.)

Prohibited:

  • Edit on any file other than the plan file
  • Write to any path outside .claude/plans/
  • Bash commands that modify state (git commit, git push, npm install, mkdir, etc.)
  • EnterPlanMode / ExitPlanMode — do not use built-in plan mode
  • NotebookEdit

Workflow

The skill operates in five phases:

Phase 1: Initial Understanding

Explore the codebase and understand the user's request thoroughly.

  1. Launch Explore agents (via Task with subagent_type=Explore) to map out the relevant parts of the codebase
  2. Read key files directly with Read, Glob, Grep
  3. If the project has an AGENTS.md or CLAUDE.md, read it for conventions
  4. 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.

  1. Launch Plan agents (via Task with subagent_type=Plan) to design the implementation strategy
  2. Identify critical files that will need to change
  3. Consider architectural trade-offs and alternative approaches
  4. Map out dependencies between changes

Phase 3: Review

Validate the emerging plan against the codebase.

  1. Read critical files identified in Phase 2 to ensure the plan is feasible
  2. Check for potential conflicts with existing code
  3. Verify assumptions about APIs, interfaces, and data structures
  4. If new questions arise, use AskUserQuestion to 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:

  1. Approve — The plan is accepted. The skill ends here.
  2. Revise — The user wants changes. Go back to the relevant phase and iterate.
  3. 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

More from jbdamask/john-claude-skills

All 4