nubos-pilot

Appearance

Getting Started ​

This walks the happy path from "empty directory" to "first phase shipped". Every step 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/roadmap.yaml + rendered ROADMAP.md
  • .nubos-pilot/STATE.md
  • .nubos-pilot/phases/01-<slug>/01-CONTEXT.md (placeholder)

If workflow.commit_docs is true, the scaffold lands in a single chore: np:new-project scaffold commit.

2. Ask "what now?" ​

np:next

Reads STATE.md + roadmap.yaml + the current phase directory and returns the next actionable step under the six-rule gate. After np:new-project, this is typically np:discuss-phase 1 or np:plan-phase 1 depending on whether CONTEXT.md is filled in.

3. Lock the decisions ​

np:discuss-phase 1

Adaptive interview that captures:

  • Locked decisions (D-01, D-02, …) — non-negotiable, every downstream task must honor them.
  • Deferred ideas — explicitly parked for a later phase.
  • Claude's discretion — Claude picks, documents the choice in the task action.

The output is a single 01-CONTEXT.md with <domain>, <decisions>, <canonical_refs>, <code_context>, <specifics> and <deferred> blocks. Two variants exist:

  • np:discuss-phase --assumptions <N> — lighter codebase-first mode.
  • np:discuss-phase-power <N> — bulk gray-area question file-UI.

4. (Optional) Research ​

np:research-phase 1

Spawns np-researcher (tier=sonnet). Produces 01-RESEARCH.md with stack, patterns, pitfalls, security domain, sources. Falls back to local-only with a ## Research Coverage annotation when WebFetch and Context7 are not callable.

5. Plan ​

np:plan-phase 1

Spawns np-planner (tier=opus). For each plan it emits a 01-NN-PLAN.md with frontmatter (wave, depends_on, files_modified, must_haves, …) and <objective>, <tasks>, <verification>, <success_criteria> body sections.

np-plan-checker (tier=opus) verifies the plan goal-backward and returns a YAML verdict. If status: issues_found, the planner re-runs in revision mode (max 2 iterations). Every iteration appends to 01-PLAN-REVIEW.md (append-only).

When parallelism, mixed tiers, or non-linear deps demand it, the planner promotes the inline <tasks> to standalone tasks/<task-id>.md files.

6. Execute ​

np:execute-phase 1

Wave-based execution. For each task in each wave the orchestrator spawns np-executor (tier=sonnet) with the task file and PLAN.md. 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 <task-id> — one atomic commit per task (ADR-0004).

Variants: np:execute-plan for a single plan, np:autonomous for an in-session auto-advance loop, np:pause-work / np:resume-work for explicit handoffs.

7. Verify ​

np:verify-work 1

Spawns np-verifier (tier=sonnet). Walks every success_criterion from ROADMAP.md, classifies each one as Pass / Fail / Defer / Needs-User-Confirm, writes 01-VERIFICATION.md. Presence of this file flips np:next from rule-4 to rule-5 and the phase is marked complete.

Optional follow-ups before/after verification:

  • np:secure-phase 1 — threat-mitigation audit against the plan's <threat_model>.
  • np:validate-phase 1 — Nyquist coverage check on tests.
  • np:code-review / np:code-review-fix — per-file review with auto-fix.
  • np:ui-review 1 / np:eval-review 1 — retroactive audits for UI / AI phases.

8. Loop ​

np:next will tell you to start the next phase, or np:progress shows the percentage across all phases and plans. When a milestone is done, np:cleanup archives it under .nubos-pilot/archive/v<X.Y>/.