Unit Types

nubos-pilot operates on exactly six user-facing planning unit-types (ADR-0003). A seventh requires a new ADR superseding 0003.

A unit-type is a user-facing, persistence-bearing noun with its own template, its own file path in the project-state tree, and its own lifecycle states. AI prompt variables, helper modules, configuration keys and Markdown subsections are not unit-types.

The six types

1. Milestone

A top-level project goal spanning multiple phases. Lives as an entry in ROADMAP.md. A milestone's completion does not produce a separate commit — editing ROADMAP.md to mark it done is the unit-level commit (commit-type milestone(...)).

2. Phase

A sequential slice of a milestone pursuing a single coherent goal. Each phase gets its own directory at .nubos-pilot/phases/<NN>-<slug>/, contains a PLAN.md (one or more), and has its own lifecycle: not-started → executing → complete.

3. Plan

The PLAN.md inside a phase describing how the phase executes: waves, tasks, verification. Multiple plans per phase are allowed (and common). Authored by np:plan-phase, consumed by np:execute-phase.

4. Task

An atomic unit of work inside a plan. By default, tasks live as inline <task> XML blocks inside PLAN.md. They get promoted to standalone tasks/<task-id>.md files when at least one of three triggers fires:

• parallelism — multiple tasks runnable in the same wave,
• mixed-tiers — tasks needing different model tiers,
• non-linear-deps — depends_on graphs beyond a straight line.

A task is the smallest unit that produces exactly one git commit (ADR-0004).

5. Todo

A captured-on-the-fly idea that lives under .nubos-pilot/todos/pending/ until it is scheduled. Created by np:add-todo. Lightweight: usually a one-line title plus a few lines of context. Promoted to a Task or Backlog item by np:triage.

6. Backlog

A deferred item parked under .nubos-pilot/backlog/. Heavier than a Todo (rationale + rough scoping), lighter than a Phase (no plan, no tasks yet). Created by np:add-backlog, which appends a 999.x entry to ROADMAP.md and scaffolds a phase directory. np:plan-milestone-gaps produces these from audit failures.

Why a hard cap?

The six types are deliberately small enough to fit on a cheatsheet. Open-ended type systems fragment workflows: every np:* command has to either swallow unknown types (complexity) or reject them (frustration). The cap keeps the workflow library consistent across projects and across contributors.

Mapping from other tools

If you come from Jira-like ontologies, the rough mapping is:

Jira-ish	nubos-pilot
Initiative / Epic	Milestone
Sprint / Iteration	Milestone or Phase
Story	Phase
Sub-task / dev ticket	Task
Idea / icebox	Todo
Future-quarter item	Backlog

The mapping is informal — the canonical names are still the six above, and workflows hard-code them.