graph

name	graph
description	Initialize or refresh the knowledge-graph snapshot for a repository. Ensures the codebase-memory-mcp engine is present (fetching it if needed), then builds draft/graph/ and reports engine, counts, hotspots, and cycles. Accepts an optional repo path.

Draft Graph

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:

• Reporting counts without actually running graph-snapshot.sh
• Claiming the graph is built when the engine was unavailable
• Treating an engine-unavailable result as a hard failure (it degrades gracefully)
• Running against a path that isn't a directory

Build, then report what the tools actually returned.

---

Step 1: Resolve the target repo

The command takes an optional path argument: /draft:graph [path].

• No argument → use the current directory (.).
• With a path → use it as the repo root.

REPO="${1:-.}"
if [ ! -d "$REPO" ]; then
  echo "ERROR: '$REPO' is not a directory."
  exit 1
fi
REPO_ABS="$(cd "$REPO" && pwd)"
echo "Target repo: $REPO_ABS"

# Locate Draft's bundled helpers. Skills run with cwd = the user's project and
# ${CLAUDE_PLUGIN_ROOT} is not exported into skill Bash, so resolve DRAFT_TOOLS here
# and call helpers as "$DRAFT_TOOLS/<tool>.sh". See core/shared/tool-resolver.md.
DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
DRAFT_SCRIPTS="${DRAFT_TOOLS%/tools}"   # parent dir holds fetch-memory-engine.sh

Step 2: Ensure the engine is present

Resolve the engine; if it is missing, fetch it once, then re-check. If it is still unavailable (e.g. offline, opted out via DRAFT_MEMORY_DISABLE), report and stop gracefully — graph features are optional everywhere in Draft.

if ! "$DRAFT_TOOLS/verify-graph-binary.sh" --repo "$REPO_ABS" --json 2>/dev/null | grep -q '"status":"ok"'; then
  echo "Graph engine not found — attempting to fetch it..."
  "$DRAFT_SCRIPTS/fetch-memory-engine.sh" || true
fi

ENGINE="$("$DRAFT_TOOLS/verify-graph-binary.sh" --repo "$REPO_ABS" --json 2>/dev/null || true)"
if ! echo "$ENGINE" | grep -q '"status":"ok"'; then
  echo "Graph engine unavailable — skipping. Install with scripts/fetch-memory-engine.sh, or unset DRAFT_MEMORY_DISABLE."
  exit 0
fi
echo "Engine: $ENGINE"

Step 3: Build / refresh the snapshot

One call resolves the engine, indexes the repo (incrementally on refresh), and updates the gate marker <repo>/draft/graph/schema.yaml (engine metadata + point-of-index counts; access: engine-live). All structural graph data is queried live from the engine — no snapshot files are committed beyond schema.yaml.

"$DRAFT_TOOLS/graph-snapshot.sh" --repo "$REPO_ABS"

If this exits non-zero, the engine became unavailable mid-run — report it and stop; do not fabricate results.

Step 4: Report

Summarize what the snapshot contains. Read draft/graph/schema.yaml for engine/version/counts, and use the live tools for a quick health view:

echo "--- Snapshot ---"
cat "$REPO_ABS/draft/graph/schema.yaml"

echo "--- Top hotspots ---"
"$DRAFT_TOOLS/hotspot-rank.sh" --repo "$REPO_ABS" --top 5

echo "--- Cycles ---"
"$DRAFT_TOOLS/cycle-detect.sh" --repo "$REPO_ABS"

echo "--- Snapshot state ---"
git -C "$REPO_ABS" rev-parse --short HEAD 2>/dev/null \
  && { git -C "$REPO_ABS" diff --quiet 2>/dev/null || echo "(working tree dirty — snapshot reflects uncommitted changes)"; }

Present a concise summary:

• Engine: version + resolution source (path / managed / bundled / override)
• Graph: node and edge counts (from schema.yaml)
• Top hotspots: the highest fan-in symbols
• Cycles: count, or None ✓
• Freshness: the commit the snapshot reflects, and whether the tree was dirty

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: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

Scenario	Behavior
Engine resolvable	Build snapshot, report counts/hotspots/cycles
Engine missing, fetch succeeds	Build proceeds after fetch
Engine missing, fetch fails / DRAFT_MEMORY_DISABLE=1	Report unavailable and exit 0 — no error, no partial snapshot
Path not a directory	Exit 1 with a clear message

See core/shared/graph-query.md and bin/README.md for the query contract and engine resolution.