roadmapsmith 0.9.14 → 0.9.16

package/README.md

@@ -12,15 +12,24 @@ Production-grade roadmap generator and sync tool for agent-driven projects.
 
 ```bash
 npm install -g roadmapsmith
+roadmapsmith setup
+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`.
+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.
+
 ### Agent Skill
 
 ```bash
-npx skills add PapiScholz/roadmapsmith --skill roadmap-sync
+npx skills add PapiScholz/roadmapsmith --skill '*' -a claude-code
 ```
 
-This adds the `roadmap-sync` agent skill. It does not install the CLI package.
+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`.
+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.
 
 ## Updating
 
@@ -37,12 +46,15 @@ npm install roadmapsmith@latest
 npx roadmapsmith@latest validate --json
 ```
 
-The `roadmap-sync` agent skill is separate from the CLI. Re-running the skills install updates the agent instructions, but it does not update the `roadmapsmith` npm binary:
+The Claude skill bundle is separate from the CLI. Re-running the skills install updates the Claude-facing instructions, but it does not update the `roadmapsmith` npm binary or the generated VS Code host files:
 
 ```bash
-npx skills add PapiScholz/roadmapsmith --skill roadmap-sync
+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.
+
 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.
 
 ## Operating Modes
@@ -51,11 +63,11 @@ Fixes are available through `@latest` only after a new npm package version has b
 
 Agent-guided discovery for empty or low-context repositories. The developer has a product idea but no implementation files, no stack decision, and no ROADMAP.md yet.
 
-The CLI creates governance files. The AI agent (using the `roadmap-sync` skill) performs the discovery interview before generating the roadmap.
+Run `roadmapsmith setup` first if you want visible VS Code tasks. `roadmapsmith zero` is the one-command entrypoint: it runs the terminal interview, creates governance files when needed, and generates the first roadmap.
 
 ```bash
-roadmapsmith init
-roadmapsmith generate --project-root .
+roadmapsmith setup
+roadmapsmith zero
 ```
 
 ### Sync/Audit Mode
@@ -63,32 +75,68 @@ roadmapsmith generate --project-root .
 Repository-backed roadmap generation, validation, and synchronization. Use when the repository already has code, tests, docs, TODOs, or an existing ROADMAP.md.
 
 ```bash
-roadmapsmith generate --project-root .
-roadmapsmith validate --json
-roadmapsmith sync
-roadmapsmith sync --dry-run
+roadmapsmith setup
+roadmapsmith maintain
 ```
 
+## Recommended Daily Flow
+
+Use the public entrypoints first:
+
+```bash
+roadmapsmith setup
+roadmapsmith zero       # empty repo
+roadmapsmith maintain   # existing repo
+```
+
+Use the lower-level commands only when you want manual control over generation, validation, or sync.
+
 ## Host Support Today
 
 | Host | Current support |
 |---|---|
-| Claude Code | Manual hook setup is documented and supported. |
-| Codex / Codex CLI | Manual CLI workflow only; no documented auto-hook equivalent yet. |
+| 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. |
 | 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. |
 
+If Node is installed outside PATH, set `ROADMAPSMITH_NODE` to a working `node` executable before using the generated VS Code tasks.
+
 ---
 
 ## Commands
 
 ```bash
+roadmapsmith /road
+roadmapsmith /zero
+roadmapsmith /maintain
+roadmapsmith /roadmap-sync maintain
+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 init [--roadmap-file <path>] [--agents-file <path>] [--dry-run]
 roadmapsmith generate [--project-root <path>] [--config <path>] [--roadmap-file <path>] [--dry-run] [--audit]
 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]
 ```
 
+## Claude Code native slash commands
+
+Install the full skill bundle for Claude Code:
+
+```bash
+npx skills add PapiScholz/roadmapsmith --skill '*' -a claude-code
+```
+
+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`
+
+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.
+
 ## Behavior
 
 - Generates deterministic `ROADMAP.md` with fixed section order.
@@ -241,10 +289,9 @@ module.exports = {
 ## Example Usage
 
 ```bash
-roadmapsmith init
-roadmapsmith generate --project-root .
+roadmapsmith zero
+roadmapsmith maintain
 roadmapsmith validate --json
-roadmapsmith sync
 roadmapsmith sync --dry-run
 ```
 
@@ -261,6 +308,8 @@ roadmapsmith sync --dry-run
 npm test
 ```
 
+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.
+
 ## Publishing
 
 ```bash
@@ -270,6 +319,12 @@ 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.
+
 ## Versioning Strategy
 
 - `patch`: bug fixes and non-breaking validation/generation improvements.