dppdppd/rpm/next

/next

Orchestrator that handles preflight maintenance, then tries to move the backlog forward. With no argument a direct /next turn ends by either starting the next obvious backlog action or asking the user to clarify what should be next; a looped /next turn must not expect user input, dispatches only unambiguous work, and otherwise idles until the loop-exhausted guard stops it.

When given a count or scope (N, blocked, all, or a group name), /next runs a bounded internal sequence instead: it works several backlog items in one turn, skipping the heavy preflight between steps (see Sequencing). How wide it runs — one worker at a time or a fan-out batch — is the orchestrator's judgment call, sized to how independent the selected work is (see Concurrency). It never waits for user input mid-sequence. For an attended multi-step push, reach for a sequence first — it is cheaper than an external loop (heavy preflight only at the start and end, not every tick) and stays in one turn. /loop /next still works and remains the right tool for genuinely unattended or scheduled runs that span many turns; it benefits from the same preflight cadence.

Project Amendments

At the start of every invocation, check whether docs/rpm/skills/next.md exists in the consuming project. If it does, read it and apply its contents as additional project-specific instructions for this skill. Amendments may add preflight steps, narrow dispatch criteria, add output requirements, or extend the worker contract. They cannot remove or override plugin defaults — on conflict, this SKILL.md wins.

Routing

Parse $ARGUMENTS into a first token and an optional second token:

• empty → run one orchestrator step (the single-step flow below).
• `status` → run the status formatter and stop:

!bash ${CLAUDE_SKILL_DIR}/scripts/status.sh

Render the output verbatim. Do not interpret, summarize, or add commentary — the user wants the raw view.

• integer `N` (≥ 1) → run a sequence of up to N cycles (see

Sequencing). N = 1 is identical to the single-step flow.

• `blocked` → run a sequence until a task needs the user, or no

actionable task remains.

• `all` → run a sequence until no actionable task remains, skipping

tasks that need the user and continuing with the rest.

• anything else → treat the first token as a * Parent **group

name** in docs/rpm/future/tasks.org (match the heading text exactly, then case-insensitively). An optional second token scopes the run within that group: N, all, or blocked (default: drain the group until it has no actionable task or one needs the user). If no parent matches, print the usage block below and stop.

Reserved first tokens (status, blocked, all, and any integer) are never interpreted as group names.

Usage block (print only when the argument is unrecognized):

/next               — one orchestrator step
/next N             — up to N steps; width per step is the orchestrator's call (one worker, or a fan-out batch); heavy preflight only at start + end
/next blocked       — run until a task needs you, or nothing is actionable
/next all           — run everything actionable, skipping tasks that need you
/next <group> [N]   — work only that backlog group (drain it, or N steps)
/next status        — in-flight subagents, recent decisions, idle streak, counters
(prefer the sequence forms above; `/loop /next` still wraps the one-step form for unattended, multi-turn runs)

Mode

There are three modes:

• Direct (single-step) — no argument, run interactively. May ask one

concise clarification question when no obvious next backlog action can be started safely.

• Loop — this invocation is visibly part of /loop /next, an

unattended dynamic loop, or repeated automatic invocation. Must not ask for input. If there is no unambiguous action, log idle with the reason and stop; after 3 consecutive idle ticks, emit loop-exhausted.

• Sequence — /next was given a count or scope (N / blocked /

all / <group>). Runs a bounded internal loop (see Sequencing). Like loop mode it never asks for input mid-sequence; it stops at the argument's termination condition or the safety ceiling.

Sequencing

Triggered by a count or scope argument. A sequence runs cycles in the foreground. Each cycle's width — a single worker or a fan-out batch — is the orchestrator's call, sized to how independent the selected work is (see Concurrency).

1. Full preflight once, at the start. Run the delegated preflight

(Preflight step 3) with phases=full — bypassing the cadence gate, since a sequence always forces full at its start — act on its report, and log a marker:

``bash bash ${CLAUDE_SKILL_DIR}/scripts/log-decision.sh preflight-full "" "sequence start" ``

1. Cycle loop. Repeat until a termination condition (below) or the

safety ceiling:

• a. Cheap inline gate. Check the termination conditions and the

outstanding-user-blocker rule (Preflight step 1). Do not run the drift scan, the contradiction check, or the preflight subagent here — that overhead is exactly what a sequence exists to avoid.

• b. Task Selection. Recompute in-flight, walk the tree,

goal-aligned dispatch, apply the group filter if scoped, and run the is-pre-completed.sh skip check.

• c. Dispatch. Dispatch using the Worker Contract, **in the

foreground — await results, do not background. Log one `actionable-backlog` per worker. Width is the orchestrator's call (see Concurrency**): one worker when the next candidates are coupled, or a fan-out batch when they are independent — awaited together before reviewing.

• d. Review inline. Evaluate each returned result, mark the backlog

entry DONE (or append changes-requested notes to the detail file), then log review-result and a paired backlog-result per worker. Lean on the worker's terse report (it also persisted the full result to the detail file) to keep orchestrator context lean.

1. Full preflight once, at the end. After the loop stops, run the

delegated preflight again with phases=full — it catches any drift the workers introduced — and log a second preflight-full marker ("sequence end").

1. Emit the sequence summary (see Output Format).

Termination

• `N` — stop after N completed cycles.
• `blocked` — stop the moment a cycle would need user input (the top

candidate's only next move is a question), or when no actionable task remains.

• `all` — stop only when no actionable task remains. If a cycle's top

candidate needs user input, skip it (leave it as-is) and continue with the next actionable task; collect skipped items for the summary.

• `<group>` — restrict Task Selection to the matched * Parent;

terminate per the second token (N / all / blocked, default drain-until-empty-or-blocked).

• Safety ceiling. blocked, all, and unbounded group runs stop

after at most 25 cycles in one invocation. On hitting it, stop and report ceiling reached — run again to continue. An explicit N above 25 is honored, still cycle-by-cycle; the ceiling only bounds the open-ended forms.

Preflight cadence

Every single-step turn — a direct /next and a /loop /next tick — decides its preflight depth by running bash ${CLAUDE_SKILL_DIR}/scripts/preflight-due.sh first. The drift scan and contradiction check are housekeeping (also run by /session-end and /audit); re-paying them on a /next that follows one minutes ago, with nothing changed, is the cost this cadence removes.

• `full` → run the delegated preflight with phases=full and log a

preflight-full marker. This fires when there is no prior marker (so the first /next of a session is always full), the last one is stale (older than the freshness window), or a guidance input changed.

• `lite` → skip the drift scan and contradiction check. Do the inline

blocker check, then run review-ready.sh:

• a worker result is pending → dispatch the preflight subagent with

phases=review-only to review just that result.

• no worker pending → there is nothing to delegate, so **dispatch no

subagent at all**. Go straight to Task Selection.

This applies to both direct and loop single-step turns; a Sequence ignores the cadence and forces full at its start and end (see Sequencing).

Orchestrator Flow

Do not treat preflight and tasking as mutually exclusive. Run preflight first, in order, and continue to task selection when the preflight item was resolved locally. Stop only when continuing would be unsafe, when a direct-mode user question is required, or when loop mode has no unambiguous next action.

This section describes a single step. A Sequence (see Sequencing) runs the full preflight once at the start and once at the end; each in-between cycle skips the preflight and goes straight to Task Selection.

Preflight

1. Outstanding user blocker — if the previous decision in

docs/rpm/~rpm-orchestrator-log.jsonl was blocked-on-user and the most recent user message did not address the question:

• Direct mode: re-surface what we are waiting on, log

blocked-on-user if needed, and stop.

• Loop mode: do not ask again. Log idle with rationale

blocked-on-user unresolved, then stop or loop-exhausted if the idle streak reached 3.

1. Decide preflight depth (cadence gate). Unless this is a Sequence

start/end (which forces full), run bash ${CLAUDE_SKILL_DIR}/scripts/preflight-due.sh and branch per Preflight cadence:

• `lite` + no pending worker (review-ready.sh finds nothing):

there is nothing to delegate. Skip step 3 entirely — do not dispatch the subagent — and go straight to Task Selection. This is the common fast path for a /next that follows a recent one.

• `lite` + a pending worker: dispatch the subagent below with

phases=review-only.

• `full`: dispatch the subagent below with phases=full and log a

preflight-full marker.

1. Delegated preflight — when the gate calls for it, dispatch the

rpm:preflight subagent (foreground) so the token-heavy work (raw scan.sh output, contradiction classification, worker diffs) stays in the agent's context, not this one. Resolve each value before sending — pass real paths, not literals:

• mode= direct or loop (this turn's mode)
• phases= full (all three phases) or review-only (Phase 3 worker

review only; used on a lite tick that has a pending worker result, per Preflight cadence), as the gate above decided

• scan_script=${CLAUDE_PLUGIN_ROOT}/skills/session-end/scripts/scan.sh
• contradiction_script=${CLAUDE_SKILL_DIR}/scripts/contradiction-check.sh
• review_ready_script=${CLAUDE_SKILL_DIR}/scripts/review-ready.sh
• log_script=${CLAUDE_SKILL_DIR}/scripts/log-decision.sh
• memory_dir=$HOME/.claude/projects/$(printf '%s' "$PWD" | sed 's|/|-|g')/memory
• instructions= the active directive files (CLAUDE.md,

AGENTS.md, MEMORY.md at project root if present, plus every plugin/skills/*/SKILL.md)

• today=$(date +%Y-%m-%d)

The agent applies obvious mechanical drift fixes, runs the contradiction check, reviews the first ready worker result, and logs each drift-fix, contradiction count, and review-result itself. It returns ONLY a compact report (drift-fixes, drift-decisions, contradictions, review, repo-safe, notes). Read that report; do NOT re-run the scans, re-review the diff, or re-log what the agent already logged.