nubos-pilot

Appearance

Planning Workflows ​

Commands that set up the project, capture decisions, and author plans.

np:new-project ​

Greenfield init with archive-aware detection. The run has five internal stages, labelled Phase -1 through Phase 3.

These Phase N labels are stages of the new-project workflow run, not milestones. Elsewhere in the CLI "phase" is a synonym for a milestone (/np:plan-phase <N> plans milestone M<N>); the new-project stage numbering is a separate, workflow-internal sequence.

  1. Phase -1 — Detect & Archive. Checks whether .nubos-pilot/PROJECT.md already exists. If it does, the workflow surfaces completion status (complete | incomplete | no-project) plus a blocker list and asks the user via the askuser gateway: Archive and start fresh (moves the project into archive/<slug>-<YYYYMMDD>/) | Close project first, then ask (chains into /np:close-project) | Abort. On an incomplete project the workflow demands a second confirmation before passing --force to the archiver. By default learnings/ and solutions/ are carried over so the new project inherits prior knowledge; opt out with --no-carry-over.
  2. Phase 0 — Workspace Scan. Deterministic inventory probe (workspace-scan --summary).
  3. Phase 1 — Bootstrap Interview. Five-question structural ask.
  4. Phase 2 — Project Discovery. Chains into /np:discuss-project --bootstrap (obligatory).
  5. Phase 3 — Additional Milestones. Proposes M002, M003 … from Discovery.

The five Phase 1 questions:

  • project_name
  • core_value — one sentence that must hold true even if everything else fails
  • primary_constraints — comma-separated (e.g. "Node 22; markdown-first")
  • first_milestone_name — e.g. "Auth & Basic UI"
  • first_milestone_goal — one sentence

Writes:

  • .nubos-pilot/PROJECT.md
  • .nubos-pilot/REQUIREMENTS.md
  • .nubos-pilot/RULES.md — project-wide always-follow rules (Always-Follow / Forbidden / Dependencies / Security / Logging / Style / Out-of-Scope). Every agent reads this before action; precedence is RULES.md (global) > M<NNN>-CONTEXT.md (phase-locked) > S<NNN>-PLAN.md (slice-scoped) > defaults.
  • .nubos-pilot/roadmap.yaml (schema_version: 2, first milestone M001 with empty slices: [])
  • .nubos-pilot/STATE.md (milestone = M001, milestone_number = 1)
  • .nubos-pilot/milestones/M001/M001-CONTEXT.md
  • .nubos-pilot/milestones/M001/M001-ROADMAP.md
  • .nubos-pilot/milestones/M001/M001-META.json
  • .nubos-pilot/milestones/M001/slices/ (empty subdirectory)

Chains automatically into /np:discuss-project and, when the workspace has source files, suggests /np:scan-codebase before planning.

np:new-milestone ​

Appends a new milestone M<NNN> to an existing project. Three-question interview: milestone_name, milestone_goal, create_req_prefix. Auto-numbers from the highest existing milestone in roadmap.yaml. Scaffolds milestones/M<NNN>/ with fresh CONTEXT/ROADMAP/META files and an empty slices/ subdirectory. Never touches PROJECT.md.

np:archive-project ​

Verbs: status (read-only — emits project-exists + completion JSON), do (move into archive/<slug>-<YYYYMMDD>/, suffix -2, -3, … on same-day collision), list (newest-first manifest list), read --name <archive-name> --rel <relative-path> (path-traversal-safe file read from a single archive). Flags on do: --force (archive even if computeCompletionStatus reports blockers; manifest records forced: true), --carry-over <a,b> (default learnings,solutions — copies originals into the archive AND keeps them top-level for the next project), --no-carry-over.

What gets moved into the archive (ARCHIVED_ITEMS in lib/archive.cjs): PROJECT.md, REQUIREMENTS.md, RULES.md, ROADMAP.md, STATE.md, roadmap.yaml, plus directories milestones/, codebase/, messages/, threads/, handoffs/, todos/, reports/, knowledge/, session/. What stays top-level: config.json (workspace config), archive/ itself, .tmp/, state/ (knowledge index), worktrees/, memory/ (vector store). Active worktrees abort the archive unless --force is set. Each archive contains an ARCHIVE.json manifest with archived_at, project_name, completion_status, milestones_count, blockers_at_archive, moved, carried_over, forced.

np:propose-milestones ​

Re-plans the not-yet-done milestone pipeline against the current PROJECT.md and REQUIREMENTS.md. Where /np:new-project creates the initial scaffold and /np:new-milestone appends a single milestone by hand, this workflow re-examines the whole open pipeline and proposes an updated sequence as add / update / remove operations. The user reviews each operation; the subcommand applies the accepted ones atomically inside one file-lock on roadmap.yaml.

Strict invariants:

  • Never writes PROJECT.md (D-29; enforced by the subcommand's _writeFile guard).
  • Never modifies completed milestones (status: done | complete | completed); raises milestone-completed-untouchable.
  • Never modifies milestones that already have slices unless confirm_force_modify: true is passed; raises milestone-has-slices.
  • Never touches M<NNN>-CONTEXT.md of existing milestones (only name and goal in roadmap.yaml change; CONTEXT.md is the user's /np:discuss-phase work and stays preserved).
  • Refuses to run while PROJECT.md still has _TBD placeholders.

Operation semantics:

  • add takes the same path as np:new-milestone --apply: appends to roadmap.yaml, creates M<NNN>/ with TBD CONTEXT/ROADMAP/META and an empty slices/.
  • update mutates name and/or goal of an existing entry in roadmap.yaml.
  • remove drops the entry from roadmap.yaml and moves M<NNN>/ to .nubos-pilot/archive/milestones/M<NNN>-<YYYY-MM-DD>/ (never hard-deletes).
bash
/np:propose-milestones
/np:propose-milestones --apply <answers.json>

Both add and remove auto-renumber as M<next> (next = max(existing) + 1) for added items.

np:discuss-project ​

Project-level context interview. Populates the PROJECT.md decision log sections. Runs once per project; the output guides every downstream milestone.

np:discuss-phase <N> ​

Milestone-level decision interview. "Phase" in the command name = milestone M<N>. Adaptive question flow over gray areas; writes M<NNN>-CONTEXT.md with:

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

Guard: if M<NNN>-CONTEXT.md already exists, prompts Overwrite / Append-update / Abort.

np:research-phase <N> ​

Milestone-level technical research. Spawns np-researcher (tier=sonnet). Produces M<NNN>-RESEARCH.md with stack, patterns, pitfalls, security domain, sources.

When WebFetch + Context7 are both unavailable, the researcher enters the Offline-Confirm Protocol: asks the user whether to proceed with local-only sources, and if yes, writes a ## Research Coverage annotation documenting what was local-only.

np:architect-phase <N> (optional) ​

Optional ADR step between /np:research-phase and /np:plan-phase. Spawns np-architect (tier=sonnet) which reads M<NNN>-RESEARCH.md + M<NNN>-CONTEXT.md + RULES.md + .nubos-pilot/codebase/INDEX.md and emits exactly one file: M<NNN>-ARCHITECTURE.md with module boundaries, a data-flow sketch, and 3–7 ADR-style decisions (D-arch-N).

Run when the milestone introduces structural change (new module, new boundary, new data flow), when CONTEXT marks architecture_review: required, or when RESEARCH flags ≥ 3 [ASSUMED] claims in the architecture-patterns dimension. Skip it for additive-only milestones; the planner handles those without an architecture pass.

bash
/np:architect-phase 1

Output is read by the planner as an extension of CONTEXT — locked. If a proposed decision would violate M<NNN>-CONTEXT.md or RULES.md, the agent emits ## CONTEXT CONFLICT and stops without writing the file; resolve via /np:discuss-phase <N> re-open.

np:plan-phase <N> ​

The planner + plan-checker + scaffolder pipeline. Input: milestone number N.

  1. Init — reads roadmap.yaml, milestone dir state, prior CONTEXT + RESEARCH.
  2. Gate 1 — if M<NNN>-CONTEXT.md missing: Run /np:discuss-phase first / Continue / Abort.
  3. Gate 2 — if RESEARCH missing and flag says required: Run /np:research-phase first / Skip / Abort (or auto-dispatch with --research).
  4. Gate 3 — if any slice already has S<NNN>-PLAN.md: Overwrite / Repromote / Abort.
  5. Verification loop (max 2 iterations):
    • spawn np-planner (tier=opus) — writes M<NNN>-ROADMAP.md + per slice S<NNN>-{ASSESSMENT,PLAN,UAT}.md
    • spawn np-plan-checker (tier=opus) — returns YAML verdict
    • on issues_found: planner re-runs in revision mode with findings
    • every iteration appends to M<NNN>-PLAN-REVIEW.md (byte-level append-only)
  6. Scaffold — scaffold-all-tasks walks every slice's S<NNN>-PLAN.md, extracts <task> blocks, creates tasks/T<NNNN>/T<NNNN>-PLAN.md + T<NNNN>-SUMMARY.md.
  7. Commit — single docs(M<NNN>): milestone plan ready for execute.

Flags:

  • --research — auto-dispatch /np:research-phase <N> before planning if RESEARCH.md is missing.
  • --repromote — skip gates + planner; just re-scaffold task files from existing slice plans.

np:agent-skills ​

Prints the agent_skills config for a given subagent (the additional skill files it should load). Used by other workflows when building the spawn prompt.

Task XML format (planner output) ​

Each <task> block inside a S<NNN>-PLAN.md MUST carry four attributes on the opening tag:

<task id="M001-S001-T0001" depends_on="" wave="1" tier="sonnet">
  <name>Seed login form</name>
  <files>src/auth/LoginForm.tsx</files>
  <action>…</action>
  <verify><automated>npm test -- LoginForm</automated></verify>
  <done>Form renders and test passes.</done>
</task>
  • id — full-id M<NNN>-S<NNN>-T<NNNN> matching the enclosing slice.
  • depends_on — comma-separated full-ids of earlier-slice tasks, or empty. Never same-slice (intra-slice tasks are parallel by contract).
  • wave — integer equal to the slice number.
  • tier — haiku | sonnet | opus.

The scaffolder reads only these opening-tag attributes. If any one is missing, the task is silently dropped from the task files.