FAQ and anti-patterns

How-to. Frequent questions and the mistakes the design tries to prevent. For the underlying rationale, 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 means milestone: /np:plan-phase 1 plans milestone M001 entirely. New code paths use "milestone" exclusively. The mismatch is intentional, since 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, because 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 and .cjs helpers that the host CLI invokes inline. With no background process there is no service discovery, no port collision, and 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?

During /np:execute-phase the Nubosloop handles this on its own: a verify failure in round 2 or later routes to np-build-fixer, which classifies the failure, proposes a minimal patch inside files_modified, and re-runs verify. No separate command is needed. The loop continues up to loop.maxRounds (default 3) before it marks the task stuck.

When the loop reaches stuck, or when you want to intervene outside the loop, three options apply, in order of preference:

1. Fix in scope. Let the loop run its np-build-fixer rounds, or escalate per Troubleshooting → When the Nubosloop is stuck.
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), run /np:reset-slice to discard, fix the task PLAN, then 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. It is 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 and REQUIREMENTS.md, and proposes add / update / remove operations. Use it after a major requirement shift, not for a routine append.

How do I check at the end of the project that every milestone passed?

Run /np:close-project. It aggregates every M<NNN>-VERIFICATION.md + M<NNN>-VALIDATION.md, surfaces blockers (failed SCs, pending SCs, missing reports, UNCOVERED requirements), and writes PROJECT-SUMMARY.md. On no blockers → roadmap.yaml.project_status = "completed". With blockers → askuser (abort / close-with-blockers / force-complete). See ADR-0016.

/np:close-project is the single project-wide aggregate check. Per-milestone verification still happens at execution time via /np:verify-work <N> and /np:validate-phase <N>; close-project only aggregates the persisted output.

My /np:close-project reports blockers that don't match the underlying VERIFICATION/VALIDATION files. Bug?

If you see "phantom" blockers (for example UNCOVERED counts that do not appear in the actual VALIDATION.md), the artefact predates ADR-0017 and the aggregator's legacy body-grep fallback fired. Run np:doctor to surface the drift, then re-run /np:verify-work <N> and /np:validate-phase <N> for the offending milestones. Current spawns write schema-bound frontmatter that the aggregator reads as canonical truth.

How do I start a successor project in the same workspace without losing history?

Run /np:new-project. Phase -1 detects the existing PROJECT.md and offers three choices: Archive and start fresh (moves the current project into .nubos-pilot/archive/<slug>-<date>/, optionally carrying over learnings/ and solutions/); Close project first (chains into /np:close-project, then asks again); or Abort. rm -rf .nubos-pilot/ is never needed. See Project Lifecycle.

When do I pass --verify-work to /np:execute-phase?

When you want /np:verify-work <N> to run automatically after every slice has committed and finalize-milestone has produced the slice summaries. It carries the same hard-fail contract as a manual /np:verify-work (exit 1 on any Fail SC). Without the flag, verify-work stays a manual step, which is useful when you want to inspect commits before starting the verifier.

Why is np-researcher-reconciler running on every /np:research-phase?

ADR-0018. Before the rule, three parallel researchers produced inconsistent shapes that the deterministic merge silently bucketed apart ("intersection ≈ 0, consensus a fiction"). Now each spawn writes a schema-bound output; the reconciler reads all of them plus the deterministic merge proposal, classifies reasoning-trace agreement (orthogonal versus identical, where identical signals groupthink), surfaces contested decisions explicitly, and writes the final M<NNN>-RESEARCH.md. The cache-bypass path still skips the entire swarm on a high-similarity learning hit.

What does "schema violation" mean when a workflow fails after a spawn?

output-lint --enforce ran on the just-written artefact and rejected it. The agent's output doesn't conform to the artefact's schema (e.g. missing frontmatter key, wrong status enum, [object Object] in a heading). Re-spawn the producing agent with the violation list as feedback — do not hand-edit the file to satisfy the linter. Hand-edits hide the underlying agent-prompt or schema bug. See Output Schemas.

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, run /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 about two minutes; catching an unbounded-scope task before execution saves hours. Disable it only when you are confident the planner output is correct (for example when 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 and response_language, which are 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 the payload and 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.