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 four configuration questions, and writes the payload into the runtime's config directory (for example .claude/nubos-pilot/ or .opencode/nubos-pilot/). After that the host CLI exposes the np:* slash-commands.

Supported runtimes

Four first-class runtimes have full adapter and managed-Markdown support. Each runtime installs the payload under its own config directory:

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

Ten additional runtimes are selectable via --agent <id> at install time: antigravity, augment, cline, codebuddy, copilot, cursor, kilo, qwen, trae, windsurf. See Runtimes for the full list and the adapter contract.

What you get

• A three-level planning ontology: Milestone → Slice (= wave) → Task.
• 33 np:* slash-commands across Planning, Execution, Review, Capture and Utility.
• 16 subagent files (13 spawnable agents plus 3 Critic audit modules), each with a fixed Tier and Tools frontmatter contract.
• Atomic-commit-per-task discipline: every undo is a mechanical git revert.

For the full mental model (the three trees, the milestone lifecycle, what a slice is) see Concept Overview. For a guided walkthrough from empty directory to first shipped milestone, see Getting Started; for the condensed copy-paste sequence, see Quickstart.

Stack

• Node.js ≥ 22 (declared in package.json engines).
• 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; it calls it through lib/git.cjs.
• Test runner is node --test; coverage runs through Node's experimental built-in.

Status and invariants

The shape of the system is pinned by the accepted ADRs (0001 through 0019), which are the authoritative reference for what nubos-pilot is and is not. Any feature that would violate one of them requires a new ADR that supersedes the existing one; there is no informal exception path.