Unit Types

nubos-pilot has a fixed three-level execution ontology plus three capture types (ADR-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. AI prompt variables, helper modules, configuration keys and Markdown subsections are not unit-types.

Execution ontology

1. Milestone

A top-level project goal. Identified as M<NNN> (e.g. M001).

• Lives at: .nubos-pilot/milestones/M<NNN>/
• Contains: M<NNN>-CONTEXT.md (decisions), M<NNN>-ROADMAP.md (slice list + order), M<NNN>-META.json (structured metadata), and a slices/ subdirectory.
• Roadmap entry: .nubos-pilot/roadmap.yaml → milestones[].id = "M001".
• Lifecycle: pending → in-progress → complete.

Each /np:discuss-phase N, /np:research-phase N, /np:plan-phase N, /np:execute-phase N, /np:verify-work N and /np:validate-phase N operates on exactly one milestone, where N is the milestone number (1, 2, 3, …).

2. Slice

An execution wave inside a milestone. Identified as S<NNN> within its milestone (e.g. M001-S001).

• Lives at: .nubos-pilot/milestones/M<NNN>/slices/S<NNN>/
• Contains: S<NNN>-PLAN.md (objective + inline <task> blocks), S<NNN>-ASSESSMENT.md (risk/effort/deps/blockers), S<NNN>-UAT.md (acceptance), optional S<NNN>-RESEARCH.md and S<NNN>-SUMMARY.md, and a tasks/ subdirectory.
• Execution rule: all tasks inside one slice run in parallel; slices run serially. Cross-slice dependencies flow forward only (task in S002 may depend on task in S001, never the reverse).

3. Task

An atomic unit of work inside a slice. Identified as T<NNNN> within its slice, with the full-id being M<NNN>-S<NNN>-T<NNNN> (e.g. M001-S001-T0001).

• Lives at: .nubos-pilot/milestones/M<NNN>/slices/S<NNN>/tasks/T<NNNN>/
• Contains: T<NNNN>-PLAN.md (scaffolded from the slice's <task> block) and T<NNNN>-SUMMARY.md (filled by the executor after commit).
• Produces exactly one git commit with subject task(M<NNN>-S<NNN>-T<NNNN>): <title> — ADR-0004.
• Lifecycle: pending → in-progress → verifying → pre-commit → done (with skipped and parked as alternative terminals).

Slice == Wave

What separates this ontology from Jira-like hierarchies is that slice and wave are the same concept. There is no separate "wave" entity; the slice itself defines which tasks run together. The planner puts parallelizable tasks into the same slice and serial dependencies into the next slice.

Capture types

4. Todo

A captured-on-the-fly idea that lives under .nubos-pilot/todos/pending/YYYY-MM-DD-<slug>.md until it is scheduled. Created by /np:add-todo. One-line title plus body. The pending_todos counter in STATE.md is single-writer-locked.

5. Note

A free-form scratch note. Project scope writes .nubos-pilot/notes/YYYY-MM-DD-<slug>.md and commits to git. Global scope writes ~/.nubos-pilot/notes/YYYY-MM-DD-<slug>.md and never commits — intended for sensitive/cross-project content. Created by /np:note.

6. Thread

A cross-session context store at .nubos-pilot/threads/<slug>.md. Lifecycle in the frontmatter: OPEN → IN_PROGRESS → RESOLVED. Created and resumed by /np:thread <slug-or-title>. last_resumed is refreshed without committing to avoid log noise.

Why this shape?

• Three execution levels keep the mental model flat: a task is always inside a slice inside a milestone. There is no four-level "milestone/phase/plan/task" hierarchy with plan as a dangling intermediate layer.
• Slice == wave removes the redundant "wave" abstraction: the planner decides parallelism by deciding which slice a task goes into.
• Capture types are lightweight: no schema, no state machine, no planning budget. They exist to catch drive-by ideas without derailing a running milestone.

Mapping from other tools

Jira-ish	nubos-pilot
Initiative / Epic	Milestone
Sprint / Iteration	Milestone or Slice
Story	Slice
Sub-task / dev ticket	Task
Idea / icebox	Todo
Cross-session context note	Thread
Throwaway scratch	Note

The mapping is informal — canonical names are Milestone / Slice / Task / Todo / Note / Thread, and workflows hard-code them.