Utility Workflows

Routing, status, diagnostics. None of these mutate plan or task state — they read it, render it, or repair the install.

np:next

Print the next actionable step under the six-rule gate. Reads STATE.md + roadmap.yaml + the current phase directory and returns the first matching rule's recommended workflow.

np:next

np:dispatch

State-router. Same logic as np:next, but invokes the resolved workflow via Skill() instead of just printing it. --force bypasses the gate; --action=<name> picks a specific workflow over the recommendation.

np:progress

Report % complete across phases and plans. Counts task commits against the total task graph and renders a progress bar per phase plus a milestone roll-up.

np:state

Print the current project state snapshot — current phase, current task, current plan, session metadata. Read-only mirror of STATE.md plus a few derived fields.

np:stats

Aggregated project stats from roadmap.yaml + STATE.md + git log + metrics/*.jsonl. Outputs a JSON shape consumed by np:session-report and np:cleanup.

np:doctor

Five-check install-integrity scan:

1. Manifest hash check — every shipped file matches its recorded hash, no unexpected files in the payload tree.
2. Runtime presence — declared runtime is callable.
3. Config schema — .nubos-pilot/config.json matches the expected shape.
4. Gitignore guard — none of the source-of-truth state files are gitignored.
5. Payload symlink check — refuses to operate when the payload directory is a symlink (security guard).

--fix applies the auto-safe fixes (regenerate missing managed blocks, restore the manifest, repair Codex's trapped [features]).

np:queue

Unified queue across todos / backlog / UAT / unplanned phases. Renders one chronological list of "things you might do next" with type tags. Useful before np:triage.

np:triage

Interactive per-item triage loop. For each item in the queue, asks the user to promote (to Task / Backlog / Phase), keep (leave in queue), or drop (move to archive). Updates underlying files and metrics.

np:cleanup

Archive completed milestones. Moves a milestone's phase directories into .nubos-pilot/archive/v<X.Y>/, collapses the corresponding ROADMAP entries into a <details> block, and writes an idempotent skip-marker so re-runs are no-ops.

Operates inside a single atomic commit (D-09 milestone-exception).

np:session-report

Generate a session report from metrics/*.jsonl since the .last-session pointer. Updates the pointer atomically (file-locked) and writes the report under .nubos-pilot/reports/<ISO-prefixed>.md.

np:help

List every available np-tools.cjs command grouped by category. --json for programmatic consumption.

np:askuser

Capability-layer prompt wrapper. Reads a spec JSON from --json '{...}' (type: input | confirm | select, prompt, options, default) and returns the chosen label. The single sanctioned path for any user prompt — bare AskUserQuestion calls in workflow Markdown are rejected by the check-workflows.cjs guard.

CHOICE=$(node np-tools.cjs askuser --json '{"type":"select","prompt":"Pick one","options":["a","b"]}')

np:commit

Atomic git commit wrapper with the gitignore guard. Use when you need to commit something outside the per-task path (e.g. ROADMAP edits during np:cleanup).

np:config-get

Read a value from .nubos-pilot/config.json by dotted key path:

node np-tools.cjs config-get workflow.commit_docs

np:generate-slug

Slugify text via lib/phase.cjs.phaseSlug — used by np:add-todo, np:add-backlog, np:thread for filename generation.

np:phase

Phase utilities. The single subcommand next-decimal <base> returns the next free decimal slot for a base phase number — used by np:add-backlog (e.g. next-decimal 999 → 999.4).

np:resolve-model

Resolve an agent / tier pair to a concrete model alias or id, consulted by workflows at the Task-spawn site. Encapsulates the Tier × Profile matrix from lib/model-profiles.cjs.

np:metrics

Record a JSONL metrics entry. Subcommands: record, now, start-timestamp, end-timestamp. Used by every other workflow that wants to be measurable.