pipeline-next

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 → done
• gh 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>   # ⚠ miss → review before selecting

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:

# 1. Check for project-local template (preferred — has project-specific stages/prompts):
#    .pipeline-templates/feature-state.json
#    .pipeline-templates/bugfix-state.json
#    .pipeline-templates/refactor-state.json
#
# 2. Fall back to the pipeline-skill's templates/ directory:
#    Locate via: the directory containing pipeline.py, or PIPELINE_SKILL_DIR env var.
#    templates/feature-state.json
#    templates/bugfix-state.json
#    templates/refactor-state.json
#
# Project-local templates override skill defaults when they exist.
# Projects customize them to add stages (e.g., Re-Review), subagent prompts,
# and project-specific checklists.

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>
  ...
═══════════════════════════════════════════