next-stage

Files (1)

• SKILL.md

SKILL.md (first lines)

# Next Stage

Start the next stage of a roadmap created by `/to-roadmap`: mark the previous stage done, hand the next stage's brief to the `/to-tasks` flow, and record the stage as in progress.

## Asking questions

Whenever you put a question to the user — one of the steps below, or an ad-hoc question when something is unclear or has drifted (a stale brief, an ambiguous roadmap state) — ask it and wait for their answer before carrying on.

This skill's own questions are few and cheap (which roadmap, a stage that won't reconcile), so resolve them before handing off — the `/to-tasks` flow it delegates to has a breakdown quiz of its own.

## Workflow

### 1. Guard: no feature in flight

If `.tasks/` exists and contains numbered task files, stop and tell the user — the current feature must be finished via `/next-task` (or explicitly discarded) before a new stage starts.

### 2. Locate the roadmap

Find `docs/roadmaps/*/ROADMAP.md` files with unchecked stages. If the user named a roadmap in their invocation, use that one; if exactly one roadmap has open stages, use it; if several do, ask which.

### 3. Reconcile stage status (fallback)

Normally `/next-task`'s finish gate marks a stage complete in `ROADMAP.md` when its final task lands, so nothing to do here. But if a stage is still annotated as in progress while `.tasks/` is empty (a finish gate was skipped, or the stage predates the finish-gate behaviour), reconcile: verify the stage's work actually landed on the repo's default branch — the universal done-signal, regardless of review process (a merged PR and a direct merge both satisfy it). Then update its entry to `[x]` and drop the annotation. Don't commit yet — this edit rides in the new stage's plan commit (step 7). If the stage's commits are NOT on the default branch (branch abandoned, PR closed, merge never happened), surface that to the user instead of ticking it.

If every stage is checked, the roadmap is complete — tell the user and stop. The roadmap directory stays as a historical record.

### 4. Read the brief

The next stage is the lowest-numbered unchecked entry. Read its brief in full, plus `ROADMAP.md` and anything the brief's "Decisions in force" section references that you need.

### 5. Decide where the stage's branch goes

`/to-tasks` creates the branch, but this skill decides what it comes off — it is the only place that knows both stages. Two conditions have to hold together for the new stage to **stack** on its predecessor:

- The predecessor's work is **not on the default branch yet** — the same check step 3 makes. A merged PR or a direct merge means there's nothing to stack on; branch off the default branch as normal.
- The new stage **builds directly on** the predecessor's work, per the brief and the roadmap's dependency notes. A stage that merely follows in sequence but stands on its own is independent — branch off the default branch.

If both hold, read `docs/agents/git-workflow.md` for a `### Stacking roadmap stages` block under `## Review process`. That block is the project's recorded mechanism, and it is what `/to-tasks` follows.

- **Block present** — pass `/to-tasks` the stacking decision and the predecessor's branch name.
- **Block absent** — the project has no stacking convention. Tell the user what you found (predecessor unmerged, new stage depends on it) and ask whether to configure one via `/setup-tobico-skills` scoped to review process, or to branch off the default branch and let the new stage's PR carry the predecessor's commits until it merges. Don't invent a mechanism.

When the predecessor is unmerged and the stage depends on it but the review process is direct-merge, there is nothing to stack — say so and branch off the default branch.

### 6. Hand off to /to-tasks

Run the `/to-tasks` flow with the brief as the plan input, telling it what step 5 decided — stack onto `<predecessor-branch>`, or branch off the default branch. Per that skill's stage-brief handling: treat the brief's "Proposed tasks" as the draft breakdown, check every item under "Re-verify at start" against the actual codebase, adjust for drift, and quiz the user on the (possibly adjusted) breakdown before writing task files.

### 7. Record the stage as in progress

Before `/to-tasks` commits the plan (its final step), edit `ROADMAP.md`: annotate the stage's entry with *(in progress)* and the feature branch name. The plan commit then carries the roadmap status changes (both the previous stage's tick from step 3 and this annotation) onto the new feature branch.

## Tips

- One stage at a time — this skill inherits `/to-tasks`'s one-feature-at-a-time rule.
- Briefs are provisional by design. If re-grounding shows a stage's chunking is badly stale, redraft it with the user rather than forcing the brief through — and consider whether later briefs need the same correction noted.
- If the user wants to take stages out of order and the roadmap's dependency notes allow it, that's fine — pick the stage they name instead of the lowest-numbered one.

From tobico/tobico-skills, MIT.

More from tobico/tobico-skills