Concept Overview

This page is a one-screen mental model. Each section links to its full reference.

The six unit-types

nubos-pilot operates on exactly six user-facing planning nouns (ADR-0003):

Unit	Lives in	Produces a commit?
Milestone	ROADMAP.md entry	Editing ROADMAP is the commit
Phase	.nubos-pilot/phases/<NN>-<slug>/	Yes, on completion
Plan	<NN>-<MM>-PLAN.md inside a phase	Yes, on completion
Task	<task> block in PLAN.md or tasks/<task-id>.md	Yes — exactly one per task
Todo	.nubos-pilot/todos/pending/*.md	On promotion
Backlog	.nubos-pilot/backlog/*.md	On move/promotion

A seventh type requires a new ADR. There is no epic, story, sprint, or ticket type — map them mentally onto Milestone / Phase / Plan.

The three orthogonal file-trees

ADR-0005 splits the world into three trees that never overlap at runtime:

1. Source — the tools/nubos-pilot/ repo. Contributor-only.
2. Install-Payload — copied to .claude/nubos-pilot/ (and optionally .opencode/nubos-pilot/) on the user machine. Owned by the user, managed by the installer through a manifest.
3. Project-State — .nubos-pilot/ next to the user's code. Mutated only through workflows under a single-writer file lock.

You can rm -rf .claude/nubos-pilot to uninstall without losing plans, or rm -rf .nubos-pilot to reset state without uninstalling.

The phase lifecycle

new-project ──► discuss-phase ──► [research-phase] ──► plan-phase ──► execute-phase ──► verify-work
                     │                    │                  │              │                │
                     ▼                    ▼                  ▼              ▼                ▼
                CONTEXT.md           RESEARCH.md         PLAN.md      task commits     VERIFICATION.md

np:next is the router: it reads STATE + roadmap + the current phase directory and tells you which step is next. np:dispatch does the same but invokes the relevant workflow via Skill().

Atomic commit per unit

Every completed unit produces exactly one git commit (ADR-0004). The format is:

<type>(<phase>-<plan>-<task>): <unit title>

This is what makes np:undo, np:undo-task and np:reset-slice mechanical git revert operations rather than heuristic search jobs.

Subagents

Workflows are markdown orchestrators. Subagents are markdown role-prompts spawned by workflows. Every agent has a fixed frontmatter contract (D-09):

---
name: <filename-stem>
description: <one-line summary>
tier: haiku | sonnet | opus
tools: Read, Write, Bash, Grep, …
color: <ui-hint>
---

tier is the only model-selection knob. Concrete model IDs and model_profile are explicitly forbidden in agent frontmatter — model resolution lives in np-tools.cjs resolve-model, consulted by the workflow at spawn time.

Invariants

The shape of nubos-pilot is fixed by ADRs 0001-0006:

• ADR-0001 — no daemon, no background process, no RPC.
• ADR-0002 + ADR-0006 — exactly one runtime dependency: yaml@^2.8.
• ADR-0003 — six unit-types max.
• ADR-0004 — one commit per unit, no bundling, no splitting.
• ADR-0005 — Source / Install-Payload / Project-State stay disjoint.

Anything that would break one of these requires a superseding ADR before any code changes.