Planning Workflows

Set up the project, capture decisions, write plans. Every workflow here either creates a phase artifact or modifies the roadmap.

np:new-project

Greenfield project scaffold. Five-question interview, then writes:

• .nubos-pilot/PROJECT.md
• .nubos-pilot/REQUIREMENTS.md
• .nubos-pilot/roadmap.yaml + rendered ROADMAP.md
• .nubos-pilot/STATE.md
• .nubos-pilot/phases/01-<slug>/01-CONTEXT.md (placeholder)

Refuses to run when PROJECT.md already exists (throws project-already-initialized); offers an explicit destructive reset path.

When workflow.commit_docs is true, the scaffold is committed in a single chore: np:new-project scaffold.

np:new-milestone

Append a new milestone (and its first phase) to an existing project. Updates roadmap.yaml, re-renders ROADMAP.md, scaffolds phases/<NN>-<slug>/.

np:discuss-phase

Adaptive interview that captures user decisions for a phase and writes <NN>-CONTEXT.md. Three modes:

• adaptive (default) — analyzes the phase, identifies gray areas, walks the user through them.
• --assumptions — lighter codebase-first mode (workflows/discuss-phase-assumptions.md).
• --power — bulk gray-area question file-UI (np:discuss-phase-power).

CONTEXT.md ends up with <domain>, <decisions>, <canonical_refs>, <code_context>, <specifics>, <deferred> blocks. Locked decisions become D-01, D-02, … and are non-negotiable for the planner downstream.

np:discuss-phase 5

np:discuss-phase-power

Power-mode variant. Writes QUESTIONS.json as the source of truth and renders CONTEXT.md only on finalize. The user edits the JSON in their editor between rounds. See Phase Artifact Schemas → QUESTIONS.json for the schema.

np:research-phase

Optional. Spawns np-researcher (tier=sonnet) to produce <NN>-RESEARCH.md with:

• ## Standard Stack
• ## Architecture Patterns
• ## Don't Hand-Roll
• ## Pitfalls
• ## Security Domain
• ## Validation Architecture
• ## Open Questions
• ## Sources — each line - <url-or-path> — <relevance> — <HIGH|MEDIUM|LOW>

Falls back to local-only with a ## Research Coverage annotation when WebFetch + Context7 are not callable (D-21..D-23).

np:plan-phase

The headline workflow. Spawns np-planner (tier=opus), runs the plan-checker revision loop, writes one or more <NN>-<MM>-PLAN.md files plus an append-only <NN>-<MM>-PLAN-REVIEW.md. Pre-step writes <NN>-PATTERNS.md and <NN>-VALIDATION.md for the planner to consume.

The plan-checker loop is bounded at 2 iterations — if the planner cannot produce a passing plan in two rounds, the workflow stops and surfaces the verdict to the user.

When parallelism, mixed-tiers, or non-linear-deps triggers fire, the planner promotes inline <task> blocks to standalone tasks/<task-id>.md files with the full 12-field frontmatter (D-01).

np:plan-phase 5
np:plan-phase 5 --gaps audit-2026-04-15.md   # gap-closure mode

np:plan-milestone-gaps

Audit-driven planning. Reads a gap report (typically np:verify-work output) and creates corrective phases at decimal-positioned slots (e.g. 4.1-fix-...). Use after a phase verifies with Fail SCs.

np:plan-diff

Renders a two-part diff between two PLAN.md versions: a semantic diff (added/removed tasks, changed files_modified, changed must_haves) and the raw git diff. Also archives plan rejections with a stored reason.

np:agent-skills

Prints the agent_skills config block for a given subagent, used by the planner when authoring task <read_first> lists. Read-only.

np:ai-integration-phase

AI-SPEC generator. Spawns four agents in sequence:

1. np-domain-researcher — business domain and real-world context.
2. np-framework-selector — interactive scoring matrix for the AI/LLM stack.
3. np-ai-researcher — chosen framework's docs distilled for the use case.
4. np-eval-planner — eval strategy, guardrails, monitoring.

Output is <NN>-AI-SPEC.md consumed by the AI executor and np:eval-review.

np:ui-phase

UI-SPEC generator. Spawns np-ui-researcher (tier=sonnet) to produce <NN>-UI-SPEC.md, then runs np-ui-checker (tier=haiku) for a 6-dimension verdict (BLOCK / FLAG / PASS) with a revision loop similar to plan-checker.