Introduction

nubos-pilot is a Markdown-driven Plan/Execute/Verify framework that installs into AI coding-agent CLIs and gives them a structured workflow for shipping software in small, reversible units.

It is not an agent and not a runtime. It is a payload of slash-commands, sub-agents, and .cjs helpers that the host CLI invokes inline. There is no background process, no socket, no service registration.

npx nubos-pilot

The installer detects the host runtime, asks a handful of configuration questions, and writes the payload into .claude/nubos-pilot/ (or .opencode/nubos-pilot/). After that the host CLI exposes the np:* slash-commands.

Supported runtimes

Runtime	Install path	Adapter
Claude Code	.claude/nubos-pilot/	lib/runtime/claude.cjs
Codex	reuses .claude/ payload + AGENTS.md	lib/runtime/codex.cjs
Gemini	reuses .claude/ payload + GEMINI.md	lib/runtime/gemini.cjs
OpenCode	.opencode/nubos-pilot/ + opencode.json	lib/runtime/opencode.cjs

What you get

• A six-type planning ontology: Milestone, Phase, Plan, Task, Todo, Backlog.
• Roughly fifty np:* slash-commands grouped into Planning, Execution, Review, Capture and Utility.
• Seventeen subagents (np-planner, np-researcher, np-executor, np-verifier, np-plan-checker, …) with a fixed Tier×Tools frontmatter contract.
• A project-state tree under .nubos-pilot/ that persists ROADMAP.md, STATE.md, phases/<NN>-<slug>/ and friends.
• Atomic-commit-per-unit discipline so np:undo, np:undo-task, and np:reset-slice reduce to mechanical git revert.

Stack

• Node.js ≥ 22 (engines).
• Exactly one runtime dependency: yaml@^2.8 (granted by ADR-0006 as a narrow amendment to the zero-runtime-deps invariant).
• git is assumed to be present — nubos-pilot does not install it, only calls it through lib/git.cjs.
• Test runner is node --test; coverage runs through Node's experimental built-in.

Status & invariants

The shape of the system is pinned by six ADRs (0001–0006) which are the authoritative source of truth for "what nubos-pilot is and isn't". Any feature that would violate one of them requires a new ADR that supersedes the existing one — there is no informal exception path.