Plan to Issues

Overview

Turn specs and implementation plans into a set of independent, well-structured GitHub issues ready for parallel execution. Each issue gets acceptance criteria, file dependency mapping, wave assignment, and priority labels.

Core principle: Issues that touch the same files MUST NOT be in the same wave. File overlap = sequential execution.

Announce at start: "I'm using the plan-to-issues skill to decompose this plan into GitHub issues."

Iron Law:

ISSUES MODIFYING THE SAME FILE MUST NEVER RUN IN THE SAME WAVE

When to Use

• Implementation plan is ready and needs to be broken into trackable units of work
• Spec document needs decomposition into parallel-safe issues
• Planning a multi-issue feature that will use /taskmaestro for parallel execution
• Roadmap or design doc needs to become actionable GitHub issues

Use this ESPECIALLY when:

• The plan has 3+ independent deliverables
• Multiple developers or agents will work in parallel
• You need wave grouping for /taskmaestro execution

Don't use when:

• Single-file change or trivial fix (just create the issue directly)
• Requirements are still unclear (use brainstorming skill first)
• Plan hasn't been written yet (use writing-plans skill first)

Input

The skill accepts one of:

• Spec document path: docs/plans/YYYY-MM-DD-<feature>.md
• Plan document path: Any markdown file with implementation steps
• Inline description: Direct feature description in the prompt

The Five Phases

Phase 1: Analyze — Identify Independent Deliverables

Read the plan and extract discrete units of work:

1. Parse the plan document

• Read the spec/plan file
• Identify each distinct feature, component, or change
• Note dependencies between items

1. Define each deliverable

• Summary: What does this issue deliver?
• Scope: Which files will be created or modified?
• Dependencies: What must be done before this?
• Acceptance criteria: How do we know it's done?

1. Estimate file touchpoints

• List every file each deliverable will create or modify
• Be specific — src/utils/parse.ts not src/utils/
• Include test files: src/utils/parse.test.ts

Completion criteria:

• [ ] All deliverables identified with clear scope
• [ ] File touchpoints listed for each deliverable
• [ ] Dependencies between deliverables noted

Phase 2: Overlap Detection — Map File Conflicts

Use `validate_parallel_issues` to verify safety:

1. Build the file overlap matrix

• Compare file lists between all deliverables
• Identify any shared files

1. Validate with MCP tool

   Call: codingbuddy validate_parallel_issues
     issues: [issue_numbers]
     issueContents: { "1": "body1", "2": "body2", ... }

1. Apply the Iron Rule

• Same file in two deliverables = different waves
• No exceptions — even "small" changes to shared files cause merge conflicts

Decision matrix:

Completion criteria:

• [ ] File overlap matrix built
• [ ] validate_parallel_issues called (if issues already exist)
• [ ] Conflicts resolved via wave separation

Phase 3: Prioritize — Assign Priority and Wave Groups

Priority levels:

Wave assignment rules:

1. Wave 1: All P0 issues + any P1 issues with zero file overlaps with P0
2. Wave 2: Issues that depend on Wave 1 completion + P1/P2 with no overlap with each other
3. Wave N: Remaining issues grouped by zero-overlap constraint

Wave 1: [#1, #2, #3]  ← No file overlaps between these
Wave 2: [#4, #5]       ← Depend on Wave 1; no overlaps between these
Wave 3: [#6]           ← Depends on Wave 2

Completion criteria:

• [ ] All deliverables have priority labels
• [ ] Wave groups assigned with zero intra-wave file overlap
• [ ] Dependency chain is clear

Phase 4: Create — Generate GitHub Issues

Create each issue with structured body:

gh issue create \
  --title "<type>(<scope>): <description>" \
  --label "<priority>,<wave>,<feature-area>" \
  --body "$(cat <<'EOF'
## Summary

<1-2 sentence description of what this issue delivers>

## Details

<Implementation details, approach, key decisions>

## Files to Create/Modify

- [ ] `path/to/file.ts` — <what changes>
- [ ] `path/to/file.test.ts` — <what tests>

## Acceptance Criteria

- [ ] <Criterion 1>
- [ ] <Criterion 2>
- [ ] <Criterion 3>

## Dependencies

- Depends on: #<number> (if any)
- Blocks: #<number> (if any)

## Wave Assignment

**Wave <N>** — <reason for this wave>
Can run in parallel with: #<numbers>
Must wait for: #<numbers> (if any)
EOF
)"

Label conventions:

Auto-create missing labels:

gh label create "wave-1" --color "4ECDC4" --description "Wave 1: parallel group" 2>/dev/null || true
gh label create "wave-2" --color "45B7D1" --description "Wave 2: parallel group" 2>/dev/null || true
gh label create "P0" --color "FF0000" --description "Critical priority" 2>/dev/null || true
gh label create "P1" --color "FF6B6B" --description "High priority" 2>/dev/null || true
gh label create "P2" --color "FFD93D" --description "Medium priority" 2>/dev/null || true
gh label create "P3" --color "95E1D3" --description "Low priority" 2>/dev/null || true

Completion criteria:

• [ ] All issues created with structured body
• [ ] Labels applied (created if missing)
• [ ] Dependencies linked between issues

Phase 5: Summarize — Output Dependency Graph and Execution Plan

Present the final decomposition:

## Decomposition Summary

### Dependency Graph

#1 ─┬─► #3
    └─► #4 ──► #6
#2 ────► #5

### Wave Execution Plan

| Wave | Issues | Parallel Safe | Depends On |
|------|--------|---------------|------------|
| 1 | #1, #2 | Yes (0 file overlaps) | — |
| 2 | #3, #4, #5 | Yes (0 file overlaps) | Wave 1 |
| 3 | #6 | N/A (single) | Wave 2 |

### File Overlap Matrix

| | #1 | #2 | #3 | #4 | #5 | #6 |
|---|---|---|---|---|---|---|
| #1 | — | 0 | 1 | 0 | 0 | 0 |
| #2 | 0 | — | 0 | 0 | 1 | 0 |
...

Total issues: 6
Waves: 3
Estimated parallel speedup: ~3x

Completion criteria:

• [ ] Dependency graph visualized
• [ ] Wave execution plan table complete
• [ ] File overlap matrix shown
• [ ] Summary shared with user

Integration with taskmaestro

The wave grouping output is designed for direct use with /taskmaestro:

/taskmaestro --issues "#1,#2,#3" --wave 1
/taskmaestro --issues "#4,#5" --wave 2

Each wave runs in parallel tmux panes with git worktree isolation.

Quick Reference

Safety Checklist

Before creating issues:

• [ ] Plan document read completely
• [ ] Every deliverable has specific file touchpoints (not directories)
• [ ] File overlap matrix checked — no intra-wave conflicts
• [ ] Priority levels assigned based on dependency chain
• [ ] Issue bodies include acceptance criteria
• [ ] Wave assignments respect the Iron Rule
• [ ] Labels exist or will be auto-created
• [ ] validate_parallel_issues called for final verification

Red Flags — STOP

Examples

Spec to Issues

Input:  docs/plans/2025-03-15-auth-redesign.md
Output: 5 GitHub issues across 2 waves

Wave 1 (parallel):
  #101 feat(auth): add JWT token service        [P0, wave-1]
  #102 feat(auth): add password hashing utils    [P0, wave-1]
  #103 feat(db): add users migration             [P0, wave-1]

Wave 2 (parallel, after Wave 1):
  #104 feat(auth): add login/register endpoints  [P1, wave-2]
  #105 feat(auth): add auth middleware            [P1, wave-2]

Plan with Overlaps

Input:  docs/plans/2025-04-01-api-v2.md

Overlap detected:
  Issue A: modifies src/routes/index.ts
  Issue B: modifies src/routes/index.ts
  → A and B MUST be in different waves

Wave 1: [A, C, D]  ← A here
Wave 2: [B, E]     ← B here (after A merges)