@drafthq/draft 2.8.3 → 3.0.0

package/scripts/tools/okf-emit.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env bash
+# okf-emit.sh — emit an Open Knowledge Format (OKF) bundle from a graph snapshot.
+#
+# OKF is an open, vendor-neutral spec (Google Cloud): a directory of markdown
+# files with YAML frontmatter, one file per concept, where the file path is the
+# concept's identity and concepts cross-link with normal markdown links. The
+# only required frontmatter field is `type`. This makes Draft's knowledge graph
+# portable — consumable by any OKF reader (visualizers, catalogs, other agents).
+# https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing
+#
+# Reads a graph snapshot's architecture.json and writes a conformant bundle:
+#   index.md            type: Repository — bundle root + progressive disclosure
+#   modules/<slug>.md   type: Module     — one concept per package, cross-linked
+#
+# Degrades gracefully: with no packages/boundaries in the snapshot it still emits
+# index.md (counts, languages, hotspots) and an empty modules/ directory.
+#
+# Usage: scripts/tools/okf-emit.sh [--repo DIR] [--snapshot DIR] [--out DIR]
+# Exit codes: 0 OK, 1 invocation error, 2 snapshot/architecture.json unavailable.
+set -euo pipefail
+
+REPO="."
+SNAPSHOT=""
+OUT=""
+
+usage() {
+    cat <<'EOF'
+okf-emit.sh — emit an Open Knowledge Format (OKF) bundle from a graph snapshot.
+
+Usage:
+  scripts/tools/okf-emit.sh [--repo DIR] [--snapshot DIR] [--out DIR]
+
+Flags:
+  --repo DIR      Repository root (default: cwd).
+  --snapshot DIR  Snapshot dir holding architecture.json (default: <repo>/draft/graph).
+  --out DIR       Bundle output dir (default: <snapshot>/okf).
+  --help          Show this help.
+
+Writes index.md + modules/<slug>.md (OKF v0.1). Exit 0 on success, 2 when no
+architecture.json is available (nothing emitted).
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --repo) REPO="$2"; shift 2;;
+        --snapshot) SNAPSHOT="$2"; shift 2;;
+        --out) OUT="$2"; shift 2;;
+        --help|-h) usage; exit 0;;
+        -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
+        *) echo "Unexpected arg: $1" >&2; usage >&2; exit 1;;
+    esac
+done
+
+[[ -d "$REPO" ]] || { echo "ERROR: --repo '$REPO' is not a directory" >&2; exit 1; }
+REPO_ABS="$(cd "$REPO" && pwd)"
+SNAP="${SNAPSHOT:-$REPO_ABS/draft/graph}"
+ARCH="$SNAP/architecture.json"
+OUT="${OUT:-$SNAP/okf}"
+
+command -v jq >/dev/null 2>&1 || { echo "jq required for OKF emit" >&2; exit 2; }
+[[ -f "$ARCH" ]] || { echo "no architecture.json at $ARCH — nothing to emit" >&2; exit 2; }
+
+# slugify a concept name into a filesystem- and link-safe identifier.
+slug() {
+    local s
+    s="$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]' \
+        | sed -e 's#[^a-z0-9]\{1,\}#-#g' -e 's#^-##' -e 's#-$##')"
+    [[ -n "$s" ]] || s="module"
+    printf '%s' "$s"
+}
+
+# escape a value for a YAML double-quoted scalar.
+yesc() {
+    local s="$1"
+    s="${s//\\/\\\\}"
+    s="${s//\"/\\\"}"
+    printf '%s' "$s"
+}
+
+TS="$(date -Iseconds 2>/dev/null || date)"
+PROJECT="$(jq -r '.project // "repository"' "$ARCH")"
+TOTAL_NODES="$(jq -r '.total_nodes // 0' "$ARCH")"
+TOTAL_EDGES="$(jq -r '.total_edges // 0' "$ARCH")"
+
+PKGS="$(jq -r '.packages[]? | [.name, (.node_count//0), (.fan_in//0), (.fan_out//0)] | @tsv' "$ARCH")"
+BOUNDS="$(jq -r '.boundaries[]? | [.from, .to, (.call_count//0)] | @tsv' "$ARCH")"
+
+mkdir -p "$OUT/modules"
+
+# --- One concept file per package, cross-linked via boundaries ---
+PKG_COUNT=0
+if [[ -n "$PKGS" ]]; then
+    while IFS=$'\t' read -r name nc fi fo; do
+        [[ -n "$name" ]] || continue
+        PKG_COUNT=$((PKG_COUNT + 1))
+        s="$(slug "$name")"
+        {
+            printf -- '---\n'
+            printf 'type: Module\n'
+            printf 'title: "%s"\n' "$(yesc "$name")"
+            printf 'description: "Code module %s: %s nodes, fan-in %s, fan-out %s."\n' \
+                "$(yesc "$name")" "$nc" "$fi" "$fo"
+            printf 'tags: [module, knowledge-graph]\n'
+            printf 'timestamp: "%s"\n' "$TS"
+            printf -- '---\n\n'
+            printf '# %s\n\n' "$name"
+            printf 'Structural module derived from the knowledge graph. Nodes: %s, fan-in: %s, fan-out: %s.\n' \
+                "$nc" "$fi" "$fo"
+
+            # Depends on (outbound boundaries)
+            outs="$(awk -F'\t' -v n="$name" '$1==n && $2!="" {print $2"\t"$3}' <<< "$BOUNDS")"
+            if [[ -n "$outs" ]]; then
+                printf '\n## Depends on\n\n'
+                while IFS=$'\t' read -r to cc; do
+                    [[ -n "$to" ]] || continue
+                    printf -- '- [%s](%s.md) — %s call(s)\n' "$to" "$(slug "$to")" "$cc"
+                done <<< "$outs"
+            fi
+
+            # Depended on by (inbound boundaries)
+            ins="$(awk -F'\t' -v n="$name" '$2==n && $1!="" {print $1"\t"$3}' <<< "$BOUNDS")"
+            if [[ -n "$ins" ]]; then
+                printf '\n## Depended on by\n\n'
+                while IFS=$'\t' read -r from cc; do
+                    [[ -n "$from" ]] || continue
+                    printf -- '- [%s](%s.md) — %s call(s)\n' "$from" "$(slug "$from")" "$cc"
+                done <<< "$ins"
+            fi
+        } > "$OUT/modules/$s.md"
+    done <<< "$PKGS"
+fi
+
+# --- Bundle index.md (reserved file: no frontmatter, §6 progressive disclosure) ---
+{
+    printf '# %s\n\n' "$PROJECT"
+    printf 'Open Knowledge Format bundle generated by Draft from the codebase-memory-mcp knowledge graph. Nodes: %s, edges: %s, modules: %s.\n' \
+        "$TOTAL_NODES" "$TOTAL_EDGES" "$PKG_COUNT"
+
+    langs="$(jq -r '.languages[]? | "* \(.language) - \(.file_count) file(s)"' "$ARCH")"
+    if [[ -n "$langs" ]]; then
+        printf '\n# Languages\n\n%s\n' "$langs"
+    fi
+
+    if [[ "$PKG_COUNT" -gt 0 ]]; then
+        printf '\n# Modules\n\n'
+        while IFS=$'\t' read -r name nc fi fo; do
+            [[ -n "$name" ]] || continue
+            printf -- '* [%s](modules/%s.md) - %s nodes, fan-in %s, fan-out %s\n' \
+                "$name" "$(slug "$name")" "$nc" "$fi" "$fo"
+        done < <(printf '%s\n' "$PKGS" | sort)
+    fi
+
+    hot="$(jq -r '.hotspots[:10][]? | "* \(.name) - fan-in \(.fan_in)"' "$ARCH")"
+    if [[ -n "$hot" ]]; then
+        printf '\n# Top hotspots\n\n%s\n' "$hot"
+    fi
+} > "$OUT/index.md"
+
+echo "OKF bundle written to $OUT (modules=$PKG_COUNT)"
+exit 0

package/scripts/tools/skill-caps.conf

@@ -19,6 +19,5 @@ status       1300
 bughunt     1200
 new-track   1100
 review      1000
-index        900
 implement    900
 decompose    700

package/skills/GRAPH.md

@@ -55,7 +55,6 @@ graph TD
     subgraph "Architecture"
         decompose["/draft:decompose"]
         adr["/draft:adr"]
-        index["/draft:index"]
         tech-debt["/draft:tech-debt"]
         impact["/draft:impact"]
     end
@@ -96,7 +95,6 @@ graph TD
     init --> learn
     init --> adr
     init --> bughunt
-    init --> index
     init --> status
     init --> deep-review
     init --> debug
@@ -124,7 +122,6 @@ graph TD
     discover --> coverage
     discover --> testing-strategy
     discover --> learn
-    discover --> index
     discover --> tour
     discover --> impact
     discover --> assist-review
@@ -178,8 +175,7 @@ graph TD
     impact -.->|reads graph| new-track
     impact -.->|reads graph| implement
 
-    %% Monorepo chain
-    init -.->|per-service| index
+    %% Monorepo: init is scope-aware — root build + module→root graph link (no separate index command)
 ```
 
 ## Dependency Matrix
@@ -193,7 +189,7 @@ graph TD
 | `implement` | init, new-track | review (triggers at phase boundaries) | Modifies source code; regenerates .ai-context.md |
 | `review` | init, new-track | implement (called at phase boundaries) | review-report-latest.md |
 | `quick-review` | init | review (fast alternative) | quick-review-report.md |
-| `bughunt` | init | review (optional), index (optional), jira (optional) | bughunt-report-latest.md |
+| `bughunt` | init | review (optional), jira (optional) | bughunt-report-latest.md |
 | `deep-review` | init | -- | deep-review audit report |
 | `coverage` | init, new-track | -- | Regenerates .ai-context.md |
 | `testing-strategy` | init | coverage (informs), bughunt (informs) | testing-strategy.md |
@@ -248,7 +244,8 @@ deep-review ──→ tech-debt ──→ new-track (prioritized items)
 
 ### Monorepo Flow
 ```
-init (per-service) → index (at root) → aggregated context
+init (root)       → whole-repo code-graph spine + sparse root map
+init (sub-module) → module snapshot + root-link.json → cross-module context via the root spine
 ```
 
 ### Quality Audit Flow
@@ -280,15 +277,15 @@ init → learn → (updates guardrails.md)
 
 | Subroutine | Defined In | Called By |
 |------------|-----------|----------|
-| Condensation Subroutine (.ai-context.md regeneration) | `core/shared/condensation.md` | implement, decompose, coverage, index |
+| Condensation Subroutine (.ai-context.md regeneration) | `core/shared/condensation.md` | implement, decompose, coverage |
 | Standard File Metadata (YAML frontmatter) | `init` | All skills that generate draft/ files |
 | Three-Stage Review | `review` | implement (at phase boundaries) |
-| Signal Classification | `init` | init refresh, index (future) |
+| Signal Classification | `init` | init refresh |
 | Pattern Learning | `core/shared/pattern-learning.md` | learn, bughunt, review, deep-review (updates guardrails.md) |
 | Context Loading | `core/shared/draft-context-loading.md` | All skills requiring draft/ context |
 | Cross-Skill Dispatch | `core/shared/cross-skill-dispatch.md` | bughunt, deep-review, implement, review |
 | Jira Sync | `core/shared/jira-sync.md` | bughunt, review, implement (when ticket linked) |
-| Graph Query | `core/shared/graph-query.md` | init, implement, bughunt, review, debug, decompose, index, impact |
+| Graph Query | `core/shared/graph-query.md` | init, implement, bughunt, review, debug, decompose, impact |
 | Graph Mermaid | `scripts/tools/mermaid-from-graph.sh` | init (injects module-deps + proto-map into architecture.md) |
 
 ## Artifact Flow

package/skills/bughunt/SKILL.md

@@ -94,6 +94,19 @@ Use track context to:
 
 If no Draft context exists, proceed with code-only analysis.
 
+## Multi-Directory Mode (monorepo)
+
+`/draft:bughunt` can sweep multiple sub-projects in one run — useful at a monorepo root. Trigger it with an explicit directory list (`bughunt <dir1> <dir2> ...`) or no list (auto-discover).
+
+1. **Resolve targets:**
+   - **Explicit list** → use the given directories; verify each exists; skip (with a warning) any that lack a `draft/` directory.
+   - **Auto-discover** → immediate child directories containing a `draft/` folder, excluding `node_modules/`, `vendor/`, `.git/`, `draft/`, and dotfiles.
+2. **Run sequentially** (not in parallel — avoids context conflicts): for each target, run the full single-target bug hunt below scoped to that directory. Each writes its own `<dir>/draft/bughunt-report-latest.md`.
+3. **Aggregate** into `draft/bughunt-summary.md` at the invocation root: a table of `dir | Critical | High | Medium | Low | Total | report link`, a grand total, and a "directories with Critical issues" callout.
+4. Report skipped directories (no `draft/`) and suggest running `/draft:init` in them first.
+
+For a single target (the common case), skip this section and proceed.
+
 ## Dimension Applicability Check
 
 Before analyzing all 14 dimensions, determine which apply to this codebase:

package/skills/discover/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: discover
-description: "Primary router for discovery, debugging, investigation, quality, and exploration workflows. Analyzes user intent and dispatches to debug, bughunt, quick-review, deep-review, coverage, testing-strategy, learn, index, tour, impact, assist-review. The recommended entry point for any 'find out', 'check', 'review', or 'investigate' request."
+description: "Primary router for discovery, debugging, investigation, quality, and exploration workflows. Analyzes user intent and dispatches to debug, bughunt, quick-review, deep-review, coverage, testing-strategy, learn, tour, impact, assist-review. The recommended entry point for any 'find out', 'check', 'review', or 'investigate' request."
 ---
 
 # Discover - Investigation & Quality Router
@@ -13,7 +13,6 @@ description: "Primary router for discovery, debugging, investigation, quality, a
 - Code quality reviews (lightweight to exhaustive to architectural)
 - Coverage analysis and test strategy design
 - Discovering and codifying project conventions
-- Monorepo indexing and context aggregation
 - Project tours, impact analysis, or reviewer assistance
 
 ## Routing Logic
@@ -29,7 +28,6 @@ Strong keyword and phrase matching with fallback to a menu when intent is broad
 | coverage, code coverage, test coverage report | `/draft:coverage` | Coverage measurement and gap report |
 | test strategy, testing plan, coverage targets, pyramid | `/draft:testing-strategy` | Test approach design |
 | learn patterns, discover conventions, update guardrails, anti-patterns | `/draft:learn` | Pattern mining + guardrail evolution |
-| index services, aggregate context, monorepo index | `/draft:index` | Monorepo service context aggregation |
 | tour, walkthrough, onboard me, getting started tour | `/draft:tour` | Guided interactive project tour |
 | blast radius, code impact, affected modules, downstream callers | `/draft:review` or `scripts/tools/graph-impact.sh` | Graph-derived blast-radius before merge |
 | impact, delivery telemetry, track analytics, CDD effectiveness | `/draft:impact` | Project-wide track delivery telemetry |
@@ -55,7 +53,7 @@ User: "learn the coding patterns in this repo and tighten guardrails"
 
 User: "index the monorepo so agents see all services"
 
-→ dispatches to `/draft:index --init-missing`
+→ Monorepo context is a foundation task, not a discover route: run `/draft:init` at the repo root (it builds the whole-repo code graph + a sparse root map linking each module). Running `/draft:init` inside a sub-module links that module up to the same root graph.
 
 ## Auto-Chains & Recommendations
 

package/skills/draft/SKILL.md

@@ -39,7 +39,7 @@ The 5 router commands provide intent-based dispatch into the 20+ specialist comm
 | `/draft:plan` | Planning & architecture | new-track, decompose, adr, tech-debt, change |
 | `/draft:ops` | Operations & lifecycle | deploy-checklist, incident-response, standup, status, revert |
 | `/draft:docs` | Authoring | documentation |
-| `/draft:discover` | Investigation & quality | debug, bughunt, quick/deep-review, coverage, testing-strategy, learn, index, tour, impact, assist-review |
+| `/draft:discover` | Investigation & quality | debug, bughunt, quick/deep-review, coverage, testing-strategy, learn, tour, impact, assist-review |
 | `/draft:jira` | Jira integration (preview, create, review) | - |
 
 ### Specialist Commands (leaf skills, invoked via routers or directly)
@@ -74,7 +74,7 @@ These commands remain available for targeted, specialist execution outside paren
 
 #### 4. Setup & Documentation
 * `/draft` - Display this command overview and help reference
-* `/draft:index` - Aggregate multi-service context in monorepo structures
+* `/draft:init` - Single scope-aware entry point: builds the root-first code graph (`draft/graph/`) and project context; run at the repo root or inside any sub-module (monorepo context comes from running it at root)
 * `/draft:discover` - Phase 0 code-spike report (hotspots, mode flags, open questions) before spec freeze
 * `/draft:documentation` - Generate structured codebase documentation (API, Onboarding, Runbooks)
 * `/draft:tech-debt` - Audit technical debt across 6 key dimensions

package/skills/draft/intent-mapping.md

@@ -33,5 +33,6 @@ Draft commands can be invoked using natural language. If you describe your goal
 | "write docs", "create readme", "api documentation" | `/draft:documentation` | Generate professional, structured docs |
 | "preview jira", "export jira issues", "jira draft" | `/draft:jira-preview` | Generate Jira markdown export from plan |
 | "create jira", "push to jira board" | `/draft:jira-create` | Create actual Jira issues via MCP integrations |
-| "index services", "aggregate context", "monorepo setup" | `/draft:index` | Aggregate multi-service context at the root |
-| "build graph", "refresh graph", "rebuild the knowledge graph", "index this repo's structure" | `/draft:graph` | Initialize/refresh the `draft/graph/` snapshot (optionally `draft graph <path>`) |
+| "index services", "aggregate context", "monorepo setup" | `/draft:init` | Single entry point — run at the repo root to build the whole-repo code graph + sparse root map; run in a sub-module to link up to it |
+| "build the code graph", "index this repo's structure", "graph memory only" | `/draft:init --graph-only` | Scope-aware, root-first code-graph build with no markdown |
+| "build graph", "refresh graph", "rebuild the knowledge graph" | `/draft:graph` | Narrow refresh of the `draft/graph/` snapshot for one repo (optionally `draft graph <path>`) |

package/skills/graph/SKILL.md

@@ -5,7 +5,7 @@ description: Initialize or refresh the knowledge-graph snapshot for a repository
 
 # Draft Graph
 
-Initialize or refresh the `draft/graph/` knowledge-graph snapshot for a repository. This is the narrow "give me a fresh structural graph" command — it does **not** generate `architecture.md`/`.ai-context.md` (that is `/draft:init`) and does **not** re-inject doc diagram slots (that is `/draft:index`).
+Initialize or refresh the `draft/graph/` knowledge-graph snapshot for a single repository. This is the narrow "give me a fresh structural graph" command — it does **not** generate `architecture.md`/`.ai-context.md` and does **not** re-inject doc diagram slots (both are `/draft:init`). For scope-aware, root-first graph memory across a monorepo (root spine + module→root links), use `/draft:init --graph-only`.
 
 ## Red Flags - STOP if you're:
 
@@ -55,7 +55,7 @@ echo "Engine: $ENGINE"
 
 ## Step 3: Build / refresh the snapshot
 
-One call resolves the engine, indexes the repo (incrementally on refresh), and writes the committed snapshot under `<repo>/draft/graph/` — `schema.yaml`, `architecture.json`, `hotspots.jsonl`, `module-deps.mermaid`, `proto-map.mermaid`.
+One call resolves the engine, indexes the repo (incrementally on refresh), and writes the committed snapshot under `<repo>/draft/graph/` — `schema.yaml`, `architecture.json`, `hotspots.jsonl`, `module-deps.mermaid`, `proto-map.mermaid`, and an Open Knowledge Format bundle under `okf/` (a portable, vendor-neutral markdown mirror of the graph — `index.md` + one cross-linked `modules/<name>.md` concept per module).
 
 ```bash
 scripts/tools/graph-snapshot.sh --repo "$REPO_ABS"
@@ -92,7 +92,7 @@ Present a concise summary:
 
 Then point the user at the natural next steps:
 
-- To re-inject the refreshed diagrams/hotspot tables into `architecture.md` / `.ai-context.md`: run `/draft:index`.
+- To re-inject the refreshed diagrams/hotspot tables into `architecture.md` / `.ai-context.md`: run `/draft:init refresh` (or `/draft:init --graph-only` to rebuild just the graph memory).
 - For a first-time full context bootstrap (architecture + profiles): run `/draft:init`.
 
 ## Graceful Degradation

package/skills/init/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: init
-description: "Initialize Draft project context for Context-Driven Development. Run once per project to create product.md, tech-stack.md, workflow.md, tracks.md, architecture.md (brownfield), .ai-context.md (derived), and .ai-profile.md (ultra-compact profile). Always performs deep analysis. Use when the user asks to 'init draft', 'set up Draft for this project', 'bootstrap context', or says 'start using Draft', 'I want to use Draft here'."
+description: "Initialize Draft project context for Context-Driven Development — the single, scope-aware entry point (works at the repo root or inside any sub-module; no separate index command). Builds the root-first code-graph knowledge memory (draft/graph/, with a module→root link) and creates product.md, tech-stack.md, workflow.md, tracks.md, architecture.md (brownfield), .ai-context.md (derived), and .ai-profile.md. Supports --graph-only (graph memory only, no markdown) and --module-only. Use when the user asks to 'init draft', 'set up Draft for this project', 'bootstrap context', 'build the code graph', or says 'start using Draft', 'I want to use Draft here'."
 ---
 
 # Draft Init
@@ -193,18 +193,24 @@ synced_to_commit: "a1b2c3d4e5f6789012345678901234567890abcd"
 
 Check for arguments:
 - `refresh`: Update existing context without full re-init
-- `index`: Route to `/draft:index`
+- `--graph-only`: Build/refresh only the code-graph knowledge memory (no markdown) — see the fast path below
+- `--module-only`: When run in a sub-module, do not touch the root graph (the module→root link is marked `pending`)
 - `discover`: Route to `/draft:discover`
 
+> `/draft:init` is the **single entry point** for building context — there is no separate `index` command. Init is scope-aware (root vs sub-module); see **Scope Detection** below.
+
 ### Route Explicit Modes Before Initialization
 
 If the user explicitly invoked a specialist mode, route directly:
 
-- `/draft:init index` → follow `/draft:index`
 - `/draft:init discover` → follow `/draft:discover`
 
 Explicit mode always wins. Do not perform standard initialization if an explicit mode is requested.
 
+### `--graph-only` Fast Path
+
+If `--graph-only` is present, run **Step 1.4** (scope-aware, root-first graph build via `graph-init.sh`) and **STOP** — generate no `architecture.md` or other markdown. This is the fast path to (re)build the whole-repo code-graph knowledge memory; in a sub-module it also ensures the root spine exists and writes the module→root link. This path is allowed even when `draft/` already exists (it refreshes the graph in place — no `draft.tmp/` staging, no overwrite prompt).
+
 ### Standard Init Check
 
 ```bash
@@ -236,16 +242,16 @@ mv draft.tmp/ draft/
 
 > **Forced re-init:** If `draft/` exists and the user explicitly requests a fresh init (not refresh), confirm with user before removing the existing `draft/` directory.
 
-### Monorepo Detection
+### Scope Detection (root vs sub-module)
+
+`/draft:init` is the single entry point and is **scope-aware** — it works the same whether run at the repository root or inside a sub-module. The root-first graph behavior is handled mechanically by `graph-init.sh` in Step 1.4; you do not detect the monorepo shape by hand.
 
-Check for monorepo indicators:
-- Multiple `package.json` / `go.mod` / `Cargo.toml` in child directories
-- `lerna.json`, `pnpm-workspace.yaml`, `nx.json`, or `turbo.json` at root
-- `packages/`, `apps/`, `services/` directories with independent manifests
+Resolve **ROOT** = nearest ancestor (above the current dir) containing `draft/` → else the git toplevel → else the current dir. Then:
 
-If monorepo detected:
-- Announce: "Detected monorepo structure. Consider using `/draft:init index` at root level to aggregate service context, or run `/draft:init` within individual service directories."
-- Ask user to confirm: initialize here (single service) or abort (use /draft:init index instead)
+- **Root init** (current dir IS root): the graph step builds the whole-repo spine. The generated markdown is a **sparse, high-level system map** that links *down* to each module's context — a large root must not carry deep per-module prose. (See "Root vs Module Markdown" below.)
+- **Module init** (current dir is BELOW root): the graph step ensures the root spine exists first (building it if missing), builds the module snapshot, and writes `draft/graph/root-link.json` (module→root). The generated markdown is the **detailed** module reference produced by the standard deep analysis in this skill.
+
+Use `--module-only` to skip touching the root (the link is marked `pending` and resolves when root init later runs). With no git and no ancestor `draft/`, init treats the current dir as root (module-local, no traversal).
 
 ### Migration Detection
 
@@ -478,20 +484,25 @@ If **Greenfield**: skip to Step 2 (Product Definition).
 
 **CRITICAL ORDERING**: Phase 0 (this step) MUST complete before writing any section of architecture.md. The graph provides: (a) exhaustive module list, (b) hotspot-ranked module priority, (c) authoritative proto API surface, (d) mermaid diagrams ready for slot injection, (e) codebase tier for .ai-context.md budget.
 
-### 1. Build the graph snapshot
+### 1. Build the graph (scope-aware, root-first)
 
-The knowledge-graph engine is `codebase-memory-mcp`, resolved by `scripts/tools/_lib.sh:find_memory_bin` (`DRAFT_MEMORY_BIN` > PATH > `~/.cache/draft/bin` > vendored `bin/<arch>/`). `draft install` fetches it (skip with `--no-graph`); install manually with `scripts/fetch-memory-engine.sh`. Set `DRAFT_MEMORY_DISABLE=1` to opt out.
+The knowledge-graph engine `codebase-memory-mcp` is Draft's **default** capability tier — deterministic call/dependency traversal beats grep/glob. It is normally already installed by `draft install`; `graph-init.sh` fetches it as a fallback when missing (blocking — download/index time is accepted, never gated on cost). Resolution: `scripts/tools/_lib.sh:find_memory_bin` (`DRAFT_MEMORY_BIN` > PATH > `~/.cache/draft/bin` > vendored `bin/<arch>/`). Set `DRAFT_MEMORY_DISABLE=1` to opt out.
 
-One command resolves the engine, indexes the repo, and writes the committed snapshot under `draft/graph/`:
+One command resolves ROOT, ensures the engine, builds the whole-repo spine, and — in a sub-module — builds the module snapshot and writes the `root-link.json` pointer:
 
 ```bash
-if scripts/tools/graph-snapshot.sh --repo .; then
-    echo "Graph snapshot written to draft/graph/ (schema.yaml, architecture.json, hotspots.jsonl, *.mermaid)."
+# Add --module-only to skip touching the root (link marked "pending").
+if scripts/tools/graph-init.sh --scope .; then
+    echo "Graph memory ready under draft/graph/ (the root spine is the structural source of truth)."
 else
-    echo "Graph engine unavailable — skipping automated graph analysis. Downstream skills degrade gracefully."
+    echo "Graph engine unavailable — proceeding with degraded manual discovery. Downstream skills degrade gracefully."
 fi
 ```
 
+- **Root init** writes `<root>/draft/graph/` — the committed, git-tracked whole-repo memory.
+- **Module init** also writes `draft/graph/root-link.json` (module→root); follow `root_graph` for cross-module understanding. The root spine is rebuilt first so the link is live.
+- Only `draft/graph/` is committed. The engine's `~/.cache` index is a disposable accelerator — never commit it; it rebuilds deterministically from source.
+
 Optionally record which engine was selected (usage-report contract):
 
 ```bash
@@ -500,7 +511,7 @@ scripts/tools/verify-graph-binary.sh --repo . --json 2>/dev/null || true
 
 See `core/shared/graph-query.md` and `bin/README.md` for the query contract and engine resolution.
 
-If the snapshot succeeds, `draft/graph/` is populated and later steps consume the always-load artifacts + injection slots.
+If the build succeeds, `draft/graph/` is populated and later steps consume the always-load artifacts + injection slots.
 
 ### 2. If graph build succeeds, load the always-load artifacts
 
@@ -1008,11 +1019,19 @@ The document is:
 
 **Full details, per-section guidance, provenance rules, and examples** live in:
 - `core/templates/architecture.md` (the source of truth for the 10 sections + Generation Contract)
-- `docs/research/proposed-graph-backed-architecture-template.md` (design rationale and fidelity rules)
 - `references/architecture-spec.md` (deprecated legacy notes — **10-section template wins on any conflict**)
 
 There is no legacy 28-section structure and no volume targets. The template itself is the contract.
 
+### Root vs Module Markdown (scope asymmetry)
+
+The depth of generated markdown depends on the scope resolved in **Scope Detection**:
+
+- **Module init** (current dir below root): generate the **full, detailed** 10-section `architecture.md` for the module subtree — the standard deep analysis described in this skill. This is where engineering depth lives.
+- **Root init** (current dir IS root, monorepo): generate a **sparse, high-level system map**, not deep per-module prose. The root `architecture.md` covers: system overview + Graph Health Dashboard (from the whole-repo spine), the module catalog with one-line responsibilities and links *down* to each module's `draft/.ai-context.md`, cross-module dependency topology (from `draft/graph/`), shared infrastructure, and system-wide invariants. Defer module internals to the module docs — a large root must not duplicate them. If a module has not been initialized, link it as "not yet initialized — run `/draft:init` there."
+
+The graph is symmetric (root spine + per-module snapshots, linked); only the **prose** is asymmetric. Both consume `draft/graph/`.
+
 **After completing analysis AND passing verification**, write to `draft/architecture.md`. This is the PRIMARY output. Then run the Condensation Subroutine.
 
 ## .ai-context.md Specification
@@ -1588,6 +1607,7 @@ Create `draft/tracks.md` with metadata header:
 
 ```markdown
 ---
+type: TrackIndex
 project: "{PROJECT_NAME}"
 module: "root"
 generated_by: "draft:init"
@@ -1633,6 +1653,23 @@ For **brownfield** projects, run `/draft:learn` (no arguments — full codebase
 
 ## Completion
 
+**Finalize OKF bundle:** After all `draft/` files are written, run the bundle tool
+to (re)generate the Open Knowledge Format root index so the whole `draft/` tree is
+a portable, vendor-neutral OKF bundle. This is the default — no flag required.
+
+```bash
+scripts/tools/okf-bundle.sh --dir draft   # writes the bundle-root draft/index.md
+scripts/tools/okf-check.sh  --dir draft   # OKF v0.1 conformance (advisory, non-fatal)
+```
+
+`okf-bundle.sh` links every concept file present (`.ai-profile.md`, `.ai-context.md`,
+`architecture.md`, `product.md`, `tech-stack.md`, `workflow.md`, `guardrails.md`), the
+tracks, and the graph sub-bundle (`graph/okf/`). Concept `type:` frontmatter comes from
+the templates; `okf-check.sh` validates §9 conformance (frontmatter + `type` on every
+concept; reserved `index.md`/`log.md` structure). It is advisory — report the result,
+do not fail init. Note: operational reports later written into `draft/` (e.g.
+`deep-review-report.md`) are not OKF concepts and will be flagged.
+
 **Finalize run memory:** Update `draft/.state/run-memory.json`:
 - `status`: `"completed"`
 - `completed_at`: current ISO timestamp
@@ -1642,6 +1679,7 @@ For **Brownfield** projects, announce:
 "Draft initialized successfully with comprehensive analysis!
 
 Created:
+- draft/index.md (Open Knowledge Format bundle root — cross-links every concept)
 - draft/.ai-profile.md (20-50 lines — ultra-compact always-injected profile, Tier 0)
 - draft/.ai-context.md (200-400 lines — token-optimized AI context, self-contained, Tier 1)
 - draft/architecture.md (comprehensive human-readable engineering reference, Tier 2)
@@ -1676,6 +1714,7 @@ For **Greenfield** projects, announce:
 "Draft initialized successfully!
 
 Created:
+- draft/index.md (Open Knowledge Format bundle root — cross-links every concept)
 - draft/product.md
 - draft/tech-stack.md
 - draft/workflow.md

package/skills/init/references/architecture-spec.md

@@ -161,14 +161,14 @@ Write the `GRAPH:module-deps` injection slot into architecture.md:
 
 If graph build succeeded (Step 1.4.7 completed), write the populated slot content using the diagram from Step 1.4.7. If filtered (>30 modules), include the filter note. Dashed edges indicate circular dependencies.
 
-If graph binary was not found: write the slot with placeholder body so draft:index can populate it later:
+If graph binary was not found: write the slot with placeholder body so draft:init --graph-only can populate it later:
 ```
 <!-- GRAPH:module-deps:START -->
-[Graph data unavailable — run draft:index to populate after graph binary is installed]
+[Graph data unavailable — run draft:init --graph-only to populate after graph binary is installed]
 <!-- GRAPH:module-deps:END -->
 ```
 
-The slot markers MUST always be written — they are required for draft:index refresh to function.
+The slot markers MUST always be written — they are required for draft:init --graph-only refresh to function.
 
 #### 4.2 Process Lifecycle (or Usage Lifecycle for libraries)
 
@@ -1078,11 +1078,11 @@ If graph build succeeded and proto files exist (Step 1.4.7 completed), write the
 If graph binary was not found or no proto files exist, write the slot with placeholder:
 ```
 <!-- GRAPH:proto-map:START -->
-[Graph data unavailable — run draft:index to populate after graph binary is installed]
+[Graph data unavailable — run draft:init --graph-only to populate after graph binary is installed]
 <!-- GRAPH:proto-map:END -->
 ```
 
-The slot markers MUST always be written — they are required for draft:index refresh to function.
+The slot markers MUST always be written — they are required for draft:init --graph-only refresh to function.
 
 ---