| name | pipeline-next |
| description | Pick the next task (or group of related tasks) from ROADMAP.md and set up a pipeline state file. Reads the roadmap, filters by milestone/priority, groups related small features into batches, checks what's already done, and creates .pipeline-state/<branch>.json from the template. Run /pipeline-run after this to execute the stages.
|
Pipeline Next — Pick a Task and Initialize
Pick the next task from the project's ROADMAP.md and create a pipeline state file.
Usage:
/pipeline-next — next highest-priority task from first milestone/pipeline-next --milestone v0.4.0 — next task from v0.4.0/pipeline-next --milestone v0.4.0 --priority P1 — next P1 task/pipeline-next --feature "auth" — specific feature by keyword/pipeline-next --list — list available tasks without starting/pipeline-next --milestone v0.4.0 --group — auto-group remaining tasks and pick next group/pipeline-next --milestone v0.4.0 --list --group — show proposed groups without starting
Steps
1. Find and read ROADMAP.md
Look for: ROADMAP.md, docs/ROADMAP.md, docs/roadmap.md
2. Parse the Priority Matrix
The table at the top maps features to priorities (P0-P3). Parse it. Items with strikethrough or ✅ are completed — skip them.
3. Parse milestones and features
Scan for ### Milestone: vX.Y.Z — Title sections. Within each, find **Feature Name** entries. Skip sections: Completed, Future, Contributing, Investigate, Differentiators, Parity Tracker.
Milestone-name format (per project convention; check the project's ROADMAP for the canonical convention if it has one): two shapes are valid:
vX.Y.Z — an actual release (3-digit SemVer), e.g., v0.9.1, v1.0.0.vX.Y.Z-N — a drain-bucket / planning iteration toward release vX.Y.Z (SemVer pre-release form), e.g., v0.9.2-1, v0.9.2-2. Drain buckets accumulate into the next release.
Both shapes match the same heading regex (### Milestone: v\S+ — Title); the parser does not need to distinguish them. SemVer ordering puts v0.9.2-1 < v0.9.2, which matches reality (drain buckets ship before the release they're targeting).
For each feature extract: name, milestone, section, priority (from matrix), issue number (#NNN if present), type (bugfix if section has "Bug Fix" or description mentions fixing/broken, else feature), and the full spec text.
4. Filter and select
Apply the user's filters (milestone, priority, feature keyword). Sort by priority (P0 first), then bug fixes before features.
5. Check what's already done
For each matching task, check:
.pipeline-state/<branch>.json exists with completed_at set → donegh pr list --state merged --head <branch> finds a merged PR → done.pipeline-state/<branch>.json exists without completed_at → resume this one
If the selected task came from a GitHub issue, also run the staleness check
(#7) before committing to it — verify the symbols/paths it cites still exist:
bash scripts/check-issue-symbols.sh <issue-number>
Print status of all matching tasks.
6. Group related tasks (--group mode)
If --group is specified, analyze the remaining (not-done) tasks and group them by relatedness. Tasks should be grouped when they:
- Touch the same files — tasks that modify the same source files
- Share a pattern — tasks that follow the same implementation pattern
- Are small and related — multiple small tasks in the same functional area
- Belong to the same ROADMAP section — tasks listed under the same section heading
Grouping criteria — analyze the actual ROADMAP tasks and group by:
- Shared files: tasks that modify the same source files
- Shared patterns: tasks that follow the same implementation pattern
- Small and related: multiple small tasks in the same functional area
- Same section: tasks listed under the same ROADMAP section heading
Grouping rules:
- Each group should have a clear theme name (e.g., "Form inputs", "Auth improvements")
- Max ~5-6 tasks per group (keeps implementation manageable)
- Large/complex tasks stay solo
- Bug fixes are never grouped with features
Print the proposed groups with --list --group. Without --list, pick the highest-priority group.
7. Create the state file
Read the template file — check project-local templates first:
For a single task: Copy template, fill in task_description, branch_name, etc.
For a group (--group mode): Copy the feature template, then:
task_description: Include ALL tasks in the group with their specs:
## Batch: <group theme>
Implement these related features as a single PR:
### 1. <task name>
<spec from ROADMAP>
### 2. <task name>
<spec from ROADMAP>
...
branch_name: feat/<group-slug> (e.g., feat/event-attributes, feat/ui-feedback-attrs)- The Planning stage will plan all tasks together
- The Implementation stage will implement all tasks in sequence
- One PR covers the entire group
- Add a
"batch_tasks" field to the state file listing the individual task names:
"batch_tasks": ["search input", "password input", "autocomplete", "slider"]
Write to .pipeline-state/<branch-name>.json. Ensure .pipeline-state/ is in .gitignore.
7.5 Derive the test-coverage expectation (#9)
Before handing off to /pipeline-run, state — at selection time, while the
task's intent is freshest — what test coverage the implementation is expected
to add, so coverage is a design input rather than a Stage-2 afterthought.
Derive it from the task type and the symbols the ROADMAP spec cites:
- bugfix → a regression test that fails before the fix and passes after,
reproducing the reported broken behavior.
- feature → unit tests for each new public symbol the spec names
(
ClassName, function_name()), plus one integration/path test if the
feature crosses a boundary (view, endpoint, event handler).
- docs-only / config-only → "no new tests expected" (state it explicitly so
the run doesn't invent busywork).
- repo has no test suite (per the CLAUDE.md pipeline-config
test_command
being empty) → state "no suite — manual/verification only" so Stage 2 doesn't
fabricate a command.
Record it in the state file as coverage_expectation (a one-line string) and
surface it in the Output below. The Test/Self-Review stages read it as the
coverage bar to meet.
8. Output
Single task:
═══════════════════════════════════════════
Task selected: <name>
Type: <feature|bugfix> | Priority: <P0-P3>
Branch: <branch-name>
State: .pipeline-state/<file>.json
Stages: <N> (from template)
Coverage expectation: <one-line, from step 7.5>
═══════════════════════════════════════════
Batch group:
═══════════════════════════════════════════
Group selected: <group theme>
Tasks: <count> features
Branch: feat/<group-slug>
State: .pipeline-state/<file>.json
Stages: <N> (from template)
Included tasks:
1. <task name>
2. <task name>
...
═══════════════════════════════════════════
