nubos-pilot

Appearance

Concept Overview ​

Concept. One-screen mental model. Each section links to its full reference. For hands-on, jump to Quickstart; for facts, see CLI Commands or Configuration.

The unit-types ​

nubos-pilot operates on three execution nouns plus three capture nouns:

UnitLives inProduces a commit?
Milestoneroadmap.yaml entry + .nubos-pilot/milestones/M<NNN>/Yes, via task commits + optional milestone-level commit
Slice (= execution wave).nubos-pilot/milestones/M<NNN>/slices/S<NNN>/Emerges from its tasks
Task.nubos-pilot/milestones/M<NNN>/slices/S<NNN>/tasks/T<NNNN>/Yes — exactly one per task
Todo.nubos-pilot/todos/pending/*.mdOn create
Note.nubos-pilot/notes/*.md (or ~/.nubos-pilot/notes/)Project-scope yes, global-scope no
Thread.nubos-pilot/threads/*.mdOn create only

Slices ARE waves: all tasks inside one slice run in parallel; slices run serially. Cross-slice dependencies flow forward only.

"Phase" = milestone in slash-command names. See Glossary.

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 project + milestone lifecycle ​

Two nested lifecycles ride the same .nubos-pilot/ tree. The milestone lifecycle handles each piece of work; the project lifecycle handles "the project is done, archive it, start the successor".

Milestone lifecycle:

new-project ──► discuss-phase ──► [research-phase] ──► plan-phase ──► execute-phase ──► verify-work
                     │                    │                  │              │                │
                     ▼                    ▼                  ▼              ▼                ▼
               M<NNN>-CONTEXT     M<NNN>-RESEARCH      S<NNN>-PLAN    task commits     M<NNN>-VERIFICATION
                                                       +T<NNNN>-PLAN

Project lifecycle (sits above):

idle ──new-project──► active ──new-milestone/execute/verify──► active ──close-project──► completed
                                                                                              │
                                                          ╲                                   │
                                                           ╲                                  ▼
                                                            ╲──new-project Phase -1──► archived
                                                                                      (.nubos-pilot/archive/<slug>-<date>/)

/np:close-project is the single project-wide aggregate verification: it reads every M<NNN>-VERIFICATION.md and M<NNN>-VALIDATION.md, surfaces blockers, writes PROJECT-SUMMARY.md, and flips roadmap.yaml.project_status to "completed". /np:new-project Phase -1 then offers archive-then-init when a project (active or completed) already exists in the workspace; learnings and solutions carry over by default so the successor inherits prior knowledge. See project lifecycle and ADR-0016.

Atomic commit per task ​

Every completed task produces exactly one git commit. The format is:

task(M<NNN>-S<NNN>-T<NNNN>): <task title>

Examples:

task(M001-S001-T0001): add login form
task(M001-S001-T0002): wire login handler
task(M001-S002-T0001): render profile page

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):

yaml
---
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 forbidden in agent frontmatter; model resolution lives in np-tools.cjs resolve-model, consulted by the workflow at spawn time.

Per-task runtime additions (opt-in surfaces) ​

Two surfaces extend the Nubosloop without changing its 6-step shape:

  • Vector-Memory is an opt-in semantic-recall layer at .nubos-pilot/memory/. When memory.enabled = true, the Pre-flight cache combines BM25 and vector via α·BM25 + (1−α)·vector, Researcher and Planner pre-recall prior decisions, and commit-phase writes the just-logged learning back. Dependencies (@huggingface/transformers, usearch) are optionalDependencies, lazy-loaded (ADR-0014).
  • Named-Agent-Messaging is an always-on file-based addressed dialogue at .nubos-pilot/messages/. Critic emits per-finding request messages, Executor and Build-Fixer read the inbox in Round 2 and later, and commit-phase refuses while pendingReplies > 0, then sweeps task messages on success. It adds no new runtime dependency (ADR-0015).

Invariants ​

The shape of nubos-pilot is fixed by the accepted ADRs (0001 through 0019). The main ones:

  • ADR-0001 — no daemon, no background process, no RPC.
  • ADR-0002, amended by ADR-0006 and ADR-0014 — runtime dependencies stay scoped: yaml@^2.8 always-on, usearch and @huggingface/transformers as optionalDependencies for the opt-in Vector-Memory layer.
  • ADR-0003 — six unit-types max.
  • ADR-0004 — one commit per unit, no bundling, no splitting.
  • ADR-0005 — Source, Install-Payload and Project-State stay disjoint; .nubos-pilot/memory/ and .nubos-pilot/messages/ are Project-State sub-trees.
  • ADR-0007 — codebase documentation layer as shared agent memory under .nubos-pilot/codebase/.
  • ADR-0008 — opt-in per-slice git worktree isolation; .nubos-pilot/worktrees/ must be gitignored.
  • ADR-0009 — no interactive TUI dependency for the dashboard; /np:dashboard stays a one-shot read-only view.
  • ADR-0010 — every task runs through the Nubosloop; commit refuses without verify-green, zero findings, and zero pendingReplies (ADR-0015 Layer-B extension).
  • ADR-0011 — k=3 Researcher-Schwarm with deterministic Mehrheit / Union / Schnittmenge merge.
  • ADR-0012 — Completeness Mandate as Pflicht-Boilerplate.
  • ADR-0013 — learnings-store versioning and migration policy.
  • ADR-0016 — project-level close and archive lifecycle.
  • ADR-0017 — strict output-schema enforcement at write-time.
  • ADR-0018 — Researcher-Schwarm schema, reconciler and disagreement-gate (amends 0011).
  • ADR-0019 — plan-side trust layer: mechanical PLAN.md validation before promote.

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