specstocode 0.5.0

package/README.md

@@ -0,0 +1,218 @@
+# ProductBuilders CLI
+
+Plan, validate, and build products — from your terminal. Turn a problem into a structured product blueprint with AI-powered story mapping.
+
+```
+   ██████╗ ██████╗
+   ██╔══██╗██╔══██╗   ProductBuilders
+   ██████╔╝██████╔╝   Stop building for nobody.
+   ██╔═══╝ ██╔══██╗
+   ██║     ██████╔╝
+   ╚═╝     ╚═════╝
+```
+
+## Install
+
+```bash
+npm install -g productbuilders
+```
+
+## Getting Started
+
+### 1. Log in
+
+```bash
+productbuilders login
+```
+
+Opens your browser to authenticate with [ProductBuilders.pro](https://productbuilders.pro). You only need to do this once per machine.
+
+### 2. Start a new project
+
+```bash
+productbuilders start
+```
+
+Interactive guided flow:
+1. **Describe your problem** — what are you trying to solve?
+2. **AI discovery questions** — sharpens your thinking with targeted questions
+3. **Pitch synthesis** — generates a one-liner pitch and target user
+4. **Name your product** — pick from AI-suggested names or type your own
+5. **Validate** — publish to Explore to get feedback before building
+6. **Scope** — generates a blueprint, story map, and optional HTML mockup
+
+### 3. Connect to your codebase
+
+After scoping, connect the story map to your project directory:
+
+```bash
+productbuilders init pb_sync_<your-token>
+```
+
+Your project now has:
+- `PRODUCTBUILDERS.md` — product context (personas, stories, acceptance criteria)
+- `.productbuilders/config.json` — sync config (auto-gitignored)
+
+### 4. Configure your AI tool
+
+```bash
+productbuilders setup
+```
+
+Sets up [Claude Code](https://claude.com/claude-code) and/or [Cursor](https://cursor.com) with:
+- `CLAUDE.md` / `.cursorrules` with product context
+- Slash commands for the development workflow (inside Claude Code, not the terminal)
+- `ARCHITECTURE.md` and `CONVENTIONS.md` scaffolding
+
+### 5. Build
+
+```bash
+productbuilders next          # See what to build first
+productbuilders done <id>     # Mark a story as complete
+productbuilders stories       # List all stories
+productbuilders status        # View progress dashboard
+```
+
+---
+
+## All Commands
+
+### Project Creation
+
+| Command | Description |
+|---------|-------------|
+| `productbuilders login` | Authenticate (opens browser) |
+| `productbuilders logout` | Log out |
+| `productbuilders start` | New project — guided flow from problem to pitch |
+| `productbuilders scope [id]` | Scope a project — blueprint, story map, mockup |
+| `productbuilders setup` | Configure Claude Code / Cursor |
+| `productbuilders templates [name]` | Browse starter templates |
+
+### Story Management
+
+| Command | Description |
+|---------|-------------|
+| `productbuilders init [token]` | Connect project to a story map |
+| `productbuilders sync` | Refresh PRODUCTBUILDERS.md |
+| `productbuilders status` | Progress dashboard |
+| `productbuilders stories [-f filter]` | List stories (filter: todo/done/keyword) |
+| `productbuilders next` | Next priority story with acceptance criteria |
+| `productbuilders done <id>` | Mark story as done (accepts ID prefix) |
+| `productbuilders add <title>` | Create a new story |
+| `productbuilders decide [title]` | Log an architectural decision |
+| `productbuilders note <id> [note]` | Add implementation notes |
+
+### Analysis (coming soon)
+
+| Command | Description |
+|---------|-------------|
+| `productbuilders complexity [id]` | AI complexity scoring |
+| `productbuilders research [query]` | Research with project context |
+| `productbuilders import [file]` | Import PRD as stories |
+
+### Integration
+
+| Command | Description |
+|---------|-------------|
+| `productbuilders mcp [--mode]` | Start MCP server (core/standard/all) |
+
+---
+
+## MCP Server
+
+Give Claude Code or Cursor native access to your story map.
+
+### Setup
+
+```json
+{
+  "mcpServers": {
+    "productbuilders": {
+      "command": "npx",
+      "args": ["productbuilders", "mcp"],
+      "cwd": "/path/to/your/project"
+    }
+  }
+}
+```
+
+Add to `~/.claude/settings.json` (Claude Code) or your Cursor MCP config.
+
+### Tool Modes
+
+Control token usage with `--mode`:
+
+| Mode | Tools | Use case |
+|------|-------|----------|
+| `core` | 5 | Day-to-day dev (list, mark done, status, notes) |
+| `standard` | 8 | Active dev (+ create, context, decisions) |
+| `all` | 11 | Full power (+ complexity, research, import) |
+
+### Available Tools
+
+| Tool | Mode | Description |
+|------|------|-------------|
+| `list_stories` | core | List stories with optional filter |
+| `mark_done` | core | Mark a story as complete |
+| `mark_in_progress` | core | Mark a story as in progress |
+| `get_status` | core | Progress summary |
+| `add_note` | core | Add implementation notes |
+| `create_story` | standard | Create a new story |
+| `get_context` | standard | Fetch PRODUCTBUILDERS.md |
+| `log_decision` | standard | Log an architectural decision |
+| `analyze_complexity` | all | AI complexity scoring |
+| `research` | all | AI research with project context |
+| `import_prd` | all | Parse PRD into stories |
+
+---
+
+## Templates
+
+Starter story maps for common product types:
+
+```bash
+productbuilders templates          # List all
+productbuilders templates saas     # View details
+```
+
+| Template | Description | Stories |
+|----------|-------------|---------|
+| `saas` | Multi-tenant SaaS with auth, billing, dashboards | 16 |
+| `marketplace` | Two-sided marketplace with payments | 13 |
+| `mobile-app` | Consumer app with feed, social, notifications | 12 |
+| `ai-tool` | AI-powered tool with streaming and billing | 12 |
+
+---
+
+## How It Works
+
+```
+ProductBuilders.pro                    Your Project
+┌──────────────────┐                  ┌──────────────────┐
+│                  │                  │                  │
+│  Story Map UI    │◄── sync API ───►│  CLI / MCP       │
+│  (plan here)     │                  │  (build here)    │
+│                  │                  │                  │
+│  ┌────────────┐  │   GET /context   │  PRODUCTBUILDERS │
+│  │ Activities │  │ ───────────────► │  .md             │
+│  │ Steps      │  │                  │                  │
+│  │ Stories    │  │  PATCH /stories  │  Claude Code /   │
+│  │ Personas   │  │ ◄─────────────── │  Cursor / etc    │
+│  └────────────┘  │                  │                  │
+└──────────────────┘                  └──────────────────┘
+```
+
+1. **Start** — describe your problem, AI generates discovery questions and a pitch
+2. **Validate** — publish to Explore, get feedback and intent signals
+3. **Scope** — AI generates blueprint, story map, and mockup
+4. **Connect** — `productbuilders init` links your codebase to the story map
+5. **Build** — your AI tool reads PRODUCTBUILDERS.md for context
+6. **Track** — mark stories done, log decisions, add notes — all flows back to the map
+
+---
+
+## Links
+
+- [ProductBuilders.pro](https://productbuilders.pro) — the web app
+- [Explore](https://productbuilders.pro/explore) — discover what others are building
+- [Community](https://productbuilders.pro/community) — connect with builders

package/bin/productbuilders.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/index.js";

package/bin/specstocode.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/index.js";

package/dist/chunk-55DTUCLY.js

@@ -0,0 +1,417 @@
+import {
+  requireAuth
+} from "./chunk-CYA6I7NV.js";
+import {
+  choose,
+  closePrompt
+} from "./chunk-WPVDURTJ.js";
+import {
+  hasConfig,
+  requireConfig
+} from "./chunk-NAOZWXOF.js";
+
+// src/commands/setup.ts
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from "fs";
+import { execSync } from "child_process";
+import { join } from "path";
+async function setup() {
+  requireAuth();
+  if (!hasConfig()) {
+    console.log("  Not connected to a project. Run `npx specstocode init` first.");
+    closePrompt();
+    return;
+  }
+  const config = requireConfig();
+  const idx = await choose("  Which AI tool do you want to configure?", [
+    "Claude Code",
+    "Cursor",
+    "Both"
+  ]);
+  const tools = idx === 0 ? ["claude"] : idx === 1 ? ["cursor"] : ["claude", "cursor"];
+  for (const tool of tools) {
+    if (tool === "claude") setupClaudeCode(config.syncToken);
+    if (tool === "cursor") setupCursor(config.syncToken);
+  }
+  generateAgentDocs();
+  console.log(`
+  \u2705 Agent configuration complete!
+
+  Your AI tool now has:
+    \u2022 Product context from your specstocode story map
+    \u2022 Slash commands for the development workflow
+    \u2022 Agent guides for implementing, testing, and documenting features
+    \u2022 Architecture and conventions scaffolding
+
+  Slash commands (use inside Claude Code / Cursor, not the terminal):
+    /pb-propose     Propose a new change \u2014 creates stories + local spec
+    /pb-next        Pick up the next story
+    /pb-implement   Full implementation playbook
+    /pb-review      Review against acceptance criteria
+    /pb-document    Document what was built
+    /pb-test        Generate tests from ACs
+    /pb-status      Show progress
+    /pb-done        Mark a story as done
+    /pb-sync        Refresh product context
+    /pb-context     Load focused context for the current story
+
+  Terminal commands (use anywhere):
+    specstocode status       Show story map progress
+    specstocode next         Next priority story
+    specstocode done <id>    Mark a story as done
+    specstocode stories      List all stories
+    specstocode sync         Refresh SPECSTOCODE.md
+  `);
+  closePrompt();
+}
+function setupClaudeCode(syncToken) {
+  const cwd = process.cwd();
+  const claudeMdPath = join(cwd, "CLAUDE.md");
+  const claudeBlock = `
+# specstocode Integration
+
+This project is connected to a specstocode story map.
+Read SPECSTOCODE.md for the full product context: personas, user journey, stories, and acceptance criteria.
+
+## Context hierarchy
+
+1. **SPECSTOCODE.md** \u2014 what to build (stories, acceptance criteria, personas)
+2. **ARCHITECTURE.md** \u2014 how the system is structured (decisions, patterns, trade-offs)
+3. **CONVENTIONS.md** \u2014 how to write code (naming, file structure, testing patterns)
+
+Refresh product context anytime: \`npx specstocode sync\`
+
+## Development workflow
+
+### Starting work
+1. Run \`npx specstocode next\` to get the highest-priority story
+2. Read the acceptance criteria \u2014 these define "done"
+3. Check ARCHITECTURE.md for relevant technical decisions
+4. Plan your approach before writing code
+
+### During development
+- Follow patterns in CONVENTIONS.md
+- If you discover a new requirement, create a story:
+  \`npx specstocode add "Story title" --activity "Activity name" --priority must\`
+- If you make an architectural decision, log it:
+  \`npx specstocode decide "Decision title" -d "What was decided and why"\`
+
+### Completing work
+1. Verify all acceptance criteria are met
+2. Add implementation notes:
+   \`npx specstocode note <story-id> "How this was implemented, gotchas"\`
+3. Mark done: \`npx specstocode done <story-id>\`
+4. Commit: \`git commit -m "feat: description [SC-<id>]"\`
+
+### Writing back to specstocode
+Everything you record flows back to the story map so the team has context:
+- **Stories**: \`npx specstocode add\` / \`done\` / \`note\`
+- **Decisions**: \`npx specstocode decide\`
+- **Context refresh**: \`npx specstocode sync\`
+`;
+  if (existsSync(claudeMdPath)) {
+    const existing = readFileSync(claudeMdPath, "utf-8");
+    if (!existing.includes("specstocode Integration")) {
+      writeFileSync(claudeMdPath, existing + "\n" + claudeBlock);
+      console.log("  \u2713 Updated CLAUDE.md with specstocode agent workflow");
+    } else {
+      console.log("  \u2713 CLAUDE.md already configured");
+    }
+  } else {
+    writeFileSync(claudeMdPath, claudeBlock.trim() + "\n");
+    console.log("  \u2713 Created CLAUDE.md with specstocode agent workflow");
+  }
+  const commandsDir = join(cwd, ".claude", "commands");
+  if (!existsSync(commandsDir)) mkdirSync(commandsDir, { recursive: true });
+  writeFileSync(
+    join(commandsDir, "pb-next.md"),
+    `# Pick up the next story
+
+1. Run \`npx specstocode next\` to get the highest-priority story
+2. Read the acceptance criteria carefully \u2014 these define "done"
+3. Check ARCHITECTURE.md for relevant technical decisions
+4. Read CONVENTIONS.md for coding patterns to follow
+5. Outline your implementation plan before writing code
+6. Ask for confirmation before proceeding
+`
+  );
+  writeFileSync(
+    join(commandsDir, "pb-implement.md"),
+    `# Implement a story
+
+## Process
+1. Run \`npx specstocode next\` to identify the story (or use the story ID provided)
+2. Read SPECSTOCODE.md for full product context
+3. Read the story's acceptance criteria \u2014 each one is a requirement
+4. Check ARCHITECTURE.md for technical decisions that affect this work
+5. Plan: which files change? Simplest approach? Edge cases in the ACs?
+6. Implement the feature
+7. Verify each acceptance criterion is met
+8. Write or update tests if applicable
+
+## Write back to specstocode
+9. Add implementation notes:
+   \`npx specstocode note <story-id> "How this was implemented"\`
+10. Log any significant decisions:
+    \`npx specstocode decide "Decision title" -d "What and why" -c architecture\`
+11. Log any trade-offs:
+    \`npx specstocode decide "Trade-off" -d "What and why" -c trade-off\`
+12. If you discovered new requirements:
+    \`npx specstocode add "title" --activity "Activity" --priority should\`
+13. Mark done: \`npx specstocode done <story-id>\`
+14. Commit: \`git commit -m "feat: description [SC-<id>]"\`
+
+## Rules
+- Don't over-engineer. Build exactly what the acceptance criteria describe.
+- Always log significant decisions \u2014 future developers need context.
+- Follow patterns in CONVENTIONS.md
+`
+  );
+  writeFileSync(
+    join(commandsDir, "pb-review.md"),
+    `# Review against acceptance criteria
+
+1. Identify the story being worked on
+2. For each acceptance criterion:
+   - Does the implementation satisfy it? (yes/no/partial)
+   - If partial, what's missing?
+3. Check for: edge cases, error handling, accessibility, security
+4. Summarise: what's done, what needs work, any concerns
+`
+  );
+  writeFileSync(
+    join(commandsDir, "pb-document.md"),
+    `# Document a feature
+
+1. Check which story was just completed
+2. Read SPECSTOCODE.md for product context
+3. Write a brief markdown doc explaining:
+   - What was built and why
+   - How it works (architecture-level)
+   - Decisions made and trade-offs
+   - How to test it manually
+4. Log decisions to specstocode:
+   \`npx specstocode decide "Title" -d "Description" -c architecture\`
+5. Add implementation notes:
+   \`npx specstocode note <story-id> "Summary of how it works"\`
+6. Update ARCHITECTURE.md if needed
+7. Update CONVENTIONS.md if new patterns were introduced
+`
+  );
+  writeFileSync(
+    join(commandsDir, "pb-test.md"),
+    `# Write tests for a story
+
+1. Get the story details: \`npx specstocode next\` or provided story ID
+2. Each acceptance criterion becomes at least one test
+3. Also consider: error cases, boundary conditions, integration points
+4. Follow testing patterns in CONVENTIONS.md
+5. Run the tests to verify they pass
+`
+  );
+  writeFileSync(
+    join(commandsDir, "pb-status.md"),
+    `Run \`npx specstocode status\` and \`npx specstocode stories --filter todo\` to show current progress and remaining backlog. Summarise what's done and what's left.`
+  );
+  writeFileSync(
+    join(commandsDir, "pb-done.md"),
+    `Ask which story was just completed, then run \`npx specstocode done <id>\`. Also ask if there are any implementation notes to add: \`npx specstocode note <id> "..."\``
+  );
+  writeFileSync(
+    join(commandsDir, "pb-sync.md"),
+    `Run \`npx specstocode sync\` to refresh SPECSTOCODE.md with the latest story map. Then re-read SPECSTOCODE.md to update your context.`
+  );
+  writeFileSync(
+    join(commandsDir, "pb-propose.md"),
+    `# Propose a new change
+
+Use this when you want to plan a new feature, improvement, or fix before writing code.
+specstocode stores the source of truth in your online story map \u2014 this command creates
+stories there AND saves a local spec for the AI to reference during implementation.
+
+## Process
+1. Ask the user: "What do you want to build or change? Describe the problem and the solution."
+2. Help them break it into 2-5 stories with clear acceptance criteria (each AC is testable)
+3. Run: \`npx specstocode propose <change-name>\`
+   - The CLI will guide through: problem, solution, activity, priority, stories + ACs
+   - Stories are created in the live story map at specstocode.com
+   - A local spec is saved to \`pb-changes/<name>/proposal.md\`
+4. Once done: \`npx specstocode sync\` to pull the new stories into SPECSTOCODE.md
+5. Run \`npx specstocode next\` to start implementing
+
+## Tips
+- Change names should be kebab-case: add-dark-mode, fix-auth-flow, onboarding-revamp
+- Keep stories small \u2014 one story = one deployable increment
+- Write ACs as testable outcomes: "Given X, when Y, then Z" or "User can..."
+- If the change is already defined in the UI, just run \`npx specstocode sync\` instead
+`
+  );
+  writeFileSync(
+    join(commandsDir, "pb-context.md"),
+    `# Load current story context
+
+Use this to focus on a single story without loading the full story map.
+
+## When to use
+- At the start of a coding session for a specific story
+- When switching between stories mid-session
+- When you need a clean, focused view of ACs and notes
+
+## Process
+1. Run \`npx specstocode next\` to get the active story \u2014 this automatically writes the context file to \`.specstocode/stories/<id>.md\`
+2. Read that file \u2014 it contains: title, user story, acceptance criteria (as checkboxes), notes, and space for relevant files
+3. Use it as your working document throughout implementation:
+   - Check off ACs as you satisfy them
+   - Add file paths under "Relevant files" as you discover them
+   - Run \`npx specstocode note <id> "..."\` to log notes (updates both remote map and local file)
+4. When all ACs are checked: \`npx specstocode done <id>\`
+
+## If you already know the story ID
+The file is at \`.specstocode/stories/<full-story-id>.md\` \u2014 read it directly.
+`
+  );
+  console.log("  \u2713 Created slash commands: /pb-propose, /pb-next, /pb-implement, /pb-review, /pb-document, /pb-test, /pb-status, /pb-done, /pb-sync, /pb-context");
+  try {
+    execSync("openclaw --version", { stdio: "ignore" });
+    const registration = JSON.stringify({
+      command: "npx",
+      args: ["specstocode", "mcp"],
+      cwd
+    });
+    execSync(`openclaw mcp set specstocode '${registration}'`, { stdio: "inherit" });
+    console.log("  \u2713 Registered with OpenClaw MCP \u2014 coding agents can now access your story map live");
+  } catch {
+    console.log(`
+  To enable MCP tools (recommended), add to your Claude Code MCP config:
+
+  {
+    "mcpServers": {
+      "specstocode": {
+        "command": "npx",
+        "args": ["specstocode", "mcp"],
+        "cwd": "${cwd}"
+      }
+    }
+  }
+
+  Or if you use OpenClaw: npx specstocode openclaw-register
+`);
+  }
+}
+function setupCursor(syncToken) {
+  const cwd = process.cwd();
+  const cursorRulesPath = join(cwd, ".cursorrules");
+  const cursorBlock = `
+# specstocode Integration
+
+## Context files
+1. **SPECSTOCODE.md** \u2014 product story map with personas, stories, acceptance criteria
+2. **ARCHITECTURE.md** \u2014 technical decisions and system structure
+3. **CONVENTIONS.md** \u2014 coding patterns, naming, file structure
+
+## Workflow
+- Next story: \`npx specstocode next\`
+- Mark done: \`npx specstocode done <id>\`
+- Add notes: \`npx specstocode note <id> "..."\`
+- Log decisions: \`npx specstocode decide "Title" -d "Why"\`
+- Create stories: \`npx specstocode add "title" --activity "Name"\`
+- Refresh context: \`npx specstocode sync\`
+
+## Rules
+- Read acceptance criteria before implementing
+- Don't over-engineer \u2014 build what's needed
+- Log decisions and trade-offs back to specstocode
+- Follow patterns in CONVENTIONS.md
+`;
+  if (existsSync(cursorRulesPath)) {
+    const existing = readFileSync(cursorRulesPath, "utf-8");
+    if (!existing.includes("specstocode Integration")) {
+      writeFileSync(cursorRulesPath, existing + "\n" + cursorBlock);
+      console.log("  \u2713 Updated .cursorrules");
+    }
+  } else {
+    writeFileSync(cursorRulesPath, cursorBlock.trim() + "\n");
+    console.log("  \u2713 Created .cursorrules");
+  }
+  console.log(`
+  To enable MCP tools in Cursor:
+
+  {
+    "mcpServers": {
+      "specstocode": {
+        "command": "npx",
+        "args": ["specstocode", "mcp"],
+        "cwd": "${cwd}"
+      }
+    }
+  }
+`);
+}
+function generateAgentDocs() {
+  const cwd = process.cwd();
+  const archPath = join(cwd, "ARCHITECTURE.md");
+  if (!existsSync(archPath)) {
+    writeFileSync(
+      archPath,
+      `# Architecture
+
+Document technical decisions here. Your AI tool reads this before implementing features.
+
+## Decisions
+
+| Date | Decision | Rationale |
+|------|----------|-----------|
+| ${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]} | Project initialised with specstocode | Story-map-driven development |
+
+## Stack
+
+_Fill in your tech stack here._
+
+## Patterns
+
+_Document recurring patterns._
+
+## Trade-offs
+
+_Record trade-offs and why._
+`
+    );
+    console.log("  \u2713 Created ARCHITECTURE.md scaffold");
+  }
+  const convPath = join(cwd, "CONVENTIONS.md");
+  if (!existsSync(convPath)) {
+    writeFileSync(
+      convPath,
+      `# Conventions
+
+Coding rules for this project. Your AI tool follows these when writing code.
+
+## File structure
+
+_Describe your preferred file/folder structure._
+
+## Naming
+
+_Naming conventions (camelCase, PascalCase, etc.)._
+
+## Testing
+
+_Testing patterns._
+
+## Git
+
+- Branches: \`feat/<description>\`, \`fix/<description>\`
+- Commits: \`feat: description [PB-<story-id>]\`
+- Always create PRs \u2014 never commit directly to main
+
+## Code style
+
+_Linting, formatting, style preferences._
+`
+    );
+    console.log("  \u2713 Created CONVENTIONS.md scaffold");
+  }
+}
+
+export {
+  setup
+};

package/dist/chunk-CYA6I7NV.js

@@ -0,0 +1,34 @@
+// src/lib/auth.ts
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+var AUTH_DIR = join(homedir(), ".specstocode");
+var AUTH_FILE = join(AUTH_DIR, "auth.json");
+function getAuth() {
+  try {
+    const raw = readFileSync(AUTH_FILE, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function saveAuth(data) {
+  if (!existsSync(AUTH_DIR)) mkdirSync(AUTH_DIR, { recursive: true });
+  writeFileSync(AUTH_FILE, JSON.stringify(data, null, 2) + "\n", { mode: 384 });
+}
+function requireAuth() {
+  const auth = getAuth();
+  if (!auth) {
+    console.error("Not logged in. Run: npx specstocode login");
+    process.exit(1);
+  }
+  return auth;
+}
+var API_BASE = "https://specstocode.com";
+
+export {
+  getAuth,
+  saveAuth,
+  requireAuth,
+  API_BASE
+};