issue-to-beads

What this skill does

# Issue-to-Beads

Converts a GitHub issue into a structured Beads work breakdown with epics, tasks, and sub-tasks - each with 3-5 objectively verifiable acceptance criteria. All beads must have relationships and dependencies mapped out.

## Prerequisites

- The user's project must have Beads initialized (`bd init` already run)
- The `bd` CLI must be available on PATH
- The `gh` CLI must be authenticated for the target GitHub repo
- The user should be in (or specify) the project directory containing `.beads/`
- The project should have an `AGENTS.md` file — read it first, as its acceptance criteria conventions and landing-the-plane workflow take precedence over this skill's defaults

## Workflow Overview

```
GitHub Issue → Fetch → Branch & Worktree → Plan-Only → Work Breakdown → File Beads → Review & Refine (up to 5x) → Handoff
```

The skill operates in seven phases:

1. **Fetch** — Pull the GitHub issue content and present a summary
2. **Branch** — Create a git branch and check out a worktree for the issue
3. **Plan** — Load the plan-only skill to explore the codebase and develop an approved plan
4. **Breakdown** — Collaborate with the user to agree on the Beads work breakdown
5. **File** — Create detailed Beads epics, tasks, sub-tasks, verifiable criteria, and beads relationships and dependencies
6. **Refine** — Review, proofread, polish, and iterate (up to 5 rounds)
7. **Handoff** — Show the tree, ready queue, and sync to git

## Phase 1: Fetch the GitHub Issue

Accept any of these input formats:
- Issue number: `#42` or `42`
- Full URL: `https://github.com/owner/repo/issues/42`
- Owner/repo + number: `myorg/myrepo#42`

Fetch the issue using `gh`:

```bash
gh issue view <number> --json title,body,labels,assignees,milestone,comments --repo <owner/repo>
```

If `--repo` is not specified, `gh` will use the current directory's git remote. If the fetch fails, ask the user for the correct repo.

Also fetch any linked issues or referenced PRs mentioned in the body to build context.

After fetching, present a brief summary to the user covering: the issue's goal, key requirements, constraints, and any open questions or ambiguities you noticed. This sets the stage for planning.

## Phase 2: Branch & Worktree

After fetching the issue, create a dedicated branch and worktree so all Beads work happens in isolation from the main branch.

### Branch Naming

Derive the branch name from the issue number and title:

```
<issue-number>-<slugified-title>
```

For example, issue #42 titled "Add user authentication" becomes `42-add-user-authentication`. Keep the slug short — truncate to ~50 characters if needed.

### Create Branch and Worktree

```bash
# Create the branch from the current HEAD
git branch <branch-name>

# Check out a worktree for the branch
git worktree add ../<branch-name> <branch-name>
```

The worktree is created as a sibling directory to the current repo. After creating it, **all subsequent work (planning, filing beads, syncing) must happen inside the worktree directory**.

If a branch or worktree with that name already exists, ask the user whether to reuse it or pick a different name.

## Phase 3: Plan (via plan-only skill)

**IMPORTANT: Do NOT use `EnterPlanMode` or built-in plan mode.** Built-in plan mode auto-executes after approval, which is not what we want here.

Load the `plan-only` skill using the `Skill` tool:

```
Skill: beads-planner:plan-only
```

The plan-only skill will:
1. Explore the codebase using Explore/Plan agents
2. Develop an implementation plan
3. Write it to `.claude/plans/<slug>.md`
4. Present it to the user for approval
5. **Stop** — no auto-execution

Once the plan-only skill completes and the user has approved the plan, copy the plan file into the project's `.plan` directory so it persists as a project artifact:

```bash
mkdir -p .plan
# Find the plan file that plan-only just wrote (most recent file in .claude/plans/)
ls -t .claude/plans/*.md | head -1
# Copy it with the issue-derived name
cp <plan-file> .plan/<issue-number>-<slug>.md
```

Use the issue number and slug from Phase 2 for the destination filename (e.g., `.plan/42-add-user-authentication.md`). The source file is whatever plan-only actually wrote — do not assume its slug matches the branch slug. Find the most recently created `.md` file in `.claude/plans/` and use that.

Then proceed to Phase 4. The plan file serves as a reference for the work breakdown — it is not a trigger for implementation.

If the user rejects the plan, stop the entire workflow.

## Phase 4: Work Breakdown

Using the approved plan as a foundation, propose the Beads work breakdown. This is where the plan gets translated into concrete, trackable work items.

### Step 4a: Propose the Work Breakdown

Present a draft work breakdown structured as:

```
Epic: [Title derived from issue]
  ├── Task 1: [Title]
  │   ├── Acceptance Criteria: [verifiable criteria]
  │   └── Blocked by: —
  ├── Task 2: [Title]
  │   ├── Acceptance Criteria: [verifiable criteria]
  │   └── Blocked by: Task 1
  └── Task 3: [Title]
      ├── Acceptance Criteria: [verifiable criteria]
      └── Blocked by: —  (can parallelize with Task 1)
```

Pay careful attention to:
- **Organization**: All tasks must belong to an Epic, which is effectively the top-level container for the GitHub issue.
- **Dependencies**: Which tasks block which? Get this right — it determines what shows up in `bd ready`.
- **Parallelization**: Tasks that are independent of each other should have no blocking dependency between them, so multiple workers can pick them up simultaneously.
- **Granularity**: File a bead for any work that would take longer than about 2 minutes to finish. If something is trivially quick, it can be a bullet point inside a parent task's description rather than its own bead.
- **Detailed designs**: Each task description should give the implementing agent enough context to start working without needing to re-read the entire GitHub issue.

Solicit feedback on the breakdown:
- Are these the right tasks?
- Is the dependency ordering correct?
- Are any tasks missing?
- Should any tasks be split or merged?

### Step 4b: Refine Acceptance Criteria

Every task must have **acceptance criteria that are objectively verifiable** — meaning a different person (or an AI agent) could determine pass/fail without subjective judgment.

Follow the conventions from the project's `AGENTS.md`:

**Always include as the final criterion:**
- "Typecheck passes"

**For tasks with testable logic, also include:**
- "Tests pass"

**For tasks that change UI, also include:**
- "Verify in browser"

Good acceptance criteria examples:
- "Status column added to tasks table with default 'pending'"
- "Filter dropdown has options: All, Active, Completed"
- "Clicking delete shows confirmation dialog"
- "Running `npm test` produces 0 failures"
- "The endpoint `GET /api/users` returns HTTP 200 with a JSON array"
- "The file `src/auth/jwt.ts` exists and exports a `verifyToken` function"

Bad acceptance criteria (too vague — never use these):
- "Works correctly"
- "User can do X easily"
- "Good UX"
- "Handles edge cases"

If something is inherently subjective (like design quality), decompose it into measurable proxies:
- "The component renders without console errors"
- "Lighthouse accessibility score ≥ 90"
- "All text meets WCAG AA contrast ratio (4.5:1)"

Present the acceptance criteria to the user for approval.

### Step 4c: Final Confirmation

Show the complete plan one more time with all tasks, dependencies, priorities, and acceptance criteria. Ask the user to confirm before proceeding to filing.

## Phase 5: File Beads

Now grind through creating every issue in Beads. This is the execution-heavy phase — be thorough and methodical.

### Beads Hierarchy

Beads uses hierarchical IDs rooted on an epic:

```
bd-a3f8        Epic
bd-a3f8.1      Task (child of epic)
bd-a3f8.2      Task (child of epic)
bd-a3f8.2.1    Sub-task (child of task)
```

Use `--parent <id>` when cr