nubos-pilot

Appearance

Getting Started ​

Tutorial. A guided tour of the happy path from empty directory to first shipped milestone, with each step explained. For the condensed copy-paste sequence, see Quickstart. For the design rationale, see Concept Overview.

Every step below is a single np:* slash-command in your host CLI.

1. Bootstrap a project ​

np:new-project

Five-question interview. The workflow writes:

  • .nubos-pilot/PROJECT.md
  • .nubos-pilot/REQUIREMENTS.md
  • .nubos-pilot/RULES.md
  • .nubos-pilot/roadmap.yaml (schema_version: 2)
  • .nubos-pilot/STATE.md
  • .nubos-pilot/milestones/M001/ with M001-CONTEXT.md, M001-ROADMAP.md, M001-META.json, and an empty slices/ subdirectory.

If the project has source files, np:scan-codebase is suggested as a follow-up to seed .nubos-pilot/codebase/ with module docs.

2. Lock the decisions ​

np:discuss-phase 1

In command names, "phase" means milestone (see Glossary). np:discuss-phase 1 captures the decisions for milestone M001.

An adaptive interview captures three categories:

  • Locked decisions (D-01, D-02, …) — non-negotiable; every downstream task must honor them.
  • Deferred ideas — explicitly parked for a later milestone.
  • Agent discretion — the agent picks and documents the choice in the task action.

Output: .nubos-pilot/milestones/M001/M001-CONTEXT.md with <domain>, <decisions>, <canonical_refs>, <code_context>, <specifics>, and <deferred> blocks.

3. (Optional) Research ​

np:research-phase 1

Spawns np-researcher (tier=sonnet). Produces M001-RESEARCH.md covering stack, patterns, pitfalls, the security domain and sources. When WebFetch and Context7 are not callable, it falls back to local-only research with a ## Research Coverage annotation.

4. Plan the entire milestone ​

np:plan-phase 1

Spawns np-planner (tier=opus). The planner breaks the milestone into slices (execution waves), and each slice into tasks (atomic units).

The planner writes:

  • M001-ROADMAP.md — slice list and execution order.
  • M001-META.json — slice_count, task_count, status.
  • Per slice: slices/S<NNN>/S<NNN>-PLAN.md with all <task> blocks inline, plus S<NNN>-ASSESSMENT.md and S<NNN>-UAT.md.

np-plan-checker (tier=opus) verifies goal-backward and returns a YAML verdict. If status: issues_found, the planner re-runs in revision mode for up to 2 iterations.

After the plan-check passes, the orchestrator runs scaffold-all-tasks, which reads every S<NNN>-PLAN.md, extracts every <task> block, and creates slices/S<NNN>/tasks/T<NNNN>/T<NNNN>-PLAN.md and T<NNNN>-SUMMARY.md for each task.

A slice is a wave: all tasks inside one slice run in parallel, slices run serially, and cross-slice dependencies flow forward only.

Two variants:

  • np:plan-phase 1 --research auto-dispatches np:research-phase 1 before planning if RESEARCH.md is missing.
  • np:plan-phase 1 --repromote re-scaffolds task files from existing slice plans without re-running the planner (useful after a bug fix to the scaffolder).

5. Execute ​

np:execute-phase 1

Wave-based execution. Slices run serially; tasks inside one slice run in parallel. For each task the orchestrator spawns np-executor (tier=sonnet) with the task plan, the slice plan, and the milestone context. The executor:

  1. Transitions the checkpoint to in-progress via np-tools.cjs checkpoint transition.
  2. Edits exactly the paths in files_modified (no auto-discovery).
  3. Runs the task's <verify><automated> command.
  4. Calls node np-tools.cjs commit-task M001-S001-T0001 for one atomic commit per task.

Each task runs through the Nubosloop: on a verify failure in round 2 or later, the loop spawns np-build-fixer automatically before the next round.

If execute-phase crashes mid-task, /np:resume-work classifies the session state; /np:reset-slice discards in-flight edits and drops the checkpoint.

6. Verify ​

np:verify-work 1

Spawns np-verifier (tier=sonnet). It walks every success_criterion from the milestone's roadmap entry, classifies each one as Pass, Fail, Defer or Needs-User-Confirm, and writes M001-VERIFICATION.md.

Optional follow-ups:

  • np:validate-phase 1 runs the Nyquist coverage audit: every requirement is observed by at least one direct test assertion.
  • np:add-tests 1 persists the VERIFICATION Pass-cases as node:test UAT files under test/uat/m001-<slug>.test.cjs.

7. Undo ​

np:undo-task M001-S001-T0001    # revert one task
np:undo 1                       # revert every task commit of milestone M001
np:undo M001-S002               # revert every task commit of slice M001-S002
np:reset-slice                  # discard in-flight task (no commit)

All undos are forward-commits via git revert --no-edit; history is never rewritten.

8. Loop ​

Start the next milestone with np:new-milestone and repeat from step 2.