Quickstart

Tutorial. Zero to first shipped milestone as a copy-paste command sequence. For a step-by-step tour with each command explained, read Getting Started. For why the tool exists, read Introduction; for the underlying mental model, read Concept Overview.

0. Install

cd your-project/
npx nubos-pilot --agent claude   # or: codex, gemini, opencode, cursor, …

Four-question interview (runtime, scope, model profile, response language). Adds .claude/nubos-pilot/ (payload) and a managed block in CLAUDE.md. Full options in Installation.

Verify:

npx nubos-pilot doctor

The eight steps

/np:new-project                    # 1. scaffold PROJECT.md, REQUIREMENTS.md, RULES.md, M001 shell
                                   #    (Phase -1 detects an existing project and offers archive-then-init)
/np:discuss-phase 1                # 2. lock decisions for milestone M001 → M001-CONTEXT.md
/np:research-phase 1               # 3. (optional) k-spawn swarm + reconciler → M001-RESEARCH.md (ADR-0018)
/np:plan-phase 1                   # 4. planner + plan-checker → S<NNN>-PLAN.md + per-task files
/np:execute-phase 1 --verify-work  # 5. wave-based execution; --verify-work auto-chains step 6 on success
/np:verify-work 1                  # 6. goal-backward verification → M001-VERIFICATION.md (schema-bound)
/np:validate-phase 1               # 7. Nyquist coverage audit → M001-VALIDATION.md (schema-bound)
/np:new-milestone                  # 8. start the next milestone, repeat from step 2

When all milestones are done:

/np:close-project                  # aggregate verification across every milestone → PROJECT-SUMMARY.md
                                   # sets roadmap.yaml.project_status = "completed" when no blockers remain

That is the entire happy path. Every step is reversible:

• /np:reset-slice — discards an in-flight task that crashed mid-execution.
• /np:undo-task M001-S001-T0001 — reverts one committed task via git revert.
• /np:undo 1 — reverts every task commit of a milestone.
• /np:new-project Phase -1 — archives the current project before starting a successor (no rm -rf needed).

Key concepts in 30 seconds

• Milestone (= "phase" in command names): a top-level project goal. /np:plan-phase 1 plans milestone M001 entirely.
• Slice (= wave): a group of tasks that run in parallel. Slices run serially.
• Task: an atomic unit. One task → one git commit (task(M001-S001-T0001): …).

Three trees on disk that never overlap:

• Source (tools/nubos-pilot/) — only contributors see this.
• Install-Payload (.claude/nubos-pilot/) — your installed copy, managed by the installer.
• Project-State (.nubos-pilot/) — your plans, decisions, and history. Survives uninstall.

Where to go next

You want to …	Read
Understand the mental model	Concept Overview
See every slash-command	Workflows Overview
See every CLI subcommand	CLI Commands
Tune config.json	Configuration
Know what each agent does	Agent Catalog
Understand project close + archive	Project Lifecycle
Understand the researcher swarm + reconciler	Researcher-Schwarm
Know why outputs are schema-linted	Output Schemas
Recover from a crash	Execution Workflows §undo / reset-slice
Understand a thrown error	Error Codes
See the on-disk file shape	Directory Layout
Know what's pinned by ADR	ADR Index

Troubleshooting one-liners

Symptom	First thing to try
commit-all-paths-gitignored	All your files_modified are gitignored — fix .gitignore or the task's path list.
Executor crashed mid-task	/np:reset-slice to discard, or /np:resume-work to classify the session.
Plan-checker keeps returning issues_found	After 2 iterations the loop stops; read M<NNN>-PLAN-REVIEW.md and re-run /np:discuss-phase if the gap is in CONTEXT.
Install seems broken	npx nubos-pilot doctor --fix.
Worktree weirdness	Set workflow.worktree_isolation: false in config.json to disable; existing worktrees stay until removed manually.
Task is stuck after Nubosloop	np:dashboard shows the marker; read the last Critic-Schwarm findings in the task's checkpoint and choose: continue with override, escalate to a human dev, or /np:reset-slice.

Your first Nubosloop

/np:execute-phase runs the Nubosloop for every task. The loop is a 6-step build → critic → route iteration that converges in 3 rounds or fewer (configurable). /np:execute-phase drives it; there is no separate command to invoke. Knowing the shape helps you read the dashboard and the checkpoints.

Walking through a task

After /np:execute-phase 1 starts, inspect a single task's progress:

# One-shot read-only snapshot of every slice's task statuses
/np:dashboard

# Inspect the checkpoint of the in-flight task
cat .nubos-pilot/checkpoints/M001-S001-T0001.json

/np:dashboard is a one-shot view (ADR-0009); re-run it to refresh.

The checkpoint's nubosloop block carries the loop state: round, last_action, accumulated findings.

Reading the round

last_action	Meaning
executor / build-fixer	A code-write spawn ran; mechanical checks are next
researcher	A new Researcher-Schwarm round is in flight (an information-missing finding routed back)
askuser	The loop is paused waiting for your answer to a Critic-flagged question
plan-checker	A locked-decision violation was detected; plan-checker reviews
commit	Critics returned 0 findings; the atomic commit landed
stuck	loop.maxRounds reached without convergence; manual intervention required

Tuning the loop

Swarm + Loop Config lists every tuning knob. The two most useful:

{
  "loop": { "maxRounds": 3 },
  "swarm": {
    "research": { "k": 3, "threshold": 0.9, "minOccurrence": 3 }
  },
  "auto_log_learning": true
}

maxRounds = 3 is the default. Most tasks converge in round 1 or 2, and round 3 catches edge cases. The configurable range is [1, 100]; when a task still fails past round 3 the cause is usually structural, so escalate rather than raise the cap.

When the loop gets stuck

When the dashboard shows stuck, read the Troubleshooting → When the Nubosloop is stuck section. Three options:

1. Manual override — fix the underlying issue yourself, then /np:resume-work.
2. Escalate — bring in a human dev with the captured Critic findings as context.
3. Reset — /np:reset-slice <task-id> discards the in-flight work and re-runs the slice.