roadmapsmith 0.9.16 → 0.9.23

package/.claude-plugin/plugin.json

@@ -0,0 +1,34 @@
+{
+  "name": "roadmapsmith",
+  "version": "0.9.23",
+  "description": "One-command evidence-backed ROADMAP.md generator and sync tool for AI coding agents, with shared RoadmapSmith plugin skills for Codex and Claude.",
+  "author": {
+    "name": "PapiScholz"
+  },
+  "homepage": "https://github.com/PapiScholz/roadmapsmith#readme",
+  "repository": "https://github.com/PapiScholz/roadmapsmith",
+  "license": "MIT",
+  "keywords": [
+    "roadmap",
+    "planning",
+    "agent",
+    "cli",
+    "validation",
+    "sync",
+    "task-tracking",
+    "evidence-based",
+    "deterministic",
+    "monorepo",
+    "claude-code",
+    "ai-agent",
+    "project-management",
+    "coding-agents",
+    "agent-skills",
+    "roadmap-generator",
+    "roadmap-sync",
+    "task-validation",
+    "developer-tools",
+    "markdown",
+    "agent-workflow"
+  ]
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,55 @@
+{
+  "name": "roadmapsmith",
+  "version": "0.9.23",
+  "description": "One-command evidence-backed ROADMAP.md generator and sync tool for AI coding agents, with shared RoadmapSmith plugin skills for Codex and Claude.",
+  "author": {
+    "name": "PapiScholz"
+  },
+  "homepage": "https://github.com/PapiScholz/roadmapsmith#readme",
+  "repository": "https://github.com/PapiScholz/roadmapsmith",
+  "license": "MIT",
+  "keywords": [
+    "roadmap",
+    "planning",
+    "agent",
+    "cli",
+    "validation",
+    "sync",
+    "task-tracking",
+    "evidence-based",
+    "deterministic",
+    "monorepo",
+    "claude-code",
+    "ai-agent",
+    "project-management",
+    "coding-agents",
+    "agent-skills",
+    "roadmap-generator",
+    "roadmap-sync",
+    "task-validation",
+    "developer-tools",
+    "markdown",
+    "agent-workflow"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "RoadmapSmith",
+    "shortDescription": "Evidence-backed roadmap workflows for AI coding agents",
+    "longDescription": "Install RoadmapSmith in Codex to expose the shared skills bundle for zero-mode onboarding, existing-repo maintenance, roadmap discovery, and evidence-backed validation while keeping the CLI and Claude bundle surfaces aligned.",
+    "developerName": "PapiScholz",
+    "category": "Developer Tools",
+    "capabilities": [
+      "Interactive",
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://github.com/PapiScholz/roadmapsmith#readme",
+    "defaultPrompt": [
+      "Help me bootstrap or maintain this repository roadmap with RoadmapSmith."
+    ],
+    "brandColor": "#2B6CB0",
+    "composerIcon": "./assets/palette.png",
+    "logo": "./assets/roadmapsmith-logo.png",
+    "screenshots": []
+  }
+}

package/README.md

@@ -17,7 +17,7 @@ roadmapsmith zero
 roadmapsmith maintain
 ```
 
-Slash entrypoints are also supported from the CLI and launcher, for example: `roadmapsmith /road`, `roadmapsmith /zero`, `roadmapsmith /maintain`, and `roadmapsmith /roadmap-sync maintain`.
+Slash entrypoints are also supported from the CLI and launcher, for example: `roadmapsmith /roadmap`, `roadmapsmith /roadmap-zero`, `roadmapsmith /roadmap-maintain`, `roadmapsmith /roadmap-update`, and the deprecated legacy router form `roadmapsmith /roadmap-sync validate`.
 The generated VS Code task layer now resolves Node automatically where possible; if it cannot, RoadmapSmith prints a readable runtime diagnostic instead of a dead task.
 `RoadmapSmith: Status` now treats "ready" as runnable task UX, not merely generated files.
 
@@ -27,9 +27,10 @@ The generated VS Code task layer now resolves Node automatically where possible;
 npx skills add PapiScholz/roadmapsmith --skill '*' -a claude-code
 ```
 
-This is the recommended Claude Code install path for native GUI slash commands such as `/road`, `/zero`, `/maintain`, `/status`, `/init`, `/generate`, `/validate`, `/sync`, `/audit`, `/setup`, and the legacy `/roadmap-sync`.
+This is the recommended Claude Code install path for native GUI slash commands such as `/roadmap`, `/roadmap-zero`, `/roadmap-maintain`, `/roadmap-status`, `/roadmap-init`, `/roadmap-generate`, `/roadmap-validate`, `/roadmap-update`, `/roadmap-audit`, and `/roadmap-setup`.
 If you install only `--skill roadmap-sync`, Claude GUI will expose only `/roadmap-sync`.
 The skill bundle does not install the CLI and it does not create visible VS Code actions by itself.
+The published `roadmapsmith` package/plugin surface now also ships the shared bundle files for both hosts (`skills.json`, `skills/*`, `.codex-plugin/plugin.json`, `.claude-plugin/plugin.json`) for downstream host installers, but consuming the CLI alone still does not auto-register native Codex or Claude GUI commands.
 
 ## Updating
 
@@ -53,9 +54,9 @@ npx skills add PapiScholz/roadmapsmith --skill '*' -a claude-code
 ```
 
 After updating the Claude skill bundle, run `/reload-skills` and, if applicable, `/reload-plugins`.
-After updating the CLI, rerun `roadmapsmith setup` in repositories where you want the latest VS Code tasks, task wrappers, launcher behavior, or Claude hook template.
+After updating the CLI, rerun `roadmapsmith setup` in repositories where you want the latest VS Code tasks, task wrappers, launcher behavior, or Claude hook template. Published npm/plugin artifacts now include the Codex and Claude bundle files for downstream host loaders, but native UX still depends on the host loading the correct surface.
 
-Fixes are available through `@latest` only after a new npm package version has been published. Before publication, install from a local checkout or a packed tarball for testing.
+Fixes are available through `@latest` after the automated release path completes on `main`. In this repo, a successful push to `main` now opens or refreshes an automated `release/vX.Y.Z` PR, that PR squashes back into `main` as the bot release commit `chore(release): vX.Y.Z`, and the follow-up `main` run publishes the new patch version. Before that completes, install from a local checkout or a packed tarball for testing.
 
 ## Operating Modes
 
@@ -96,7 +97,7 @@ Use the lower-level commands only when you want manual control over generation,
 | Host | Current support |
 |---|---|
 | Claude Code | Supported through the full RoadmapSmith skill bundle for native GUI slash commands, plus `roadmapsmith setup` for visible VS Code tasks and the optional repo-local Claude hook. |
-| Codex / Codex CLI | Supported through a visible VS Code task workflow and slash-capable launcher UX after `roadmapsmith setup`. Codex chat itself remains unchanged unless the host exposes native slash registration. |
+| Codex / Codex CLI | Supported through the native Codex plugin surface (`.codex-plugin/plugin.json` + repo marketplace) and the visible VS Code task workflow after `roadmapsmith setup`. |
 | CI | Use disposable checkouts if you run `sync --audit`, because it still mutates the roadmap today. |
 | Other hosts | Use the skill plus manual CLI commands. |
 
@@ -107,15 +108,16 @@ If Node is installed outside PATH, set `ROADMAPSMITH_NODE` to a working `node` e
 ## Commands
 
 ```bash
-roadmapsmith /road
-roadmapsmith /zero
-roadmapsmith /maintain
-roadmapsmith /roadmap-sync maintain
+roadmapsmith /roadmap
+roadmapsmith /roadmap-zero
+roadmapsmith /roadmap-maintain
+roadmapsmith /roadmap-update
+roadmapsmith /roadmap-sync validate
 roadmapsmith setup [--project-root <path>] [--config <path>] [--editor vscode] [--hosts <codex,claude>] [--dry-run]
 roadmapsmith zero [--project-root <path>] [--config <path>]
-roadmapsmith maintain [--project-root <path>] [--config <path>] [--roadmap-file <path>]
+roadmapsmith maintain [--project-root <path>] [--config <path>] [--roadmap-file <path>] [--full-regen]
 roadmapsmith init [--roadmap-file <path>] [--agents-file <path>] [--dry-run]
-roadmapsmith generate [--project-root <path>] [--config <path>] [--roadmap-file <path>] [--dry-run] [--audit]
+roadmapsmith generate [--project-root <path>] [--config <path>] [--roadmap-file <path>] [--dry-run] [--audit] [--full-regen]
 roadmapsmith sync [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--dry-run] [--audit]
 roadmapsmith validate [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--task <id|text>] [--json]
 roadmapsmith doctor [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--json]
@@ -133,9 +135,39 @@ Then reload the session:
 
 1. Run `/reload-skills`
 2. If RoadmapSmith was installed through a Claude plugin, also run `/reload-plugins`
-3. Confirm the slash menu shows `/road`, `/zero`, `/maintain`, `/status`, `/init`, `/generate`, `/validate`, `/sync`, `/audit`, `/setup`, and `/roadmap-sync`
+3. Confirm the slash menu shows `/roadmap`, `/roadmap-zero`, `/roadmap-maintain`, `/roadmap-status`, `/roadmap-init`, `/roadmap-generate`, `/roadmap-validate`, `/roadmap-update`, `/roadmap-audit`, and `/roadmap-setup`
 
-Native Claude GUI slash commands come from the installed skill bundle. CLI slash routing such as `roadmapsmith /road` is a separate surface and does not populate the Claude GUI menu by itself.
+Native Claude GUI slash commands come from the installed skill bundle. CLI slash routing such as `roadmapsmith /roadmap` is a separate surface and does not populate the Claude GUI menu by itself. The packed npm artifact now mirrors that bundle on disk so published plugin/distribution flows can expose the same slash set without depending on a source checkout.
+
+## Codex native plugin install
+
+RoadmapSmith now exposes a native Codex plugin manifest at `.codex-plugin/plugin.json` and a repo-local marketplace at `.agents/plugins/marketplace.json`.
+
+From the repository root:
+
+```bash
+codex plugin marketplace add .
+```
+
+Then restart Codex, open the plugin directory, install `roadmapsmith` from the `RoadmapSmith Local Plugins` marketplace, and confirm the plugin resolves the shared `./skills/` bundle.
+
+Codex native plugin support means install/enable discovery inside Codex. It is separate from Claude-specific `/reload-skills` behavior, and the VS Code task layer remains the fallback/manual workflow when you are not using the plugin directory.
+
+`roadmapsmith doctor --json` now reports native slash surfaces separately from the VS Code task layer:
+
+- `claudeGui`
+- `claudeCli`
+- `codexGui`
+- `codexCli`
+
+Each surface includes the detected source, expected slash commands, missing commands, and duplicate registrations such as a second `/roadmap-sync` coming from a legacy user skill install.
+
+If Codex shows `Roadmap Sync` twice, the usual cause is a collision between:
+
+- `~/.agents/skills/roadmap-sync`
+- the installed `roadmapsmith` Codex plugin
+
+The repo does not remove user-global skills automatically. Use the `doctor` output to confirm the duplicate and then disable or remove the legacy skill if you want a single `/roadmap-sync` entry.
 
 ## Behavior
 
@@ -306,6 +338,8 @@ roadmapsmith sync --dry-run
 
 ```bash
 npm test
+npm run validate:qa-regression
+npm run validate:functional-smoke
 ```
 
 If `npm test` fails in your shell with "`node` is not recognized", treat that as a local PATH/runtime issue first and rerun the suite with an explicit Node executable.
@@ -313,17 +347,20 @@ If `npm test` fails in your shell with "`node` is not recognized", treat that as
 ## Publishing
 
 ```bash
+npm run validate:qa-regression
+npm run validate:functional-smoke
 npm test
-npm version patch   # or minor / major
-npm publish --access public
-git push origin main --follow-tags
 ```
 
 Repository-specific release note:
 
 - The canonical release automation lives in `.github/workflows/ci.yml`.
-- This repository publishes from GitHub Actions on `main`; local `npm publish` is a maintainer workflow, not the default repo release path.
-- Before publishing, verify the UX/release gate in `docs/release-ux-gate.md` and update `CHANGELOG.md` with the user-visible behavior changes.
+- Every successful push to `main` now bumps `PATCH` through an automated `release/vX.Y.Z` PR, writes the version back with the squashed bot commit `chore(release): vX.Y.Z`, and then the follow-up `main` run publishes npm plus the GitHub Release.
+- Repair reruns on the bot release commit do not bump again; they only publish/create any missing artifacts left behind by a partial failure.
+- On repos where GitHub blocks `GITHUB_TOKEN` from creating or merging PRs, provide a dedicated secret such as `RELEASE_BOT_TOKEN` so the protected-branch release PR flow can complete.
+- Before any push, run the dual validation gate with separate owners: `QA/Regression` uses `npm run validate:qa-regression` and `Functional/Smoke` uses `npm run validate:functional-smoke`.
+- The release gate now includes packed-artifact verification for `skills.json`, `skills/*`, `.codex-plugin/plugin.json`, `.claude-plugin/plugin.json`, and the referenced Codex assets so the published surface matches the GitHub-source bundle for both hosts.
+- Before merging to `main`, verify the UX/release gate in `docs/release-ux-gate.md` and keep `CHANGELOG.md` ready for CI-managed version section generation.
 
 ## Versioning Strategy
 

package/bin/cli.js

@@ -11,7 +11,7 @@ const { buildSetupFiles, applySetupFiles, inspectHostSetup, parseHosts, assertSu
 const { getSlashAction, renderSlashPalette, resolveSlashInvocation } = require('../src/slash');
 const { renderRoadmapTemplate, renderAgentsTemplate } = require('../src/templates');
 const { generateRoadmapDocument } = require('../src/generator');
-const { parseRoadmap } = require('../src/parser');
+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');
@@ -20,14 +20,15 @@ function printHelp() {
   console.log([
     'Usage:',
     '  roadmapsmith zero [--project-root <path>] [--config <path>]',
-    '  roadmapsmith maintain [--project-root <path>] [--config <path>] [--roadmap-file <path>]',
-    '  roadmapsmith /road',
-    '  roadmapsmith /road <action>',
-    '  roadmapsmith /roadmap-sync <action>',
-    '  roadmapsmith /zero | /maintain | /status | /init | /generate | /validate | /sync | /audit | /setup',
+    '  roadmapsmith maintain [--project-root <path>] [--config <path>] [--roadmap-file <path>] [--full-regen]',
+    '  roadmapsmith /roadmap',
+    '  roadmapsmith /roadmap <action>',
+    '  roadmapsmith /roadmap-zero | /roadmap-maintain | /roadmap-status | /roadmap-init | /roadmap-generate | /roadmap-validate | /roadmap-update | /roadmap-audit | /roadmap-setup',
+    '  roadmapsmith /road <action>              # deprecated compatibility alias',
+    '  roadmapsmith /roadmap-sync <action>      # deprecated legacy compatibility root',
     '  roadmapsmith init [--roadmap-file <path>] [--agents-file <path>] [--dry-run]',
     '  roadmapsmith setup [--project-root <path>] [--config <path>] [--editor vscode] [--hosts <codex,claude>] [--dry-run]',
-    '  roadmapsmith generate [--project-root <path>] [--config <path>] [--roadmap-file <path>] [--dry-run] [--audit]',
+    '  roadmapsmith generate [--project-root <path>] [--config <path>] [--roadmap-file <path>] [--dry-run] [--audit] [--full-regen]',
     '  roadmapsmith sync [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--dry-run] [--audit]',
     '  roadmapsmith validate [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--task <id|text>] [--json]',
     '  roadmapsmith doctor [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--json]'
@@ -55,14 +56,6 @@ function maybeFilterTasks(tasks, filterValue) {
   });
 }
 
-function tasksInManagedBlock(parsedRoadmap) {
-  if (!parsedRoadmap.managedRange) {
-    return parsedRoadmap.tasks;
-  }
-  const { start, end } = parsedRoadmap.managedRange;
-  return parsedRoadmap.tasks.filter((task) => task.lineIndex > start && task.lineIndex < end);
-}
-
 function printAudit(audit) {
   console.log(`Audit summary: ${audit.checkedWithoutEvidence.length} checked-without-evidence, ${audit.readyButUnchecked.length} ready-but-unchecked.`);
   if (audit.checkedWithoutEvidence.length > 0) {
@@ -79,6 +72,35 @@ function printAudit(audit) {
   }
 }
 
+function formatSurfaceLabel(surfaceKey) {
+  return surfaceKey
+    .replace(/([A-Z])/g, ' $1')
+    .replace(/^./, (character) => character.toUpperCase());
+}
+
+function printNativeSurfaceStatus(surfaces) {
+  if (!surfaces || typeof surfaces !== 'object') {
+    return;
+  }
+
+  console.log('\nNative slash surfaces:');
+  for (const [surfaceKey, surface] of Object.entries(surfaces)) {
+    const label = formatSurfaceLabel(surfaceKey);
+    console.log(`- ${label}: ${surface.ready ? 'ready' : 'needs attention'} (${surface.message})`);
+    console.log(`  Source: ${surface.source}`);
+    console.log(`  Verification: ${surface.verification}`);
+    if (Array.isArray(surface.missingCommands) && surface.missingCommands.length > 0) {
+      console.log(`  Missing commands: ${surface.missingCommands.join(', ')}`);
+    }
+    if (Array.isArray(surface.duplicates) && surface.duplicates.length > 0) {
+      const duplicateSummary = surface.duplicates
+        .map((duplicate) => `${duplicate.command}${duplicate.reason ? ` (${duplicate.reason})` : ''}`)
+        .join(', ');
+      console.log(`  Duplicates: ${duplicateSummary}`);
+    }
+  }
+}
+
 function formatSetupVerb(result, dryRun) {
   if (dryRun) {
     return result.before == null ? 'Would create' : 'Would update';
@@ -128,7 +150,9 @@ function runGenerateCommand(projectRoot, config, flags, options = {}) {
     roadmapPath: roadmapFile,
     existingContent,
     config,
-    plugins
+    plugins,
+    preserveManagedBlock: options.preserveManagedBlock === true,
+    forceFullRegenerate: options.forceFullRegenerate === true || isEnabled(flags['full-regen'])
   });
 
   const writeResult = writeText(roadmapFile, document, { dryRun });
@@ -151,6 +175,13 @@ function runGenerateCommand(projectRoot, config, flags, options = {}) {
   }
 }
 
+function runRegenerateCommand(projectRoot, config, flags, options = {}) {
+  runGenerateCommand(projectRoot, config, flags, {
+    ...options,
+    forceFullRegenerate: true
+  });
+}
+
 function runSyncCommand(projectRoot, config, flags, options = {}) {
   const roadmapFile = resolveRoadmapFile(projectRoot, config, flags['roadmap-file']);
   const content = readTextIfExists(roadmapFile);
@@ -201,6 +232,7 @@ function printHumanStatus(payload) {
   }
   console.log(`Codex readiness: ${payload.hosts.codex.ready ? 'ready' : 'needs setup'} (${payload.hosts.codex.message})`);
   console.log(`Claude readiness: ${payload.hosts.claude.ready ? 'ready' : 'needs setup'} (${payload.hosts.claude.message})`);
+  printNativeSurfaceStatus(payload.surfaces);
   console.log('\nRecommended entrypoints: roadmapsmith zero (empty repo), roadmapsmith maintain (existing repo).');
   if (!payload.cli.ready) {
     console.log('\nInstalling the skill alone does not expose the CLI in VS Code. Install the CLI and rerun roadmapsmith setup.');
@@ -258,7 +290,11 @@ async function runZeroCommand(projectRoot, flags) {
 
 function runMaintainCommand(projectRoot, flags) {
   const config = loadConfig({ projectRoot, configPath: flags.config });
-  runGenerateCommand(projectRoot, config, flags);
+  const fullRegen = isEnabled(flags['full-regen']);
+  runGenerateCommand(projectRoot, config, flags, {
+    preserveManagedBlock: !fullRegen,
+    forceFullRegenerate: fullRegen
+  });
   runSyncCommand(projectRoot, config, { ...flags, audit: true }, { audit: true });
 }
 
@@ -292,6 +328,10 @@ async function run() {
       return;
     }
 
+    if (slashInvocation.deprecated && slashInvocation.deprecationMessage) {
+      process.stderr.write(`${slashInvocation.deprecationMessage}\n`);
+    }
+
     if (slashAction.id === 'status') {
       const projectRoot = path.resolve(String(flags['project-root'] || process.cwd()));
       const config = loadConfig({ projectRoot, configPath: flags.config });
@@ -333,6 +373,13 @@ async function run() {
     return;
   }
 
+  if (effectiveCommand === 'regenerate') {
+    const projectRoot = path.resolve(String(flags['project-root'] || process.cwd()));
+    const config = loadConfig({ projectRoot, configPath: flags.config });
+    runRegenerateCommand(projectRoot, config, flags);
+    return;
+  }
+
   if (effectiveCommand === 'setup') {
     const projectRoot = path.resolve(String(flags['project-root'] || process.cwd()));
     loadConfig({ projectRoot, configPath: flags.config });
@@ -484,6 +531,17 @@ async function run() {
         logError(`[fail] Claude hook incomplete: ${hostStatus.hosts.claude.message}`);
         ok = false;
       }
+
+      if (hostStatus.surfaces) {
+        Object.entries(hostStatus.surfaces).forEach(([surfaceKey, surface]) => {
+          const prefix = surface.ready ? '[ok]' : '[warn]';
+          log(`${prefix} ${formatSurfaceLabel(surfaceKey)}: ${surface.message}`);
+          if (Array.isArray(surface.duplicates) && surface.duplicates.length > 0) {
+            const duplicateSummary = surface.duplicates.map((duplicate) => duplicate.command).join(', ');
+            log(`[warn] ${formatSurfaceLabel(surfaceKey)} duplicates: ${duplicateSummary}`);
+          }
+        });
+      }
     }
 
     if (jsonMode) {

package/package.json

@@ -1,14 +1,25 @@
 {
   "name": "roadmapsmith",
-  "version": "0.9.16",
-  "description": "One-command evidence-backed ROADMAP.md generator and sync tool for AI coding agents.",
+  "version": "0.9.23",
+  "description": "One-command evidence-backed ROADMAP.md generator and sync tool for AI coding agents, with shared RoadmapSmith plugin skills for Codex and Claude.",
   "main": "src/index.js",
   "bin": {
     "roadmapsmith": "bin/cli.js"
   },
   "type": "commonjs",
   "scripts": {
-    "test": "node --test test/*.test.js"
+    "test": "node scripts/run-tests.js",
+    "validate:qa-regression": "node scripts/pre-push-gate.js qa-regression",
+    "validate:functional-smoke": "node scripts/pre-push-gate.js functional-smoke",
+    "validate:pre-push": "node scripts/pre-push-gate.js all",
+    "release:auto": "node scripts/auto-release.js",
+    "release:version": "node scripts/release-version.js --write",
+    "release:changelog": "node scripts/generate-changelog.js",
+    "sync-bundle-metadata": "node scripts/sync-bundle-metadata.js --write",
+    "check-bundle-metadata": "node scripts/sync-bundle-metadata.js",
+    "verify-pack-surface": "node scripts/verify-pack-surface.js",
+    "prepack": "node scripts/sync-bundle-metadata.js && node scripts/stage-claude-bundle.js",
+    "postpack": "node scripts/clean-staged-claude-bundle.js"
   },
   "keywords": [
     "roadmap",
@@ -51,6 +62,11 @@
     "bin",
     "src",
     "templates",
-    "README.md"
+    "README.md",
+    "skills",
+    "skills.json",
+    ".claude-plugin",
+    ".codex-plugin",
+    "assets"
   ]
 }

package/skills/roadmap/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: roadmap
+description: Show the RoadmapSmith native slash palette without side effects.
+---
+
+# RoadmapSmith Palette
+
+Use this command as the native discovery entrypoint for the shared RoadmapSmith slash bundle.
+
+## 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.
+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:
+   - `/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.
+
+## Output contract
+
+- Show what each command does in one sentence.
+- Include namespaced slash examples plus CLI equivalents.
+- Do not modify files or generate a roadmap from this command alone.

package/skills/roadmap-audit/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: roadmap-audit
+description: Run the sync-plus-audit workflow through the RoadmapSmith CLI.
+---
+
+# RoadmapSmith Audit
+
+Use this command when the user wants the post-sync mismatch summary after applying evidence-backed checklist updates.
+
+## 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.

package/skills/roadmap-generate/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: roadmap-generate
+description: Run the preserve-first roadmap update flow through the RoadmapSmith CLI.
+---
+
+# RoadmapSmith Generate
+
+Use this command when the user wants the managed roadmap block updated from repository evidence without replacing substantive existing domain content.
+
+## 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.

package/skills/roadmap-init/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: roadmap-init
+description: Create ROADMAP.md and AGENTS.md through the RoadmapSmith CLI.
+---
+
+# RoadmapSmith Init
+
+Use this command when the governance files are missing and the user wants them created without running the full Zero Mode interview.
+
+## 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.

package/skills/roadmap-maintain/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: roadmap-maintain
+description: Run the preserve-first existing-repository maintenance workflow through the RoadmapSmith CLI.
+---
+
+# RoadmapSmith Maintain
+
+Use this command when the repository already has code, tests, docs, or an existing roadmap and the user wants the default maintenance flow.
+
+## 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 .`.
+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.
+5. 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.

package/skills/roadmap-setup/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: roadmap-setup
+description: Generate RoadmapSmith host integration files through the CLI.
+---
+
+# RoadmapSmith Setup
+
+Use this command when the user wants RoadmapSmith host integration files generated or refreshed for the current repository.
+
+## 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.

package/skills/roadmap-status/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: roadmap-status
+description: Inspect RoadmapSmith readiness through doctor JSON and summarize the result.
+---
+
+# RoadmapSmith Status
+
+Use this command to inspect whether the shared bundle, native host surfaces, CLI, roadmap files, VS Code task UX, runtime, and Claude hook are ready.
+
+## Required behavior
+
+1. Prefer the local engine inside this repository:
+   - `node roadmap-skill/bin/cli.js doctor --json --project-root .`
+   - on this Windows machine, prefer `C:\Program Files\nodejs\node.exe roadmap-skill/bin/cli.js doctor --json --project-root .` if `node` is not in PATH
+2. Otherwise prefer `roadmapsmith doctor --json --project-root .`.
+3. Parse and summarize the JSON output in plain language.
+4. Explicitly call out missing commands or duplicate `/roadmap-sync` registration when doctor reports them.

package/skills/roadmap-sync/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: roadmap-sync
+description: Legacy namespaced root and policy guidance for RoadmapSmith slash workflows.
+---
+
+# RoadmapSmith Legacy Root
+
+Use this skill when the host exposes or the user invokes `/roadmap-sync`, or when the agent needs the RoadmapSmith operating rules for roadmap maintenance.
+
+## Required behavior
+
+1. Treat bare `/roadmap-sync` as legacy palette/help, and treat `/roadmap-sync <action>` as the deprecated compatibility root.
+2. Prefer the namespaced native commands for new guidance:
+   - `/roadmap` for discovery
+   - `/roadmap-zero`
+   - `/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.

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

@@ -0,0 +1,7 @@
+{
+  "interface": {
+    "display_name": "Roadmap Sync",
+    "short_description": "Legacy root plus policy for evidence-backed ROADMAP.md slash workflows.",
+    "default_prompt": "Prefer /roadmap for discovery, /roadmap-maintain for existing repos, and /roadmap-update for direct sync."
+  }
+}

package/skills/roadmap-update/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: roadmap-update
+description: Apply evidence-backed checklist sync through the RoadmapSmith CLI.
+---
+
+# RoadmapSmith Update
+
+Use this command when the user wants the direct sync surface without routing through the legacy `/roadmap-sync <action>` root.
+
+## Required behavior
+
+1. Prefer the local engine inside this repository:
+   - `node roadmap-skill/bin/cli.js sync --project-root .`
+   - on this Windows machine, prefer `C:\Program Files\nodejs\node.exe roadmap-skill/bin/cli.js sync --project-root .` if `node` is not in PATH
+2. Otherwise prefer `roadmapsmith sync --project-root .`.
+3. Explain that `/roadmap-update` is the visible namespaced sync command, while `/roadmap-sync <action>` remains legacy compatibility.
+4. Keep the evidence-backed sync semantics unchanged: sync updates checklist state from repository evidence; it is not a full regeneration path.