feat(init)!: single scope-aware /draft:init, remove /draft:index (3.0.0)

/draft:init is now the single, scope-aware entry point. It builds the whole-repo code-graph knowledge memory first (the root spine), then scope-local context. New scripts/tools/graph-init.sh resolves the repo ROOT (ancestor-draft/ -> git toplevel -> cwd), ensures the engine (fetching as fallback), builds the committed root snapshot, and in a sub-module writes the module snapshot + draft/graph/root-link.json pointing up to the root graph. Adds --graph-only and --module-only flags; markdown is scope-asymmetric (sparse root / detailed module) while the graph stays symmetric. Rewires routers (discover, draft, intent-mapping), methodology, shared procedures, and 6 root-aggregation templates from index to init; the multi-directory bug sweep moves to /draft:bughunt. Also syncs pending OKF feature docs and bumps 2.8.3 -> 3.0.0 across package.json, plugin.json, marketplace.json, web, and docs.

BREAKING CHANGE: /draft:index is removed. Run /draft:init at the repo root for whole-repo context (graph spine + sparse root map), or inside a sub-module for detailed context linked up to the root graph.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: mayurpise

.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": "2.8.3",
+      "version": "3.0.0",
       "author": {
         "name": "mayurpise"
       },

.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": "2.8.3",
+  "version": "3.0.0",
   "author": {
     "name": "mayurpise"
   },

CHANGELOG.md

@@ -5,7 +5,51 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [3.0.0] - 2026-06-14
+
+### Added
+- **Open Knowledge Format (OKF) emission by default.** The knowledge-graph
+  snapshot now also writes an [OKF v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
+  bundle to `draft/graph/okf/` (`index.md` + cross-linked `modules/<name>.md`
+  concept pages) via the new `scripts/tools/okf-emit.sh`, on every `/draft:graph`
+  and `/draft:init` run. A portable, vendor-neutral markdown
+  mirror of the graph.
+- **The whole `draft/` directory is an OKF bundle.** `scripts/tools/okf-bundle.sh`
+  writes `draft/index.md` (the bundle-root index) cross-linking every concept —
+  context docs, tracks, and the graph sub-bundle. Project-doc templates
+  (`architecture.md`, `.ai-context.md`, `.ai-profile.md`, `product.md`,
+  `tech-stack.md`, `workflow.md`, `guardrails.md`) and track templates
+  (`spec/plan/hld/lld/discovery/rca`, `tracks.md`) now carry an OKF `type:`
+  frontmatter field.
+- **OKF v0.1 conformance checker.** `scripts/tools/okf-check.sh` validates §9 of
+  the spec — parseable frontmatter with a non-empty `type` on every concept, and
+  the reserved-file rules for `index.md`/`log.md`. Wired (advisory) into
+  `/draft:init`.
+- **Scope-aware, root-first code-graph memory.** `/draft:init` is now the single,
+  scope-aware entry point and builds the whole-repo "code-graph knowledge memory"
+  first, wherever it is run. New `scripts/tools/graph-init.sh` resolves the repo
+  ROOT (nearest ancestor with `draft/` → git toplevel → cwd), ensures the
+  knowledge-graph engine is present (fetching it as a fallback), builds the
+  committed root snapshot (`draft/graph/`), and — when run inside a sub-module —
+  builds the module snapshot and writes `draft/graph/root-link.json` pointing up
+  to the root graph, so any module has full cross-module understanding.
+- **`/draft:init --graph-only` and `--module-only` flags.** `--graph-only`
+  (re)builds just the code-graph memory with no markdown; `--module-only` skips
+  touching the root (the module→root link is marked `pending`).
+
+### Changed
+- **`/draft:init` markdown is scope-asymmetric.** A root init now generates a
+  sparse, high-level system map that links down to each module's context (no deep
+  per-module prose); a module init generates the full detailed reference. The
+  graph layer stays symmetric (root spine + per-module snapshots, linked).
+
+### Removed
+- **`/draft:index` is removed — folded into the scope-aware `/draft:init`.**
+  Monorepo context now comes from running `/draft:init` at the repo root (sparse
+  root map + whole-repo graph spine) and in each sub-module (detailed context +
+  `root-link.json`). The multi-directory bug-hunt sweep moved to
+  `/draft:bughunt` (explicit dir list or auto-discovery). Total surface: 33 skills.
+  (Web/book references to `/draft:index` will be updated in a follow-up docs pass.)
 
 ## [2.8.3] - 2026-06-14
 

CLAUDE.md

@@ -4,16 +4,16 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Repository Overview
 
-Draft is a Claude Code plugin that implements Context-Driven Development methodology. It provides a two-tier command surface: 4 primary workflow commands (`/draft:init`, `/draft:new-track`, `/draft:implement`, `/draft:review`) plus 5 routers (`/draft:plan`, `/draft:ops`, `/draft:docs`, `/draft:discover`, `/draft:jira`) as the recommended public interface. 25 specialist commands are dispatched underneath the routers. The unified `/draft:jira` router supports `preview`, `create`, and the advanced `review <JIRA-ID>` qualification pipeline (deep-review + bughunt + coverage + test-gap analysis). Run `/draft` for the full intent map. Total surface: 34 skills.
+Draft is a Claude Code plugin that implements Context-Driven Development methodology. It provides a two-tier command surface: 4 primary workflow commands (`/draft:init`, `/draft:new-track`, `/draft:implement`, `/draft:review`) plus 5 routers (`/draft:plan`, `/draft:ops`, `/draft:docs`, `/draft:discover`, `/draft:jira`) as the recommended public interface. 24 specialist commands are dispatched underneath the routers. The unified `/draft:jira` router supports `preview`, `create`, and the advanced `review <JIRA-ID>` qualification pipeline (deep-review + bughunt + coverage + test-gap analysis). Run `/draft` for the full intent map. Total surface: 33 skills.
 
-Draft also ships a **knowledge graph engine** under `bin/<arch>/` (native Aether binaries) + `scripts/tools/` (14 deterministic shell helpers). Skills are markdown (source of truth, processed by a bash build script into platform-specific integration files for Copilot and Gemini); the graph engine and shell helpers handle mechanical work that markdown can't.
+Draft also ships a **knowledge graph engine** under `bin/<arch>/` (native Aether binaries) + `scripts/tools/` (34 deterministic shell helpers). Skills are markdown (source of truth, processed by a bash build script into platform-specific integration files for Copilot and Gemini); the graph engine and shell helpers handle mechanical work that markdown can't.
 
 ## Build & Test Commands
 
 ```bash
 make build              # Generate integration files from skills
 make build-integrations # Same as above (explicit target)
-make test               # Run all 25 test suites (skills, build, tools)
+make test               # Run all 44 test suites (skills, build, tools)
 make lint               # Run shellcheck + markdownlint
 make clean              # Remove generated integrations
 
@@ -47,7 +47,7 @@ core/agents/*.md          ──┘
 ```
 
 The build script (`scripts/build-integrations.sh`) reads `SKILL_ORDER`, `CORE_FILES`, and `TOOLS` from `scripts/lib.sh` (sourced) and:
-1. Iterates `SKILL_ORDER` (34 skills in current two-tier model, order matters)
+1. Iterates `SKILL_ORDER` (33 skills in current two-tier model, order matters)
 2. Validates YAML frontmatter (`name:` and `description:` required)
 3. Validates body format: blank, `# Title`, blank, then content
 4. Extracts body via `extract_body()`, skipping frontmatter
@@ -68,7 +68,7 @@ The build script (`scripts/build-integrations.sh`) reads `SKILL_ORDER`, `CORE_FI
 - **`core/agents/`** — Behavioral protocols for specialized agents (architect, debugger, planner, rca, reviewer, ops, writer)
 - **`core/templates/`** — 20 templates for files that `/draft:init` generates in user projects
 - **`bin/<arch>/`** — Knowledge graph engine native binaries (from Aether). `bin/<arch>/graph` (+ optional `graph-clang`). Output artifacts under `draft/graph/`. CLI and schema documented in `bin/README.md`. Legacy `graph/bin/` layout supported for transition.
-- **`scripts/tools/`** — 14 deterministic shell helpers (git-metadata, classify-files, hotspot-rank, cycle-detect, etc.). Skills call these for mechanical work.
+- **`scripts/tools/`** — 34 deterministic shell helpers (git-metadata, classify-files, hotspot-rank, cycle-detect, etc.). Skills call these for mechanical work.
 - **`scripts/lib.sh`** — Shared definitions sourced by build script: `SKILL_ORDER`, `CORE_FILES`, `TOOLS`.
 - **`web/`** — Static website deployed to GitHub Pages (`getdraft.dev`), deployed via `.github/workflows/pages.yml`. Includes the Draft Book (22 chapters + 2 appendices) under `web/book/`.
 - **`draft/`** — Dogfooding: Draft's own context files, generated by running `/draft:init` on this repo

Makefile

@@ -30,6 +30,7 @@ TEST_SCRIPTS = \
 	./tests/test-tools-manage-symlinks.sh \
 	./tests/test-tools-mermaid-from-graph.sh \
 	./tests/test-tools-graph-snapshot.sh \
+	./tests/test-tools-graph-init.sh \
 	./tests/test-tools-okf-emit.sh \
 	./tests/test-tools-okf-bundle.sh \
 	./tests/test-tools-okf-check.sh \

README.md

@@ -113,9 +113,9 @@ curl -o .gemini.md https://raw.githubusercontent.com/drafthq/draft/main/integrat
 
 ---
 
-## Beyond `/draft:review` — 33 more commands
+## Beyond `/draft:review` — 32 more commands
 
-`/draft:review` is the wedge. Once Draft has indexed your repo, you also get spec-driven planning, TDD-enforced implementation, exhaustive bug hunting, deep architectural audits, and 29 more commands covering the full development lifecycle.
+`/draft:review` is the wedge. Once Draft has indexed your repo, you also get spec-driven planning, TDD-enforced implementation, exhaustive bug hunting, deep architectural audits, and 32 more commands covering the full development lifecycle.
 
 ---
 
@@ -187,7 +187,7 @@ The graph powers `/draft:graph` and `/draft:impact`, enriches `/draft:bughunt` a
 
 ### Deterministic helper tools
 
-Skills also call into **14 shell helpers** under `scripts/tools/` for mechanical work — git metadata, file classification, test-framework detection, hotspot ranking, freshness checks, ADR indexing. All emit JSON, follow a uniform exit-code contract, and degrade gracefully when their input source is unavailable.
+Skills also call into **34 shell helpers** under `scripts/tools/` for mechanical work — git metadata, file classification, test-framework detection, hotspot ranking, freshness checks, ADR indexing, and Open Knowledge Format emission/validation (`okf-emit.sh`, `okf-bundle.sh`, `okf-check.sh`). All emit JSON or markdown, follow a uniform exit-code contract, and degrade gracefully when their input source is unavailable.
 
 ---
 

bin/README.md

@@ -44,6 +44,19 @@ contracts — see `hotspot-rank.sh`, `cycle-detect.sh`, `mermaid-from-graph.sh`,
 and `verify-graph-binary.sh`. The shared wrappers (`memory_cli`,
 `memory_ensure_index`, `memory_project_for_repo`) live in `_lib.sh`.
 
+## Snapshot artifacts
+
+`scripts/tools/graph-snapshot.sh` writes a small, committed, PR-reviewable snapshot under `<repo>/draft/graph/`:
+
+| Artifact | Content |
+|----------|---------|
+| `schema.yaml` | Engine + project metadata, node/edge counts, artifact list (gates graph use). |
+| `architecture.json` | `get_architecture(all)`: node labels, edge types, languages, packages (fan-in/out), entry points, routes, hotspots. |
+| `hotspots.jsonl` | Fan-in-ranked symbols, one JSON object per line. |
+| `module-deps.mermaid` | File co-change coupling diagram. |
+| `proto-map.mermaid` | Detected service-route diagram. |
+| `okf/` | Open Knowledge Format v0.1 bundle (`index.md` + cross-linked `modules/<name>.md`), emitted by default — a portable markdown mirror of the graph. Validate with `okf-check.sh`. |
+
 ## Offline / air-gapped distributions
 
 To ship the engine in-tree, place the binary at `bin/<os>-<arch>/codebase-memory-mcp` (resolution step 4). This is optional and not the default; the managed fetch is preferred.

core/methodology.md

@@ -30,7 +30,7 @@ Draft solves this through **Context-Driven Development**: structured documents t
 - [Command Workflows](#command-workflows)
   - [/draft:init](#draftinit--initialize-project)
   - [/draft:plan](#draftplan--planning-orchestrator)
-  - [/draft:index](#draftindex--monorepo-service-index)
+  - [Monorepo Support (via /draft:init)](#monorepo-support-via-draftinit)
   - [/draft:new-track](#draftnew-track--create-feature-track)
   - [/draft:implement](#draftimplement--execute-tasks)
   - [/draft:status](#draftstatus--show-progress)
@@ -405,7 +405,7 @@ Draft auto-classifies the project:
 - **Brownfield (existing codebase):** Detected by the presence of `package.json`, `requirements.txt`, `go.mod`, `Cargo.toml`, `src/`, or git history with commits. Draft scans the existing stack and pre-fills `tech-stack.md`.
 - **Greenfield (new project):** Empty or near-empty directory. Developer provides all context through dialogue.
 - **Mature high-context brownfield:** Projects with strong existing agent-optimized docs (CLAUDE.md, INVARIANTS.md, ADRs, etc.) now receive an early Context Quality Audit, graph fidelity declaration, and explicit Relationship/Gaps sections so the generated architecture.md acts as graph-primary overlay rather than duplicative prose.
-- **Monorepo:** Detected by `lerna.json`, `pnpm-workspace.yaml`, `nx.json`, `turbo.json`, or multiple package manifests in child directories. Suggests `/draft:index` instead.
+- **Monorepo:** Detected by `lerna.json`, `pnpm-workspace.yaml`, `nx.json`, `turbo.json`, or multiple package manifests in child directories. `/draft:init` is scope-aware — run it at the root for whole-repo context (sparse root map + the code-graph spine), or inside a sub-module to generate detailed module context that links up to the root graph. See **Monorepo Support (via /draft:init)** below.
 
 #### Initialization Sequence
 
@@ -499,32 +499,31 @@ The parent command should move planning forward rather than listing options.
 
 ---
 
-### `/draft:index` — Monorepo Service Index
+### Monorepo Support (via `/draft:init`)
 
-Aggregates Draft context from multiple services in a monorepo into unified root-level documents. Designed for organizations with multiple services, each with their own `draft/` context.
+There is no separate index command — `/draft:init` is the single, scope-aware entry point. The same command behaves differently by where it is run, so a monorepo needs no special tooling.
 
-#### What It Does
+#### Root init (run at the repo root)
 
-1. **Scans** immediate child directories for services (detects `package.json`, `go.mod`, `Cargo.toml`, etc.)
-2. **Reads** each service's `draft/product.md`, `draft/.ai-context.md` (or legacy `draft/architecture.md`), `draft/tech-stack.md`
-3. **Synthesizes** root-level documents:
+1. **Builds the whole-repo code-graph spine** — `graph-init.sh` indexes every file at every depth into one unified graph and writes the committed `draft/graph/` snapshot (the structural source of truth).
+2. **Generates a sparse root map** (not deep per-module prose), aggregating the children into root-level documents:
    - `draft/service-index.md` — Service registry with status, tech, and links
-   - `draft/dependency-graph.md` — Inter-service dependency topology
+   - `draft/dependency-graph.md` — Inter-service dependency topology (from the graph)
    - `draft/tech-matrix.md` — Technology distribution across services
-   - `draft/product.md` — Synthesized product vision (if not exists)
-   - `draft/.ai-context.md` — System-of-systems architecture view
-   - `draft/tech-stack.md` — Org-wide technology standards
+   - `draft/architecture.md` — High-level system map linking *down* to each module's `draft/.ai-context.md`
+   - `draft/.ai-context.md` / `draft/.ai-profile.md` — Condensed system-of-systems views
 
-#### Arguments
+#### Module init (run inside a sub-module)
 
-- `init-missing` — Run `/draft:init` on services that lack a `draft/` directory
-- `bughunt [dir1 dir2 ...]` — Run `/draft:bughunt` across subdirectories with `draft/` folders. If no directories specified, auto-discovers all subdirectories with `draft/`. Generates summary report at `draft-index-bughunt-summary.md`.
+1. **Ensures the root spine exists first** (builds it if missing), then builds the module's own `draft/graph/` snapshot.
+2. **Writes `draft/graph/root-link.json`** — a pointer up to the root graph so the module has full cross-module understanding regardless of where init ran.
+3. **Generates the detailed module reference** (full 10-section `architecture.md` for the subtree). Use `--module-only` to skip touching the root (link marked `pending`).
 
 #### When to Use
 
-- After running `/draft:init` on individual services
-- After adding or removing services from the monorepo
-- Periodically to refresh cross-service context
+- After cloning or adding a service — run `/draft:init` in it (auto-links to the root spine)
+- At the root after services change — refresh the whole-repo graph + sparse root map
+- `/draft:init --graph-only` to (re)build just the code-graph knowledge memory, no markdown
 
 ---
 

core/shared/condensation.md

@@ -16,7 +16,7 @@ This is a self-contained, callable procedure for generating `draft/.ai-context.m
 
 Any skill that mutates `architecture.md` should execute this subroutine afterward to keep the derived context files in sync.
 
-**Called by:** `/draft:init`, `/draft:init refresh`, `/draft:implement`, `/draft:decompose`, `/draft:coverage`, `/draft:index`
+**Called by:** `/draft:init`, `/draft:init refresh`, `/draft:implement`, `/draft:decompose`, `/draft:coverage`
 
 ### Inputs
 

core/shared/draft-context-loading.md

@@ -38,7 +38,7 @@ This matrix is the **single source of truth** for which Layer 0.5 files load per
 
 | Command type | Commands | Guardrails loaded |
 |---|---|---|
-| **Read-only** | `/draft:status`, `/draft:standup`, `/draft:tour`, `/draft:index`, `/draft:coverage` | **none** |
+| **Read-only** | `/draft:status`, `/draft:standup`, `/draft:tour`, `/draft:coverage` | **none** |
 | **Spec / Plan** | `/draft:new-track`, `/draft:decompose`, `/draft:adr`, `/draft:testing-strategy`, `/draft:documentation` | `design-norms.md` only (architecture-shaped rules) |
 | **Code-touching (generation)** | `/draft:implement`, `/draft:debug`, `/draft:change`, `/draft:revert` | `code-quality.md` + `security.md` + `secure-patterns.md` + `language-standards.md` (detected stack) |
 | **Review** | `/draft:review`, `/draft:quick-review`, `/draft:deep-review`, `/draft:assist-review`, `/draft:bughunt`, `/draft:tech-debt` | `review-checks.md` + `security.md` + `language-standards.md` (detected stack); deep-review also loads `code-quality.md` + `design-norms.md` |
@@ -75,9 +75,11 @@ If `draft/graph/schema.yaml` exists, the project has automated graph analysis da
 | `draft/graph/architecture.json` | Node labels, edge types, languages, packages (fan-in/out), entry points, routes, hotspots | JSON |
 | `draft/graph/hotspots.jsonl` | Fan-in-ranked symbols, one object per line: `{id, name, fanIn}` | JSONL |
 
+The snapshot also includes `draft/graph/okf/` — an Open Knowledge Format v0.1 bundle (`index.md` + `modules/*.md`) emitted by default. It is a portable mirror of the graph, not an always-load target.
+
 Note: `.ai-context.md` embeds a condensed graph summary (`GRAPH:MODULES`, `GRAPH:HOTSPOTS`, `GRAPH:CYCLES`) for first-pass structural ground truth. `architecture.json` is authoritative for deep structure.
 
-Note: The canonical embedded mermaid diagrams are in architecture.md injection slots (`<!-- GRAPH:module-deps:START/END -->`, `<!-- GRAPH:proto-map:START/END -->`), refreshed by `draft:index`. For current data, regenerate via `scripts/tools/mermaid-from-graph.sh`.
+Note: The canonical embedded mermaid diagrams are in architecture.md injection slots (`<!-- GRAPH:module-deps:START/END -->`, `<!-- GRAPH:proto-map:START/END -->`), refreshed by `draft:init`. For current data, regenerate via `scripts/tools/mermaid-from-graph.sh`.
 
 **Live structural queries** (run on demand — no per-language index files; the engine's model is unified):