nubos-pilot 0.1.0

package/workflows/execute-phase.md

@@ -0,0 +1,142 @@
+---
+command: np:execute-phase
+description: Wave-based phase execution. Spawns executor (sonnet) per task with atomic-commit-per-unit enforced via np-tools.cjs commit-task helper (D-03/D-25).
+---
+
+# /np:execute-phase
+
+<objective>
+Run every wave of every plan in a given phase: for each task in wave-order,
+start a checkpoint, spawn agents/np-executor.md (sonnet), verify, and invoke
+`node np-tools.cjs commit-task <task-id>` for the atomic commit. All git
+operations route through lib/git.cjs — agents NEVER call `git` directly
+(ADR-0004, CLAUDE.md §Git operations).
+</objective>
+
+## Initialize
+
+```bash
+PHASE="$1"
+INIT=$(node np-tools.cjs init execute-phase "$PHASE")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+AGENT_SKILLS_EXECUTOR=$(node np-tools.cjs agent-skills executor 2>/dev/null)
+RUNTIME=$(node -e "console.log(require('./lib/runtime/index.cjs').detect().runtime)")
+```
+
+Parse JSON for: `phase`, `padded`, `phase_dir`, `plans[]` (each with
+`plan_path`, `waves`, `task_count`), `executor_tier`, `agent_skills`.
+
+`PLAN_ID` is iterated from `plans[]` (e.g. `06-01`) and `TASK_ID` is iterated
+from each plan's `waves[]` entries. Both are used by the metrics-record calls
+in the per-task loop below.
+
+## Pre-Flight — orphan-checkpoint guard
+
+Detect stale checkpoints from a prior run before starting new work:
+
+```bash
+RESUME=$(node np-tools.cjs init resume-work)
+RESUME_STATUS=$(echo "$RESUME" | node -e "process.stdin.on('data', d => console.log(JSON.parse(d).status))")
+if [ "$RESUME_STATUS" = "orphan" ]; then
+  CHOICE=$(node np-tools.cjs askuser --json '{
+    "type": "select",
+    "header": "Verwaiste Checkpoints gefunden",
+    "question": "Vor dem Phase-Start wurden Checkpoint-Dateien ohne passenden STATE.current_task gefunden. Was tun?",
+    "options": [
+      {"label": "Clean working tree (reset-slice)", "description": "Verwirft die in-flight Task und löscht ihren Checkpoint."},
+      {"label": "Resume the orphan task",            "description": "Setzt STATE.current_task auf den Checkpoint-Eintrag und spawnt den Executor."},
+      {"label": "Abort",                              "description": "Exit, User entscheidet manuell."}
+    ]
+  }')
+  case "$CHOICE" in
+    "Abort") exit 0 ;;
+  esac
+fi
+```
+
+## Execution — per wave, per task
+
+For each plan in `plans[]`, for each wave in `plan.waves`, for each task-id
+in the wave:
+
+```bash
+TASK_ID="06-01-T01"   # example — iterated from waves[]
+PLAN_ID="06-01"       # example — iterated from plans[]
+
+# Start crash-safety checkpoint.
+node np-tools.cjs checkpoint start "$TASK_ID" --phase "$PHASE" --plan "$PLAN_ID" --wave 1
+
+# Fetch the executor-spawn payload (files_modified + task_name + tier).
+TASK_JSON=$(node np-tools.cjs init execute-phase execute-task "$PHASE" "$TASK_ID")
+if [[ "$TASK_JSON" == @file:* ]]; then TASK_JSON=$(cat "${TASK_JSON#@file:}"); fi
+
+# --- Resolve executor model + start metrics clock (D-06) ---
+EXECUTOR_START=$(node np-tools.cjs metrics start-timestamp)
+EXECUTOR_MODEL=$(node np-tools.cjs resolve-model executor --profile balanced)
+```
+
+Spawn `agents/np-executor.md` (tier: sonnet, from `executor_tier`, model
+resolved as `$EXECUTOR_MODEL`) with a `<files_to_read>` block containing: the
+plan file, the task file, prior phase SUMMARY.md files. The host runtime
+consumes `$EXECUTOR_MODEL` via its spawn adapter (empty string → omit the
+`model:` parameter per Phase 8 D-22 inherit-pattern). The executor edits
+EXACTLY the paths in `files_modified` (D-04 — no scope expansion), runs any
+`<verify>` commands, then invokes the commit helper:
+
+```bash
+node np-tools.cjs checkpoint transition "$TASK_ID" verifying
+node np-tools.cjs checkpoint transition "$TASK_ID" pre-commit
+
+# Atomic commit — LOUD FAIL propagates if every files_modified entry is
+# gitignored (D-25). The helper prints a JSON payload `{ok, task_id, sha, files}`.
+node np-tools.cjs commit-task "$TASK_ID"
+COMMIT_STATUS=$?
+
+# --- Close metrics record for this executor task (D-06/D-08) ---
+EXECUTOR_END=$(node np-tools.cjs metrics end-timestamp)
+EXECUTOR_STATUS=ok
+[ "$COMMIT_STATUS" -ne 0 ] && EXECUTOR_STATUS=error
+node np-tools.cjs metrics record \
+  --agent np-executor --tier sonnet --resolved-model "$EXECUTOR_MODEL" \
+  --phase "$PHASE" --plan "$PLAN_ID" --task "$TASK_ID" \
+  --started "$EXECUTOR_START" --ended "$EXECUTOR_END" \
+  --tokens-in "${TOKENS_IN:-0}" --tokens-out "${TOKENS_OUT:-0}" \
+  --retry-count "${RETRY_COUNT:-0}" --status "$EXECUTOR_STATUS" --runtime "$RUNTIME"
+
+if [ "$COMMIT_STATUS" -ne 0 ]; then
+  echo "[np:execute-phase] commit-task failed for $TASK_ID — aborting wave." >&2
+  exit "$COMMIT_STATUS"
+fi
+```
+
+After a full phase completes: point the operator at `/np:verify-work
+$PHASE`.
+
+## Scope Guardrail
+
+<!-- scope_guardrail -->
+**Do:**
+- Start one checkpoint per task before spawning the executor agent.
+- Spawn `agents/np-executor.md` (sonnet) once per task with only the task's
+  `files_modified` in scope.
+- Route every commit through `node np-tools.cjs commit-task` so
+  `assertCommittablePaths` (D-25) runs.
+- Hard-stop the wave when `commit-task` returns a non-zero exit (D-23
+  propagation — don't mask the failure).
+
+**Don't:**
+- Invoke `git commit`, `git add`, or any bare git command from this
+  workflow or the spawned agent (CLAUDE.md §Git operations).
+- Bundle two tasks into one commit (ADR-0004 atomicity).
+- Skip the checkpoint start step — it's the crash-safety primitive
+  `resume-work` depends on.
+- Pass `--no-verify` or `--force` anywhere in the pipeline.
+<!-- /scope_guardrail -->
+
+## Output
+
+- One git commit per completed task (`task(<phase>-<plan>-T<NN>): <name>`).
+- Per-task checkpoint lifetime: `start` → (`transition verifying|pre-commit`)+
+  → `deleteCheckpoint` (inside commit-task on success).
+- STATE.md updated via `startTask`'s coordinated lock-cycle (D-08).
+- Verified work surface for `/np:verify-work $PHASE`.

package/workflows/execute-plan.md

@@ -0,0 +1,82 @@
+---
+command: np:execute-plan
+description: Execute all tasks in a single plan (wave-ordered, atomic-commit-per-task). Sub-case of /np:execute-phase scoped to one plan.
+---
+
+# /np:execute-plan
+
+<objective>
+Same semantics as `/np:execute-phase` but scoped to one plan — useful when
+re-running or revising a single plan after its peers have already shipped.
+</objective>
+
+## Initialize
+
+```bash
+PLAN_ID="$1"   # e.g. 06-01
+INIT=$(node np-tools.cjs init execute-plan "$PLAN_ID")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+AGENT_SKILLS_EXECUTOR=$(node np-tools.cjs agent-skills executor 2>/dev/null)
+```
+
+Parse: `plan_id`, `phase`, `padded`, `plan_path`, `tasks_dir`, `waves`,
+`task_count`, `executor_tier`, `agent_skills`.
+
+## Pre-Flight — orphan-checkpoint guard
+
+```bash
+RESUME=$(node np-tools.cjs init resume-work)
+RESUME_STATUS=$(echo "$RESUME" | node -e "process.stdin.on('data', d => console.log(JSON.parse(d).status))")
+if [ "$RESUME_STATUS" = "orphan" ]; then
+  CHOICE=$(node np-tools.cjs askuser --json '{
+    "type": "select",
+    "header": "Verwaiste Checkpoints gefunden",
+    "question": "Checkpoints ohne passenden STATE.current_task gefunden — weitermachen?",
+    "options": [
+      {"label": "Clean and proceed", "description": "reset-slice + fresh start."},
+      {"label": "Abort",              "description": "Exit, User entscheidet manuell."}
+    ]
+  }')
+  case "$CHOICE" in
+    "Abort") exit 0 ;;
+  esac
+fi
+```
+
+## Execution — per wave, per task
+
+For each wave in `waves`, for each `TASK_ID`:
+
+```bash
+TASK_ID="06-01-T01"
+node np-tools.cjs checkpoint start "$TASK_ID" --phase "$phase" --plan "$PLAN_ID" --wave 1
+
+TASK_JSON=$(node np-tools.cjs init execute-phase execute-task "$phase" "$TASK_ID")
+if [[ "$TASK_JSON" == @file:* ]]; then TASK_JSON=$(cat "${TASK_JSON#@file:}"); fi
+```
+
+Spawn `agents/np-executor.md` (sonnet) per task with `files_modified`,
+`<files_to_read>` = [plan_path, task_file, prior SUMMARY.md files].
+Executor performs the work, runs the `<verify>` command, then:
+
+```bash
+node np-tools.cjs checkpoint transition "$TASK_ID" verifying
+node np-tools.cjs checkpoint transition "$TASK_ID" pre-commit
+node np-tools.cjs commit-task "$TASK_ID"
+COMMIT_STATUS=$?
+if [ "$COMMIT_STATUS" -ne 0 ]; then
+  echo "[np:execute-plan] commit-task failed for $TASK_ID" >&2
+  exit "$COMMIT_STATUS"
+fi
+```
+
+## Scope Guardrail
+
+**Do:** one commit per task via `commit-task`; one executor per task.
+**Don't:** bundle tasks, call bare `git`, or span multiple plans.
+
+## Output
+
+- N commits (N = count of tasks in the plan), each
+  `task(<plan_id>-T<NN>): <name>`.
+- Plan ready for `/np:verify-work` (phase-scoped).

package/workflows/help.md

@@ -0,0 +1,8 @@
+# np:help
+
+List every available `np-tools.cjs` command grouped by category. Pass `--json`
+for programmatic consumption.
+
+```bash
+node np-tools.cjs help
+```

package/workflows/new-milestone.md

@@ -0,0 +1,166 @@
+---
+command: np:new-milestone
+description: Append a milestone + first phase to an initialized project. Never rewrites PROJECT.md (D-29).
+---
+
+# np:new-milestone
+
+Append a new milestone and its first phase to an already-initialized
+project. This workflow is the counterpart to `np:new-project`: `new-project`
+creates the root; `new-milestone` grows it.
+
+## Philosophy
+
+<philosophy>
+A milestone is a scope anchor — the unit that ships together and earns a
+retrospective. Adding a milestone is never a rewrite of prior work: the
+previous milestone's phases, plans, and SUMMARY.md files stay exactly as
+they were. Only `roadmap.yaml` and (optionally) `REQUIREMENTS.md` grow.
+PROJECT.md is sacrosanct — see D-29.
+</philosophy>
+
+## Scope Guardrail
+
+<scope_guardrail>
+This workflow ONLY touches:
+
+- `.nubos-pilot/roadmap.yaml` (append milestone + first phase)
+- `.nubos-pilot/ROADMAP.md` (regenerated via lib/roadmap-render)
+- `.nubos-pilot/STATE.md` (advance milestone + current_phase pointers)
+- `.nubos-pilot/phases/<NN>-<slug>/` (new phase directory +
+  `<NN>-CONTEXT.md` placeholder)
+- `.nubos-pilot/REQUIREMENTS.md` (APPEND a new H2 section ONLY when
+  `create_req_prefix` is `true`)
+
+It NEVER writes `.nubos-pilot/PROJECT.md` — D-29 strict invariant. The
+subcommand has a defensive guard (`_writeFile`) that throws
+`new-milestone-forbidden-write` if any code path ever routes a PROJECT.md
+target to it.
+</scope_guardrail>
+
+## Downstream Awareness
+
+<downstream_awareness>
+Phase numbers are global across the roadmap — a phase dir at
+`.nubos-pilot/phases/<NN>-<slug>/` is keyed by the integer `NN`. The
+subcommand computes the next global number across all milestones before
+seeding the new milestone; this avoids the per-milestone numbering in
+`lib/roadmap.cjs addPhase` (Phase 05-05) which would collide with phase
+1 of the previous milestone on disk.
+</downstream_awareness>
+
+## Guard
+
+Refuse early when not in an initialized project.
+
+```bash
+if [ ! -f .nubos-pilot/PROJECT.md ]; then
+  echo "Error: no .nubos-pilot/PROJECT.md found. Run np:new-project first."
+  exit 1
+fi
+```
+
+The subcommand raises `project-not-initialized` anyway, but the shell
+check gives a cleaner message before the interview starts.
+
+## Single-Call Init
+
+```bash
+INIT=$(node np-tools.cjs init new-milestone)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Payload: four questions — `milestone_name`, `milestone_goal`,
+`first_phase_name`, `create_req_prefix` (confirm).
+
+## Interview
+
+Four questions through `np-tools.cjs askuser`. No runtime-native
+question tool is permitted anywhere in this file.
+
+```bash
+ANS_MS_NAME=$(node np-tools.cjs askuser --json '{"type":"input","prompt":"Milestone name (e.g. v2.0)?"}')
+ANS_MS_GOAL=$(node np-tools.cjs askuser --json '{"type":"input","prompt":"Milestone goal (one sentence)?"}')
+ANS_FIRST_PHASE=$(node np-tools.cjs askuser --json '{"type":"input","prompt":"First phase name for this milestone?"}')
+ANS_REQ_PREFIX=$(node np-tools.cjs askuser --json '{"type":"confirm","prompt":"Create a new Requirements section for this milestone?","default":false}')
+```
+
+<answer_validation>
+The subcommand slugifies `milestone_name` and `first_phase_name`; empty
+results throw `invalid-slug`. Duplicate milestone ids (after slugify)
+throw `roadmap-duplicate-milestone` and this workflow prints the error
+and exits — the user decides whether to pick a different name.
+</answer_validation>
+
+## Apply
+
+```bash
+ANSWERS=$(mktemp -t np-new-milestone-answers.XXXXXX)
+trap 'rm -f "$ANSWERS"' EXIT
+
+node -e '
+  const fs = require("fs");
+  const prefix = process.env.ANS_REQ_PREFIX;
+  const payload = {
+    milestone_name: process.env.ANS_MS_NAME,
+    milestone_goal: process.env.ANS_MS_GOAL,
+    first_phase_name: process.env.ANS_FIRST_PHASE,
+    create_req_prefix: prefix === "true" || prefix === "yes" || prefix === "y",
+  };
+  fs.writeFileSync(process.env.ANSWERS, JSON.stringify(payload));
+' ANS_MS_NAME="$ANS_MS_NAME" ANS_MS_GOAL="$ANS_MS_GOAL" ANS_FIRST_PHASE="$ANS_FIRST_PHASE" ANS_REQ_PREFIX="$ANS_REQ_PREFIX" ANSWERS="$ANSWERS"
+
+node np-tools.cjs init new-milestone --apply "$ANSWERS"
+```
+
+On success the subcommand emits:
+
+```json
+{
+  "mode": "apply",
+  "milestoneId": "v2-0",
+  "phaseNumber": 11,
+  "phaseSlug": "second-phase",
+  "created_req_prefix": true
+}
+```
+
+## D-29 Invariant
+
+<!--
+Defense-in-depth: the subcommand already refuses to write PROJECT.md via
+_writeFile(). This comment is a reminder for humans reviewing this
+workflow: NEVER add a step here that reads, appends to, or rewrites
+PROJECT.md. If a future change needs to "also update PROJECT.md", it
+belongs in a separate workflow that the user invokes explicitly.
+-->
+
+## Optional Commit
+
+```bash
+if [ "$(node np-tools.cjs config-get workflow.commit_docs 2>/dev/null)" = "true" ]; then
+  git add .nubos-pilot/
+  git commit -m "chore: np:new-milestone add $ANS_MS_NAME"
+fi
+```
+
+## Output
+
+```
+np:new-milestone complete.
+
+Appended milestone: <milestone_name> (id=<slug>)
+First phase: <NN>-<slug>
+
+Next: run `np:next` to see the newly-current phase, or start
+`np:discuss-phase <NN>` to gather context for it.
+```
+
+## Errors
+
+| Code | Trigger | User action |
+|------|---------|-------------|
+| `project-not-initialized` | no `PROJECT.md` in `.nubos-pilot/` | Run `np:new-project` first |
+| `roadmap-duplicate-milestone` | milestone id (slugified name) already exists | Pick a different name |
+| `invalid-slug` | milestone/phase name has no `[a-z0-9]` content | Pick a different name |
+| `new-milestone-forbidden-write` | internal safeguard tripped | File a bug — should never surface |

package/workflows/new-project.md

@@ -0,0 +1,213 @@
+---
+command: np:new-project
+description: Greenfield project scaffold — runs interactive interview, writes PROJECT.md + REQUIREMENTS.md + roadmap.yaml + first phase dir + ROADMAP.md.
+---
+
+# np:new-project
+
+Initialize a new project through a short interview, then scaffold the five
+baseline artifacts (`PROJECT.md`, `REQUIREMENTS.md`, `roadmap.yaml`,
+`ROADMAP.md`, `STATE.md`) plus the first phase directory with a
+`CONTEXT.md` placeholder. This is the greenfield entry point; all other
+`np:*` workflows assume a project exists.
+
+## Philosophy
+
+<philosophy>
+The most leveraged moment in any project is the first interview. Deep
+questioning up front means better roadmaps, better plans, and better
+executions. `np:new-project` does not try to be clever — it asks five
+specific questions whose answers hard-constrain every downstream workflow,
+writes the five files, and exits. The user can edit `PROJECT.md` and
+`REQUIREMENTS.md` any time; this workflow's job is to produce a
+well-formed scaffold, not to pretend to understand the project.
+</philosophy>
+
+## Scope Guardrail
+
+<scope_guardrail>
+This workflow ONLY touches `.nubos-pilot/` and creates its first phase
+directory. It NEVER:
+
+- runs outside the current working directory
+- writes when `.nubos-pilot/PROJECT.md` already exists (D-28 Pitfall 8)
+- mutates files in parent directories
+- spawns agents or long-running tasks
+
+If `.nubos-pilot/PROJECT.md` already exists, the subcommand throws
+`project-already-initialized` and this workflow offers two paths: abort
+or destructively reset (user must confirm destructively).
+</scope_guardrail>
+
+## Downstream Awareness
+
+<downstream_awareness>
+The five files this workflow writes are consumed by:
+
+- `np:next` (reads `.nubos-pilot/STATE.md` + `.nubos-pilot/roadmap.yaml`)
+- `np:discuss-phase` (reads `PROJECT.md` for constraints, writes
+  `phases/01-<slug>/01-CONTEXT.md` which we scaffold as placeholder)
+- `np:plan-phase` (reads `REQUIREMENTS.md` for requirement IDs)
+- `np:progress` (reads `roadmap.yaml` for totals)
+
+Downstream workflows expect `REQUIREMENTS.md` to have `REQ-*` IDs matching
+the format `**REQ-NN**`. The template seeds `REQ-01` as a TBD — the user
+is expected to edit it before running `np:plan-phase 1`.
+</downstream_awareness>
+
+## Single-Call Init
+
+All context — the interview question set plus metadata — comes from a
+single `np-tools.cjs init new-project` call.
+
+```bash
+INIT=$(node np-tools.cjs init new-project)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+The payload shape:
+
+```json
+{
+  "mode": "interview",
+  "questions": [
+    { "key": "project_name", "type": "input", "question": "Project name?" },
+    { "key": "core_value", "type": "input", "question": "Core value — one sentence…" },
+    { "key": "primary_constraints", "type": "input", "question": "Primary constraints…" },
+    { "key": "first_milestone_name", "type": "input", "question": "First milestone name…" },
+    { "key": "first_phase_name", "type": "input", "question": "First phase name…" }
+  ]
+}
+```
+
+## Interview
+
+All five questions go through `np-tools.cjs askuser` (Phase 3 D-03). No
+runtime-native question tool is permitted anywhere in this file — the
+gateway subcommand is the single allowed path.
+
+```bash
+ANS_PROJECT_NAME=$(node np-tools.cjs askuser --json '{"type":"input","prompt":"Project name?"}')
+ANS_CORE_VALUE=$(node np-tools.cjs askuser --json '{"type":"input","prompt":"Core value (1 sentence)?"}')
+ANS_CONSTRAINTS=$(node np-tools.cjs askuser --json '{"type":"input","prompt":"Primary constraints (comma-separated)?"}')
+ANS_FIRST_MS=$(node np-tools.cjs askuser --json '{"type":"input","prompt":"First milestone name?"}')
+ANS_FIRST_PHASE=$(node np-tools.cjs askuser --json '{"type":"input","prompt":"First phase name?"}')
+```
+
+<answer_validation>
+The subcommand slugifies `first_milestone_name` and `first_phase_name`
+and throws `invalid-slug` if either produces an empty string after
+stripping non-`[a-z0-9-]` characters. The user sees this error immediately
+and can re-run the workflow with a different answer.
+
+`project_name`, `core_value`, and `primary_constraints` are stored verbatim
+inside the rendered templates — the subcommand's `render()` helper treats
+them as plain strings, so shell metacharacters, Markdown syntax, and YAML
+control chars are all inert. Task 2's NP-5 test asserts this.
+</answer_validation>
+
+## Apply
+
+Write the five answers to a tmp JSON file and feed it to the subcommand.
+
+```bash
+ANSWERS=$(mktemp -t np-new-project-answers.XXXXXX)
+trap 'rm -f "$ANSWERS"' EXIT
+
+node -e '
+  const fs = require("fs");
+  const payload = {
+    project_name: process.env.ANS_PROJECT_NAME,
+    core_value: process.env.ANS_CORE_VALUE,
+    primary_constraints: process.env.ANS_CONSTRAINTS,
+    first_milestone_name: process.env.ANS_FIRST_MS,
+    first_phase_name: process.env.ANS_FIRST_PHASE,
+  };
+  fs.writeFileSync(process.env.ANSWERS, JSON.stringify(payload));
+' ANS_PROJECT_NAME="$ANS_PROJECT_NAME" ANS_CORE_VALUE="$ANS_CORE_VALUE" ANS_CONSTRAINTS="$ANS_CONSTRAINTS" ANS_FIRST_MS="$ANS_FIRST_MS" ANS_FIRST_PHASE="$ANS_FIRST_PHASE" ANSWERS="$ANSWERS"
+
+node np-tools.cjs init new-project --apply "$ANSWERS"
+```
+
+We pass the answers via env → `node -e` → JSON file to keep shell
+metacharacters inert (no heredoc interpolation). The subcommand emits
+`{mode:"apply", milestoneId, firstPhaseNumber, firstPhaseSlug, created: [...]}`
+on success.
+
+## Re-Init Guard
+
+When `PROJECT.md` already exists, the subcommand throws
+`project-already-initialized`. The workflow catches it and offers a
+decision:
+
+```bash
+set +e
+node np-tools.cjs init new-project --apply "$ANSWERS"
+APPLY_STATUS=$?
+set -e
+
+if [ "$APPLY_STATUS" -ne 0 ]; then
+  CHOICE=$(node np-tools.cjs askuser --json '{
+    "type": "select",
+    "prompt": "Project already initialized. Choose:",
+    "options": [
+      "Abort (recommended)",
+      "Delete existing .nubos-pilot/ and retry (destructive)"
+    ]
+  }')
+  case "$CHOICE" in
+    *destructive*|*Delete*)
+      rm -rf ./.nubos-pilot
+      node np-tools.cjs init new-project --apply "$ANSWERS"
+      ;;
+    *)
+      exit 1
+      ;;
+  esac
+fi
+```
+
+Default on ambiguity: abort. This workflow never deletes `.nubos-pilot/`
+without an explicit `select` answer containing `Delete`.
+
+## Optional Commit
+
+When `config.commit_docs` is true, commit the scaffold. Use `execFileSync`
+arg arrays (no shell-string concatenation) — see Phase 3 D-03 docs.
+
+```bash
+if [ "$(node np-tools.cjs config-get workflow.commit_docs 2>/dev/null)" = "true" ]; then
+  git add .nubos-pilot/
+  git commit -m "chore: np:new-project scaffold"
+fi
+```
+
+## Output
+
+On success, print a summary block and point the user at `np:next`:
+
+```
+np:new-project complete.
+
+Created:
+  .nubos-pilot/PROJECT.md
+  .nubos-pilot/REQUIREMENTS.md
+  .nubos-pilot/roadmap.yaml
+  .nubos-pilot/ROADMAP.md
+  .nubos-pilot/STATE.md
+  .nubos-pilot/phases/01-<slug>/01-CONTEXT.md
+
+Next: run `np:next` to resume, or edit REQUIREMENTS.md before discussing
+the first phase with `np:discuss-phase 1`.
+```
+
+## Errors
+
+| Code | Trigger | User action |
+|------|---------|-------------|
+| `project-already-initialized` | `PROJECT.md` exists | Abort or re-run with destructive option |
+| `invalid-slug` | milestone/phase name has no `[a-z0-9]` content | Re-run with a different name |
+| `answers-missing-field` | empty answer | Re-run and fill all 5 fields |
+
+All errors propagate from the subcommand as `NubosPilotError` with a
+stable `code` — workflow consumers can script against them.

package/workflows/next.md

@@ -0,0 +1,8 @@
+# np:next
+
+Print the next actionable step for the current project state — resolved by the
+six-rule workflow gate (D-15).
+
+```bash
+node np-tools.cjs next
+```