@drafthq/draft 3.2.1 → 3.3.1

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "draft",
       "source": "./",
       "description": "Context-Driven Development: draft specs and plans before implementation. Structured workflows for features and fixes.",
-      "version": "3.2.1",
+      "version": "3.3.1",
       "author": {
         "name": "mayurpise"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "draft",
   "description": "Context-Driven Development: draft specs and plans before implementation. Structured workflows for features and fixes.",
-  "version": "3.2.1",
+  "version": "3.3.1",
   "author": {
     "name": "mayurpise"
   },

package/.cursor-plugin/plugin.json

@@ -0,0 +1,28 @@
+{
+  "name": "draft",
+  "displayName": "Draft",
+  "description": "Context-Driven Development: draft specs and plans before implementation. Structured workflows for features and fixes.",
+  "version": "3.3.1",
+  "skills": "./skills/",
+  "agents": "./core/agents/",
+  "author": {
+    "name": "mayurpise"
+  },
+  "homepage": "https://github.com/drafthq/draft",
+  "license": "MIT",
+  "keywords": [
+    "context-driven-development",
+    "ai-assisted",
+    "planning",
+    "specifications",
+    "architecture",
+    "code-review",
+    "monorepo",
+    "tdd",
+    "validation",
+    "enterprise",
+    "incremental-refresh",
+    "signal-detection",
+    "state-management"
+  ]
+}

package/README.md

@@ -67,7 +67,7 @@ Each host installs the way that host actually loads extensions — no manual ste
 | Host | `draft install …` | What it does |
 |------|-------------------|--------------|
 | **Claude Code** | `claude-code` | Registers the plugin via `claude plugin marketplace add` + `claude plugin install` (user scope). Restart Claude Code. |
-| **Cursor** | `cursor` | Copies the plugin into `~/.cursor/plugins/local/draft/` (auto-loaded). Restart Cursor. |
+| **Cursor** | `cursor` | Copies the plugin into `~/.cursor/plugins/local/draft/`, writes `.cursor-plugin/plugin.json`, registers `draft@draft-plugins` in Cursor's plugin registry, and enables it. Restart Cursor (or Developer: Reload Window). Existing installs upgrade with `draft install cursor --force`. |
 | **Codex** | `codex` | Writes `./AGENTS.md`, which Codex reads automatically. |
 | **opencode** | `opencode` | Writes `./AGENTS.md` + `~/.agents/skills/draft/`, both auto-discovered. |
 
@@ -92,7 +92,7 @@ Run `/draft` for the full command map.
 ```
 
 ### Cursor — from GitHub
-Cursor natively supports the `.claude-plugin/` structure. Add via *Settings > Rules, Skills, Subagents > Rules > New > Add from Github*:
+Cursor requires `.cursor-plugin/plugin.json`; the `draft install cursor` command also registers the plugin via the shared Claude plugin registry that Cursor reads on many builds. To add from source instead, use *Settings > Rules, Skills, Subagents > Rules > New > Add from Github*:
 ```
 https://github.com/drafthq/draft.git
 ```
@@ -223,6 +223,24 @@ Skills also call into **shell helpers** under `scripts/tools/` for mechanical wo
                                    files with changed hashes
 ```
 
+### Context output modes (`/draft:init`)
+
+`/draft:init` packages your architecture context in one of two modes, selected
+automatically by repo size (override with `DRAFT_INIT_MODE`):
+
+- **`monolith`** (default for small repos, tiers 1–2) — a single
+  graph-primary `architecture.md` is the source of truth; `.ai-context.md` is
+  the token-optimized AI view derived from it.
+- **`okf`** (default for larger repos, tiers 3+) — an **OKF concept taxonomy**
+  under `draft/wiki/` is the source of truth (one concept per file, cross-links
+  form the graph), `.ai-context.md` becomes the navigable index root
+  (Synopsis + Concept Map), and `architecture.md` is demoted to a generated
+  rendered view. An optional self-contained offline HTML viewer ships under
+  `draft/wiki/web/`.
+
+Both modes produce the same `product.md`, `tech-stack.md`, `workflow.md`,
+`guardrails.md`, tracks, and `.state/` — only the architecture packaging differs.
+
 [Full workflow →](core/methodology.md#core-workflow)
 
 ---

package/cli/src/hosts/cursor.js

@@ -2,11 +2,15 @@
 
 const path = require('path');
 const { asset } = require('../lib/paths');
+const { readPluginVersion } = require('../lib/plugin-manifest');
+const { applyCursorRegistration } = require('../lib/cursor-registry');
 
-// Cursor natively understands the .claude-plugin structure. Install the same
-// native plugin tree, by default to the user-level plugin directory so it is
-// available across all projects.
+// Cursor discovers Draft through two layers, both shipped here: the native
+// .cursor-plugin/plugin.json manifest, and the shared Claude plugin registry
+// under ~/.claude/ (written in postInstall). A file copy alone is not enough —
+// current Cursor builds never surface /draft:* commands without registration.
 const ITEMS = [
+  { p: '.cursor-plugin', kind: 'copyTree' },
   { p: '.claude-plugin', kind: 'copyTree' },
   { p: 'skills', kind: 'copyTree' },
   { p: 'core', kind: 'copyTree' },
@@ -37,14 +41,40 @@ module.exports = {
       dest: path.join(base, it.p),
       label: it.p,
     }));
-    // Guard the whole install dir on the manifest's presence.
+    // Guard the whole install dir on the .cursor-plugin manifest's presence.
     actions[0].guard = true;
 
     return {
       targetSummary: `${base} (${ctx.scope})`,
       actions,
       graph: true,
-      done: `Draft installed to ${base}. Restart Cursor to detect the plugin.`,
+      // Runs after the file copies: register + enable the plugin in the shared
+      // Claude registry. On a dry run it computes the merges and writes nothing.
+      postInstall(c) {
+        const installedManifest = path.join(base, '.cursor-plugin', 'plugin.json');
+        const version = readPluginVersion(
+          c.dryRun ? asset('.cursor-plugin', 'plugin.json') : installedManifest
+        );
+        return applyCursorRegistration({
+          home: c.home,
+          installPath: base,
+          version,
+          scope: c.scope,
+          dryRun: c.dryRun,
+        });
+      },
+      done: [
+        `Draft installed to ${base}.`,
+        'Plugin registered and enabled in ~/.claude/plugins/.',
+        'Restart Cursor (Developer: Reload Window) to load /draft:* commands.',
+      ].join(' '),
+      fallbackTitle: 'If /draft commands do not appear after restart:',
+      fallback: [
+        `Confirm ${base}/.cursor-plugin/plugin.json exists`,
+        'Confirm ~/.claude/plugins/installed_plugins.json contains "draft@draft-plugins"',
+        'Confirm ~/.claude/settings.json has "draft@draft-plugins": true',
+        'Run Developer: Reload Window in Cursor',
+      ],
     };
   },
 };

package/cli/src/installer.js

@@ -108,6 +108,18 @@ function install(host, ctx) {
     fetchGraph(ctx);
   }
 
+  // Host-specific registration (e.g. Cursor's plugin registry). On a real
+  // install the hook performs the writes (logging each path); on a dry run it
+  // returns the planned paths so we can surface them without touching disk.
+  if (plan.postInstall) {
+    const reg = plan.postInstall(ctx);
+    if (reg && ctx.dryRun) {
+      log.plan(`would update registry: ${reg.kmPath}`);
+      log.plan(`would update registry: ${reg.ipPath}`);
+      log.plan(`would update registry: ${reg.settingsPath}`);
+    }
+  }
+
   // Record the install path so skills can locate scripts/tools/ from the user's
   // project cwd (best-effort; graph skills glob-fallback if the marker is absent).
   if (!ctx.dryRun) {

package/cli/src/lib/cursor-registry.js

@@ -0,0 +1,122 @@
+'use strict';
+
+// Cursor reads plugins from the shared Claude plugin registry under ~/.claude/
+// on many builds, so a file copy alone never surfaces /draft:* commands. This
+// module merges Draft into the three registry files non-destructively:
+//   - ~/.claude/plugins/known_marketplaces.json   (marketplace entry)
+//   - ~/.claude/plugins/installed_plugins.json     (install record)
+//   - ~/.claude/settings.json                       (enabledPlugins flag)
+// Every write preserves all other plugins, hooks, and unknown keys. Reads of a
+// corrupt JSON file fail loud rather than silently clobbering user data.
+const fs = require('fs');
+const path = require('path');
+const log = require('./log');
+
+const MARKETPLACE_KEY = 'draft-plugins';
+const PLUGIN_KEY = `draft@${MARKETPLACE_KEY}`; // name@<marketplace name>
+
+function readJson(filePath, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (err) {
+    if (err.code === 'ENOENT') return fallback;
+    throw new Error(`Cannot parse ${filePath}: ${err.message}`);
+  }
+}
+
+function writeJsonAtomic(filePath, data) {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = `${filePath}.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', 'utf8');
+  fs.renameSync(tmp, filePath);
+}
+
+function claudeHome(home) {
+  return path.join(home, '.claude');
+}
+
+function registryPaths(home) {
+  const base = path.join(claudeHome(home), 'plugins');
+  return {
+    kmPath: path.join(base, 'known_marketplaces.json'),
+    ipPath: path.join(base, 'installed_plugins.json'),
+    settingsPath: path.join(claudeHome(home), 'settings.json'),
+  };
+}
+
+function registryScope(scope) {
+  return scope === 'project' ? 'project' : 'user';
+}
+
+// Pure: compute the merged registry objects without touching disk. Callers that
+// want to persist them use applyCursorRegistration (which delegates here first).
+function registerCursorPlugin(opts) {
+  const { home, version, scope } = opts;
+  const installPath = path.resolve(opts.installPath);
+  const now = new Date().toISOString();
+  const paths = registryPaths(home);
+
+  // --- known_marketplaces.json: overwrite only our key. ---
+  const km = readJson(paths.kmPath, {});
+  km[MARKETPLACE_KEY] = {
+    source: { source: 'directory', path: installPath },
+    installLocation: installPath,
+    lastUpdated: now,
+  };
+
+  // --- installed_plugins.json: merge our key, preserve installedAt on upgrade. ---
+  const ip = readJson(paths.ipPath, { version: 2, plugins: {} });
+  if (typeof ip.version !== 'number') ip.version = 2;
+  if (!ip.plugins || typeof ip.plugins !== 'object') ip.plugins = {};
+  const existing = Array.isArray(ip.plugins[PLUGIN_KEY]) ? ip.plugins[PLUGIN_KEY][0] : null;
+  const installedAt = existing && existing.installedAt ? existing.installedAt : now;
+  ip.plugins[PLUGIN_KEY] = [
+    {
+      scope: registryScope(scope),
+      installPath,
+      version,
+      installedAt,
+      lastUpdated: now,
+    },
+  ];
+
+  // --- settings.json: flip our enabledPlugins flag, preserve everything else. ---
+  const settings = readJson(paths.settingsPath, {});
+  if (!settings.enabledPlugins || typeof settings.enabledPlugins !== 'object') {
+    settings.enabledPlugins = {};
+  }
+  settings.enabledPlugins[PLUGIN_KEY] = true;
+
+  return {
+    kmPath: paths.kmPath,
+    km,
+    ipPath: paths.ipPath,
+    ip,
+    settingsPath: paths.settingsPath,
+    settings,
+  };
+}
+
+// Compute the merges and, unless dryRun, persist them atomically. Returns the
+// same shape as registerCursorPlugin so the installer can log the paths.
+function applyCursorRegistration(opts) {
+  const result = registerCursorPlugin(opts);
+  if (opts.dryRun) return result;
+
+  log.plan(`writing: ${result.kmPath}`);
+  writeJsonAtomic(result.kmPath, result.km);
+  log.plan(`writing: ${result.ipPath}`);
+  writeJsonAtomic(result.ipPath, result.ip);
+  log.plan(`writing: ${result.settingsPath}`);
+  writeJsonAtomic(result.settingsPath, result.settings);
+
+  return result;
+}
+
+module.exports = {
+  PLUGIN_KEY,
+  MARKETPLACE_KEY,
+  registerCursorPlugin,
+  applyCursorRegistration,
+};

package/cli/src/lib/plugin-manifest.js

@@ -0,0 +1,20 @@
+'use strict';
+
+// Read name/version from a plugin manifest JSON (.cursor-plugin/plugin.json or
+// .claude-plugin/plugin.json). Fails loud if either required field is missing —
+// a manifest without a version would corrupt the registry's install record.
+const fs = require('fs');
+
+function readPluginManifest(manifestPath) {
+  const raw = fs.readFileSync(manifestPath, 'utf8');
+  const data = JSON.parse(raw);
+  if (!data.name) throw new Error(`Missing name in ${manifestPath}`);
+  if (!data.version) throw new Error(`Missing version in ${manifestPath}`);
+  return data;
+}
+
+function readPluginVersion(manifestPath) {
+  return readPluginManifest(manifestPath).version;
+}
+
+module.exports = { readPluginManifest, readPluginVersion };

package/core/methodology.md

@@ -300,7 +300,7 @@ You should see the list of available Draft commands. If not, check that the plug
 
 ### Supported Platforms
 
-Draft works with **Claude Code** (native `.claude-plugin/` support) and **Cursor** (supports `.claude/` plugin structure natively). No build pipeline required.
+Draft works with **Claude Code** (native `.claude-plugin/` support) and **Cursor** (requires `.cursor-plugin/plugin.json` plus registration in the shared Claude plugin registry, both handled by `draft install cursor`). No build pipeline required.
 
 ---
 

package/core/templates/okf/ai-context-index.md

@@ -0,0 +1,48 @@
+---
+project: "{PROJECT_NAME}"
+module: "{MODULE_NAME or 'root'}"
+generated_by: "draft:init"
+generated_at: "{ISO_TIMESTAMP}"
+draft_init_mode: okf
+---
+
+# {PROJECT_NAME} — AI Context Index
+
+> Index root for the OKF taxonomy bundle (`wiki/`). Read **Synopsis** for broad
+> tasks (they usually terminate here). For focused tasks, route through the
+> **Concept Map** to ≤N concept pages — each lists `x-grounded-paths`. This is
+> both the cheap broad-context path AND the progressive-disclosure entry point.
+
+## Synopsis
+
+<!-- 150–250 lines: the cheap broad-context path (prior .ai-context.md value
+     preserved). Architecture in brief, key invariants, where to start, top
+     hotspots. A broad task should be answerable from this section alone. -->
+
+- **Architecture in brief:** {2–4 sentences}
+- **Key invariants:** {bullet list, provenance-tagged}
+- **Where to start:** {entrypoints + core subsystems}
+- **Top hotspots:** {from hotspot-rank.sh — symbol, fan-in}
+
+## Concept Map
+
+<!-- Routing table built from each concept's frontmatter `description`.
+     Open a section index for the full per-concept list. -->
+
+| Section | Routing |
+|---------|---------|
+| `wiki/systems/` | {one-line per subsystem — what it owns, when to open} |
+| `wiki/features/` | {one-line per feature} |
+| `wiki/reference/` | config, schemas, APIs, ADRs, runbooks |
+| `wiki/entrypoints/` | binaries / CLIs / handler roots |
+
+Full taxonomy: [wiki/index.md](wiki/index.md).
+
+## How to navigate
+
+1. **Broad task** (summarize, "what owns X", topology) → answer from **Synopsis**.
+2. **Focused task** ("what breaks if I change Y", "add a field to Z") → open the
+   matching concept via the **Concept Map**; follow its `x-grounded-paths` and
+   `Used by` cross-links. Do not read the whole bundle.
+3. Every concept page is verified against the live call graph; trust its
+   `Blast radius` section over re-deriving by hand.

package/core/templates/okf/concept.md

@@ -0,0 +1,54 @@
+---
+type: Subsystem                    # required (OKF) — one of the frozen vocab below
+title: "{CONCEPT_TITLE}"           # OKF
+description: >                     # OKF — LOAD-BEARING: the agent's routing key.
+  Write this as a ROUTING DECISION, not a summary. It must answer
+  "should the agent open this file for the task at hand?" from the index
+  alone. Name the responsibilities and the words a task would use.
+resource: "{CANONICAL_SOURCE_PATH}"   # OKF — canonical source path(s)
+tags: [tag1, tag2]                 # OKF
+timestamp: "{ISO_TIMESTAMP}"       # OKF — last regeneration
+# Draft extensions (ignored by generic OKF consumers; namespaced x-):
+x-grounded-paths: ["{path/a}", "{path/b}"]   # exact source files this page grounds
+x-hotspot-score: 0.0                          # from hotspot-rank.sh (0..1)
+x-callers: ["{module/a}", "{module/b}"]       # from graph-callers.sh
+---
+
+# {CONCEPT_TITLE}
+
+<!--
+Frozen `type` vocabulary (changing it churns every file — versioned via
+index.md: okf_types_version):
+  Subsystem  — major graph cluster / package boundary        → systems/
+  Module     — single package/dir with cohesive responsibility → systems/
+  Feature    — user-facing capability spanning modules         → features/
+  Entrypoint — binary / main / CLI / handler root              → entrypoints/
+  API        — public interface, route group, RPC surface      → reference/
+  DataModel  — schema, table, core struct/type                 → reference/
+  Dependency — notable external dep + how it's used            → reference/
+  ADR        — architecture decision record                    → reference/
+  Runbook    — operational procedure                           → reference/
+-->
+
+## What it is
+
+One paragraph: the concept's responsibility and boundary. Graph-grounded.
+
+## How it works
+
+Primary control/data flow. At least one Mermaid diagram for a significant
+concept (workflow, state, or sequence). Grounded in the call graph.
+
+## Used by
+
+Cross-links to callers (from `x-callers`). Each link is a relative path to
+another concept page so `okf-validate.sh` can resolve it.
+
+## Blast radius
+
+What breaks if this changes (from `graph-impact.sh`). Lists `x-grounded-paths`
+so a focused task knows exactly which source files to open.
+
+## See also
+
+- [Related concept](../systems/other.md)

package/core/templates/okf/index.md

@@ -0,0 +1,40 @@
+---
+type: Subsystem
+title: "{PROJECT_NAME} — Knowledge Bundle"
+description: >
+  Root index of the OKF taxonomy bundle. Start here, then route into
+  overview/, systems/, features/, reference/, or entrypoints/ via the
+  Concept Map. Open a concept only when its description matches the task.
+resource: .
+tags: [index]
+timestamp: "{ISO_TIMESTAMP}"
+okf_version: "0.1"
+okf_types_version: "0.1"
+---
+
+# {PROJECT_NAME} — Knowledge Bundle
+
+> OKF v0.1 bundle. One concept per file; cross-links form the graph. The
+> live call graph (`codebase-memory-mcp`) is the grounding source; this bundle
+> is the navigable serialization. `../ai-context.md` is the consumption entry point.
+
+## Sections
+
+| Section | Holds | Index |
+|---------|-------|-------|
+| `overview/` | System map, getting-started, glossary | [overview/index.md](overview/index.md) |
+| `systems/` | Subsystems & modules (graph clusters) | [systems/index.md](systems/index.md) |
+| `features/` | User-facing capabilities spanning modules | [features/index.md](features/index.md) |
+| `reference/` | APIs, data models, dependencies, ADRs, runbooks | [reference/index.md](reference/index.md) |
+| `entrypoints/` | Binaries / mains / CLIs / handler roots | see pages below |
+
+## Concept Map
+
+<!-- Built from each concept's frontmatter `description` (the routing key).
+     One line per concept. Regenerated on every init/refresh. -->
+<!-- CONCEPT-MAP:START -->
+<!-- CONCEPT-MAP:END -->
+
+## Change log
+
+See [log.md](log.md) for chronological regeneration history.

package/core/templates/okf/section-index.md

@@ -0,0 +1,25 @@
+---
+type: Subsystem
+title: "{SECTION_TITLE}"
+description: >
+  Section index. Lists every concept in this section with its one-line
+  routing description so an agent can pick the right page without opening
+  each one. {SECTION_PURPOSE}
+resource: .
+tags: [index]
+timestamp: "{ISO_TIMESTAMP}"
+---
+
+# {SECTION_TITLE}
+
+> Section of the OKF bundle. Back to [bundle root](../index.md).
+
+## Concepts
+
+<!-- One row per concept page in this section. `description` is the routing key
+     copied from each page's frontmatter. Regenerated on every init/refresh. -->
+
+| Concept | Type | Routing description |
+|---------|------|---------------------|
+| [{concept-a}]({concept-a}.md) | Module | {one-line routing desc} |
+| [{concept-b}]({concept-b}.md) | Feature | {one-line routing desc} |