FAQ & Anti-Patterns

How-to. Frequent questions and the mistakes the design tries to prevent. For the underlying why, see Concept Overview and the ADRs.

Concepts

Why is "phase" the same thing as "milestone"?

Slash-commands keep the word "phase" for backwards compatibility (np:plan-phase, np:discuss-phase, np:execute-phase). Internally, phase = milestone. /np:plan-phase 1 plans milestone M001 entirely. New code paths use "milestone" exclusively. The mismatch is intentional — renaming the slash-commands would break every project's muscle memory.

Why three execution levels (Milestone → Slice → Task) instead of four?

ADR-0003 caps the ontology. A four-level hierarchy with a separate "wave" entity duplicates work — slice and wave are the same concept. The planner decides parallelism by deciding which slice a task goes into; there is no second hierarchy level.

Why one commit per task, not one per slice?

ADR-0004. One commit per task makes /np:undo, /np:undo-task, and /np:reset-slice mechanical git revert operations rather than heuristic search jobs. A slice-level commit would force the undo machinery to parse diffs.

Why doesn't the agent commit on its own?

The executor does commit — but exclusively through np-tools.cjs commit-task <M-S-T>. That wrapper runs the gitignore-guard, formats the commit message canonically, deletes the checkpoint, and flips task frontmatter to done. A bare git commit from the agent would skip all of that and break the undo invariants.

Why no daemon?

ADR-0001. nubos-pilot is a payload of Markdown + .cjs helpers that the host CLI invokes inline. No background process means no service discovery, no port collisions, no dangling state on kill -9. Concurrency safety comes from O_EXCL lockfiles in lib/core.cjs::withFileLock.

Workflow questions

Should I always run np:research-phase?

No. Research is optional. Skip it when the milestone is purely additive in a stack you already know (e.g. "add another endpoint to an existing API"). Run it when the milestone introduces an unfamiliar dependency, a security-sensitive surface, or a stack the planner needs to learn before writing the plan.

Should I always run np:architect-phase?

No, this one is more selective. Run it when:

• the milestone introduces structural change (new module, new boundary, new data flow),
• M<NNN>-CONTEXT.md carries architecture_review: required,
• M<NNN>-RESEARCH.md flagged ≥ 3 [ASSUMED] claims in the architecture-patterns dimension.

For purely additive milestones the planner handles structure inline; the extra step is overhead.

What if np-plan-checker keeps returning issues_found?

The loop is bounded at 2 iterations. After that, control returns to you. Open M<NNN>-PLAN-REVIEW.md and read the findings. The most common cause is a gap in M<NNN>-CONTEXT.md — a missing decision the planner has no way to make. Re-run /np:discuss-phase <N> (Append-update mode) to lock the missing decision, then /np:plan-phase <N>.

What if a task fails verification?

Three options, in order of preference:

1. Fix in scope. Spawn np-build-fixer (manual — there is no /np:fix-build slash-command yet) with the failing task's payload. It classifies the failure, proposes a minimal patch inside files_modified, re-runs verify. Hard-capped at 3 attempts.
2. Fix manually. Edit the files yourself, then /np:resume-work to pick up where the executor left off.
3. Reset and re-plan. If the failure reveals a planning gap (the task was wrong-shaped), /np:reset-slice to discard, fix the task PLAN, re-run /np:execute-phase.

When do I run /np:add-tests?

After /np:verify-work reports Pass for the SCs you want to lock as regression tests. The command persists those Pass-cases as node:test UAT files under test/uat/m<nnn>-<slug>.test.cjs. Sentinel-preserving — your hand-written tests survive regeneration.

How does /np:propose-milestones differ from /np:new-milestone?

• /np:new-milestone appends one milestone you describe.
• /np:propose-milestones re-examines the whole open pipeline against the current PROJECT.md + REQUIREMENTS.md and proposes add / update / remove operations. Use it after a major requirement shift, not for routine append.

Anti-patterns

Don't put the same task in two slices "to be safe"

Tasks within a slice are parallel; cross-slice deps flow forward only. Putting T0001 in both S001 and S002 either (a) creates duplicate commits or (b) the second one no-ops. Either way, the plan-checker flags it. If two milestones genuinely need the same work, model it as a cross-slice depends_on, not a duplicate.

Don't edit roadmap.yaml by hand mid-plan

Use /np:propose-milestones, /np:new-milestone, or update-phase-meta. The yaml is parsed under a lock; hand-edits during a workflow run can race the parser. After-the-fact corrections are fine if no workflow is mid-flight.

Don't add model or model_profile to agent frontmatter

Forbidden by D-09. Concrete model selection is tier-based and resolved at spawn time by np-tools.cjs resolve-model. Embedding a literal model id breaks portability across runtimes.

Don't add hooks to agent frontmatter

Same reason. Hooks are runtime-specific (Claude Code ≠ Codex ≠ Gemini); they live in the runtime-adapter layer, not in the portable agent contract.

Don't put a host-specific prompt call in workflow Markdown

check-workflows.cjs lints for this. Use node np-tools.cjs askuser --json '{…}' exclusively — the capability layer routes through whatever the host CLI exposes.

Don't git revert task commits manually

Use /np:undo-task or /np:undo. The slash-commands also reset task frontmatter to pending so the next /np:execute-phase picks them up. A bare git revert leaves the frontmatter as done, and the next plan run sees a phantom completed task.

Don't rm -rf .nubos-pilot/ to "start fresh"

That destroys all your plans, decisions, history, and metrics. To uninstall the tool, use npx nubos-pilot uninstall — it removes the install payload but preserves .nubos-pilot/. To clear state for a specific milestone, /np:undo <N> followed by editing roadmap.yaml.

Don't set agents.parallelization: false to "make execution safer"

The kill-switch exists for constrained environments (single-thread CI, rate-limited model APIs). On a normal dev machine, parallel execution within a slice is the whole point of slice-as-wave. Turning it off makes a 5-task slice take 5× longer for no safety benefit — atomicity is per-task, not per-slice.

Don't disable the plan-checker to "save time"

agents.plan_checker: false skips the adversarial review loop. The two iterations cost ~2 minutes; catching an unbounded-scope task before execution saves hours. Disable only when you are confident the planner output is correct (e.g. you're re-running /np:plan-phase --repromote after a fix).

Don't expect agents to spawn other agents

The orchestration graph is one level deep by design. Workflows orchestrate; agents read, write, reason, and exit. If you find yourself wanting an agent to spawn a sub-agent, the right shape is a workflow that runs both in sequence.

Configuration

Where is agent_skills documented?

config.json can carry an agent_skills map (e.g. { "np-researcher": ["nubos-research-skill"] }) that lists additional skill files an agent should load at spawn time. The map is read by np-tools.cjs agent-skills <name> and consumed by the workflow when building the spawn prompt. See Agent skills.

Should I commit config.json?

Yes. It captures runtime, model_profile, response_language — project-wide settings the team needs to share. Sensitive values (API keys, tokens) should never live there; use environment variables or your runtime's secret store.

Should I commit .nubos-pilot/state/?

No. Everything under state/ is ephemeral derived cache (knowledge-index.json, session-snapshot.json). Add .nubos-pilot/state/ to .gitignore if your generator hasn't already.

Multi-runtime

Can I install for several runtimes at once?

Yes. npx nubos-pilot --agents claude,codex,cursor installs payload + managed-block for all three. The tool maintains separate manifest files per runtime path; update and uninstall walk all of them.

What happens when I switch runtimes mid-project?

The .nubos-pilot/ Project-State tree is runtime-agnostic. Re-run npx nubos-pilot --agent <new> to lay down a fresh payload; your plans and decisions survive untouched.

Does /np:doctor check all installed runtimes?

It checks the runtime that detect-runtime resolves to. To verify a different one, set runtime in config.json first or invoke from inside that host CLI.