Quickstart

Tutorial. Zero to first shipped milestone in seven slash-commands. 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 seven steps

/np:new-project          # 1. scaffold PROJECT.md, REQUIREMENTS.md, RULES.md, M001 shell
/np:discuss-phase 1      # 2. lock decisions for milestone M001 → M001-CONTEXT.md
/np:research-phase 1     # 3. (optional) stack + pitfalls research → M001-RESEARCH.md
/np:plan-phase 1         # 4. planner + plan-checker → S<NNN>-PLAN.md + per-task files
/np:execute-phase 1      # 5. wave-based execution; one atomic commit per task
/np:verify-work 1        # 6. goal-backward verification → M001-VERIFICATION.md
/np:new-milestone        # 7. start the next milestone, repeat from step 2

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.

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
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.