roadmapsmith 0.9.32 → 0.9.34

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "roadmapsmith",
-  "version": "0.9.32",
+  "version": "0.9.34",
   "description": "Evidence-backed ROADMAP.md workflows for AI coding agents, with canonical RoadmapSmith status and maintain surfaces plus advanced sync/generate tools and legacy compatibility aliases.",
   "author": {
     "name": "PapiScholz"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "roadmapsmith",
-  "version": "0.9.32",
+  "version": "0.9.34",
   "description": "Evidence-backed ROADMAP.md workflows for AI coding agents, with canonical RoadmapSmith status and maintain surfaces plus advanced sync/generate tools and legacy compatibility aliases.",
   "author": {
     "name": "PapiScholz"

package/README.md

@@ -8,7 +8,7 @@ This package owns the RoadmapSmith CLI, validator, sync engine, host setup files
 
 - `roadmapsmith setup`
 - `roadmapsmith zero`
-- `roadmapsmith maintain`
+- `roadmapsmith maintain [--dry-run]`
 - `roadmapsmith status [--json]`
 - `roadmapsmith validate [--json] [--strict]`
 - `roadmapsmith update [--task <stable-id> --evidence "<single-line evidence>"]`
@@ -40,11 +40,39 @@ This package owns the RoadmapSmith CLI, validator, sync engine, host setup files
 
 ### Zero Mode
 
-Use for empty or low-context repositories. `roadmapsmith zero` runs the terminal interview, updates config, and generates the first roadmap.
+Use for empty or low-context repositories. `roadmapsmith zero` runs the terminal interview when TTY is available, or consumes a complete brief from config plus flags in non-interactive environments.
+
+Non-interactive inputs:
+
+- `--product-name`
+- `--primary-user`
+- `--problem-statement`
+- `--target-outcome`
+- `--anti-goal` (repeatable)
+- `--preferred-stack`
+- `--constraint` (repeatable)
+- `--done-criterion` (repeatable)
+
+Without TTY, Zero Mode requires a complete brief from config/flags and fails clearly when required fields are missing.
 
 ### Sync/Audit Mode
 
-Use for repositories that already contain code, tests, docs, TODOs, or an existing roadmap. `roadmapsmith maintain` is the preserve-first one-command flow.
+Use for repositories that already contain code, tests, docs, TODOs, or an existing roadmap. `roadmapsmith maintain` is the preserve-first one-command flow for an existing managed roadmap block.
+
+If `ROADMAP.md` is authored and non-empty but has no `<!-- rs:managed:* -->` block:
+
+- `maintain` refuses to seed managed content implicitly
+- `update` is the conservative inline-annotation path
+- `generate` is the explicit managed-section creation path
+
+For write-capable surfaces (`maintain`, `generate`, `sync`, `update`), prefer `--dry-run` first.
+
+## Managed Block Ownership
+
+- `maintain` owns the managed roadmap block only.
+- `update` can annotate existing task lines even when no managed block exists.
+- `generate` is the explicit path that creates or replaces managed roadmap content.
+- Manually inserting empty `<!-- rs:managed:start -->` markers is no longer required as a workaround.
 
 ## Verification Model
 

package/bin/cli.js

@@ -14,14 +14,21 @@ const { generateRoadmapDocument } = require('../src/generator');
 const { parseRoadmap, tasksInManagedBlock } = require('../src/parser');
 const { buildValidationContext, validateTasks, auditValidation, CONFIDENCE_RANK, applyMinimumConfidence } = require('../src/validator');
 const { applySync } = require('../src/sync');
-const { buildZeroModeConfigPatch, buildZeroModeDefaults, collectZeroModeAnswers, isInteractiveTerminal } = require('../src/zero');
+const {
+  buildZeroModeConfigPatch,
+  collectZeroModeAnswers,
+  formatMissingZeroModeFields,
+  getMissingZeroModeFields,
+  isInteractiveTerminal,
+  resolveZeroModeAnswers
+} = require('../src/zero');
 
 function printHelp() {
   console.log([
     'Usage:',
     '  Canonical commands:',
-    '  roadmapsmith zero [--project-root <path>] [--config <path>]',
-    '  roadmapsmith maintain [--project-root <path>] [--config <path>] [--roadmap-file <path>] [--full-regen] [--refresh-annotations]',
+    '  roadmapsmith zero [--project-root <path>] [--config <path>] [--product-name <text>] [--primary-user <text>] [--problem-statement <text>] [--target-outcome <text>] [--anti-goal <text> ...] [--preferred-stack <text>] [--constraint <text> ...] [--done-criterion <text> ...]',
+    '  roadmapsmith maintain [--project-root <path>] [--config <path>] [--roadmap-file <path>] [--dry-run] [--full-regen] [--refresh-annotations]',
     '  roadmapsmith status [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--json]',
     '  roadmapsmith validate [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--task <id|text>] [--json] [--strict]',
     '  roadmapsmith update [--task <stable-id> --evidence <text>] [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--dry-run]',
@@ -140,6 +147,42 @@ function formatSetupVerb(result, dryRun) {
   return result.before == null ? 'Created' : 'Updated';
 }
 
+function emitPreWriteWarning(roadmapFile, options = {}) {
+  if (options.dryRun || options.suppressWarning) {
+    return;
+  }
+  if (options.warningState && options.warningState.emitted) {
+    return;
+  }
+
+  const commandName = options.commandName || 'roadmapsmith';
+  console.log(`Warning: ${commandName} will modify ${roadmapFile}. Review the preview first with --dry-run.`);
+  if (options.managedSectionNote) {
+    console.log(options.managedSectionNote);
+  }
+
+  if (options.warningState) {
+    options.warningState.emitted = true;
+  }
+}
+
+function assertMaintainCanWrite(roadmapFile, content) {
+  if (content == null || String(content).trim().length === 0) {
+    return;
+  }
+
+  const parsed = parseRoadmap(content);
+  if (parsed.hasManagedBlock) {
+    return;
+  }
+
+  throw new Error(
+    `Refusing to let roadmapsmith maintain seed a managed section into an authored roadmap without <!-- rs:managed:start --> markers: ${roadmapFile}\n` +
+    'For conservative inline annotations, run `roadmapsmith update --dry-run` then `roadmapsmith update`.\n' +
+    'To intentionally create a managed section, run `roadmapsmith generate --dry-run` then `roadmapsmith generate`.'
+  );
+}
+
 function runInitCommand(projectRoot, config, flags) {
   const roadmapFile = resolveRoadmapFile(projectRoot, config, flags['roadmap-file']);
   const agentsFile = resolveAgentsFile(projectRoot, config, flags['agents-file']);
@@ -187,6 +230,13 @@ function runGenerateCommand(projectRoot, config, flags, options = {}) {
     forceFullRegenerate: options.forceFullRegenerate === true || isEnabled(flags['full-regen'])
   });
 
+  emitPreWriteWarning(roadmapFile, {
+    commandName: options.commandName || 'roadmapsmith generate',
+    dryRun,
+    suppressWarning: options.suppressPreWriteWarning,
+    warningState: options.warningState,
+    managedSectionNote: 'This command may create or replace a managed roadmap section depending on the current file state and flags.'
+  });
   const writeResult = writeText(roadmapFile, document, { dryRun });
   if (dryRun) {
     if (writeResult.changed) {
@@ -229,6 +279,12 @@ function runSyncCommand(projectRoot, config, flags, options = {}) {
   const forceRefresh = isEnabled(flags['refresh-annotations']);
   const next = applySync(content, syncTasks, results, { forceRefresh });
   const dryRun = isEnabled(flags['dry-run']);
+  emitPreWriteWarning(roadmapFile, {
+    commandName: options.commandName || 'roadmapsmith sync',
+    dryRun,
+    suppressWarning: options.suppressPreWriteWarning,
+    warningState: options.warningState
+  });
   const writeResult = writeText(roadmapFile, next, { dryRun });
 
   if (dryRun) {
@@ -266,7 +322,7 @@ function runUpdateCommand(projectRoot, config, flags) {
   const hasTask = flags.task != null;
   const hasEvidence = flags.evidence != null;
   if (!hasTask && !hasEvidence) {
-    runSyncCommand(projectRoot, config, flags);
+    runSyncCommand(projectRoot, config, flags, { commandName: 'roadmapsmith update' });
     return;
   }
   if (!hasTask || !hasEvidence || Array.isArray(flags.task) || Array.isArray(flags.evidence)) {
@@ -306,6 +362,10 @@ function runUpdateCommand(projectRoot, config, flags) {
 
   const next = applySync(draft, [draftTask], { [taskId]: result });
   const dryRun = isEnabled(flags['dry-run']);
+  emitPreWriteWarning(roadmapFile, {
+    commandName: 'roadmapsmith update',
+    dryRun
+  });
   const writeResult = writeText(roadmapFile, next, { dryRun });
   if (dryRun) {
     if (writeResult.changed) {
@@ -371,40 +431,69 @@ function runStatusCommand(projectRoot, config, flags, options = {}) {
 async function runZeroCommand(projectRoot, flags) {
   const configPath = resolveConfigPath({ projectRoot, configPath: flags.config });
   const config = loadConfig({ projectRoot, configPath: flags.config });
-  if (!isInteractiveTerminal(process.stdin, process.stdout)) {
-    throw new Error('Zero Mode requires an interactive terminal. Run roadmapsmith zero from a terminal session, or add a config/brief workflow before retrying in non-interactive mode.');
+  const roadmapFile = resolveRoadmapFile(projectRoot, config, flags['roadmap-file']);
+  const roadmapExistedBeforeInit = fs.existsSync(roadmapFile);
+  const defaults = resolveZeroModeAnswers(projectRoot, config, flags);
+  const interactive = isInteractiveTerminal(process.stdin, process.stdout);
+  let answers = defaults;
+
+  if (!interactive) {
+    const missingFields = getMissingZeroModeFields(defaults);
+    if (missingFields.length > 0) {
+      throw new Error(
+        'Zero Mode requires a complete brief in non-interactive environments. Missing: ' +
+        `${formatMissingZeroModeFields(missingFields).join(', ')}. ` +
+        'Provide the missing values with CLI flags or in roadmap-skill.config.json before retrying.'
+      );
+    }
+    console.log('RoadmapSmith Zero Mode');
+    console.log('Using config/flag discovery inputs in non-interactive mode.\n');
+  } else {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+
+    try {
+      console.log('RoadmapSmith Zero Mode');
+      console.log('Answer the discovery interview to generate the first roadmap.\n');
+      answers = await collectZeroModeAnswers((prompt) => rl.question(prompt), defaults);
+    } finally {
+      rl.close();
+    }
   }
 
-  const defaults = buildZeroModeDefaults(projectRoot, config);
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout
+  const existingUserConfig = readUserConfig({ projectRoot, configPath: flags.config });
+  const nextUserConfig = buildZeroModeConfigPatch(projectRoot, existingUserConfig, answers);
+  writeText(configPath, JSON.stringify(nextUserConfig, null, 2));
+  console.log(`Updated ${configPath}`);
+  const nextConfig = loadConfig({ projectRoot, configPath: flags.config });
+  runInitCommand(projectRoot, nextConfig, flags);
+  runGenerateCommand(projectRoot, nextConfig, flags, {
+    commandName: 'roadmapsmith zero',
+    suppressPreWriteWarning: true,
+    forceFullRegenerate: !roadmapExistedBeforeInit
   });
-
-  try {
-    console.log('RoadmapSmith Zero Mode');
-    console.log('Answer the discovery interview to generate the first roadmap.\n');
-    const answers = await collectZeroModeAnswers((prompt) => rl.question(prompt), defaults);
-    const existingUserConfig = readUserConfig({ projectRoot, configPath: flags.config });
-    const nextUserConfig = buildZeroModeConfigPatch(projectRoot, existingUserConfig, answers);
-    writeText(configPath, JSON.stringify(nextUserConfig, null, 2));
-    console.log(`Updated ${configPath}`);
-    const nextConfig = loadConfig({ projectRoot, configPath: flags.config });
-    runInitCommand(projectRoot, nextConfig, flags);
-    runGenerateCommand(projectRoot, nextConfig, flags);
-  } finally {
-    rl.close();
-  }
 }
 
 function runMaintainCommand(projectRoot, flags) {
   const config = loadConfig({ projectRoot, configPath: flags.config });
+  const roadmapFile = resolveRoadmapFile(projectRoot, config, flags['roadmap-file']);
+  const existingContent = readTextIfExists(roadmapFile);
+  assertMaintainCanWrite(roadmapFile, existingContent);
   const fullRegen = isEnabled(flags['full-regen']);
+  const warningState = { emitted: false };
   runGenerateCommand(projectRoot, config, flags, {
+    commandName: 'roadmapsmith maintain',
     preserveManagedBlock: !fullRegen,
-    forceFullRegenerate: fullRegen
+    forceFullRegenerate: fullRegen,
+    warningState
+  });
+  runSyncCommand(projectRoot, config, { ...flags, audit: true }, {
+    audit: true,
+    commandName: 'roadmapsmith maintain',
+    warningState
   });
-  runSyncCommand(projectRoot, config, { ...flags, audit: true }, { audit: true });
 }
 
 async function run() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roadmapsmith",
-  "version": "0.9.32",
+  "version": "0.9.34",
   "description": "Evidence-backed ROADMAP.md workflows for AI coding agents, with canonical RoadmapSmith status and maintain surfaces plus advanced sync/generate tools and legacy compatibility aliases.",
   "main": "src/index.js",
   "bin": {

package/skills/roadmap/SKILL.md

@@ -10,21 +10,14 @@ Use this command as the native discovery entrypoint for the shared RoadmapSmith
 ## Required behavior
 
 1. Treat `/roadmap` as a no-side-effects palette. Do not run mutating commands from this skill.
-2. When working inside the RoadmapSmith repository itself and `roadmap-skill/bin/cli.js` exists, prefer the local engine:
-   - `node roadmap-skill/bin/cli.js /roadmap`
-   - on this Windows machine, prefer `C:\Program Files\nodejs\node.exe roadmap-skill/bin/cli.js /roadmap` if `node` is not in PATH
-3. Otherwise, if the `roadmapsmith` CLI is available, you may run `roadmapsmith /roadmap` from the project root and use that output directly. If its global shim cannot resolve `node`, use `& "C:\Program Files\nodejs\node.exe" "$env:APPDATA\npm\node_modules\roadmapsmith\bin\cli.js" /roadmap`.
-4. If the CLI is missing, provide the palette manually and explain the install path:
-   - `npm install -g roadmapsmith`
-   - `npx skills add PapiScholz/roadmapsmith --skill '*' -a claude-code`
-   - run `/reload-skills`
-   - if RoadmapSmith was installed as a Claude plugin, also run `/reload-plugins`
-5. Explain the preferred native host entrypoints:
+2. If the `roadmapsmith` CLI is available, run `roadmapsmith /roadmap` from the project root and use that output directly.
+3. If the CLI is missing, direct the user to the official repository README for installation instructions.
+4. Explain the preferred native host entrypoints:
    - `/roadmap-zero`
    - `/roadmap-maintain`
    - `/roadmap-status`
    - `/roadmap-init`, `/roadmap-generate`, `/roadmap-validate`, `/roadmap-update`, `/roadmap-audit`, and `/roadmap-setup`
-6. Mention that `/roadmap-sync <action>` remains a deprecated legacy CLI compatibility root, and `/road` plus `/road <action>` remain deprecated CLI compatibility aliases.
+5. Mention that `/roadmap-sync <action>` remains a deprecated legacy CLI compatibility root, and `/road` plus `/road <action>` remain deprecated CLI compatibility aliases.
 
 ## Output contract
 

package/skills/roadmap-audit/SKILL.md

@@ -9,8 +9,5 @@ Use this command when the user wants the post-sync mismatch summary after applyi
 
 ## Required behavior
 
-1. Prefer the local engine inside this repository:
-   - `node roadmap-skill/bin/cli.js sync --audit --project-root .`
-   - on this Windows machine, prefer `C:\Program Files\nodejs\node.exe roadmap-skill/bin/cli.js sync --audit --project-root .` if `node` is not in PATH
-2. Otherwise prefer `roadmapsmith sync --audit --project-root .`.
-3. Explain that this is the current sync-plus-audit flow, not a standalone read-only audit engine.
+1. Run `roadmapsmith sync --audit --project-root .`.
+2. Explain that this is the current sync-plus-audit flow, not a standalone read-only audit engine.

package/skills/roadmap-generate/SKILL.md

@@ -9,10 +9,7 @@ Use this command when the user wants the managed roadmap block updated from repo
 
 ## Required behavior
 
-1. Prefer the local engine inside this repository:
-   - `node roadmap-skill/bin/cli.js generate --project-root .`
-   - on this Windows machine, prefer `C:\Program Files\nodejs\node.exe roadmap-skill/bin/cli.js generate --project-root .` if `node` is not in PATH
-2. Otherwise prefer `roadmapsmith generate --project-root .`.
-3. Explain that `generate` is preserve-first when a substantive managed block already exists.
-4. When the user explicitly wants the destructive path, use `roadmapsmith generate --project-root . --full-regen`.
-5. Summarize what stayed preserved, whether generation refused, and what new additions, if any, were inserted.
+1. Run `roadmapsmith generate --project-root .`.
+2. Explain that `generate` is preserve-first when a substantive managed block already exists.
+3. To allow full roadmap regeneration, add `--full-regen`: `roadmapsmith generate --project-root . --full-regen`.
+4. Summarize what stayed preserved, whether generation refused, and what new additions, if any, were inserted.

package/skills/roadmap-init/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: roadmap-init
-description: Create ROADMAP.md and AGENTS.md through the RoadmapSmith CLI.
+description: Initialize project governance files through the RoadmapSmith CLI.
 ---
 
 # RoadmapSmith Init
@@ -9,8 +9,5 @@ Use this command when the governance files are missing and the user wants them c
 
 ## Required behavior
 
-1. Prefer the local engine inside this repository:
-   - `node roadmap-skill/bin/cli.js init --project-root .`
-   - on this Windows machine, prefer `C:\Program Files\nodejs\node.exe roadmap-skill/bin/cli.js init --project-root .` if `node` is not in PATH
-2. Otherwise prefer `roadmapsmith init`.
-3. Treat this command as CLI-backed and summarize whether files were created or skipped.
+1. Run `roadmapsmith init`.
+2. Summarize whether files were created or skipped.

package/skills/roadmap-maintain/SKILL.md

@@ -9,12 +9,8 @@ Use this command when the repository already has code, tests, docs, or an existi
 
 ## Required behavior
 
-1. Prefer the local engine inside this repository:
-   - `node roadmap-skill/bin/cli.js maintain --project-root .`
-   - on this Windows machine, prefer `C:\Program Files\nodejs\node.exe roadmap-skill/bin/cli.js maintain --project-root .` if `node` is not in PATH
-2. Otherwise prefer `roadmapsmith maintain --project-root .`. If that global shim fails because `node` is not in PATH, run `& "C:\Program Files\nodejs\node.exe" "$env:APPDATA\npm\node_modules\roadmapsmith\bin\cli.js" maintain --project-root .`.
-3. Treat this command as CLI-backed. Do not silently replace it with manual reasoning when the CLI is unavailable.
-4. Mention that maintain runs preserve-first generate, sync, and audit in one invocation.
+1. Run `roadmapsmith maintain --project-root .`. Prefer `--dry-run` first when previewing impact.
+2. Treat this command as CLI-backed. Do not silently replace it with manual reasoning when the CLI is unavailable.
+3. Mention that maintain runs preserve-first generate, sync, and audit in one invocation, but only for an existing managed roadmap block.
+4. If the roadmap is non-empty and lacks `<!-- rs:managed:* -->`, direct the user to `roadmapsmith update` for conservative inline annotations or `roadmapsmith generate` for explicit managed-section creation.
 5. After a successful maintain cycle, do not propose generate, sync, or audit separately unless the user needs manual control or inspection.
-6. Mention that `roadmapsmith maintain --full-regen` or `roadmapsmith generate --full-regen` is the explicit destructive rebuild path when the user truly wants a full managed-block replacement.
-7. When the user wants stale or outdated warning annotations to be recomputed from scratch (including annotations that were written by a prior maintain run or an external agent), use `roadmapsmith maintain --refresh-annotations`. This forces all existing warning text to be replaced with the current deterministic result rather than preserved. It is distinct from `--full-regen` (which rebuilds the managed block structure) — `--refresh-annotations` only affects warning annotations on still-failing tasks.

package/skills/roadmap-setup/SKILL.md

@@ -9,9 +9,6 @@ Use this command when the user wants RoadmapSmith host integration files generat
 
 ## Required behavior
 
-1. Prefer the local engine inside this repository:
-   - `node roadmap-skill/bin/cli.js setup --project-root . --hosts codex,claude`
-   - on this Windows machine, prefer `C:\Program Files\nodejs\node.exe roadmap-skill/bin/cli.js setup --project-root . --hosts codex,claude` if `node` is not in PATH
-2. Otherwise prefer `roadmapsmith setup --project-root . --hosts codex,claude`.
-3. Explain that setup affects the repository host layer: VS Code tasks, launcher/wrappers, and the optional repo-local Claude hook.
-4. Do not claim that setup alone creates native host slash commands; those come from the installed bundle/plugin.
+1. Run `roadmapsmith setup --project-root . --hosts codex,claude`.
+2. Explain that setup generates VS Code task definitions for the current repository.
+3. Do not claim that setup alone creates native host slash commands; those come from the installed bundle/plugin.

package/skills/roadmap-status/SKILL.md

@@ -9,10 +9,7 @@ Use this command to inspect whether the shared bundle, native host surfaces, CLI
 
 ## Required behavior
 
-1. Prefer the local engine inside this repository:
-   - `node roadmap-skill/bin/cli.js status --json --project-root .`
-   - on this Windows machine, prefer `C:\Program Files\nodejs\node.exe roadmap-skill/bin/cli.js status --json --project-root .` if `node` is not in PATH
-2. Otherwise prefer `roadmapsmith status --json --project-root .`. If its global shim cannot resolve `node`, use `& "C:\Program Files\nodejs\node.exe" "$env:APPDATA\npm\node_modules\roadmapsmith\bin\cli.js" status --json --project-root .`.
-3. Treat `roadmapsmith doctor --json` as compatibility-only output for existing automation, not as the primary recommendation.
+1. Run `roadmapsmith status --json --project-root .`.
+2. Treat `roadmapsmith doctor --json` as compatibility-only output for existing automation, not as the primary recommendation.
 4. Parse and summarize the JSON output in plain language.
 5. Explicitly call out missing canonical commands, duplicate legacy `/roadmap-sync` registration, and any missing advanced VS Code labels as warnings rather than canonical-readiness failures.

package/skills/roadmap-sync/SKILL.md

@@ -16,5 +16,5 @@ Use this skill only when the host exposes or the user explicitly invokes `/roadm
    - `/roadmap-maintain`
    - `/roadmap-status`
    - `/roadmap-init`, `/roadmap-generate`, `/roadmap-validate`, `/roadmap-update`, `/roadmap-audit`, and `/roadmap-setup`
-3. When the user explicitly invokes `/roadmap-sync <action>`, route to the matching CLI-backed action without changing semantics and mention the migration path to `/roadmap <action>` or the direct `/roadmap-*` command.
-4. Preserve the operating rules for evidence-backed roadmap maintenance and checklist synchronization: heuristic file/token matches may diagnose candidates, but only explicit `Evidence:` or typed `Verify:` checks may complete an unchecked implementation task. Never claim a behavioral task is complete without fresh test evidence or human verification.
+3. When the user explicitly invokes `/roadmap-sync <action>`, route to the matching CLI-backed action without changing semantics and mention the migration path to the direct `/roadmap-*` command.
+4. When routing `/roadmap-sync validate`, the tool uses the same validation rules as `/roadmap-validate`. Implementation tasks require an explicit `Evidence:` line or a `Verify:` check to be marked complete.

package/skills/roadmap-sync/agents/openai.yaml

@@ -2,6 +2,6 @@
   "interface": {
     "display_name": "Roadmap Sync (Deprecated)",
     "short_description": "DEPRECATED legacy root; use /roadmap-maintain or /roadmap-update.",
-    "default_prompt": "Prefer /roadmap, /roadmap-status, /roadmap-maintain, and /roadmap-update."
+    "default_prompt": "Prefer /roadmap, /roadmap-status, /roadmap-maintain, and /roadmap-update; use /roadmap-update when markers are missing."
   }
 }

package/skills/roadmap-update/SKILL.md

@@ -9,10 +9,7 @@ Use this command when the user wants the canonical public `update` surface witho
 
 ## Required behavior
 
-1. Prefer the local engine inside this repository:
-   - `node roadmap-skill/bin/cli.js update --project-root .`
-   - on this Windows machine, prefer `C:\Program Files\nodejs\node.exe roadmap-skill/bin/cli.js update --project-root .` if `node` is not in PATH
-2. Otherwise prefer `roadmapsmith update --project-root .`. If its global shim fails because `node` is not in PATH, run `& "C:\Program Files\nodejs\node.exe" "$env:APPDATA\npm\node_modules\roadmapsmith\bin\cli.js" update --project-root .`.
-3. Explain that `/roadmap-update` is the visible namespaced command for the public `update` family, while `/roadmap-sync <action>` remains deprecated compatibility only.
-4. Keep the evidence-backed refresh semantics unchanged: no-argument `update` syncs the roadmap from repository evidence, and `sync` remains the advanced CLI alias for that same mutating refresh path. It is not a full regeneration path and not an independent audit engine.
-5. To complete one task, run `roadmapsmith update --task <stable-id> --evidence "<single-line evidence>"`. It writes only after the supplied evidence validates at high confidence; use `--dry-run` to preview it.
+1. Run `roadmapsmith update --project-root .`.
+2. Explain that `/roadmap-update` is the visible namespaced command for the public `update` family, while `/roadmap-sync <action>` remains deprecated compatibility only.
+3. The no-argument `update` syncs the roadmap from repository evidence. The `sync` alias covers the same refresh path. It is not a full regeneration path and not an independent audit engine.
+4. To mark a specific task complete, run `roadmapsmith update --task TASK-ID --evidence "description"`. The CLI validates before writing; use `--dry-run` to preview.

package/skills/roadmap-validate/SKILL.md

@@ -9,8 +9,5 @@ Use this command when the user wants per-task evidence status without mutating t
 
 ## Required behavior
 
-1. Prefer the local engine inside this repository:
-   - `node roadmap-skill/bin/cli.js validate --json --project-root .`
-   - on this Windows machine, prefer `C:\Program Files\nodejs\node.exe roadmap-skill/bin/cli.js validate --json --project-root .` if `node` is not in PATH
-2. Otherwise prefer `roadmapsmith validate --json --project-root .`.
-3. Treat this command as CLI-backed and non-mutating.
+1. Run `roadmapsmith validate --json --project-root .`.
+2. This command is non-mutating.

package/skills/roadmap-zero/SKILL.md

@@ -9,9 +9,6 @@ Use this command when the repository is empty or low-context and the user needs
 
 ## Required behavior
 
-1. Prefer the local engine inside this repository:
-   - `node roadmap-skill/bin/cli.js zero --project-root .`
-   - on this Windows machine, prefer `C:\Program Files\nodejs\node.exe roadmap-skill/bin/cli.js zero --project-root .` if `node` is not in PATH
-2. Otherwise prefer `roadmapsmith zero --project-root .`.
-3. Treat this command as CLI-backed and interactive.
-4. If the CLI is missing, explain the install path instead of improvising the workflow manually.
+1. Run `roadmapsmith zero --project-root .`.
+2. In non-interactive environments, provide or reuse a complete brief from config plus flags such as `--primary-user`, `--problem-statement`, `--target-outcome`, and repeatable `--done-criterion`.
+3. If the CLI is missing, explain the install path instead of improvising the workflow manually.

package/skills.json

@@ -12,7 +12,7 @@
     "npx skills add PapiScholz/roadmapsmith --skill '*' -a claude-code",
     "roadmapsmith setup",
     "roadmapsmith zero",
-    "roadmapsmith maintain",
+    "roadmapsmith maintain --dry-run",
     "roadmapsmith /roadmap",
     "roadmapsmith update --task p2-customer-history --evidence \"src/app/api/customers/route.ts, test/customers.test.js\"",
     "roadmapsmith validate --json"
@@ -21,74 +21,74 @@
     "command": "npx skills add PapiScholz/roadmapsmith --skill '*' -a claude-code",
     "source": "PapiScholz/roadmapsmith",
     "skill": "*",
-    "notes": "Recommended Claude Code install path for native GUI slash commands. Canonical surfaces: /roadmap, /roadmap-zero, /roadmap-maintain, /roadmap-status, /roadmap-validate, /roadmap-update, /roadmap-setup. The public CLI update family covers both checklist refresh and verified single-task completion; sync remains the advanced alias for the mutating refresh path. Advanced surfaces: /roadmap-init, /roadmap-generate, /roadmap-audit. DEPRECATED: /roadmap-sync remains only as a compatibility root for existing automation; use /roadmap-maintain or /roadmap-update for new workflows. Install the roadmapsmith CLI separately for actual command execution; roadmapsmith status is the public readiness command and roadmapsmith doctor remains a compatibility alias. Then run /reload-skills and, if applicable, /reload-plugins. Codex native plugin installs use the repo/package .codex-plugin surface instead of this Claude-specific skills CLI path."
+    "notes": "Recommended Claude Code install path for native GUI slash commands. Canonical surfaces: /roadmap, /roadmap-zero, /roadmap-maintain, /roadmap-status, /roadmap-validate, /roadmap-update, /roadmap-setup. The public CLI update family covers both checklist refresh and verified single-task completion; sync remains the advanced alias for the mutating refresh path. /roadmap-maintain now owns only existing managed roadmap blocks, while /roadmap-update is the conservative annotation path for authored roadmaps without markers. /roadmap-zero can consume a complete discovery brief from config plus CLI flags in non-interactive environments. Advanced surfaces: /roadmap-init, /roadmap-generate, /roadmap-audit. DEPRECATED: /roadmap-sync remains only as a compatibility root for existing automation; use /roadmap-maintain or /roadmap-update for new workflows. Install the roadmapsmith CLI separately for actual command execution; roadmapsmith status is the public readiness command and roadmapsmith doctor remains a compatibility alias. Then run /reload-skills and, if applicable, /reload-plugins. Codex native plugin installs use the repo/package .codex-plugin surface instead of this Claude-specific skills CLI path."
   },
   "skills": [
     {
       "name": "roadmap",
       "path": "skills/roadmap",
       "description": "Native slash palette for RoadmapSmith commands and recommended entrypoints across supported hosts.",
-      "version": "0.9.32"
+      "version": "0.9.34"
     },
     {
       "name": "roadmap-zero",
       "path": "skills/roadmap-zero",
-      "description": "Native slash entrypoint for the one-command Zero Mode CLI workflow.",
-      "version": "0.9.32"
+      "description": "Native slash entrypoint for Zero Mode, including non-interactive config-plus-flag discovery.",
+      "version": "0.9.34"
     },
     {
       "name": "roadmap-maintain",
       "path": "skills/roadmap-maintain",
-      "description": "Native slash entrypoint for the preserve-first generate + sync + audit flow.",
-      "version": "0.9.32"
+      "description": "Native slash entrypoint for conservative managed-block maintenance plus sync and audit output.",
+      "version": "0.9.34"
     },
     {
       "name": "roadmap-status",
       "path": "skills/roadmap-status",
       "description": "Native slash readiness check grounded in roadmapsmith status JSON.",
-      "version": "0.9.32"
+      "version": "0.9.34"
     },
     {
       "name": "roadmap-init",
       "path": "skills/roadmap-init",
       "description": "Native slash entrypoint for creating ROADMAP.md and AGENTS.md.",
-      "version": "0.9.32"
+      "version": "0.9.34"
     },
     {
       "name": "roadmap-generate",
       "path": "skills/roadmap-generate",
       "description": "Native slash entrypoint for managed roadmap updates that require --full-regen before destructive replacement.",
-      "version": "0.9.32"
+      "version": "0.9.34"
     },
     {
       "name": "roadmap-validate",
       "path": "skills/roadmap-validate",
       "description": "Native slash entrypoint for evidence-backed roadmap validation.",
-      "version": "0.9.32"
+      "version": "0.9.34"
     },
     {
       "name": "roadmap-update",
       "path": "skills/roadmap-update",
-      "description": "Native slash entrypoint for evidence-backed sync and verified single-task completion.",
-      "version": "0.9.32"
+      "description": "Native slash entrypoint for evidence-backed inline annotation refresh and verified single-task completion.",
+      "version": "0.9.34"
     },
     {
       "name": "roadmap-sync",
       "path": "skills/roadmap-sync",
       "description": "DEPRECATED legacy compatibility root; use roadmap-maintain or roadmap-update.",
-      "version": "0.9.32"
+      "version": "0.9.34"
     },
     {
       "name": "roadmap-audit",
       "path": "skills/roadmap-audit",
       "description": "Native slash entrypoint for the advanced sync-plus-audit mutating summary workflow.",
-      "version": "0.9.32"
+      "version": "0.9.34"
     },
     {
       "name": "roadmap-setup",
       "path": "skills/roadmap-setup",
       "description": "Native slash entrypoint for generating RoadmapSmith host integration files.",
-      "version": "0.9.32"
+      "version": "0.9.34"
     }
   ]
 }

package/src/zero.js

@@ -2,6 +2,17 @@
 
 const path = require('path');
 
+const ZERO_MODE_FLAG_SPECS = {
+  productName: { flag: '--product-name', configPath: 'product.name', type: 'scalar' },
+  primaryUser: { flag: '--primary-user', configPath: 'product.primaryUser', type: 'scalar', required: true },
+  problemStatement: { flag: '--problem-statement', configPath: 'zeroMode.problemStatement', type: 'scalar', required: true },
+  targetOutcome: { flag: '--target-outcome', configPath: 'product.targetOutcome', type: 'scalar', required: true },
+  antiGoals: { flag: '--anti-goal', configPath: 'product.antiGoals', type: 'list' },
+  preferredStack: { flag: '--preferred-stack', configPath: 'zeroMode.preferredStack', type: 'scalar' },
+  constraints: { flag: '--constraint', configPath: 'zeroMode.constraints', type: 'list' },
+  doneCriteria: { flag: '--done-criterion', configPath: 'zeroMode.doneCriteria', type: 'list', required: true }
+};
+
 const ZERO_MODE_QUESTIONS = [
   { id: 'productName', prompt: '1. What product are we building?' },
   { id: 'primaryUser', prompt: '2. Who is the target user?' },
@@ -54,6 +65,80 @@ function buildZeroModeDefaults(projectRoot, config) {
   };
 }
 
+function getSingleFlagValue(value) {
+  if (Array.isArray(value)) {
+    return value[value.length - 1];
+  }
+  return value;
+}
+
+function getListFlagValues(value) {
+  const rawValues = Array.isArray(value) ? value : [value];
+  return rawValues.flatMap((item) => splitListAnswer(item));
+}
+
+function resolveZeroModeAnswers(projectRoot, config, flags = {}) {
+  const defaults = buildZeroModeDefaults(projectRoot, config);
+  const answers = { ...defaults };
+
+  for (const [field, spec] of Object.entries(ZERO_MODE_FLAG_SPECS)) {
+    const flagKey = spec.flag.slice(2);
+    if (!Object.prototype.hasOwnProperty.call(flags, flagKey)) {
+      continue;
+    }
+
+    if (spec.type === 'list') {
+      answers[field] = getListFlagValues(flags[flagKey]).join('; ');
+      continue;
+    }
+
+    const raw = getSingleFlagValue(flags[flagKey]);
+    answers[field] = String(raw == null ? '' : raw).trim();
+  }
+
+  if (!String(answers.productName || '').trim()) {
+    answers.productName = path.basename(projectRoot);
+  }
+
+  return answers;
+}
+
+function getMissingZeroModeFields(answers = {}) {
+  const missing = [];
+  for (const [field, spec] of Object.entries(ZERO_MODE_FLAG_SPECS)) {
+    if (!spec.required) {
+      continue;
+    }
+
+    if (spec.type === 'list') {
+      if (splitListAnswer(answers[field]).length === 0) {
+        missing.push({
+          field,
+          flag: spec.flag,
+          configPath: spec.configPath
+        });
+      }
+      continue;
+    }
+
+    if (!String(answers[field] || '').trim()) {
+      missing.push({
+        field,
+        flag: spec.flag,
+        configPath: spec.configPath
+      });
+    }
+  }
+  return missing;
+}
+
+function formatMissingZeroModeFields(missingFields) {
+  return missingFields.map((item) => {
+    const label = item.field.replace(/([A-Z])/g, ' $1').toLowerCase();
+    return `${label} (${item.flag} or config ${item.configPath})`;
+  });
+}
+
 async function collectZeroModeAnswers(ask, defaults = {}) {
   const answers = {};
   for (const question of ZERO_MODE_QUESTIONS) {
@@ -124,6 +209,9 @@ module.exports = {
   buildZeroModeConfigPatch,
   buildZeroModeDefaults,
   collectZeroModeAnswers,
+  formatMissingZeroModeFields,
+  getMissingZeroModeFields,
   isInteractiveTerminal,
+  resolveZeroModeAnswers,
   splitListAnswer
 };