@drafthq/draft 3.2.0 → 3.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/.claude-plugin/marketplace.json +1 -1
  2. package/.claude-plugin/plugin.json +1 -1
  3. package/.cursor-plugin/plugin.json +28 -0
  4. package/README.md +2 -2
  5. package/cli/src/hosts/cursor.js +35 -5
  6. package/cli/src/installer.js +20 -0
  7. package/cli/src/lib/cursor-registry.js +122 -0
  8. package/cli/src/lib/marker.js +93 -0
  9. package/cli/src/lib/plugin-manifest.js +20 -0
  10. package/core/methodology.md +1 -1
  11. package/core/shared/condensation.md +3 -2
  12. package/core/shared/git-report-metadata.md +3 -2
  13. package/core/shared/graph-query.md +4 -3
  14. package/core/shared/tool-resolver.md +71 -4
  15. package/core/templates/okf/ai-context-index.md +48 -0
  16. package/core/templates/okf/concept.md +54 -0
  17. package/core/templates/okf/index.md +40 -0
  18. package/core/templates/okf/section-index.md +25 -0
  19. package/core/templates/plan.md +3 -2
  20. package/integrations/agents/AGENTS.md +792 -102
  21. package/integrations/copilot/.github/copilot-instructions.md +792 -102
  22. package/package.json +3 -2
  23. package/scripts/lib.sh +10 -0
  24. package/scripts/tools/graph-preflight.sh +259 -0
  25. package/scripts/tools/okf-render-views.sh +373 -0
  26. package/scripts/tools/okf-validate.sh +204 -0
  27. package/scripts/tools/resolve-tools.sh +78 -0
  28. package/skills/adr/SKILL.md +3 -2
  29. package/skills/bughunt/SKILL.md +10 -1
  30. package/skills/coverage/SKILL.md +8 -3
  31. package/skills/debug/SKILL.md +16 -5
  32. package/skills/decompose/SKILL.md +29 -12
  33. package/skills/deep-review/SKILL.md +19 -6
  34. package/skills/deploy-checklist/SKILL.md +6 -5
  35. package/skills/graph/SKILL.md +15 -6
  36. package/skills/impact/SKILL.md +12 -1
  37. package/skills/implement/SKILL.md +20 -4
  38. package/skills/init/SKILL.md +36 -10
  39. package/skills/init/references/architecture-spec.md +17 -6
  40. package/skills/init/references/okf-emitter.md +223 -0
  41. package/skills/learn/SKILL.md +15 -4
  42. package/skills/quick-review/SKILL.md +13 -3
  43. package/skills/review/SKILL.md +32 -8
  44. package/skills/standup/SKILL.md +3 -2
  45. package/skills/status/SKILL.md +3 -2
  46. package/skills/tech-debt/SKILL.md +20 -6
  47. package/skills/upload/SKILL.md +3 -2
  48. package/integrations/copilot/.github/copilot-instructions.md.7iDz8X +0 -91
  49. package/integrations/copilot/.github/copilot-instructions.md.DoBdtd +0 -91
  50. package/integrations/copilot/.github/copilot-instructions.md.McGoBW +0 -122
  51. package/integrations/copilot/.github/copilot-instructions.md.VsPyLB +0 -91
  52. package/integrations/copilot/.github/copilot-instructions.md.XAVr7D +0 -91
  53. package/integrations/copilot/.github/copilot-instructions.md.YoFVFa +0 -91
  54. package/integrations/copilot/.github/copilot-instructions.md.a9DeW0 +0 -91
  55. package/integrations/copilot/.github/copilot-instructions.md.oxQs3B +0 -91
  56. package/integrations/copilot/.github/copilot-instructions.md.ww33Ly +0 -91
@@ -68,7 +68,16 @@ Read and follow the base procedure in `core/shared/draft-context-loading.md`.
68
68
  - **Leverage Storage Topology** — Identify data loss risks at each tier (cache eviction without writeback, event log gaps, missing archive)
69
69
  - **Leverage Consistency Boundaries** — Find bugs at eventual consistency seams (stale reads, lost events, missing reconciliation)
70
70
  - **Leverage Failure Recovery Matrix** — Verify idempotency claims, check for partial failure states without recovery paths
71
- - **Leverage Graph Data** (if `draft/graph/` exists) — Query `scripts/tools/graph-arch.sh --repo .` for dependency awareness. Flag dependencies on unexpected modules. Flag code in modules involved in dependency cycles as higher risk. Run `scripts/tools/hotspot-rank.sh --repo .` to prioritize analysis of high-complexity, high-fanIn files. See `core/shared/graph-query.md`.
71
+ - **Leverage Graph Data** (if `draft/graph/` exists) — First resolve the bundled helpers:
72
+ ```bash
73
+ # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
74
+ # is not exported into skill Bash). See core/shared/tool-resolver.md.
75
+ DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
76
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
77
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
78
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
79
+ ```
80
+ Query `"$DRAFT_TOOLS/graph-arch.sh" --repo .` for dependency awareness. Flag dependencies on unexpected modules. Flag code in modules involved in dependency cycles as higher risk. Run `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .` to prioritize analysis of high-complexity, high-fanIn files. See `core/shared/graph-query.md`.
72
81
  - **Leverage Learned Anti-Patterns** — If `draft/guardrails.md` exists, read the `## Learned Anti-Patterns` section. During the bug sweep, when a bug matches a learned anti-pattern, prefix the report entry with `[KNOWN-ANTI-PATTERN: {pattern name}]`. This distinguishes recurring documented patterns from newly discovered bugs, and signals that a systemic fix may be needed rather than a one-off patch.
73
82
 
74
83
  ### 2. Confirm Scope
@@ -33,8 +33,9 @@ If no active track and no argument provided:
33
33
  **Preferred:** use the deterministic `detect-test-framework.sh` wrapper — it emits JSON `{languages:[{language,framework,runner_command,test_globs,config_file}]}`. Resolve via the canonical tool resolver (see [core/shared/tool-resolver.md](../../core/shared/tool-resolver.md)):
34
34
 
35
35
  ```bash
36
- DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$HOME/.claude/plugins/draft}/scripts/tools"
37
- [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$HOME/.cursor/plugins/local/draft/scripts/tools"
36
+ DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
37
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
38
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
38
39
  [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
39
40
  [ -x "$DRAFT_TOOLS/detect-test-framework.sh" ] && \
40
41
  bash "$DRAFT_TOOLS/detect-test-framework.sh" --root .
@@ -73,7 +74,11 @@ Build the coverage command with the appropriate scope/filter flags.
73
74
  **Preferred:** invoke the normalized `run-coverage.sh` dispatcher — it dispatches to the language-specific runner and emits a normalized JSON `{language,tool,total:{lines,branches},per_file:[{path,lines,branches,uncovered_lines}]}`. This avoids per-language ad-hoc parsing in Step 5.
74
75
 
75
76
  ```bash
76
- # DRAFT_TOOLS resolved in Step 2 above
77
+ # Re-resolve helpers (this is a separate Bash session from Step 2).
78
+ DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
79
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
80
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
81
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
77
82
  [ -x "$DRAFT_TOOLS/run-coverage.sh" ] && \
78
83
  bash "$DRAFT_TOOLS/run-coverage.sh" --root .
79
84
  ```
@@ -9,12 +9,23 @@ You are conducting a structured debugging session following systematic investiga
9
9
 
10
10
  ## MANDATORY GRAPH LOOKUP (read before Isolate/Diagnose)
11
11
 
12
+ First resolve the bundled helpers:
13
+
14
+ ```bash
15
+ # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
16
+ # is not exported into skill Bash). See core/shared/tool-resolver.md.
17
+ DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
18
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
19
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
20
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
21
+ ```
22
+
12
23
  When `draft/graph/schema.yaml` exists, this skill **must** follow the graph-first lookup contract in [core/shared/graph-query.md](../../core/shared/graph-query.md) §Mandatory Lookup Contract. During Steps 3–4 (Isolate, Diagnose):
13
24
 
14
- 1. Locate the suspect file's module via `scripts/tools/graph-arch.sh --repo .` before tracing data flow.
15
- 2. Use `scripts/tools/graph-callers.sh --repo . --symbol <fn>` to enumerate call sites of suspect functions — not `grep`.
16
- 3. Use `scripts/tools/graph-impact.sh --repo . --file <path>` to size the blast radius before proposing a fix.
17
- 4. Run `scripts/tools/hotspot-rank.sh --repo .` to know whether the file is high-fanIn (any fix needs extra caution).
25
+ 1. Locate the suspect file's module via `"$DRAFT_TOOLS/graph-arch.sh" --repo .` before tracing data flow.
26
+ 2. Use `"$DRAFT_TOOLS/graph-callers.sh" --repo . --symbol <fn>` to enumerate call sites of suspect functions — not `grep`.
27
+ 3. Use `"$DRAFT_TOOLS/graph-impact.sh" --repo . --file <path>` to size the blast radius before proposing a fix.
28
+ 4. Run `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .` to know whether the file is high-fanIn (any fix needs extra caution).
18
29
 
19
30
  Filesystem `grep` is reserved for source-text scans (literal error strings, stack-trace symbols when the graph misses). Use the fallback sentence on graph miss.
20
31
 
@@ -62,7 +73,7 @@ Key context for debugging:
62
73
  - `.ai-context.md` — Module boundaries, data flows, invariants (crucial for tracing)
63
74
  - `tech-stack.md` — Language-specific debugging tools and techniques
64
75
  - `guardrails.md` — Known anti-patterns that may be causing the issue
65
- - `draft/graph/` (MANDATORY when present) — Query `scripts/tools/graph-arch.sh --repo .` for dependency/module context and `scripts/tools/hotspot-rank.sh --repo .` for complexity awareness. Use `scripts/tools/graph-callers.sh --repo . --symbol <fn>` to find all callers, and `scripts/tools/graph-impact.sh --repo . --file <path>` to size blast radius before any fix. See [core/shared/graph-query.md](../../core/shared/graph-query.md).
76
+ - `draft/graph/` (MANDATORY when present) — Query `"$DRAFT_TOOLS/graph-arch.sh" --repo .` for dependency/module context and `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .` for complexity awareness. Use `"$DRAFT_TOOLS/graph-callers.sh" --repo . --symbol <fn>` to find all callers, and `"$DRAFT_TOOLS/graph-impact.sh" --repo . --file <path>` to size blast radius before any fix. See [core/shared/graph-query.md](../../core/shared/graph-query.md).
66
77
 
67
78
  ## Step 1: Parse Arguments
68
79
 
@@ -9,12 +9,23 @@ You are decomposing a project or track into modules with clear responsibilities,
9
9
 
10
10
  ## MANDATORY GRAPH LOOKUP (read before any analysis)
11
11
 
12
+ First resolve the bundled helpers:
13
+
14
+ ```bash
15
+ # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
16
+ # is not exported into skill Bash). See core/shared/tool-resolver.md.
17
+ DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
18
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
19
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
20
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
21
+ ```
22
+
12
23
  When `draft/graph/schema.yaml` exists, this skill **must** follow the graph-first lookup contract in [core/shared/graph-query.md](../../core/shared/graph-query.md) §Mandatory Lookup Contract. Module identification (Step 3) and dependency mapping (Step 4) **start from the graph**:
13
24
 
14
- 1. Query `scripts/tools/graph-arch.sh --repo .` for the authoritative module list and fan-in/out.
15
- 2. Run `scripts/tools/hotspot-rank.sh --repo .` to identify candidate modules to split.
16
- 3. Use `scripts/tools/graph-callers.sh`/`graph-impact.sh` on demand for symbols/callers inside a candidate module.
17
- 4. Run `scripts/tools/cycle-detect.sh --repo .` to enumerate existing cycles before proposing new boundaries.
25
+ 1. Query `"$DRAFT_TOOLS/graph-arch.sh" --repo .` for the authoritative module list and fan-in/out.
26
+ 2. Run `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .` to identify candidate modules to split.
27
+ 3. Use `"$DRAFT_TOOLS/graph-callers.sh"`/`"$DRAFT_TOOLS/graph-impact.sh"` on demand for symbols/callers inside a candidate module.
28
+ 4. Run `"$DRAFT_TOOLS/cycle-detect.sh" --repo .` to enumerate existing cycles before proposing new boundaries.
18
29
 
19
30
  Filesystem `grep`/`find` for module discovery is only permitted **after** a documented graph miss, using the fallback sentence `Graph returned no match for <X>; falling back to grep.` and recorded in the Graph Usage Report.
20
31
 
@@ -156,11 +167,11 @@ ls -d src/*/ lib/*/ app/*/ packages/*/ 2>/dev/null
156
167
 
157
168
  When graph data is available, the graph is the **primary** (not optional) source for module discovery — manual scanning above is reserved for the graph-miss fallback path:
158
169
 
159
- - **Module boundaries**: Query `scripts/tools/graph-arch.sh --repo .` — module list with node counts and per-language file counts
170
+ - **Module boundaries**: Query `"$DRAFT_TOOLS/graph-arch.sh" --repo .` — module list with node counts and per-language file counts
160
171
  - **Dependency edges**: Weighted inter-module dependencies with exact include counts — replaces manual import tracing
161
172
  - **Cycle detection**: Circular dependency paths already computed — use for identifying tight coupling and decomposition candidates
162
- - **Hotspots**: Run `scripts/tools/hotspot-rank.sh --repo .` — high-complexity files that may need further decomposition
163
- - **Per-module detail**: query `scripts/tools/graph-callers.sh`/`graph-impact.sh` for symbol/call detail within modules of interest
173
+ - **Hotspots**: Run `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .` — high-complexity files that may need further decomposition
174
+ - **Per-module detail**: query `"$DRAFT_TOOLS/graph-callers.sh"`/`"$DRAFT_TOOLS/graph-impact.sh"` for symbol/call detail within modules of interest
164
175
 
165
176
  This data is deterministic and exhaustive. The manual scanning recipes above only run **after** the graph misses on the concept the user named — and the miss must be reported in the Graph Usage Report footer. See [core/shared/graph-query.md](../../core/shared/graph-query.md) §Concept-to-Files Recipe.
166
177
 
@@ -404,8 +415,11 @@ After writing all generated files, strip trailing whitespace and blank lines at
404
415
  Resolve the script via the canonical tool resolver (see [core/shared/tool-resolver.md](../../core/shared/tool-resolver.md)):
405
416
 
406
417
  ```bash
407
- DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$HOME/.claude/plugins/draft}/scripts/tools"
408
- [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$HOME/.cursor/plugins/local/draft/scripts/tools"
418
+ # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
419
+ # is not exported into skill Bash). See core/shared/tool-resolver.md.
420
+ DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
421
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
422
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
409
423
  [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
410
424
  # Fix all generated markdown for this track:
411
425
  [ -x "$DRAFT_TOOLS/fix-whitespace.sh" ] && bash "$DRAFT_TOOLS/fix-whitespace.sh" --track <id>
@@ -452,7 +466,7 @@ references, sunset criteria) survive every regenerate. After rewriting:
452
466
  2. Update plan.md `generated_at:` to the current ISO-8601 timestamp.
453
467
  3. Ensure plan.md `generated_at` ≥ sibling hld.md / lld.md `generated_at`
454
468
  (the hygiene validator fails on stale plan).
455
- 4. Run `scripts/tools/check-track-hygiene.sh <track_dir>` and resolve any
469
+ 4. Run `"$DRAFT_TOOLS/check-track-hygiene.sh" <track_dir>` and resolve any
456
470
  findings before promoting status past `draft`.
457
471
 
458
472
  If the plan does not yet have the bracket markers (pre-2.0 track), insert
@@ -648,8 +662,11 @@ As the last step after the completion announcement, emit a metrics record. Best-
648
662
 
649
663
  **Emit call:**
650
664
  ```bash
651
- DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$HOME/.claude/plugins/draft}/scripts/tools"
652
- [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$HOME/.cursor/plugins/local/draft/scripts/tools"
665
+ # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
666
+ # is not exported into skill Bash). See core/shared/tool-resolver.md.
667
+ DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
668
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
669
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
653
670
  [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
654
671
  [ -x "$DRAFT_TOOLS/emit-skill-metrics.sh" ] && bash "$DRAFT_TOOLS/emit-skill-metrics.sh" \
655
672
  '{"skill":"decompose","scope":"<scope>","track_id":"<id_or_null>","modules_count":<N>,"lld_generated":<bool>,"high_complexity_modules":<N>}'
@@ -11,10 +11,20 @@ Perform an exhaustive end-to-end lifecycle review of a service, component, or mo
11
11
 
12
12
  When `draft/graph/schema.yaml` exists, this skill **must** follow the graph-first lookup contract in [core/shared/graph-query.md](../../core/shared/graph-query.md) §Mandatory Lookup Contract. Deep-review uses the graph to **narrow review scope** — a key 30–50% scope reduction:
13
13
 
14
- 1. Use `scripts/tools/graph-impact.sh`/`graph-callers.sh` and `scripts/tools/graph-arch.sh --repo .` for the audited module's structure — do not enumerate via `find`.
15
- 2. Run `scripts/tools/graph-impact.sh --repo . --file <each-changed-file>` per file in the diff (or per file in the module if no diff) to obtain the affected module set deterministically.
16
- 3. Run `scripts/tools/cycle-detect.sh --repo .` and flag any cycle that includes the audited module as Architecture Resilience finding.
17
- 4. Run `scripts/tools/hotspot-rank.sh --repo .` to identify high-fanIn files inside the module — these get deeper inspection.
14
+ First resolve the bundled helpers:
15
+ ```bash
16
+ # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
17
+ # is not exported into skill Bash). See core/shared/tool-resolver.md.
18
+ DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
19
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
20
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
21
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
22
+ ```
23
+
24
+ 1. Use `"$DRAFT_TOOLS/graph-impact.sh"`/`graph-callers.sh` and `"$DRAFT_TOOLS/graph-arch.sh" --repo .` for the audited module's structure — do not enumerate via `find`.
25
+ 2. Run `"$DRAFT_TOOLS/graph-impact.sh" --repo . --file <each-changed-file>` per file in the diff (or per file in the module if no diff) to obtain the affected module set deterministically.
26
+ 3. Run `"$DRAFT_TOOLS/cycle-detect.sh" --repo .` and flag any cycle that includes the audited module as Architecture Resilience finding.
27
+ 4. Run `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .` to identify high-fanIn files inside the module — these get deeper inspection.
18
28
 
19
29
  Filesystem `grep` is reserved for source-text scans (API contract strings, secret patterns, log message audits). Module enumeration and caller tracing go through the graph.
20
30
 
@@ -318,8 +328,11 @@ As the last step after saving the deep-review report, emit a metrics record. Bes
318
328
 
319
329
  **Emit call:**
320
330
  ```bash
321
- DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$HOME/.claude/plugins/draft}/scripts/tools"
322
- [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$HOME/.cursor/plugins/local/draft/scripts/tools"
331
+ # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
332
+ # is not exported into skill Bash). See core/shared/tool-resolver.md.
333
+ DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
334
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
335
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
323
336
  [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
324
337
  [ -x "$DRAFT_TOOLS/emit-skill-metrics.sh" ] && bash "$DRAFT_TOOLS/emit-skill-metrics.sh" \
325
338
  '{"skill":"deep-review","module":"<module>","phases_completed":<N>,"critical_count":<N>,"important_count":<N>,"sec_violations":<N>,"acid_violations":<N>,"graph_queries":<N>,"fallback_grep_count":<N>}'
@@ -11,9 +11,9 @@ You are generating a pre-deployment verification checklist customized to this pr
11
11
 
12
12
  When `draft/graph/schema.yaml` exists, this skill **must** follow the graph-first lookup contract in [core/shared/graph-query.md](../../core/shared/graph-query.md) §Mandatory Lookup Contract. Use the graph to validate module boundaries before the deploy:
13
13
 
14
- 1. For each file in the deploy diff, run `scripts/tools/graph-impact.sh --repo . --file <path>` to enumerate the modules affected — flag any module **not** declared in `hld.md` §Detailed Design as a deployment-scope miss.
15
- 2. Run `scripts/tools/cycle-detect.sh --repo .` (and query `scripts/tools/graph-arch.sh --repo .` for the module overview) to ensure no fresh cycles were introduced after HLD sign-off.
16
- 3. Run `scripts/tools/hotspot-rank.sh --repo .` — any hotspot in the diff escalates the Resiliency row of Phase 0.
14
+ 1. For each file in the deploy diff, run `"$DRAFT_TOOLS/graph-impact.sh" --repo . --file <path>` to enumerate the modules affected — flag any module **not** declared in `hld.md` §Detailed Design as a deployment-scope miss.
15
+ 2. Run `"$DRAFT_TOOLS/cycle-detect.sh" --repo .` (and query `"$DRAFT_TOOLS/graph-arch.sh" --repo .` for the module overview) to ensure no fresh cycles were introduced after HLD sign-off.
16
+ 3. Run `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .` — any hotspot in the diff escalates the Resiliency row of Phase 0.
17
17
 
18
18
  Filesystem `grep` is reserved for source-text scans (migration file names, flag-key strings). Module/impact discovery goes through the graph.
19
19
 
@@ -67,8 +67,9 @@ by validator.
67
67
  ```bash
68
68
  TRACK_DIR="$1" # absolute path to track-under-deploy, or .
69
69
 
70
- DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$HOME/.claude/plugins/draft}/scripts/tools"
71
- [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$HOME/.cursor/plugins/local/draft/scripts/tools"
70
+ DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
71
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
72
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
72
73
  [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
73
74
 
74
75
  "$DRAFT_TOOLS/check-track-hygiene.sh" "$TRACK_DIR" || rc=$?
@@ -33,6 +33,15 @@ if [ ! -d "$REPO" ]; then
33
33
  fi
34
34
  REPO_ABS="$(cd "$REPO" && pwd)"
35
35
  echo "Target repo: $REPO_ABS"
36
+
37
+ # Locate Draft's bundled helpers. Skills run with cwd = the user's project and
38
+ # ${CLAUDE_PLUGIN_ROOT} is not exported into skill Bash, so resolve DRAFT_TOOLS here
39
+ # and call helpers as "$DRAFT_TOOLS/<tool>.sh". See core/shared/tool-resolver.md.
40
+ DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
41
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
42
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
43
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
44
+ DRAFT_SCRIPTS="${DRAFT_TOOLS%/tools}" # parent dir holds fetch-memory-engine.sh
36
45
  ```
37
46
 
38
47
  ## Step 2: Ensure the engine is present
@@ -40,12 +49,12 @@ echo "Target repo: $REPO_ABS"
40
49
  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.
41
50
 
42
51
  ```bash
43
- if ! scripts/tools/verify-graph-binary.sh --repo "$REPO_ABS" --json 2>/dev/null | grep -q '"status":"ok"'; then
52
+ if ! "$DRAFT_TOOLS/verify-graph-binary.sh" --repo "$REPO_ABS" --json 2>/dev/null | grep -q '"status":"ok"'; then
44
53
  echo "Graph engine not found — attempting to fetch it..."
45
- scripts/fetch-memory-engine.sh || true
54
+ "$DRAFT_SCRIPTS/fetch-memory-engine.sh" || true
46
55
  fi
47
56
 
48
- ENGINE="$(scripts/tools/verify-graph-binary.sh --repo "$REPO_ABS" --json 2>/dev/null || true)"
57
+ ENGINE="$("$DRAFT_TOOLS/verify-graph-binary.sh" --repo "$REPO_ABS" --json 2>/dev/null || true)"
49
58
  if ! echo "$ENGINE" | grep -q '"status":"ok"'; then
50
59
  echo "Graph engine unavailable — skipping. Install with scripts/fetch-memory-engine.sh, or unset DRAFT_MEMORY_DISABLE."
51
60
  exit 0
@@ -58,7 +67,7 @@ echo "Engine: $ENGINE"
58
67
  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`.
59
68
 
60
69
  ```bash
61
- scripts/tools/graph-snapshot.sh --repo "$REPO_ABS"
70
+ "$DRAFT_TOOLS/graph-snapshot.sh" --repo "$REPO_ABS"
62
71
  ```
63
72
 
64
73
  If this exits non-zero, the engine became unavailable mid-run — report it and stop; do not fabricate results.
@@ -72,10 +81,10 @@ echo "--- Snapshot ---"
72
81
  cat "$REPO_ABS/draft/graph/schema.yaml"
73
82
 
74
83
  echo "--- Top hotspots ---"
75
- scripts/tools/hotspot-rank.sh --repo "$REPO_ABS" --top 5
84
+ "$DRAFT_TOOLS/hotspot-rank.sh" --repo "$REPO_ABS" --top 5
76
85
 
77
86
  echo "--- Cycles ---"
78
- scripts/tools/cycle-detect.sh --repo "$REPO_ABS"
87
+ "$DRAFT_TOOLS/cycle-detect.sh" --repo "$REPO_ABS"
79
88
 
80
89
  echo "--- Snapshot state ---"
81
90
  git -C "$REPO_ABS" rev-parse --short HEAD 2>/dev/null \
@@ -16,11 +16,22 @@ Generate a project-wide impact report measuring Context-Driven Development effec
16
16
 
17
17
  ## Execution Constraints
18
18
 
19
+ First resolve the bundled helpers:
20
+
21
+ ```bash
22
+ # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
23
+ # is not exported into skill Bash). See core/shared/tool-resolver.md.
24
+ DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
25
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
26
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
27
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
28
+ ```
29
+
19
30
  1. **Load Track State:**
20
31
  - Read all `draft/tracks.md` entries.
21
32
  - For each track, read `metadata.json` to extract: `created_at`, `updated`, `status`, phase counts, task counts, `scope_includes`, `scope_excludes`.
22
33
  - If no tracks exist, report "No tracks found. Run `/draft:new-track` to create your first track."
23
- - Run `scripts/tools/check-scope-conflicts.sh` to surface adjacent
34
+ - Run `"$DRAFT_TOOLS/check-scope-conflicts.sh"` to surface adjacent
24
35
  tracks sharing scope tags — duplicate effort signals in impact
25
36
  reporting. Schema:
26
37
  [core/shared/template-contract.md](../../core/shared/template-contract.md).
@@ -133,9 +133,21 @@ If one of these applies, route directly to the specialist workflow and stop this
133
133
  - Keep matching invariants as **active constraints** for this task — these govern code generation, not just review
134
134
  - If invariants reference lock ordering, fail-closed behavior, or data integrity rules: these are non-negotiable during implementation
135
135
  9. **Load graph context** (if `draft/graph/schema.yaml` exists):
136
- - Run `scripts/tools/hotspot-rank.sh --repo .` — check if any files this task will modify appear as hotspots
136
+
137
+ First resolve the bundled helpers:
138
+
139
+ ```bash
140
+ # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
141
+ # is not exported into skill Bash). See core/shared/tool-resolver.md.
142
+ DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
143
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
144
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
145
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
146
+ ```
147
+
148
+ - Run `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .` — check if any files this task will modify appear as hotspots
137
149
  - If modifying a hotspot file (high fanIn), warn: "This task modifies {file} (fanIn={N}). Changes here affect many downstream files. Consider running a graph impact query."
138
- - Query `scripts/tools/graph-impact.sh`/`graph-callers.sh` for the module(s) being modified — gives file-level dependency context
150
+ - Query `"$DRAFT_TOOLS/graph-impact.sh"`/`"$DRAFT_TOOLS/graph-callers.sh"` for the module(s) being modified — gives file-level dependency context
139
151
  - See `core/shared/graph-query.md` for on-demand query subroutines (callers, impact)
140
152
  10. Update the track's entry in `draft/tracks.md` from `[ ]` to `[~]` In Progress
141
153
 
@@ -625,9 +637,13 @@ After a phase passes review, refresh `metadata.json.impact` so future tracks can
625
637
  ```
626
638
  That is the `files_touched` list. Derive `modules_touched` as the unique top-level path segments (e.g. `auth/login.go` → `auth`).
627
639
 
628
- 2. **Compute downstream blast radius (graph-aware, optional):** If `draft/graph/schema.yaml` exists, for each file in `files_touched` query:
640
+ 2. **Compute downstream blast radius (graph-aware, optional):** If `draft/graph/schema.yaml` exists, for each file in `files_touched` query (this runs in its own Bash session — re-resolve the helpers):
629
641
  ```bash
630
- scripts/tools/graph-impact.sh --repo . --file <path>
642
+ DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
643
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
644
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
645
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
646
+ "$DRAFT_TOOLS/graph-impact.sh" --repo . --file <path>
631
647
  ```
632
648
  Aggregate across all files: `downstream_files` = total unique downstream files (deduped), `downstream_modules` = union of `affected_modules`, `max_depth` = max across queries, `by_category` = sum of each query's `by_category`. If the graph is absent, leave these fields as zeros / empty arrays — the snapshot still records the directly-touched files.
633
649
 
@@ -199,6 +199,23 @@ Check for arguments:
199
199
 
200
200
  > `/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.
201
201
 
202
+ ### Output Mode (`DRAFT_INIT_MODE`)
203
+
204
+ Init has two output modes. The default is **tier-gated (`auto`)** — resolved from the codebase tier computed in Step 1.4.5 — and the `DRAFT_INIT_MODE` environment variable overrides it:
205
+
206
+ ```bash
207
+ DRAFT_INIT_MODE="${DRAFT_INIT_MODE:-auto}"
208
+ # auto → resolved AFTER tier is known (Step 1.4.5):
209
+ # tier 1–2 (micro/small) → monolith
210
+ # tier 3–5 (medium/large/XL) → okf
211
+ # monolith / okf → explicit override; honored as-is.
212
+ ```
213
+
214
+ - **`monolith`** — the standard path documented in this skill: a single `architecture.md` (10-section graph-primary) + derived `.ai-context.md` / `.ai-profile.md`. The default for **small repos (tier 1–2)**, where one linear document beats a taxonomy with little to navigate. Also the A/B baseline and the over-fetch fallback.
215
+ - **`okf`** — emit an OKF-conformant concept taxonomy bundle (`draft/wiki/`) with `.ai-context.md` as the index root and `architecture.md` demoted to a generated rendered view. The default for **tier 3+ repos**, where navigation + maintainability pay off. When active, follow `references/okf-emitter.md` for the decomposition + serialization + validation stage; all shared phases (5-phase analysis, graph snapshot, `.state/` hashing, scope detection, atomic staging) are reused unchanged.
216
+
217
+ The tier-gated default rests on **maintainability/readability** (one navigable concept per file, cleaner PRs, a generated `architecture.md` preserved for linear onboarding) — not on the A/B benchmark, which was accuracy-parity (`docs/audit/okf-benchmark.md`). `monolith` is **retained, not retired**: it is the tier-1/2 default, the A/B baseline, and the fallback. If `DRAFT_INIT_MODE` is unset, do not commit to a mode until **Step 1.4.5** has computed the tier.
218
+
202
219
  ### Route Explicit Modes Before Initialization
203
220
 
204
221
  If the user explicitly invoked a specialist mode, route directly:
@@ -491,8 +508,15 @@ The knowledge-graph engine `codebase-memory-mcp` is Draft's **default** capabili
491
508
  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:
492
509
 
493
510
  ```bash
511
+ # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
512
+ # is not exported into skill Bash). See core/shared/tool-resolver.md.
513
+ DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
514
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
515
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
516
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
517
+
494
518
  # Add --module-only to skip touching the root (link marked "pending").
495
- if scripts/tools/graph-init.sh --scope .; then
519
+ if "$DRAFT_TOOLS/graph-init.sh" --scope .; then
496
520
  echo "Graph memory ready under draft/graph/ (the root spine is the structural source of truth)."
497
521
  else
498
522
  echo "Graph engine unavailable — proceeding with degraded manual discovery. Downstream skills degrade gracefully."
@@ -506,7 +530,7 @@ fi
506
530
  Optionally record which engine was selected (usage-report contract):
507
531
 
508
532
  ```bash
509
- scripts/tools/verify-graph-binary.sh --repo . --json 2>/dev/null || true
533
+ "$DRAFT_TOOLS/verify-graph-binary.sh" --repo . --json 2>/dev/null || true
510
534
  ```
511
535
 
512
536
  See `core/shared/graph-query.md` and `bin/README.md` for the query contract and engine resolution.
@@ -518,13 +542,13 @@ If indexing succeeds, `draft/graph/schema.yaml` is written and later steps query
518
542
  Pull the architecture view once and reuse it across phases:
519
543
 
520
544
  ```bash
521
- ARCH=$(scripts/tools/graph-arch.sh --repo .)
545
+ ARCH=$("$DRAFT_TOOLS/graph-arch.sh" --repo .)
522
546
  ```
523
547
 
524
548
  - `$ARCH | jq '.packages'` — module list with fan-in/out
525
549
  - `$ARCH | jq '.routes'` — detected service endpoints
526
550
  - `$ARCH | jq '.languages, .node_labels, .layers, .boundaries'` — language mix, node shape, layering
527
- - `scripts/tools/hotspot-rank.sh --repo . --top 20` — complexity/fan-in hotspots (live)
551
+ - `"$DRAFT_TOOLS/hotspot-rank.sh" --repo . --top 20` — complexity/fan-in hotspots (live)
528
552
 
529
553
  ### 3. Use graph data to accelerate Step 1.5
530
554
 
@@ -555,8 +579,10 @@ Apply tier table:
555
579
 
556
580
  Hold tier in memory. This governs: architecture.md length minimum, .ai-context.md budget, and module deep-dive depth.
557
581
 
582
+ **Resolve the output mode now (if `auto`).** If `DRAFT_INIT_MODE` is unset/`auto`, finalize it from the tier just computed: **tier 1–2 → `monolith`**, **tier 3–5 → `okf`** (see **Output Mode** in Pre-Check). An explicit `DRAFT_INIT_MODE=monolith|okf` always wins and skips this resolution. Announce the resolved mode, e.g. `Tier 4 (large) → okf mode (wiki taxonomy bundle).` If `okf`, switch to `references/okf-emitter.md` for the decomposition + serialization + render-views + validate stage from here on; all the shared analysis above is reused unchanged.
583
+
558
584
  **Step 1.4.6 — Build Module Priority List:**
559
- From `scripts/tools/hotspot-rank.sh --repo .`: count hotspot symbols per module.
585
+ From `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .`: count hotspot symbols per module.
560
586
  From `$ARCH | jq '.packages[]'`: read `fan_in` per module.
561
587
  Rank modules by: `(hotspot_count × 2) + fan_in_count`.
562
588
  Top-ranked modules drive Section 6 deep-dive ordering and depth. Modules ranked zero on both: summary treatment only.
@@ -567,7 +593,7 @@ Query for diagram content and write into architecture.md slots using the standar
567
593
 
568
594
  For Section 4.4 (module-deps slot):
569
595
  ```bash
570
- scripts/tools/mermaid-from-graph.sh --repo . --diagram module-deps
596
+ "$DRAFT_TOOLS/mermaid-from-graph.sh" --repo . --diagram module-deps
571
597
  ```
572
598
  The tool emits a ready-to-inject ` ```mermaid ``` ` block (or an empty stub on exit 2). Write between the markers:
573
599
  ```
@@ -577,7 +603,7 @@ The tool emits a ready-to-inject ` ```mermaid ``` ` block (or an empty stub on e
577
603
  ```
578
604
 
579
605
  For Section 20 (hotspots slot):
580
- Run `scripts/tools/hotspot-rank.sh --repo . --top 10`, take the top 10 by fanIn, build a markdown table:
606
+ Run `"$DRAFT_TOOLS/hotspot-rank.sh" --repo . --top 10`, take the top 10 by fanIn, build a markdown table:
581
607
  ```
582
608
  <!-- GRAPH:hotspots:START -->
583
609
  | Symbol | fanIn |
@@ -589,7 +615,7 @@ Run `scripts/tools/hotspot-rank.sh --repo . --top 10`, take the top 10 by fanIn,
589
615
 
590
616
  For Appendix E (proto-map slot):
591
617
  ```bash
592
- scripts/tools/mermaid-from-graph.sh --repo . --diagram proto-map
618
+ "$DRAFT_TOOLS/mermaid-from-graph.sh" --repo . --diagram proto-map
593
619
  ```
594
620
  The tool emits a ` ```mermaid ``` ` block from detected routes (empty stub if none). Write:
595
621
  ```
@@ -666,7 +692,7 @@ For tier 3+, readers run simultaneously; wall clock = slowest reader, not the su
666
692
  The engine is already indexed. Query it live throughout this protocol (reuse `$ARCH` from Step 1.4.2):
667
693
  - `$ARCH | jq '.packages'` — module list with `.fan_in`/`.fan_out` (for grouping)
668
694
  - `$ARCH | jq '.languages, .node_labels'` — file/symbol counts, tier metrics
669
- - `scripts/tools/hotspot-rank.sh --repo .` — top hotspot symbols per module (feed to readers)
695
+ - `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .` — top hotspot symbols per module (feed to readers)
670
696
 
671
697
  #### Phase 1: Spawn Parallel Module Readers
672
698
 
@@ -793,7 +819,7 @@ If any reader agent fails to produce valid JSON after one retry:
793
819
  When the Agent tool is unavailable or reader agents fail after retry, write `draft/architecture.md` using the **10-section graph-primary structure** (checklist above + `core/templates/architecture.md`). Do not use legacy 28-section or Pass 1/2/3 volume protocols.
794
820
 
795
821
  1. Use the ranked module list from Step 1.4.6 (graph-first — do not re-scan by directory if Phase 0 succeeded).
796
- 2. For each top module (up to 20 by fan-in), query the engine for its symbols/callers (`scripts/tools/graph-callers.sh`, `graph-impact.sh`, or `$ARCH | jq '.packages[] | select(.name=="<m>")'`), read the hotspot files and 3–5 key sources; embed graph blocks and at least one workflow/state diagram per significant module inside §4–§8 as appropriate.
822
+ 2. For each top module (up to 20 by fan-in), query the engine for its symbols/callers (`"$DRAFT_TOOLS/graph-callers.sh"`, `"$DRAFT_TOOLS/graph-impact.sh"`, or `$ARCH | jq '.packages[] | select(.name=="<m>")'`), read the hotspot files and 3–5 key sources; embed graph blocks and at least one workflow/state diagram per significant module inside §4–§8 as appropriate.
797
823
  3. Always include §9 Graph Coverage Gaps and §10 Relationship when the Context Audit requires them.
798
824
  4. Run Completion Verification (defined later in this skill) before condensation. Fidelity, provenance, and gap honesty block completion — not line counts.
799
825
 
@@ -275,7 +275,18 @@ Only when material: authentication/authorization checkpoints, distributed transa
275
275
 
276
276
  **Core rule:** The graph is the source of truth for structure. LLM synthesis exists only to interpret the graph into actionable design understanding — primarily via one accurate workflow or state diagram per module — plus tiny supporting notes. The previous volume-oriented deep-dive expectations are superseded.
277
277
 
278
- For each module returned by `scripts/tools/graph-arch.sh --repo . | jq '.packages[]'`, produce a subsection whose **primary content** is the deterministic graph block followed by one synthesized behavioral diagram. Every module gets a slot; do not sample. The block's fan-in/out and node counts come from `.packages[]`; public API and key call edges come from live per-package queries (`scripts/tools/graph-callers.sh`, `graph-impact.sh`) and `scripts/tools/hotspot-rank.sh --repo .`.
278
+ First resolve the bundled helpers:
279
+
280
+ ```bash
281
+ # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
282
+ # is not exported into skill Bash). See core/shared/tool-resolver.md.
283
+ DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
284
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
285
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
286
+ [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
287
+ ```
288
+
289
+ For each module returned by `"$DRAFT_TOOLS/graph-arch.sh" --repo . | jq '.packages[]'`, produce a subsection whose **primary content** is the deterministic graph block followed by one synthesized behavioral diagram. Every module gets a slot; do not sample. The block's fan-in/out and node counts come from `.packages[]`; public API and key call edges come from live per-package queries (`"$DRAFT_TOOLS/graph-callers.sh"`, `"$DRAFT_TOOLS/graph-impact.sh"`) and `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .`.
279
290
 
280
291
  #### 7.{N} {module-name}
281
292
 
@@ -362,7 +373,7 @@ Regardless of tier, any directory whose name contains `ops`, `handlers`, `execut
362
373
  | ... | (enumerate ALL — no sampling, no "and others") | | | |
363
374
  ```
364
375
 
365
- Use `scripts/tools/graph-callers.sh --symbol <module>` or `scripts/tools/graph-arch.sh --repo .` to get the complete file list. Use `scripts/tools/hotspot-rank.sh --repo .` to flag high-complexity operations.
376
+ Use `"$DRAFT_TOOLS/graph-callers.sh" --symbol <module>` or `"$DRAFT_TOOLS/graph-arch.sh" --repo .` to get the complete file list. Use `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .` to flag high-complexity operations.
366
377
 
367
378
  #### Example: Full Sub-Module Treatment for `icebox/` (917 files)
368
379
 
@@ -516,10 +527,10 @@ Include architecturally significant implementations (high fan-in, core extension
516
527
  | (enumerate ALL — use hotspot-rank.sh and graph-callers.sh / get_architecture for file list and line counts) |
517
528
  ```
518
529
 
519
- > **MANDATORY (graph data)**: Query `scripts/tools/graph-arch.sh --repo .` or
520
- > `scripts/tools/graph-callers.sh --symbol <module>` to get the complete file list with line counts.
530
+ > **MANDATORY (graph data)**: Query `"$DRAFT_TOOLS/graph-arch.sh" --repo .` or
531
+ > `"$DRAFT_TOOLS/graph-callers.sh" --symbol <module>` to get the complete file list with line counts.
521
532
  > Filter for files in operation sub-directories (paths containing `/ops/`,
522
- > `/handlers/`, `/executors/`, `/workers/`). Use `scripts/tools/hotspot-rank.sh --repo .` to flag
533
+ > `/handlers/`, `/executors/`, `/workers/`). Use `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .` to flag
523
534
  > high-complexity operations (high line count or fanIn). Do NOT skip this step — incomplete
524
535
  > catalogs cause AI agents to reinvent existing functionality.
525
536
 
@@ -1214,7 +1225,7 @@ Fix: Cross-reference ALL data sources (Appendix B), ALL implementation outputs (
1214
1225
 
1215
1226
  **FAILURE 4 — Missing Sub-Modules:**
1216
1227
  Detection: A module with 100+ source files (check graph data) has no Sub-Module Structure table.
1217
- Fix: Query `scripts/tools/graph-arch.sh --repo .` or `scripts/tools/graph-callers.sh --symbol <name>`, group results by immediate sub-directory, and generate the table with file counts and one-line role descriptions per sub-directory.
1228
+ Fix: Query `"$DRAFT_TOOLS/graph-arch.sh" --repo .` or `"$DRAFT_TOOLS/graph-callers.sh" --symbol <name>`, group results by immediate sub-directory, and generate the table with file counts and one-line role descriptions per sub-directory.
1218
1229
 
1219
1230
  **FAILURE 4b — Shallow Sub-Module Treatment:**
1220
1231
  Detection: Large sub-modules (50+ files) listed only as table rows with no dedicated deep-dive subsection. Or ops/handler directories have no operation catalog.