Utility Workflows

Routing, status, diagnostics. None of these mutate milestone, slice, or task state; they read it, render it, or repair the install. The two indexing workflows (np:knowledge, np:context-stats) write a derived cache under .nubos-pilot/state/ (gitignored) but never touch source-of-truth artifacts.

np:state

Print the current project state snapshot: current milestone, current task, 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 downstream tooling.

np:dashboard

One-shot read-only overview of milestones, slices, and tasks. Each slice line shows per-status counts plus a checkbox row of every task's status ([ ] pending, [~] in-progress, [x] done, [-] skipped, [!] parked).

/np:dashboard

Internally calls node .nubos-pilot/bin/np-tools.cjs dashboard. Flags:

• --json — emit the snapshot as JSON for scripting.
• --no-color — plain text (no ANSI), useful when piping or non-TTY.

There is no --watch and no interactive drill-down; re-run the command for a fresh view. Drill-down composes existing commands: handoff-read <id>, render-todo <slice-full-id>, checkpoint show <task-full-id>, worktree-list. See ADR-0009 for the rationale.

np:doctor

Install and layout integrity scan. It runs 12 checks (bin/np-tools/doctor.cjs):

1. Manifest integrity — every shipped file matches its recorded hash; no unexpected files in the payload tree.
2. Version mismatch — the installed payload version matches the expected package.json version.
3. Hooks missing — declared hook files exist on disk.
4. Codex trapped features — detects a broken ~/.codex/config.toml and offers an auto-fix.
5. Askuser broken — the prompt capability is callable.
6. Codebase docs — reports stale modules that should be refreshed via /np:update-docs.
7. Milestone layout — every milestone in roadmap.yaml has a matching milestones/M<NNN>/ directory; flags a legacy .nubos-pilot/phases/ directory if still present.
8. Output schemas — every on-disk M<NNN>-VERIFICATION.md and M<NNN>-VALIDATION.md artifact passes schema lint (ADR-0017).
9. Nubosloop config — the swarm.knowledge_adapter and loop.maxRounds config values are well-formed.
10. Nubosloop critics — the critic agent files the Nubosloop expects are installed in the payload.
11. Nubosloop knowledge store — the learnings store at .nubos-pilot/knowledge/learnings.json is present and parseable.
12. Orphan tmp files — sweeps stale temp files (older than 1h) left under the state directory by a hard-killed process.

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

npx nubos-pilot doctor
npx nubos-pilot doctor --fix

np:scan-codebase

Initial deep codebase inventory. Walks the workspace, buckets files into coherent modules, hashes each file, writes .nubos-pilot/codebase/INDEX.md + one modules/<id>.md per module. Every dev-agent (executor, planner, researcher, …) is instructed to read the INDEX + relevant module doc before editing source.

np:update-docs

Re-scans the workspace, diffs against the previous hash manifest, dispatches np-codebase-documenter for each stale module, applies the returned prose, and commits the refresh as docs(codebase): …. Called automatically by /np:execute-phase, and manually after any substantial code change.

np:session-report

Generate a session report from metrics/*.jsonl since the .last-session pointer. Updates the pointer atomically (file-locked).

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 | multiselect, prompt, options, default) and returns the chosen label. This is the single sanctioned path for any user prompt; bare host-specific prompt calls in workflow Markdown are rejected by the check-workflows.cjs lint.

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. documentation edits, manual ROADMAP fixes).

np:config-get

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

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

np:generate-slug

Slugify text via lib/layout.cjs.slugify. Used by /np:add-todo, /np:note, and /np:thread for filename generation. Produces [a-z0-9-]+ only.

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:

node np-tools.cjs resolve-model planner --profile frontier       # → opus
node np-tools.cjs resolve-model np-executor --profile balanced   # → sonnet

Model-profile options: frontier, quality, balanced, budget, inherit.

np:metrics

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

np:knowledge "<query>"

Local BM25-light full-text search across every markdown file under .nubos-pilot/: PROJECT.md, REQUIREMENTS.md, RULES.md, every milestone tree, codebase/, todos/, threads/, and notes/. The first call builds .nubos-pilot/state/knowledge-index.json (gitignored); later calls re-use it. Rebuilds are idempotent.

node .nubos-pilot/bin/np-tools.cjs knowledge-search "jose jwt verify" --limit 10

Returns JSON { query, terms, total_hits, hits[], index_built_at } where each hit carries rel_path, line_start, line_end, score, and a six-line preview. Used by np-planner, np-researcher, np-architect, np-build-fixer, and np-security-reviewer to find cross-milestone references and prior locked decisions without re-reading every artifact.

Read-only: no source mutation, no STATE change, no commit. The cache file lives under .nubos-pilot/state/, which is gitignored.

np:context-stats

Localized markdown snapshot of the knowledge index — files, bytes, and estimated tokens grouped by top-level directory (PROJECT.md, REQUIREMENTS.md, RULES.md, milestones/, codebase/, todos/, threads/, notes/). Complements np:stats (phases + metrics) by surfacing the context-window budget the project's markdown surface implies.

node .nubos-pilot/bin/np-tools.cjs context-stats           # markdown
node .nubos-pilot/bin/np-tools.cjs context-stats json      # raw JSON

Labels follow .nubos-pilot/config.json → response_language (en/de). The token estimate uses ≈ 0.27 tokens/byte for markdown; it is a heuristic, not authoritative. Read-only.