@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.
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/.cursor-plugin/plugin.json +28 -0
- package/README.md +2 -2
- package/cli/src/hosts/cursor.js +35 -5
- package/cli/src/installer.js +20 -0
- package/cli/src/lib/cursor-registry.js +122 -0
- package/cli/src/lib/marker.js +93 -0
- package/cli/src/lib/plugin-manifest.js +20 -0
- package/core/methodology.md +1 -1
- package/core/shared/condensation.md +3 -2
- package/core/shared/git-report-metadata.md +3 -2
- package/core/shared/graph-query.md +4 -3
- package/core/shared/tool-resolver.md +71 -4
- package/core/templates/okf/ai-context-index.md +48 -0
- package/core/templates/okf/concept.md +54 -0
- package/core/templates/okf/index.md +40 -0
- package/core/templates/okf/section-index.md +25 -0
- package/core/templates/plan.md +3 -2
- package/integrations/agents/AGENTS.md +792 -102
- package/integrations/copilot/.github/copilot-instructions.md +792 -102
- package/package.json +3 -2
- package/scripts/lib.sh +10 -0
- package/scripts/tools/graph-preflight.sh +259 -0
- package/scripts/tools/okf-render-views.sh +373 -0
- package/scripts/tools/okf-validate.sh +204 -0
- package/scripts/tools/resolve-tools.sh +78 -0
- package/skills/adr/SKILL.md +3 -2
- package/skills/bughunt/SKILL.md +10 -1
- package/skills/coverage/SKILL.md +8 -3
- package/skills/debug/SKILL.md +16 -5
- package/skills/decompose/SKILL.md +29 -12
- package/skills/deep-review/SKILL.md +19 -6
- package/skills/deploy-checklist/SKILL.md +6 -5
- package/skills/graph/SKILL.md +15 -6
- package/skills/impact/SKILL.md +12 -1
- package/skills/implement/SKILL.md +20 -4
- package/skills/init/SKILL.md +36 -10
- package/skills/init/references/architecture-spec.md +17 -6
- package/skills/init/references/okf-emitter.md +223 -0
- package/skills/learn/SKILL.md +15 -4
- package/skills/quick-review/SKILL.md +13 -3
- package/skills/review/SKILL.md +32 -8
- package/skills/standup/SKILL.md +3 -2
- package/skills/status/SKILL.md +3 -2
- package/skills/tech-debt/SKILL.md +20 -6
- package/skills/upload/SKILL.md +3 -2
- package/integrations/copilot/.github/copilot-instructions.md.7iDz8X +0 -91
- package/integrations/copilot/.github/copilot-instructions.md.DoBdtd +0 -91
- package/integrations/copilot/.github/copilot-instructions.md.McGoBW +0 -122
- package/integrations/copilot/.github/copilot-instructions.md.VsPyLB +0 -91
- package/integrations/copilot/.github/copilot-instructions.md.XAVr7D +0 -91
- package/integrations/copilot/.github/copilot-instructions.md.YoFVFa +0 -91
- package/integrations/copilot/.github/copilot-instructions.md.a9DeW0 +0 -91
- package/integrations/copilot/.github/copilot-instructions.md.oxQs3B +0 -91
- package/integrations/copilot/.github/copilot-instructions.md.ww33Ly +0 -91
package/skills/bughunt/SKILL.md
CHANGED
|
@@ -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) —
|
|
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
|
package/skills/coverage/SKILL.md
CHANGED
|
@@ -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="$
|
|
37
|
-
[ -d "$DRAFT_TOOLS" ] || DRAFT_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
|
-
#
|
|
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
|
```
|
package/skills/debug/SKILL.md
CHANGED
|
@@ -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 `
|
|
15
|
-
2. Use `
|
|
16
|
-
3. Use `
|
|
17
|
-
4. Run `
|
|
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 `
|
|
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 `
|
|
15
|
-
2. Run `
|
|
16
|
-
3. Use `
|
|
17
|
-
4. Run `
|
|
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 `
|
|
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 `
|
|
163
|
-
- **Per-module detail**: query `
|
|
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
|
-
|
|
408
|
-
|
|
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 `
|
|
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
|
-
|
|
652
|
-
|
|
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
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
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
|
-
|
|
322
|
-
|
|
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 `
|
|
15
|
-
2. Run `
|
|
16
|
-
3. Run `
|
|
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="$
|
|
71
|
-
[ -d "$DRAFT_TOOLS" ] || DRAFT_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=$?
|
package/skills/graph/SKILL.md
CHANGED
|
@@ -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 !
|
|
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
|
-
|
|
54
|
+
"$DRAFT_SCRIPTS/fetch-memory-engine.sh" || true
|
|
46
55
|
fi
|
|
47
56
|
|
|
48
|
-
ENGINE="$(
|
|
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
|
-
|
|
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
|
-
|
|
84
|
+
"$DRAFT_TOOLS/hotspot-rank.sh" --repo "$REPO_ABS" --top 5
|
|
76
85
|
|
|
77
86
|
echo "--- Cycles ---"
|
|
78
|
-
|
|
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 \
|
package/skills/impact/SKILL.md
CHANGED
|
@@ -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 `
|
|
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
|
-
|
|
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 `
|
|
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
|
-
|
|
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
|
|
package/skills/init/SKILL.md
CHANGED
|
@@ -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
|
|
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
|
-
|
|
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=$(
|
|
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
|
-
- `
|
|
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 `
|
|
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
|
-
|
|
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 `
|
|
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
|
-
|
|
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
|
-
- `
|
|
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 (`
|
|
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
|
-
|
|
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 `
|
|
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 `
|
|
520
|
-
> `
|
|
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 `
|
|
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 `
|
|
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.
|