intentdocs 0.8.0

package/README.md

@@ -0,0 +1,261 @@
+# intentdocs
+
+**IntentDocs is an MCP-native spec-driven development platform for Claude Code, Cursor and other AI coding agents.** It captures product intent as structured specifications — a story map with acceptance criteria, data model and build order — gives agents live access to those specs over MCP or this CLI, and records implementation progress and verification against what was planned.
+
+This package is the `intent` CLI: the bridge between your repository and your IntentDocs project. Learn the concepts at [intentdocs.com/intent-driven-development](https://www.intentdocs.com/intent-driven-development) and the file format at [intentdocs.com/intent-md](https://www.intentdocs.com/intent-md).
+
+## Install
+
+```bash
+npm install -g intentdocs
+```
+
+Installs the **`intent`** command.
+
+Or use without installing:
+
+```bash
+npx intentdocs init
+```
+
+## How it works
+
+intentdocs is the **context engineering harness** for agentic development. It structures everything your AI coding agent needs to work reliably — not just the stories, but the full picture:
+
+| Context type | What it holds | How to populate |
+|---|---|---|
+| **Instructions** | Role, goals, boundaries for this project | Project page → Instructions |
+| **Scope** | Story maps, user stories, acceptance criteria | Web UI or `intent add` / `intent propose` |
+| **Memory** | Architectural decisions, lessons learned | `intent decide` / `intent done` |
+| **Examples** | Reference patterns, before/after code | `intent example` |
+| **Tools** | APIs, services, MCP config | Project page → Tools |
+| **Guardrails** | Hard constraints, safety rules | Project page → Guardrails |
+
+All of this is assembled into `CLAUDE.md` (or `AGENTS.md` / `GEMINI.md`) by running:
+
+```bash
+intent sync --context
+```
+
+```
+intentdocs.com                        Your project
+┌─────────────────────┐               ┌──────────────────────────┐
+│  Project page       │               │  CLI                     │
+│  ├ Instructions     │               │  ├ CLAUDE.md   ← harness │
+│  ├ Story maps       │◄── sync ─────►│  ├ INTENT.md             │
+│  ├ Decisions        │               │  ├ .intent/              │
+│  ├ Examples         │  --context    │  │   stories/<id>.md     │
+│  ├ Tools / MCP      │──────────────►│  └ mcp.json              │
+│  └ Guardrails       │               │                          │
+└─────────────────────┘               │  Claude Code / Cursor    │
+                                      └──────────────────────────┘
+```
+
+---
+
+## Getting Started
+
+### 1. Log in
+
+```bash
+intent login
+```
+
+Opens your browser to authenticate. One-time per machine.
+
+### 2. Connect your codebase
+
+Run inside your project directory after creating a project on [intentdocs.com](https://intentdocs.com):
+
+```bash
+npx intentdocs init
+```
+
+This creates:
+- `CLAUDE.md` — full context harness assembled from your project page (instructions, stories, decisions, examples, tools, guardrails)
+- `INTENT.md` — story map summary (stories, ACs, status)
+- `ARCHITECTURE.md` — pre-filled with your detected tech stack
+- `.intent/config.json` — sync config (auto-gitignored)
+
+### 3. Set up your AI tool
+
+```bash
+intent setup
+```
+
+Configures [Claude Code](https://claude.com/claude-code) or [Cursor](https://cursor.com) with:
+- Slash commands for the full development workflow
+- `CONVENTIONS.md` scaffolding
+
+### 4. Build
+
+```bash
+intent next          # Pick up the next story
+intent done <id>     # Mark complete + log a decision or lesson
+intent decide        # Log an architectural decision
+intent example       # Log a reference pattern
+intent sync          # Refresh INTENT.md
+intent sync --context  # Regenerate CLAUDE.md from your project page
+```
+
+---
+
+## All Commands
+
+### Setup & sync
+
+| Command | Description |
+|---|---|
+| `intent login` | Authenticate (opens browser) |
+| `intent logout` | Log out |
+| `intent init` | Connect project directory to a story map + generate CLAUDE.md |
+| `intent setup` | Configure Claude Code / Cursor with slash commands |
+| `intent sync` | Refresh `INTENT.md` with latest stories |
+| `intent sync --context` | Regenerate `CLAUDE.md` from your full project page context |
+
+### Story management
+
+| Command | Description |
+|---|---|
+| `intent status` | Progress dashboard + recent activity |
+| `intent stories [-f filter]` | List stories (`todo` / `done` / keyword) |
+| `intent next` | Next priority story with acceptance criteria |
+| `intent done <id>` | Mark done — prompts for a decision or lesson learned |
+| `intent add <title>` | Create a new story |
+| `intent propose [name]` | Plan a new feature — creates stories + saves a local spec |
+| `intent note <id> [text]` | Add implementation notes to a story |
+
+### Context & memory
+
+| Command | Description |
+|---|---|
+| `intent decide [title]` | Log an architectural or product decision |
+| `intent example` | Log a reference pattern (before/after code) for this codebase |
+
+### AI features (Builder plan)
+
+| Command | Description |
+|---|---|
+| `intent complexity` | AI complexity scoring — 1-10 score, risks, suggested effort |
+| `intent research` | AI research with your project context |
+| `intent import` | Parse a PRD into structured user stories |
+| `intent next --stub` | Generate a failing test skeleton from acceptance criteria |
+
+### MCP server
+
+| Command | Description |
+|---|---|
+| `intent mcp [--mode]` | Start MCP server (`core` / `standard` / `all`) |
+
+---
+
+## Slash Commands (Claude Code / Cursor)
+
+Run `intent setup` to install these. Use inside your AI coding agent, not the terminal.
+
+| Command | What it does |
+|---|---|
+| `/intent-next` | Pick up the next story |
+| `/intent-implement` | Full implementation playbook — load harness → ACs → code → done |
+| `/intent-propose` | Plan a new feature before writing code |
+| `/intent-review` | Review implementation against acceptance criteria |
+| `/intent-document` | Document what was built |
+| `/intent-test` | Generate tests from acceptance criteria |
+| `/intent-decide` | Log an architectural or product decision |
+| `/intent-example` | Log a reference pattern for this codebase |
+| `/intent-status` | Show story map progress and recent activity |
+| `/intent-done` | Mark a story done + log a decision |
+| `/intent-sync` | Refresh story map or regenerate full CLAUDE.md harness |
+| `/intent-context` | Load focused context for the current story |
+
+---
+
+## MCP Server
+
+The intentdocs MCP server exposes **tools** (actions your agent can take) and **resources** (project context your agent can read). Configure it once and your AI coding agent has native access to your full spec.
+
+Give Claude Code or Cursor native tool and resource access to your story map.
+
+Add to `~/.claude/settings.json` (Claude Code) or your Cursor MCP config:
+
+```json
+{
+  "mcpServers": {
+    "intentdocs": {
+      "command": "npx",
+      "args": ["intentdocs", "mcp"],
+      "cwd": "/path/to/your/project"
+    }
+  }
+}
+```
+
+### Available tools (19)
+
+| Tool | Description |
+|---|---|
+| `list_projects` | List user's projects |
+| `get_context` | Full product context for a project |
+| `list_stories` | List stories with optional filter |
+| `update_stories` | Batch update story status/fields, including user-story text (`as_a`/`i_want`/`so_that`) |
+| `create_stories` | Batch create new stories |
+| `report_criteria` | Report acceptance criteria pass/fail results |
+| `add_criteria` | Append acceptance criteria to a story — returns new criterion IDs for use with `report_criteria` |
+| `replace_criteria` | Replace ALL acceptance criteria on a story — returns new criterion IDs |
+| `check_release_readiness` | Pre-flight scan for missing ACs and implementation plans |
+| `start_story` | Mark a story in_progress (blocks if another is already in_progress) |
+| `complete_story` | Mark a story done + returns next story in release |
+| `get_status` | Progress summary |
+| `raise_blocker` | Flag a blocker on a story |
+| `add_note` | Add implementation notes |
+| `log_decision` | Log an architectural decision |
+| `analyze_complexity` | AI complexity scoring |
+| `research` | AI research with project context |
+| `import_prd` | Parse a PRD into stories |
+| `get_build_order` | Recommended implementation order |
+
+### MCP Resources
+
+Resources let any MCP-compatible agent (Claude Code, Cursor, Codex) discover and read your project spec without invoking commands. Unlike tools, resources are read-only and auto-discoverable — your coding agent can pull exactly the context it needs.
+
+| Resource | URI | Description |
+|---|---|---|
+| Story Map | `intentdocs://project/storymap` | Full product context — personas, activities, stories, acceptance criteria |
+| Stories | `intentdocs://project/stories` | All stories with status, priority, effort, and ACs |
+| Status | `intentdocs://project/status` | Progress summary — done/in-progress/todo counts |
+| Decisions | `intentdocs://project/decisions` | Architectural and product decisions |
+| Data Model | `intentdocs://project/data-model` | Schema and data model from your spec |
+| Build Order | `intentdocs://project/build-order` | Recommended implementation order |
+
+Resources are always available regardless of tool mode.
+
+**Example usage in Claude Code:**
+
+Your coding agent can read these directly:
+```
+Read resource: intentdocs://project/data-model
+```
+
+No command needed — the agent discovers available resources from the MCP server automatically.
+
+---
+
+## AI Features & Pricing
+
+AI-powered commands are gated behind the Builder plan. Unlock two ways:
+
+1. **Upgrade** — [intentdocs.com/pricing](https://intentdocs.com/pricing)
+2. **Bring your own Anthropic key** — works on any plan:
+
+```bash
+intent keys set       # add your Anthropic API key (encrypted at rest)
+intent keys status    # check whether a key is configured
+intent keys remove    # fall back to plan limits
+```
+
+---
+
+## Links
+
+- [intentdocs.com](https://intentdocs.com) — web app
+- [npm](https://www.npmjs.com/package/intentdocs) — this package

package/bin/intent.js

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

package/dist/chunk-4OWPN2RE.js

@@ -0,0 +1,249 @@
+import {
+  ask,
+  closePrompt,
+  confirm
+} from "./chunk-WPVDURTJ.js";
+import {
+  getContext
+} from "./chunk-6XKB6RTU.js";
+import {
+  writeConfig
+} from "./chunk-ICOMMHKG.js";
+import {
+  API_BASE,
+  requireAuth
+} from "./chunk-PCNDP5SX.js";
+
+// src/commands/scope.ts
+import { writeFileSync, existsSync } from "fs";
+import { join } from "path";
+async function apiFetch(path, token, opts = {}) {
+  return fetch(`${API_BASE}${path}`, {
+    ...opts,
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${token}`,
+      ...opts.headers ?? {}
+    }
+  });
+}
+async function scope(projectId) {
+  const auth = requireAuth();
+  const { token } = auth;
+  if (!projectId) {
+    projectId = await ask("  Project ID (from `intent start`): ");
+  }
+  if (!projectId?.trim()) {
+    console.log("  Project ID required.");
+    closePrompt();
+    return;
+  }
+  console.log("\n  \u{1F52C} Scoping your product\n");
+  console.log("  I'll ask a few questions to build your story map.\n");
+  const journey = await ask(
+    "  What are the main steps a user takes through your product?\n  (e.g. Sign up \u2192 Browse \u2192 Purchase \u2192 Review)\n  > "
+  );
+  const personas = await ask(
+    "\n  Who are the key personas? Describe 1-2 types of user.\n  (e.g. 'Sarah, a busy marketing manager who needs...')\n  > "
+  );
+  const mvp = await ask(
+    "\n  What's the minimum you need to build to test the idea?\n  (e.g. 'A simple landing page with a sign-up form and one core workflow')\n  > "
+  );
+  const constraints = await ask(
+    "\n  Any technical constraints or preferences?\n  (e.g. 'Must be a web app, using React and Supabase')\n  > "
+  );
+  console.log("\n  Generating blueprint + story map...");
+  console.log("  This takes 1-3 minutes. Doing this manually takes hours.\n");
+  const scopingContext = [
+    journey ? `User journey: ${journey}` : "",
+    personas ? `Key personas: ${personas}` : "",
+    mvp ? `MVP scope: ${mvp}` : "",
+    constraints ? `Technical constraints: ${constraints}` : ""
+  ].filter(Boolean).join("\n");
+  const res = await apiFetch("/api/blueprint/generate", token, {
+    method: "POST",
+    body: JSON.stringify({
+      projectId,
+      phase: "generation",
+      idea: scopingContext,
+      messages: [
+        { role: "user", content: scopingContext }
+      ]
+    })
+  });
+  if (!res.ok) {
+    const errText = await res.text();
+    if (errText.includes("RATE_LIMIT")) {
+      console.error("  Rate limit reached. Try again later or upgrade your plan.");
+    } else {
+      console.error(`  Generation failed: ${errText.slice(0, 200)}`);
+    }
+    closePrompt();
+    return;
+  }
+  const reader = res.body?.getReader();
+  const decoder = new TextDecoder();
+  let fullResponse = "";
+  let dots = 0;
+  if (reader) {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      fullResponse += decoder.decode(value, { stream: true });
+      dots++;
+      if (dots % 20 === 0) process.stdout.write(".");
+    }
+  }
+  console.log("\n");
+  try {
+    const cleaned = fullResponse.replace(/^\s*```json\s*/m, "").replace(/\s*```\s*$/m, "").trim();
+    const firstBrace = cleaned.indexOf("{");
+    const lastBrace = cleaned.lastIndexOf("}");
+    if (firstBrace !== -1 && lastBrace > firstBrace) {
+      const bp = JSON.parse(cleaned.slice(firstBrace, lastBrace + 1));
+      console.log("  \u2713 Blueprint generated!\n");
+      if (bp.founding_hypothesis) {
+        console.log(`  Hypothesis: ${bp.founding_hypothesis.slice(0, 150)}${bp.founding_hypothesis.length > 150 ? "..." : ""}
+`);
+      }
+      if (bp.personas?.length) {
+        console.log(`  Personas: ${bp.personas.map((p) => p.name).join(", ")}`);
+      }
+      if (bp.stories?.length) {
+        console.log(`  Stories: ${bp.stories.length} user stories generated`);
+      }
+      if (bp.build_order?.length) {
+        console.log(`  Build order: ${bp.build_order.length} steps`);
+      }
+    }
+  } catch {
+    console.log("  \u2713 Blueprint generated (couldn't parse summary)\n");
+  }
+  console.log("\n  Connecting project to your codebase...");
+  const mapsRes = await apiFetch(
+    `/api/storymapper/project/${projectId}`,
+    token
+  );
+  let syncToken = null;
+  if (mapsRes.ok) {
+    const mapData = await mapsRes.json();
+    if (mapData.mapId) {
+      const tokenRes = await apiFetch(
+        `/api/storymapper/${mapData.mapId}/sync-token`,
+        token,
+        { method: "POST" }
+      );
+      if (tokenRes.ok) {
+        const tokenData = await tokenRes.json();
+        syncToken = tokenData.sync_token;
+      }
+    }
+  }
+  if (syncToken) {
+    writeConfig({ syncToken, apiBase: API_BASE });
+    console.log("  \u2713 Connected\n");
+    try {
+      const config = { syncToken, apiBase: API_BASE };
+      const md = await getContext(config);
+      writeFileSync(join(process.cwd(), "INTENT.md"), md);
+      console.log("  \u2713 Downloaded INTENT.md\n");
+    } catch {
+      console.log("  \u26A0 Could not download INTENT.md\n");
+    }
+  }
+  const wantMockup = await confirm(
+    "  Want to generate an HTML mockup of your product?"
+  );
+  if (wantMockup) {
+    const designSystem = await ask(
+      "\n  Any existing design system? (e.g. Tailwind + shadcn, Material UI, or 'none')\n  > "
+    );
+    const inspiration = await ask(
+      "\n  Any products or sites that inspire the look & feel?\n  > "
+    );
+    const mockupPrompt = buildMockupPrompt(projectId, designSystem, inspiration);
+    const mockupPath = join(process.cwd(), "MOCKUP_PROMPT.md");
+    writeFileSync(mockupPath, mockupPrompt);
+    console.log(`
+  \u2713 Saved MOCKUP_PROMPT.md
+`);
+    console.log("  To generate the mockup, tell your AI coding tool:");
+    console.log("    'Read MOCKUP_PROMPT.md and generate the HTML mockup'\n");
+  }
+  const hasGit = existsSync(join(process.cwd(), ".git"));
+  if (!hasGit) {
+    const wantRepo = await confirm("  Initialize a git repo for this project?");
+    if (wantRepo) {
+      const { execSync } = await import("child_process");
+      try {
+        execSync("git init", { stdio: "ignore" });
+        execSync("git add INTENT.md", { stdio: "ignore" });
+        if (existsSync(join(process.cwd(), "MOCKUP_PROMPT.md"))) {
+          execSync("git add MOCKUP_PROMPT.md", { stdio: "ignore" });
+        }
+        execSync('git commit -m "Initial commit \u2014 intentdocs project context"', {
+          stdio: "ignore"
+        });
+        console.log("  \u2713 Git repo initialized with first commit\n");
+      } catch {
+        console.log("  \u26A0 Git init failed \u2014 do it manually\n");
+      }
+    }
+  }
+  const { confirm: confirmSetup } = await import("./prompt-WAWCRGHN.js");
+  const wantSetup = await confirmSetup(
+    "  Configure your AI tool (Claude Code / Cursor) with intentdocs agent workflows?"
+  );
+  if (wantSetup) {
+    const { setup } = await import("./setup-SOI2HQAL.js");
+    await setup();
+    return;
+  }
+  console.log(`
+  \u2705 Your project is scoped and ready to build!
+
+  Next steps:
+    \u2022 intent setup          \u2014 configure your AI tool
+    \u2022 intent status         \u2014 see your story map progress
+    \u2022 intent next           \u2014 see what to build first
+    \u2022 intent done <id>      \u2014 mark stories as you complete them
+
+  Your story map is also live at ${API_BASE}
+  Seek advice from the community and our resources.
+  `);
+  closePrompt();
+}
+function buildMockupPrompt(projectId, designSystem, inspiration) {
+  return `# Mockup Generation Prompt
+
+Read INTENT.md for the full product context (personas, stories, acceptance criteria).
+
+## Task
+Generate a single-file HTML mockup that demonstrates the core user journey.
+The mockup should be a clickable prototype \u2014 not production code, but enough
+to validate the UX with real users.
+
+## Requirements
+- Single HTML file with inline CSS and minimal JS
+- Mobile-first responsive design
+- All key screens from the user journey (see INTENT.md)
+- Realistic placeholder content (not lorem ipsum)
+- Navigation between screens via anchor links or simple JS
+
+## Design
+${designSystem && designSystem !== "none" ? `- Design system: ${designSystem}` : "- Use a clean, modern design with system fonts"}
+${inspiration ? `- Inspiration: ${inspiration}` : "- Keep it simple and functional"}
+- Dark mode preferred
+- Accessible (proper contrast, semantic HTML)
+
+## Output
+Save as \`mockup.html\` in the project root.
+
+## Project ID
+${projectId}
+`;
+}
+
+export {
+  scope
+};

package/dist/chunk-6FGYJ3W2.js

@@ -0,0 +1,140 @@
+// src/lib/story-context.ts
+import { mkdirSync, writeFileSync, readFileSync, existsSync } from "fs";
+import { join } from "path";
+
+// src/lib/criteria.ts
+function criterionPriority(ac) {
+  return ac.priority ?? "should";
+}
+function findBlockingMusts(criteria) {
+  return criteria.filter(
+    (ac) => criterionPriority(ac) === "must" && ac.last_result?.status !== "pass"
+  );
+}
+function criterionStatusLabel(ac) {
+  return ac.last_result?.status ?? "unreported";
+}
+var METHOD_LABELS = {
+  executable: "executable",
+  agent_self_check: "self-check",
+  visual_render: "visual",
+  founder_confirm: "founder"
+};
+function renderCriterionLines(ac) {
+  const checkbox = ac.done ? "x" : " ";
+  const isLegacy = ac.priority === void 0 && ac.verification === void 0;
+  if (isLegacy) {
+    return [`- [${checkbox}] ${ac.text}`];
+  }
+  const priority = criterionPriority(ac);
+  const verification = ac.verification ?? { method: "founder_confirm", check_prompt: ac.text };
+  const methodLabel = METHOD_LABELS[verification.method];
+  const lines = [`- [${checkbox}] [${priority}][${methodLabel}] ${ac.text}`];
+  if (verification.method === "executable") {
+    const expectSuffix = verification.expected ? `  \u2192 expect: ${verification.expected}` : "";
+    lines.push(`      check: ${verification.command ?? ""}${expectSuffix}`);
+  } else {
+    lines.push(`      check: ${verification.check_prompt ?? ac.text}`);
+  }
+  return lines;
+}
+
+// src/lib/story-context.ts
+var CONTEXT_DIR = ".intent/stories";
+function storyContextPath(storyId) {
+  return join(process.cwd(), CONTEXT_DIR, `${storyId}.md`);
+}
+function writeStoryContext(story) {
+  const dir = join(process.cwd(), CONTEXT_DIR);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const acLines = story.acceptance_criteria.length ? story.acceptance_criteria.flatMap((ac) => renderCriterionLines(ac)).join("\n") : "_No acceptance criteria defined._";
+  const specSection = story.notes?.trim() ? [`## Spec`, ``, story.notes.trim(), ``] : [];
+  const plan = story.implementation_plan;
+  const hasPlan = plan?.status === "ready" && plan.markdown;
+  const approachSection = hasPlan ? [
+    `## Implementation Plan`,
+    ``,
+    `_Generated by IntentDocs.com${plan.generated_at ? ` on ${plan.generated_at.slice(0, 10)}` : ""}_`,
+    ``,
+    plan.markdown,
+    ``,
+    ...plan.files_to_create?.length ? [`### Files to create`, ``, ...plan.files_to_create.map((f) => `- \`${f}\``), ``] : [],
+    ...plan.files_to_modify?.length ? [`### Files to modify`, ``, ...plan.files_to_modify.map((f) => `- \`${f}\``), ``] : []
+  ] : [
+    `## Approach`,
+    ``,
+    `_Plan your approach here before writing code._`,
+    ``
+  ];
+  const md = [
+    `# ${story.title}`,
+    ``,
+    `**ID:** \`${story.id}\``,
+    `**Activity:** ${story.activity}`,
+    `**Priority:** ${story.priority} | **Effort:** ${story.effort} | **Release:** ${story.release}`,
+    `**Status:** ${story.status}`,
+    ``,
+    `## User story`,
+    ``,
+    story.user_story ?? "_No user story defined._",
+    ``,
+    `## Done when`,
+    ``,
+    acLines,
+    ``,
+    ...specSection,
+    ...approachSection,
+    `## Implementation notes`,
+    ``,
+    `_Notes added via \`intent note ${story.id.slice(0, 8)} "..."\`_`,
+    ``,
+    `## Decisions`,
+    ``,
+    `_Log decisions via \`intent decide "..." -s ${story.id.slice(0, 8)}\`_`,
+    ``,
+    `## Relevant files`,
+    ``,
+    `_Add file paths here as you explore the codebase._`,
+    ``,
+    `---`,
+    ``,
+    `Mark done: \`intent done ${story.id.slice(0, 8)}\``
+  ].join("\n");
+  const path = storyContextPath(story.id);
+  writeFileSync(path, md);
+  return path;
+}
+function appendNoteToContext(storyId, note) {
+  const path = storyContextPath(storyId);
+  if (!existsSync(path)) return false;
+  const content = readFileSync(path, "utf-8");
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace("T", " ").slice(0, 16);
+  const noteEntry = `- [${timestamp}] ${note}`;
+  const marker = "## Implementation notes";
+  const markerIdx = content.indexOf(marker);
+  if (markerIdx === -1) return false;
+  const placeholder = "_Notes added via";
+  if (content.includes(placeholder)) {
+    writeFileSync(path, content.replace(
+      /^_Notes added via.*$/m,
+      `${noteEntry}`
+    ));
+  } else {
+    const nextSection = content.indexOf("\n## ", markerIdx + marker.length);
+    const insertAt = nextSection === -1 ? content.length : nextSection;
+    writeFileSync(
+      path,
+      content.slice(0, insertAt).trimEnd() + "\n" + noteEntry + "\n" + content.slice(insertAt)
+    );
+  }
+  return true;
+}
+
+export {
+  criterionPriority,
+  findBlockingMusts,
+  criterionStatusLabel,
+  storyContextPath,
+  writeStoryContext,
+  appendNoteToContext
+};