roadmapsmith 0.1.0 → 0.2.0

package/README.md

@@ -2,36 +2,46 @@
 
 Production-grade roadmap generator and sync tool for agent-driven projects.
 
-## Install Status
+## Install
 
-This package and skill are in private/internal development. Public install flows are not available yet.
+### CLI
 
-### Primary install path: agent skill (available for private repository users)
+```bash
+npm install -g roadmapsmith
+```
+
+### Agent Skill
 
 ```bash
 npx skills add PapiScholz/roadmapsmith --skill roadmap-sync
 ```
 
-This install command adds the `roadmap-sync` agent skill. It does not install the CLI package.
+This adds the `roadmap-sync` agent skill. It does not install the CLI package.
+
+## Operating Modes
+
+### Zero Mode
 
-### Optional CLI package install (future, unavailable until npm publication)
+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.
 
 ```bash
-npm install -g roadmapsmith
+roadmapsmith init
+roadmapsmith generate --project-root .
 ```
 
-### Local development usage
+### Sync/Audit Mode
+
+Repository-backed roadmap generation, validation, and synchronization. Use when the repository already has code, tests, docs, TODOs, or an existing ROADMAP.md.
 
 ```bash
-cd roadmap-skill
-node bin/cli.js --help
-node bin/cli.js init --dry-run
-node bin/cli.js generate --project-root . --dry-run --audit
+roadmapsmith generate --project-root .
+roadmapsmith validate --json
+roadmapsmith sync --audit
 ```
 
-### Legacy/internal alias
-
-The `roadmap-skill` CLI alias remains for backward compatibility and internal use, but public examples use `roadmapsmith`.
+---
 
 ## Commands
 
@@ -76,6 +86,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"
+  ],
+
   "taskMatchers": [
     {
       "pattern": "src/payments/",
@@ -171,49 +202,17 @@ roadmapsmith sync --dry-run
 npm test
 ```
 
-## Publishing (Future, Not Yet)
-
-### npm (public package, future)
-
-1. Run tests.
+## Publishing
 
 ```bash
 npm test
-```
-
-2. Bump version using semver.
-
-```bash
-npm version patch
-# or: npm version minor
-# or: npm version major
-```
-
-3. Publish package.
-
-```bash
+npm version patch   # or minor / major
 npm publish --access public
-```
-
-4. Push tags.
-
-```bash
 git push origin main --follow-tags
 ```
 
-### skills.sh / `npx skills add` discoverability (future)
-
-1. After internal release-readiness is complete, make the repository public with `skills/roadmap-sync/SKILL.md` and `skills.json`.
-2. Verify install flow from a clean project:
-
-```bash
-npx skills add PapiScholz/roadmapsmith --skill roadmap-sync
-```
-
-3. Confirm the installed skill appears in your agent skill list. This install command adds the agent skill, not the CLI package.
-
 ## Versioning Strategy
 
 - `patch`: bug fixes and non-breaking validation/generation improvements.
 - `minor`: backward-compatible features (new flags, new plugin hooks, additive config fields).
-- `major`: breaking CLI/config behavior or marker/format changes.
+- `major`: breaking CLI/config behavior or marker/format changes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roadmapsmith",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Generate, sync, and validate deterministic project roadmaps for agent-driven execution.",
   "main": "src/index.js",
   "bin": {