roadmapsmith 0.9.13 → 0.9.15

package/README.md

@@ -12,15 +12,22 @@ 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
 ```
 
-This adds the `roadmap-sync` agent skill. It does not install the CLI package.
+This adds the `roadmap-sync` agent skill only. It does not install the CLI and it does not create visible VS Code actions by itself.
 
 ## Updating
 
@@ -34,15 +41,17 @@ npm install -g roadmapsmith@latest
 npm install roadmapsmith@latest
 
 # One-off execution without installing
-npx roadmapsmith@latest sync --audit
+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 `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 or the generated VS Code host files:
 
 ```bash
 npx skills add PapiScholz/roadmapsmith --skill roadmap-sync
 ```
 
+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 +60,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,20 +72,50 @@ 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 --audit
+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 | Supported through `roadmapsmith setup`: visible VS Code tasks, slash-capable launcher UX, and optional repo-local Claude hook wiring. |
+| 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]
 ```
 
 ## Behavior
@@ -84,6 +123,7 @@ roadmapsmith validate [--roadmap-file <path>] [--project-root <path>] [--config
 - Generates deterministic `ROADMAP.md` with fixed section order.
 - Uses stable task IDs: `<!-- rs:task=<slug> -->`.
 - Sync marks `[x]` only when validation passes.
+- `sync --audit` currently runs sync and then prints a mismatch summary; it is not yet a dedicated read-only audit mode.
 - Validation evidence gate:
   - code OR test OR artifact evidence required.
   - test evidence required for code tasks when test frameworks are detected.
@@ -113,26 +153,27 @@ Create `roadmap-skill.config.json`:
 {
   "roadmapFile": "./ROADMAP.md",
   "agentsFile": "./AGENTS.md",
-
-  // Forward-compatible fields — recognized by the skill/agent for Zero Mode discovery context,
-  // but not yet read by the generator or validator. Safe to add now; they will be wired in a future release.
-  "northStar": "Ship a self-hosted CLI tool for website capture and AI-readable design analysis.",
-  "targetUser": "Frontend developers, full-stack developers, and AI coding agents.",
-  "problemStatement": "Developers lack a unified tool to capture screenshots, crawl pages, extract assets, and export structured context.",
-  "v1Outcome": "A stable CLI that captures full-page screenshots, crawls internal links, exports metadata, and produces an AI-readable report.",
-  "antiGoals": [
-    "Do not bypass authentication",
-    "Do not target private systems without authorization"
-  ],
-  "risks": [
-    "Browser automation instability",
-    "Scope creep into generic scraping"
-  ],
-  "exitCriteria": [
-    "CLI works against a public test site",
-    "Screenshots and metadata are exported deterministically",
-    "README documents safe and authorized usage"
-  ],
+  "roadmapProfile": "professional",
+  "product": {
+    "name": "My Project",
+    "northStar": "Ship a self-hosted CLI tool for website capture and AI-readable design analysis.",
+    "positioning": "What makes this different from alternatives.",
+    "primaryUser": "Frontend developers, full-stack developers, and AI coding agents.",
+    "targetOutcome": "A stable CLI that captures full-page screenshots, crawls internal links, exports metadata, and produces an AI-readable report.",
+    "antiGoals": [
+      "Do not bypass authentication",
+      "Do not target private systems without authorization"
+    ],
+    "risks": [
+      "Browser automation instability",
+      "Scope creep into generic scraping"
+    ],
+    "successCriteria": [
+      "CLI works against a public test site",
+      "Screenshots and metadata are exported deterministically",
+      "README documents safe and authorized usage"
+    ]
+  },
 
   "taskMatchers": [
     {
@@ -229,17 +270,16 @@ module.exports = {
 ## Example Usage
 
 ```bash
-roadmapsmith init
-roadmapsmith generate --project-root .
+roadmapsmith zero
+roadmapsmith maintain
 roadmapsmith validate --json
-roadmapsmith sync --audit
 roadmapsmith sync --dry-run
 ```
 
 ## Dry Run and Audit
 
 - `--dry-run`: shows file diff preview without writing.
-- `--audit`: reports roadmap/code mismatches:
+- `--audit`: currently runs sync and then reports roadmap/code mismatches:
   - checked without evidence
   - ready but unchecked
 
@@ -249,6 +289,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
@@ -258,6 +300,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.