@drafthq/draft 3.5.3 → 3.7.1

package/skills/decompose/SKILL.md

@@ -14,7 +14,7 @@ First resolve the bundled helpers:
 ```bash
 # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
 # is not exported into skill Bash). See core/shared/tool-resolver.md.
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+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"
@@ -29,7 +29,7 @@ When `draft/graph/schema.yaml` exists, this skill **must** follow the graph-firs
 
 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.
 
-## Red Flags - STOP if you're:
+## Red Flags - STOP if you're
 
 See [shared red flags](../../core/shared/red-flags.md) — applies to all code-touching skills. In particular, the **Ground-Truth Red Flags** are load-bearing for decompose: HLD/LLD are design-mandated artifacts and TBD citations on Modified modules fail review.
 
@@ -44,6 +44,7 @@ must pass clean on the regenerated set. Plan.md must back-link to
 [core/shared/discovery-schema.md](../../core/shared/discovery-schema.md).
 
 Skill-specific:
+
 - Defining modules without understanding the codebase
 - Creating modules with circular dependencies
 - Making modules too large (>3 files, excluding test files) or too small (single function)
@@ -67,6 +68,7 @@ For track-scoped decomposition, also derive the human-readable track title used
 - `{TRACK_TITLE}` — first-level heading text from the active track's `spec.md` (the `# ...` line). If `spec.md` has no H1, fall back to the `{TRACK_ID}`.
 
 Also extract from `spec.md` frontmatter:
+
 - `classification.criticality`, `classification.data_classification`, `classification.deployment_surface` — copy verbatim into hld.md frontmatter.
 - `approvers.*` — pre-fill the HLD Approvals table (tech_leads, arb_leads, cloudops_leads, qa_leads, pm_leads) and LLD Approvals table (team_leads, tech_leads, qa). If a field is empty in spec.md, leave the table cell empty — do not invent names.
 
@@ -100,6 +102,7 @@ Parse `$ARGUMENTS` for flags first, then strip them before interpreting the rema
 - `--lld` → **LLD mode** — generate Section 6 (Low-Level Design) in addition to HLD. Strip from arguments before scope detection.
 
 Scope detection (on stripped arguments):
+
 - `project` or no argument with no active track → **Project-wide** decomposition → `draft/architecture.md` + `draft/.ai-context.md`
 - Track ID or active track exists → **Track-scoped** decomposition → `draft/tracks/<id>/hld.md` (always) + `draft/tracks/<id>/lld.md` (when triggered)
 
@@ -135,25 +138,30 @@ For brownfield projects, scan the existing codebase using these concrete steps:
 ### Codebase Scanning Patterns
 
 **Directory structure** — Map top-level organization:
+
 ```bash
 ls -d src/*/ lib/*/ app/*/ packages/*/ 2>/dev/null
 ```
 
 **Entry points** — Find main files and exports:
+
 - Look for: `index.ts`, `main.ts`, `app.ts`, `mod.rs`, `__init__.py`, `main.go`
 - Check `package.json` `main`/`exports` fields, `pyproject.toml` entry points, `go.mod` module path
 
 **Existing module boundaries** — Identify by:
+
 - Directory-per-feature patterns (e.g., `src/auth/`, `src/users/`)
 - Package files (`package.json` in subdirs, `__init__.py`, `go` package declarations)
 - Barrel exports (`index.ts` re-exporting from a directory)
 
 **Dependency patterns** — Trace imports:
+
 - Search for `import` / `require` / `from` statements across source files
 - Identify which directories import from which other directories
 - Flag cross-cutting imports (e.g., `utils/` imported everywhere)
 
 **File type filters by language:**
+
 | Language | Source Extensions | Config Files |
 |----------|-------------------|--------------|
 | TypeScript/JS | `*.ts`, `*.tsx`, `*.js`, `*.jsx` | `tsconfig.json`, `package.json` |
@@ -180,6 +188,7 @@ This data is deterministic and exhaustive. The manual scanning recipes above onl
 Propose a module breakdown through dialogue:
 
 For each module, define:
+
 - **Name** - Short, descriptive identifier
 - **Responsibility** - One sentence: what this module owns
 - **Files** - Expected source files (existing or to be created)
@@ -193,6 +202,7 @@ For each module, define:
 2. Target 1-3 files per module
 3. Every module needs a clear API boundary
 4. **Minimal Coupling** — communicate through interfaces, not internals
+
 - Modules should be testable in isolation
 - Each module typically contains: API, control flow, execution state, functions
 
@@ -200,7 +210,7 @@ For each module, define:
 
 **STOP.** Present the module breakdown to the developer.
 
-```
+```yaml
 ---
                    MODULE BREAKDOWN
 ---
@@ -235,7 +245,7 @@ After modules are approved:
 
 **STOP.** Present the dependency diagram and implementation order.
 
-```
+```yaml
 ---
                  DEPENDENCY ANALYSIS
 ---
@@ -277,6 +287,7 @@ Template selection depends on scope:
 - **Track-scoped** → `core/templates/hld.md` (always) and `core/templates/lld.md` (when triggered)
 
 **Output location:**
+
 - Project-wide: Update `draft/architecture.md` with the module changes, then run the Condensation Subroutine (defined in `core/shared/condensation.md`) to regenerate `draft/.ai-context.md`.
 - Track-scoped: write to `draft/tracks/<id>/hld.md` and (when triggered) `draft/tracks/<id>/lld.md`.
 
@@ -287,6 +298,7 @@ Template selection depends on scope:
 Generate `draft/tracks/<id>/hld.md` from `core/templates/hld.md`. Populate every section that has a directive — do not ship placeholders.
 
 **Frontmatter:**
+
 - Copy git metadata from current repo state.
 - Copy `classification.*` from `spec.md` frontmatter (criticality, data_classification, deployment_surface). The HLD's `links.*` block is statically correct in `core/templates/hld.md` — do not copy it from spec.md.
 
@@ -297,6 +309,7 @@ Generate `draft/tracks/<id>/hld.md` from `core/templates/hld.md`. Populate every
 **§Requirements:** Do not duplicate `spec.md`. Verify the link references resolve to actual sections in spec.md; if a section is missing, flag it.
 
 **§High Level Design / Architecture:**
+
 - **`<!-- GRAPH:track-component-diagram -->` slot:** Render Mermaid `flowchart TD` with three subgraphs — `Track` (modules in scope from Step 3), `Existing` (existing modules this track touches per integration edges), `External` (DB, queue, 3P APIs). Label edges with transport (HTTP / RPC / queue / direct call) when non-obvious.
 - **Architecture narrative** (≤300 words). Explain how blackbox requirements map to the architecture. Name the architectural style. Justify from observable evidence.
 
@@ -307,11 +320,13 @@ Generate `draft/tracks/<id>/hld.md` from `core/templates/hld.md`. Populate every
 **§High Level Design / Alternatives Considered:** Table format. Promote any non-trivial rejected alternative to a standalone ADR via `/draft:adr` and link both ways.
 
 **§Detailed Design:**
+
 - **`<!-- GRAPH:track-component-table -->` slot:** Render one row per module from Step 3. Columns: Module, Status (`New`/`Modified`/`Existing`), Files (count + comma list), Public API count, Fan-In, Fan-Out, Complexity (`Low`/`Medium`/`High`), Primary Deps, Citation (`path:line` of entry symbol).
 - **Mandatory Citation Gate:** For every row whose Status is `Modified` or `Existing`, the Citation cell **MUST** resolve to a real `path:line` from a file you Read in this run. `TBD` is only legal for `Status: New` rows, and only when the planned file path is filled (e.g. `Citation: newscribe/server/ops/shuffle_memory_eligibility.h (planned)`). If a Modified-row Citation is unresolved, **halt** — Read the file, locate the entry symbol, and fill the cell before emitting the table. See [graph-query.md](../../core/shared/graph-query.md) §Ground-Truth Discipline rules G1 and G3.
 - **Per-component subsection:** One `#### {Component Name}` block per module. Fill Responsibility, Status, Entry point (resolved `path:line` for Modified/Existing modules), Public API link to LLD, Whitebox requirements addressed (AC IDs from spec.md), Design notes (≤200 words).
 
 **§Dependencies:**
+
 - **`<!-- GRAPH:track-dependencies -->` slot:** Render rows per cross-module integration edge of kind `call`/`import`/`event`/`shared-schema`. Columns: Dependent Component, Edge Kind, Impact Assessment (Small/Medium/Large — graph fan-in heuristic: 1–2 = Small, 3–5 = Medium, 6+ = Large), Description, Citation. The Citation column is bound by the same Mandatory Citation Gate as the component table.
 
 **§Intellectual Property, §Checklist, §Deployment, §Observability:** These are author-driven sections that the design author completes before the HLD is presented for approval. Decompose's job is to **scaffold structured TBD bullets**, not to invent claims and not to leave bare `-` placeholders.
@@ -388,11 +403,13 @@ When triggered, generate `draft/tracks/<id>/lld.md` from `core/templates/lld.md`
 **§Requirements:** Link-only to `spec.md`; list AC IDs covered by this LLD.
 
 **§Low Level Design / Classes and Interfaces:**
+
 - **`<!-- GRAPH:track-class-table -->` slot:** Render per-module table from graph public-API index. One row per public symbol. Columns: Symbol, Kind (class/iface/func/method), Signature, Visibility, Citation (`path:line`), Concurrency Notes.
 - **Mandatory Citation Gate (LLD):** Same rule as HLD §Detailed Design. For every symbol whose owning module has Status `Modified` or `Existing`, Citation must resolve to a real `path:line` from a file Read in this run. For `Status: New` symbols, Citation may be `<planned path>:<planned line or TBD>` provided the file path is concrete. A bare `TBD` cell is a halt — fix before emitting.
 - **Per-component subsection:** Public API table with full signatures, params, returns, errors, citation. Document Preconditions, Postconditions, Invariants (thread safety, idempotency, ordering).
 
 **§Low Level Design / Data Model:**
+
 - **`<!-- GRAPH:track-data-models -->` slot:** Render one block per new/modified entity. Pull proto/struct/class declarations and field metadata from the graph data-model index.
 - **Per-model subsection:** Field table (type, nullable, default, validation), Storage, Indexes/Keys, Migration path.
 
@@ -417,7 +434,7 @@ Resolve the script via the canonical tool resolver (see [core/shared/tool-resolv
 ```bash
 # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
 # is not exported into skill Bash). See core/shared/tool-resolver.md.
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+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"
@@ -432,6 +449,7 @@ Run unconditionally — idempotent if files are already clean.
 ### CHECKPOINT (MANDATORY)
 
 **STOP.** Present the generated `hld.md` (and `lld.md` if generated) to the developer. Call out:
+
 - Which graph slots were populated vs. unpopulated (and why — e.g., "no proto definitions found, GRAPH:track-data-models slot empty").
 - Whether LLD was generated, and the trigger (`--lld` flag or auto-triggered by High-complexity module X).
 - Author-driven sections that still need manual content: §IP, §Checklist (HLD), §PaaS/§UT (LLD), §Observability metrics/thresholds.
@@ -452,7 +470,7 @@ If this is a track-scoped decomposition and a `plan.md` exists:
 `core/templates/plan.md` (and tracks generated from it at template_version
 ≥ 2.0.0) wraps phase tables in:
 
-```
+```text
 <!-- DECOMPOSE:REGENERATE START -->
 ... phase tables ...
 <!-- DECOMPOSE:REGENERATE END -->
@@ -479,6 +497,7 @@ When restructuring plan.md around modules, follow these rules for existing tasks
 **Completed tasks `[x]`:** Preserve exactly as-is. Map them to the appropriate module phase. Do not rename, reorder, or modify. Add a note: `(preserved from original plan)`.
 
 **In-progress tasks `[~]`:** Map to the appropriate module phase. Flag for developer review if the task spans multiple modules:
+
 ```markdown
 - [~] **Task 2.1:** Original task description
   - ⚠ REVIEW: This task may need splitting across modules [auth] and [database]
@@ -489,6 +508,7 @@ When restructuring plan.md around modules, follow these rules for existing tasks
 **Blocked tasks `[!]`:** Preserve the blocked status and reason. Map to appropriate module. If the blocker is in a different module, add a cross-module dependency note.
 
 **Conflict handling:** If a task doesn't map cleanly to any module:
+
 1. List it under a `### Unmapped Tasks` section at the end
 2. Flag it for developer decision
 3. Never silently drop tasks
@@ -497,7 +517,7 @@ When restructuring plan.md around modules, follow these rules for existing tasks
 
 **STOP.** Present the updated plan structure.
 
-```
+```text
 PROPOSED PLAN RESTRUCTURE
 ---
 Phase 1: [Module A] (Foundation)
@@ -521,7 +541,8 @@ After applying the approved plan changes:
 ## Completion
 
 **Track-scoped announcement:**
-```
+
+```text
 Track decomposition complete.
 
 Created: draft/tracks/<id>/hld.md
@@ -547,7 +568,8 @@ Next steps:
 ```
 
 **Project-wide announcement** (when scope = project):
-```
+
+```text
 Project architecture refresh complete.
 
 Updated: draft/architecture.md
@@ -570,6 +592,7 @@ When adding new modules to the project-wide architecture:
 4. Run the Condensation Subroutine (defined in `core/shared/condensation.md`) to regenerate `draft/.ai-context.md`
 
 **Safe write pattern for architecture.md:**
+
 1. Backup `architecture.md` → `architecture.md.backup`
 2. Write changes to `architecture.md.new`
 3. Present diff for review
@@ -579,12 +602,14 @@ When adding new modules to the project-wide architecture:
 ## Updating design context
 
 **Project-wide rerun** (running `/draft:decompose` on existing `.ai-context.md` / `architecture.md`):
+
 1. Read the existing context file
 2. Ask developer what changed (new modules, removed modules, restructured boundaries)
 3. Follow the same checkpoint process for changes
 4. Update `draft/architecture.md`, preserving completed module statuses and stories, then regenerate `.ai-context.md`
 
 **Track-scoped rerun** (running `/draft:decompose <track>` on existing `hld.md` / `lld.md`):
+
 1. Read the existing HLD (and LLD if present)
 2. If the track's `spec.md` has materially changed, prefer `/draft:change` first to amend spec/plan and flag HLD/LLD impact
 3. Otherwise, regenerate the graph-fenced slots only (component diagram, component table, dependencies table, class table, data models). Author-driven sections (§IP, §Checklist, §PaaS, §UT, §Observability) and the §Approvals table are preserved verbatim
@@ -598,7 +623,7 @@ When adding new modules to the project-wide architecture:
 
 After defining module boundaries and interfaces:
 
-```
+```text
 "Decomposition complete. Consider:
 
 Testing:
@@ -614,7 +639,8 @@ Architecture:
 ### Dependency Cycle Detection
 
 If dependency analysis (Step 4) detects cycles or high coupling:
-```
+
+```text
 "Detected dependency cycles / high coupling. Consider:
   → /draft:tech-debt — Catalog architecture debt and prioritize remediation"
 ```
@@ -622,6 +648,7 @@ If dependency analysis (Step 4) detects cycles or high coupling:
 ### ADR Auto-Invocation
 
 When decomposition involves breaking a monolith, choosing module boundaries, or extracting services:
+
 - Auto-invoke: "This decomposition is a significant architectural decision. Creating ADR to document rationale."
 - Invoke `/draft:adr "Module boundary decisions for {project}"`
 
@@ -644,11 +671,13 @@ If `draft/graph/schema.yaml` does not exist, set `Graph files queried: NONE` and
 ## Graph Usage Report (append to output)
 
 Emit the canonical footer from [core/shared/graph-usage-report.md](../../core/shared/graph-usage-report.md) §Canonical footer. The lint hook `scripts/tools/check-graph-usage-report.sh` validates the section on save.
+
 ## Skill Telemetry
 
 As the last step after the completion announcement, emit a metrics record. Best-effort — never block.
 
 **Payload fields:**
+
 ```json
 {
   "skill": "decompose",
@@ -661,10 +690,11 @@ As the last step after the completion announcement, emit a metrics record. Best-
 ```
 
 **Emit call:**
+
 ```bash
 # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
 # is not exported into skill Bash). See core/shared/tool-resolver.md.
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+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"

package/skills/deep-review/SKILL.md

@@ -12,10 +12,11 @@ Perform an exhaustive end-to-end lifecycle review of a service, component, or mo
 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:
 
 First resolve the bundled helpers:
+
 ```bash
 # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
 # is not exported into skill Bash). See core/shared/tool-resolver.md.
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+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"
@@ -28,11 +29,12 @@ DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
 
 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.
 
-## Red Flags - STOP if you're:
+## Red Flags - STOP if you're
 
 See [shared red flags](../../core/shared/red-flags.md) — applies to all code-touching skills.
 
 Skill-specific:
+
 - Acting without reading the Draft context (`draft/.ai-context.md`, `draft/tech-stack.md`, `draft/product.md`)
 - Modifying production code. This command is for auditing and reporting only. Fixes should be handled in a separate implementation track.
 - Reviewing a module that was already reviewed recently, unless explicitly requested.
@@ -74,6 +76,7 @@ If `.ai-context.md` is missing, check for `draft/architecture.md` as a fallback
 ## Review Phases
 
 ### Phase 1: Context & Structural Analysis
+
 - Load Draft context following the procedure in `core/shared/draft-context-loading.md`. Use loaded context to understand intended boundaries and critical invariants.
 - **Load track HLD/LLD if any track owns this module.** Scan `draft/tracks/*/hld.md` for §Detailed Design components matching the module path. When found, extract claims from §High-Level Design / Key Design Decisions, §Checklist (Performance/Scale/Security/Resiliency/Multi-tenancy/Upgrade/Cost), §Observability, §Deployment, and any LLD §Classes and Interfaces invariants and §Error Handling policies. These claims become the design contract this audit measures against (HLD claims vs code reality).
 - **Load Learned Anti-Patterns** — If `draft/guardrails.md` exists, read the `## Learned Anti-Patterns` section before analysis begins. During the audit, when an issue matches a learned anti-pattern, prefix the finding with `[KNOWN-ANTI-PATTERN: {pattern name}]`. This separates newly discovered issues from documented recurring patterns and allows the report to recommend systemic remediation rather than isolated fixes.
@@ -124,7 +127,7 @@ Every finding in this phase must cite the relevant rule range (e.g., `[RC-008..R
   - **Latency profiles:** Are p50, p95, p99 latency targets defined and achievable?
   - **Error budget:** What percentage of the error budget has been consumed? Is the module in "protect" or "innovate" mode?
   - **Availability:** Does the module's uptime target (99.9%, 99.99%) match its actual architecture?
-  - If no SLOs are defined, recommend defining them. Reference: Google SRE (https://sre.google/sre-book/service-level-objectives/).
+  - If no SLOs are defined, recommend defining them. Reference: Google SRE (<https://sre.google/sre-book/service-level-objectives/>).
 - **Database Schema Analysis:**
   - **Missing indexes:** Queries filtering/joining on unindexed columns.
   - **Wide table scans:** SELECT * or queries without WHERE clauses on large tables.
@@ -154,6 +157,7 @@ For each HLD claim extracted in Phase 1, validate it against code:
 Surface gaps as findings with prefix `[HLD-DRIFT: §<section>]` (Important if the gap is documentation-vs-implementation drift; Critical if the code violates a stated invariant or security claim).
 
 ### Phase 4: Identify Actionable Fixes (Spec Generation)
+
 Instead of mutating the source code, translate all findings into clear, actionable requirements that a developer (or agent) can implement via Test-Driven Development.
 
 ### Phase 5: Resilience & Chaos Engineering Assessment
@@ -225,11 +229,13 @@ reviewer: "{model name from runtime}"
 **Verdict:** PASS / CONDITIONAL PASS / FAIL
 
 **Verdict criteria:**
+
 - **FAIL** = any Critical issue found.
 - **CONDITIONAL PASS** = no Critical issues but Important issues exist.
 - **PASS** = only Minor issues or no issues.
 
 Format findings as actionable tasks:
+
 ```markdown
 ### [Critical/Important/Minor] Issue Name `[RC-### or CQ-### or SEC-## if applicable]`
 **File:** path/to/file:line
@@ -245,6 +251,7 @@ Cite the most specific rule ID from `core/guardrails/review-checks.md` (RC-###),
 **For Phase 3 (Security):** Load `core/guardrails/security.md` and apply the 5-step security reasoning chain. Hard red line violations (SEC-01…SEC-10) are always Critical. Run `core/guardrails/dependency-triage.md` procedure for any dependency manifest files in the module's scope `[RC-014]`.
 
 **Constraints:**
+
 - Do not refactor code yourself.
 - Flag ambiguous fixes for human review instead of guessing.
 - If the module is too large, decompose it and review sub-modules sequentially.
@@ -272,6 +279,7 @@ Every deep-review report must end with a `## Next Actions` section listing the s
 ```
 
 Rules:
+
 - Production-blocking findings (`[SEC-*]`, ACID violations, unbounded resource use) produce blocker rows.
 - Suggest `/draft:adr` for structural changes, `/draft:new-track` for multi-week remediation, `/draft:incident-response` for hot issues, `/draft:tech-debt` for systemic items.
 - Cap at 10 actions; group related fixes under one row.
@@ -283,14 +291,16 @@ Rules:
 After deep-review audit completion:
 
 **If architecture debt found:**
-```
+
+```text
 "Architecture debt identified in module audit. Consider:
   → /draft:tech-debt — Catalog and prioritize the architecture debt
   → /draft:adr — Document undiscovered design decisions found during review"
 ```
 
 **If documentation gaps found:**
-```
+
+```text
   → /draft:documentation runbook — Generate operational runbook for this module"
 ```
 
@@ -307,11 +317,13 @@ If `draft/graph/schema.yaml` does not exist, set `Graph files queried: NONE` and
 ## Graph Usage Report (append to report)
 
 Emit the canonical footer from [core/shared/graph-usage-report.md](../../core/shared/graph-usage-report.md) §Canonical footer. The lint hook `scripts/tools/check-graph-usage-report.sh` validates the section on save.
+
 ## Skill Telemetry
 
 As the last step after saving the deep-review report, emit a metrics record. Best-effort — never block.
 
 **Payload fields:**
+
 ```json
 {
   "skill": "deep-review",
@@ -327,10 +339,11 @@ As the last step after saving the deep-review report, emit a metrics record. Bes
 ```
 
 **Emit call:**
+
 ```bash
 # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
 # is not exported into skill Bash). See core/shared/tool-resolver.md.
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+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"

package/skills/deploy-checklist/SKILL.md

@@ -17,11 +17,12 @@ When `draft/graph/schema.yaml` exists, this skill **must** follow the graph-firs
 
 Filesystem `grep` is reserved for source-text scans (migration file names, flag-key strings). Module/impact discovery goes through the graph.
 
-## Red Flags — STOP if you're:
+## Red Flags — STOP if you're
 
 See [shared red flags](../../core/shared/red-flags.md) — applies to all code-touching skills.
 
 Skill-specific:
+
 - Deploying without a rollback plan
 - Skipping database migration verification
 - Deploying on Friday without explicit team approval
@@ -67,7 +68,7 @@ by validator.
 ```bash
 TRACK_DIR="$1" # absolute path to track-under-deploy, or .
 
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+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"
@@ -87,6 +88,7 @@ not be considered "ready to deploy" if `pre_deploy_status != passing`.
 ## Step 1: Parse Arguments
 
 Check for arguments:
+
 - `/draft:deploy-checklist` — Interactive: detect active track or ask for service name
 - `/draft:deploy-checklist <service>` — Generate checklist for named service
 - `/draft:deploy-checklist track <id>` — Generate from track's change scope
@@ -111,7 +113,7 @@ Generate a four-phase checklist customized to the project's tech stack. Adapt it
 
 ### Phase 0: HLD/LLD Gate (track-scoped only, when hld.md exists)
 
-> ** blocker:** the HLD's §Checklist sections were the design-time commitment. If they are still empty at deploy time, the design was never validated against operational reality. This phase enforces that.
+> **blocker:** the HLD's §Checklist sections were the design-time commitment. If they are still empty at deploy time, the design was never validated against operational reality. This phase enforces that.
 
 For `criticality ∈ {high, mission-critical}` (read from `hld.md` frontmatter `classification.criticality`), every row below MUST be checked before Phase 1 begins. For `standard` criticality, missing rows produce warnings but do not block. For `low`, this phase is informational.
 
@@ -176,6 +178,7 @@ If a partial file is needed for tracking, write it with `status: BLOCKED` in the
 ### Rollback Triggers
 
 Initiate rollback if ANY of these occur:
+
 - Error rate exceeds 2x baseline
 - p95 latency exceeds 3x baseline
 - Data corruption detected
@@ -195,10 +198,12 @@ Initiate rollback if ANY of these occur:
 ## Step 4: Present and Track
 
 Present the checklist interactively. For each critical item (marked **bold**):
+
 - If unchecked and user wants to proceed: warn "Critical item unchecked: [item]. Are you sure? [y/N]"
 - Default: stop and address critical items
 
 Allow the user to:
+
 - Check off items as they complete them
 - Add custom items specific to this deployment
 - Mark items as N/A with justification
@@ -219,6 +224,7 @@ Include the report header table immediately after frontmatter:
 ```
 
 Save to:
+
 - Track-scoped: `draft/tracks/<id>/deploy-checklist.md`
 - Standalone: `draft/deploy-checklist-<timestamp>.md` with symlink `deploy-checklist-latest.md`
 
@@ -241,6 +247,7 @@ If `draft/graph/schema.yaml` does not exist, set `Graph files queried: NONE` and
 ## Graph Usage Report (append to checklist)
 
 Emit the canonical footer from [core/shared/graph-usage-report.md](../../core/shared/graph-usage-report.md). The lint hook `scripts/tools/check-graph-usage-report.sh` validates the section on save.
+
 ## Cross-Skill Dispatch
 
 - **Auto-invoked by:** `/draft:upload` (pre-upload verification)

package/skills/documentation/SKILL.md

@@ -7,7 +7,7 @@ description: Technical documentation writing and maintenance. Modes — readme,
 
 You are generating or updating technical documentation for this project using structured writing principles.
 
-## Red Flags — STOP if you're:
+## Red Flags — STOP if you're
 
 - Writing docs without reading the code first
 - Duplicating information that exists elsewhere (link instead)
@@ -22,6 +22,7 @@ You are generating or updating technical documentation for this project using st
 ## Pre-Check
 
 1. Check for Draft context:
+
 ```bash
 ls draft/ 2>/dev/null
 ```
@@ -41,6 +42,7 @@ If `draft/` doesn't exist, this skill works standalone — generate docs from co
 ## Step 2: Gather Source Material
 
 ### README Mode
+
 - Read existing `README.md` (if any)
 - Read `draft/product.md` — Product vision, users, goals
 - Read `draft/tech-stack.md` — Technologies, setup requirements
@@ -48,6 +50,7 @@ If `draft/` doesn't exist, this skill works standalone — generate docs from co
 - Scan for `Makefile`, `package.json`, `pyproject.toml` — Build/run commands
 
 ### Runbook Mode
+
 - Read `draft/architecture.md` or `draft/.ai-context.md` — Service topology, dependencies
 - Read `draft/workflow.md` — Deployment conventions
 - Read `draft/tech-stack.md` — Infrastructure details
@@ -55,12 +58,14 @@ If `draft/` doesn't exist, this skill works standalone — generate docs from co
 - If Jira MCP available: check recent incident tickets for the service
 
 ### API Mode
+
 - Read source code for public interfaces, exported functions, API routes
 - Read existing API docs (Swagger, OpenAPI, JSDoc, docstrings)
 - Read `draft/architecture.md` — API conventions, data models
 - Read `draft/tech-stack.md` — API framework details
 
 ### Onboarding Mode
+
 - Read ALL draft context files in order:
   1. `draft/product.md` — What is this project?
   2. `draft/tech-stack.md` — What technologies?
@@ -83,6 +88,7 @@ Follow these principles (from `core/agents/writer.md`):
 ## Step 4: Generate Document
 
 ### README Structure
+
 ```markdown
 # {Project Name}
 
@@ -105,6 +111,7 @@ Follow these principles (from `core/agents/writer.md`):
 ```
 
 ### Runbook Structure
+
 ```markdown
 # Runbook: {Service Name}
 
@@ -128,6 +135,7 @@ Follow these principles (from `core/agents/writer.md`):
 ```
 
 ### API Documentation Structure
+
 ```markdown
 # API: {Module Name}
 
@@ -144,6 +152,7 @@ Follow these principles (from `core/agents/writer.md`):
 ```
 
 ### Onboarding Structure
+
 ```markdown
 # Welcome to {Project Name}
 
@@ -172,6 +181,7 @@ Follow these principles (from `core/agents/writer.md`):
 ## Step 5: Output
 
 Save to:
+
 - README: `README.md` in project root
 - Runbook: `draft/docs/runbook-<service>.md`
 - API: `draft/docs/api-<module>.md`
@@ -180,6 +190,7 @@ Save to:
 Create `draft/docs/` directory if needed.
 
 **Pre-save validation:**
+
 - Every file path referenced in the doc resolves to a real file (broken links are a common LLM failure mode here).
 - Every relative link in the doc resolves under the project root.
 - Code blocks copied from sources match the current commit (no stale snippets).