nubos-pilot

Appearance

ADR-0003: Max Six Unit-Types ​

  • Status: Accepted
  • Date: 2026-04-14
  • Supersedes: None

Context and Problem Statement ​

Planning ontologies tend to grow without upper bound — epics, stories, sub-stories, initiatives, spikes, tickets, tasks, subtasks. Each new type fragments workflows, multiplies templates, and forces the user to internalize yet another naming distinction. The question for nubos-pilot is: how many user-facing planning "unit-types" exist, and what are they?

For the purpose of this ADR, 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. An AI prompt variable, an internal helper module (e.g. lib/tasks.cjs), a configuration key, or a subsection inside a file are not unit-types — they are implementation details invisible to the user's mental model.

Decision Drivers ​

  • Transparency (Core Value) — users must be able to mental-model the whole planning system without a reference card.
  • Cheatsheet-legible — six named types still fit on a cheatsheet a user internalizes in minutes.
  • Surface-area cost — each type costs a template + a workflow verb + a state-machine chunk.
  • Cap-and-escape-hatch beats open-ended ontology for a tool that is supposed to be "transparent" by Core Value.

Considered Options ​

  • Cap at exactly six — Milestone, Phase, Plan, Task, Todo, Backlog. (CHOSEN)
  • Open-ended type system — let users define new unit-types at will.
  • Flat "ticket" model — a single unit-type with tags/categories.

Decision Outcome ​

Chosen: "Cap at exactly six". The six types are enumerated below. Downstream agents do not auto-consume this list; workflows hard-code the six type names inside their own code.

The six unit-types ​

  1. Milestone — a top-level project goal spanning multiple phases. Milestones live as entries in ROADMAP.md. A milestone's completion does not itself produce a commit (see ADR-0004 for the milestone exception); instead, editing ROADMAP.md to mark the milestone done is the atomic commit that records the milestone's completion.

  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, and has its own lifecycle (not-started → executing → complete). Phases are the primary unit most workflows operate on.

  3. Plan — the PLAN.md inside a phase describing how the phase executes: waves, tasks, verification. There is typically one PLAN per phase, and it is authored by np:plan-phase and consumed by the execution workflows.

  4. Task — an atomic unit of work inside a plan. Tasks are authored as <task> XML blocks inside PLAN.md by default. Promotion to standalone tasks/*.md files is permitted when parallelism, mixed model-tiers, or non-linear dependencies demand it. 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. Todos are the lightweight capture path for ideas that surface during execution but don't yet belong to any plan. Promoted todos become tasks or backlog items as part of their scheduling.

  6. Backlog — a deferred item parked under .nubos-pilot/backlog/. Backlog items are scheduled for later but not yet bound to a phase. They are heavier than todos (they carry rationale and rough scoping) and lighter than phases (they have no plan, no tasks yet).

Consequences ​

  • Good — every workflow knows exactly which of the six types it operates on; no type-discovery logic is needed.
  • Good — the full type catalogue fits on a cheatsheet.
  • Bad — users coming from tools that use "epic", "story", "sprint", or "initiative" must map those concepts onto Milestone / Phase / Plan. Accepted trade-off.
  • Neutral — adding a seventh type is not forbidden forever; it requires a new ADR superseding or amending ADR-0003.

Pros and Cons of the Options ​

Cap at exactly six — chosen ​

  • Good — the six types cover every planning granularity encountered.
  • Good — every type has a unique, obvious scope; nothing overlaps.
  • Good — N × 3 artifact cost stays fixed and small.
  • Bad — no native "epic" or "initiative" for users coming from Jira-like tools. Mitigated by the Milestone/Phase mapping.

Open-ended type system — rejected ​

  • Good — users with niche workflows could model their exact process.
  • Bad — fragments the workflow library; every np:* either swallows unknown types (complexity) or errors on them (frustration).
  • Bad — template proliferation breaks the Core-Value transparency.
  • Bad — cross-project conventions break down.

Flat "ticket" model — rejected ​

  • Good — simplest possible ontology — "everything is a ticket".
  • Bad — loses granularity between a 5-minute Todo and a 3-week Milestone. Users end up re-creating hierarchy via tags.
  • Bad — workflow logic becomes branch-heavy.

Enforcement ​

CI-gate enforcement against a seventh unit-type is deferred to a later deploy/CI phase. Current enforcement consists of human PR review and this ADR as the authoritative reference.

More Information ​

  • Related ADR: ADR-0004 — atomic-commit-per-unit binds the one-commit rule to each of the six types.
  • Related ADR: ADR-0005 — the Project-State tree is where five of the six types physically live.
  • REQUIREMENTS.md: §"Foundation" row FND-03 — "Milestone/Phase/Plan/Task/Todo/Backlog, keine weiteren ohne ADR".