@drafthq/draft 3.5.3 → 3.7.1

package/skills/draft/SKILL.md

@@ -7,7 +7,7 @@ description: "Lists Draft's canonical workflow commands, explains the Context-Dr
 
 Draft is a methodology for structured software development: **Context → Spec & Plan → Implement → Verify**
 
-## Red Flags - STOP if you're:
+## Red Flags - STOP if you're
 
 - Jumping straight to implementation without reading existing Draft context
 - Suggesting `/draft:implement` before a track has an approved spec and plan
@@ -22,16 +22,19 @@ Draft is a methodology for structured software development: **Context → Spec &
 ## Workflow Commands
 
 ### Canonical Workflow
-```
+
+```text
 init → plan → implement → review → upload
                ↑            |
                └────────────┘  (review auto-invoked at phase boundaries)
 ```
 
 ### Primary Workflow (Parent) Commands
+
 These 7 canonical parent commands coordinate and orchestrate the entire development lifecycle, automatically routing to specialist subcommands when appropriate.
 
 ### Routed Core Workflows (5 routers)
+
 The 5 router commands provide intent-based dispatch into the 20+ specialist commands. Use the router form for discoverability; leaf commands remain supported for compatibility.
 
 | Router | Scope | Dispatches To (examples) |
@@ -47,39 +50,45 @@ The 5 router commands provide intent-based dispatch into the 20+ specialist comm
 ---
 
 ### Specialist & Subcommands
+
 These commands remain available for targeted, specialist execution outside parent command orchestration. **Every command below appears exactly once in this reference.**
 
 #### 1. Planning & Architecture
-* `/draft:new-track` - Create a new feature/bug track with structured `spec.md` and `plan.md`
-* `/draft:decompose` - Perform module-level decomposition with dependency mapping
-* `/draft:change` - Safely manage and document mid-track requirement changes and plan updates
-* `/draft:adr` - Write Architecture Decision Records to capture permanent technical choices
+
+- `/draft:new-track` - Create a new feature/bug track with structured `spec.md` and `plan.md`
+- `/draft:decompose` - Perform module-level decomposition with dependency mapping
+- `/draft:change` - Safely manage and document mid-track requirement changes and plan updates
+- `/draft:adr` - Write Architecture Decision Records to capture permanent technical choices
 
 #### 2. Quality & Testing
-* `/draft:quick-review` - Fast, lightweight 4-dimension code review for staged changes or diffs
-* `/draft:bughunt` - Exhaustive 14-dimension codebase-wide bug hunt with verification protocol
-* `/draft:deep-review` - Rigorous module-scoped lifecycle audit (ACID compliance, resilience)
-* `/draft:coverage` - Measure and report code coverage (targeting 95%+ for changed code)
-* `/draft:testing-strategy` - Design testing plan and identify coverage/mocking strategies
-* `/draft:learn` - Discover coding patterns from recent Git diffs and update `draft/guardrails.md`
+
+- `/draft:quick-review` - Fast, lightweight 4-dimension code review for staged changes or diffs
+- `/draft:bughunt` - Exhaustive 14-dimension codebase-wide bug hunt with verification protocol
+- `/draft:deep-review` - Rigorous module-scoped lifecycle audit (ACID compliance, resilience)
+- `/draft:coverage` - Measure and report code coverage (targeting 95%+ for changed code)
+- `/draft:testing-strategy` - Design testing plan and identify coverage/mocking strategies
+- `/draft:learn` - Discover coding patterns from recent Git diffs and update `draft/guardrails.md`
 
 #### 3. Operations & Debugging
-* `/draft:status` - Display a comprehensive overview of active track phases, tasks, and modules
-* `/draft:revert` - Safely roll back active tasks or commits using Git-aware tracking
-* `/draft:debug` - Structured 4-stage debugging flow (reproduce → isolate → diagnose → fix)
-* `/draft:standup` - Summarize git activity and file changes for standup reporting
-* `/draft:deploy-checklist` - Pre-deployment checklist verification with automated rollback triggers
-* `/draft:upload` - Pre-upload gate: review, HLD approvals, validator chain, then git upload/PR
-* `/draft:incident-response` - Coordinate incident lifecycle (triage → mitigate → postmortem)
+
+- `/draft:status` - Display a comprehensive overview of active track phases, tasks, and modules
+- `/draft:revert` - Safely roll back active tasks or commits using Git-aware tracking
+- `/draft:debug` - Structured 4-stage debugging flow (reproduce → isolate → diagnose → fix)
+- `/draft:standup` - Summarize git activity and file changes for standup reporting
+- `/draft:deploy-checklist` - Pre-deployment checklist verification with automated rollback triggers
+- `/draft:upload` - Pre-upload gate: review, HLD approvals, validator chain, then git upload/PR
+- `/draft:incident-response` - Coordinate incident lifecycle (triage → mitigate → postmortem)
 
 #### 4. Setup & Documentation
-* `/draft` - Display this command overview and help reference
-* `/draft:init` - Single scope-aware entry point: builds the root-first code graph (`draft/graph/`) and project context; run at the repo root or inside any sub-module (monorepo context comes from running it at root)
-* `/draft:discover` - Phase 0 code-spike report (hotspots, mode flags, open questions) before spec freeze
-* `/draft:documentation` - Generate structured codebase documentation (API, Onboarding, Runbooks)
-* `/draft:tech-debt` - Audit technical debt across 6 key dimensions
+
+- `/draft` - Display this command overview and help reference
+- `/draft:init` - Single scope-aware entry point: builds the root-first code graph (`draft/graph/`) and project context; run at the repo root or inside any sub-module (monorepo context comes from running it at root)
+- `/draft:discover` - Phase 0 code-spike report (hotspots, mode flags, open questions) before spec freeze
+- `/draft:documentation` - Generate structured codebase documentation (API, Onboarding, Runbooks)
+- `/draft:tech-debt` - Audit technical debt across 6 key dimensions
 
 **Integration:**
+
 | Command | Purpose |
 |---------|---------|
 | `/draft:jira` | Unified Jira workflows (preview / create / review) |
@@ -123,9 +132,10 @@ flowchart TD
 ## Actionability: Command Invocation Examples
 
 ### Example 1: `/draft:status`
+
 Parses active tracks, phases, tasks, and module mappings:
 
-```
+```yaml
 PROJECT: Bookshelf API Service
 
 [track-042] OAuth2 Integration  —  [~] In Progress  (Phase 2/3, 4/9 tasks)
@@ -137,9 +147,10 @@ PROJECT: Bookshelf API Service
 ```
 
 ### Example 2: `/draft:implement`
+
 Reads `plan.md`, picks the current incomplete task, and continues it (TDD-aware):
 
-```
+```text
 Active track: [track-042] OAuth2 Integration
 Current task: [~] 2.1 Implement token generation endpoint
 TDD: on  →  writing tests/auth/token_generation_test.go (Red stage)
@@ -163,9 +174,9 @@ Used throughout `plan.md` files and referenced by the validation checkpoints abo
 
 You can also use natural language. Prefer the 5 router commands (`/draft:plan`, `/draft:ops`, `/draft:docs`, `/draft:discover`, `/draft:jira`) for grouped access; they analyze intent and dispatch.
 
-* **[quality-guide.md](./quality-guide.md)** — Quality Audit Spectrum, command choices, and coordination with external bug-hunting tools.
-* **[context-files.md](./context-files.md)** — Schema, role, and usage of each file inside the `draft/` context directory.
-* **[intent-mapping.md](./intent-mapping.md)** — Maps natural language phrasing to precise Draft commands for conversational AI usage.
+- **[quality-guide.md](./quality-guide.md)** — Quality Audit Spectrum, command choices, and coordination with external bug-hunting tools.
+- **[context-files.md](./context-files.md)** — Schema, role, and usage of each file inside the `draft/` context directory.
+- **[intent-mapping.md](./intent-mapping.md)** — Maps natural language phrasing to precise Draft commands for conversational AI usage.
 
 ---
 

package/skills/draft/context-files.md

@@ -6,7 +6,7 @@ When the `draft/` directory exists at the root of a project, the files within it
 
 All context files reside in `draft/` at your project root:
 
-```
+```text
 draft/
 ├── architecture.md       # Full human engineering reference (Source of Truth)
 ├── .ai-context.md        # Token-optimized AI context (derived automatically)
@@ -22,36 +22,43 @@ draft/
 ## Detailed File Reference
 
 ### 1. `draft/architecture.md` (Engineering Source of Truth)
+
 * **Purpose:** Comprehensive, human-readable reference detailing the system's design, domain model, services, module diagrams, and key data flows.
 * **When to read:** When designing new components, onboarding, or reviewing module boundaries.
 * **When to update:** After running decomposition, making major architectural changes, or completing an epic.
 
 ### 2. `draft/.ai-context.md` (Token-Optimized AI Context)
+
 * **Purpose:** A derived, lightweight (200-400 lines) copy of the architecture file designed specifically to maximize AI model efficiency. It omits verbose descriptions and captures essential system definitions, directory structures, and module APIs.
 * **When to read:** AI models read this automatically on every invocation to orient themselves.
 * **When to update:** Generated automatically whenever `draft/architecture.md` changes. Do not edit this file manually.
 
 ### 3. `draft/product.md` (Product & Business Vision)
+
 * **Purpose:** Defines the high-level business goals, core user personas, key workflows, success metrics, and long-term vision.
 * **When to read:** Before proposing features or starting plans, to verify alignment with business goals.
 * **When to update:** When product strategy changes or a new epic is initiated.
 
 ### 4. `draft/tech-stack.md` (Constraints & Stack Decisions)
+
 * **Purpose:** Records explicit details of the languages, frameworks, databases, libraries, deployment environment, and testing tools used. Contains absolute constraints (e.g., "No external ORMs allowed").
 * **When to read:** Before proposing libraries or deciding how to implement tasks.
 * **When to update:** When upgrading dependencies or making team-wide tech stack decisions.
 
 ### 5. `draft/workflow.md` (Work & Style Preferences)
+
 * **Purpose:** Outlines coding style conventions, test-driven development (TDD) rules, commit message guidelines, git branch naming schemes, and build scripts.
 * **When to read:** During implementation and review cycles to ensure compliance.
 * **When to update:** When adjusting developer processes, lint rules, or build tooling.
 
 ### 6. `draft/guardrails.md` (Learned Patterns & Anti-Patterns)
+
 * **Purpose:** Stores positive code conventions and negative anti-patterns discovered during development. This serves as an automated memory for the AI.
 * **When to read:** Before coding to avoid repeating common codebase-specific mistakes.
 * **When to update:** Run `/draft:learn` to automatically extract rules from your Git diffs or write them manually when discovering a repeated bug.
 
 ### 7. `draft/tracks.md` (Track Registry)
+
 * **Purpose:** Registers all active, completed, and blocked tracks (feature or bug fixes). Contains IDs, descriptions, and current status markers.
 * **When to read:** Before planning new work to prevent duplication, or when generating status reports.
 * **When to update:** Automatically updated by `/draft:plan` and `/draft:status`.

package/skills/draft/quality-guide.md

@@ -16,26 +16,34 @@ This guide helps you choose the most effective quality control and review comman
 ## Command Decision Guide
 
 ### 1. Fast Feedback / Pre-Commit Sanity Check
+>
 > [!TIP]
 > Use **`/draft:quick-review`** when you want a fast, lightweight sanity check of your modified files before opening a PR or running full reviews.
+
 - **When to run:** Before staging changes, during local development loops.
 - **Why:** Zero setup, rapid turnaround, checks standard dimensions (security, performance, styling).
 
 ### 2. Track Completion & Pull Request Quality Gate
+>
 > [!IMPORTANT]
 > Use **`/draft:review`** (the canonical review command) when you finish a development phase or an entire track.
+
 - **When to run:** Before submitting work for final PR approval.
 - **Why:** It validates the implementation directly against the active track's `spec.md` and `plan.md` to ensure all acceptance criteria and quality gates are met. It also auto-invokes coverage checks when TDD is active.
 
 ### 3. Debugging Hard-to-Find Defects or Refactoring
+>
 > [!WARNING]
 > Use **`/draft:bughunt`** if you are encountering elusive bugs, regression errors, or before refactoring a legacy module.
+
 - **When to run:** Prior to refactoring complex areas, or when users report intermittent production bugs.
 - **Why:** Conducts a deep, 14-dimension sweep specifically designed to surface edge cases, race conditions, memory leaks, and logic flaws.
 
 ### 4. Shipping Core Infrastructure to Production
+>
 > [!CAUTION]
 > Use **`/draft:deep-review`** before launching a critical service, API, database layer, or high-throughput component.
+
 - **When to run:** Before major deployments or architectural sign-offs.
 - **Why:** Audits the architecture for ACID compliance, concurrency safety, fault tolerance, rate limiting, and telemetry, providing a formal readiness score.
 
@@ -45,7 +53,7 @@ This guide helps you choose the most effective quality control and review comman
 
 Many AI tools and editors provide built-in bug-hunting agents (such as Claude Code's native `bughunt` or other automated scanners). Draft's quality commands are designed to be **complementary**:
 
-* **Built-in Agents:** Typically focus on fast, generic static analysis, automated linting, and rapid parallel auto-fixes.
-* **Draft Quality Commands:** Leverage project-specific context (including `draft/architecture.md`, `draft/product.md`, `draft/tech-stack.md`, and `draft/guardrails.md`). This eliminates false positives and ensures findings align with your specific domain constraints, team conventions, and technical stack choices.
+- **Built-in Agents:** Typically focus on fast, generic static analysis, automated linting, and rapid parallel auto-fixes.
+- **Draft Quality Commands:** Leverage project-specific context (including `draft/architecture.md`, `draft/product.md`, `draft/tech-stack.md`, and `draft/guardrails.md`). This eliminates false positives and ensures findings align with your specific domain constraints, team conventions, and technical stack choices.
 
 For maximum quality assurance, run built-in scanners in parallel with Draft commands!

package/skills/graph/SKILL.md

@@ -7,7 +7,7 @@ description: Initialize or refresh the knowledge-graph snapshot for a repository
 
 Initialize or refresh the `draft/graph/` knowledge-graph snapshot for a single repository. This is the narrow "give me a fresh structural graph" command — it does **not** generate `architecture.md`/`.ai-context.md` and does **not** re-inject doc diagram slots (both are `/draft:init`). For scope-aware, root-first graph memory across a monorepo (root spine + module→root links), use `/draft:init --graph-only`.
 
-## Red Flags - STOP if you're:
+## Red Flags - STOP if you're
 
 - Reporting counts without actually running `graph-snapshot.sh`
 - Claiming the graph is built when the engine was unavailable
@@ -37,7 +37,7 @@ echo "Target repo: $REPO_ABS"
 # Locate Draft's bundled helpers. Skills run with cwd = the user's project and
 # ${CLAUDE_PLUGIN_ROOT} is not exported into skill Bash, so resolve DRAFT_TOOLS here
 # and call helpers as "$DRAFT_TOOLS/<tool>.sh". See core/shared/tool-resolver.md.
-DRAFT_TOOLS="$(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/impact/SKILL.md

@@ -7,7 +7,8 @@ description: Generate a project-wide impact report on Draft track delivery — p
 
 Generate a project-wide impact report measuring Context-Driven Development effectiveness across all tracks.
 
-## Red Flags - STOP if you're:
+## Red Flags - STOP if you're
+
 - Profiling code coverage instead of measuring track-level impact.
 - Rewriting tracker logic when local state objects are available for inspection.
 - Generating reports without reading existing track metadata first.
@@ -21,7 +22,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"
@@ -92,6 +93,7 @@ Every impact/telemetry report must end with a `## Next Actions` section listing
 ```
 
 Rules:
+
 - Impact reports are advisory — `Blocker? = no` is the default; mark `yes` only when a metric breach demands immediate process change.
 - Suggest `/draft:tech-debt` for systemic friction, `/draft:adr` for methodology adjustments, `/draft:tour` for onboarding gaps.
 - Cap at 7 actions.

package/skills/implement/SKILL.md

@@ -15,7 +15,7 @@ It owns the common execution loop and absorbs three adjacent commands when appro
 - `/draft:coverage`
 - `/draft:revert`
 
-## Red Flags - STOP if you're:
+## Red Flags - STOP if you're
 
 - Implementing without an approved spec and plan
 - Skipping TDD cycle when workflow.md has TDD enabled
@@ -139,7 +139,7 @@ If one of these applies, route directly to the specialist workflow and stop this
    ```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"
@@ -152,9 +152,11 @@ If one of these applies, route directly to the specialist workflow and stop this
 10. Update the track's entry in `draft/tracks.md` from `[ ]` to `[~]` In Progress
 
 If no active track found:
+
 - Tell user: "No active track found. Run `/draft:plan` to create or resume planned work."
 
 **Architecture / Design Mode Activation:**
+
 - Automatically enabled when `.ai-context.md`, graph-primary `architecture.md`, or track `hld.md`/`lld.md` exists.
 - Project-level context from `/draft:init`.
 - Track-level design docs from `/draft:decompose`.
@@ -168,21 +170,25 @@ Run once, before the first task of a new track:
 ### AC Coverage Check
 
 For each acceptance criterion in `spec.md`:
+
 - Verify at least one task in `plan.md` references or addresses it
 - If an AC has no corresponding task, flag it: "⚠️ AC: '[criterion]' has no task in plan.md"
 
 ### Sync Check (if `.ai-context.md` exists)
 
 Compare the `synced_to_commit` values in the YAML frontmatter of `spec.md` and `plan.md`.
+
 - **Skip if** either file has no YAML frontmatter or no `synced_to_commit` field (quick-mode tracks omit it).
 - If they differ: "⚠️ Spec and plan were synced to different commits — verify they are still aligned."
 
 ### Result
 
 **Issues found:** List them, then ask:
-```
+
+```text
 Readiness issues found (see above). Proceed anyway or update first? [proceed/update]
 ```
+
 - `proceed` → add a `## Notes` entry in `plan.md` listing the issues, then continue to Step 2
 - `update` → stop here and let the user refine spec or plan before re-running
 
@@ -201,7 +207,8 @@ Before starting TDD cycle for the first task:
 ### Bug Track Test Guardrail
 
 If track type is `bugfix` (from metadata.json):
-```
+
+```text
 BEFORE writing any test file:
   ASK: "This is a bug fix track. Want me to write tests as part of the fix? [Y/n]"
   If declined: skip TDD cycle, note in plan.md: "Tests: developer-handled"
@@ -210,12 +217,14 @@ BEFORE writing any test file:
 ## Step 2: Find Next Task
 
 Scan `plan.md` for the first uncompleted task:
+
 - `[ ]` = Pending (pick this one)
 - `[~]` = In Progress (resume this one)
 - `[x]` = Completed (skip)
 - `[!]` = Blocked (skip - requires manual intervention)
 
 **IMPORTANT:** If blocked task found, notify user:
+
 - "Task [task description] is marked `[!]` Blocked"
 - Show the blocked task details and recovery message
 - "Resolve the blockage manually before continuing implementation"
@@ -274,7 +283,7 @@ When the next task involves creating or substantially modifying a code file:
 
 ### Story Format
 
-```
+```text
 // Story: [Module/File Name]
 //
 // Input:  [what this module/function receives]
@@ -320,7 +329,8 @@ Study the control flow for the task and propose intermediate state variables:
 5. Propose execution state: input state, intermediate state, output state, error state
 
 Present in this format:
-```
+
+```text
 EXECUTION STATE: [Task/Module Name]
 ─────────────────────────────────────────────────────────
 Input State:
@@ -435,12 +445,13 @@ For each task, follow this workflow based on `workflow.md`. If skeletons were ge
 
 When refactoring code that lacks tests, write characterization tests first to capture current behavior as a baseline. Identify seams (interfaces for test doubles, swappable imports), record actual outputs for representative inputs, then proceed with the TDD cycle for new behavior.
 
-### If TDD Enabled:
+### If TDD Enabled
 
 **Iron Law:** No production code without a failing test first.
 
 **3a. RED - Write Failing Test**
-```
+
+```text
 1. Create/update test file as specified in task
 2. Write test that captures the requirement
 3. RUN test - VERIFY it FAILS (not syntax error, actual assertion failure)
@@ -449,6 +460,7 @@ When refactoring code that lacks tests, write characterization tests first to ca
 ```
 
 **Test Quality Checklist (REQUIRED for every test):**
+
 - No shared mutable state between test cases — each test sets up its own state
 - Assertion density: every test must have at least one meaningful assertion (not just `assertTrue(true)`)
 - No logic in tests: no conditionals, loops, or try/catch in test code — tests should be trivially readable
@@ -461,7 +473,8 @@ When refactoring code that lacks tests, write characterization tests first to ca
 After writing example-based tests, consider property-based tests for pure functions (algebraic properties, round-trip serialization, sort invariants). Not mandatory — skip if properties are not obvious.
 
 **3b. GREEN - Implement Minimum Code**
-```
+
+```text
 1. Write MINIMUM code to make test pass (no extras)
 2. RUN test - VERIFY it PASSES
 3. Show test output with pass
@@ -475,7 +488,8 @@ Structured logging at decision points, metrics for latency-sensitive ops, tracin
 For new API endpoints or service-to-service interfaces, suggest consumer-driven contract tests. Skip for purely internal modules.
 
 **3c. REFACTOR - Clean with Tests Green**
-```
+
+```text
 1. Review code for improvements
 2. Refactor while keeping tests green
 3. RUN all related tests after each change
@@ -484,15 +498,17 @@ For new API endpoints or service-to-service interfaces, suggest consumer-driven
 ```
 
 **Red Flags - STOP and restart the cycle if:**
+
 - About to write code before test exists
 - Test passes immediately (testing wrong thing)
 - Thinking "just this once" or "too simple to test"
 - Running tests mentally instead of actually executing
 
-### If TDD Not Enabled:
+### If TDD Not Enabled
 
 **3a. Implement**
-```
+
+```text
 1. Implement the task as specified
 2. Test manually or run existing tests
 3. Announce: "Implementation complete"
@@ -571,6 +587,7 @@ Before marking ANY task/phase/track complete:
    - If **YES**: Show evidence, then mark `[x]`
 
 **Red Flags - STOP if you're thinking:**
+
 - "Should pass", "probably works"
 - Satisfaction before running verification
 - About to mark `[x]` without fresh evidence from this session
@@ -588,16 +605,19 @@ When all tasks in a phase are `[x]`:
 ### Three-Stage Review (REQUIRED)
 
 **Stage 1: Automated Validation**
+
 - Fast static checks: architecture conformance, dead code, circular dependencies, performance anti-patterns. Review for common security anti-patterns (OWASP top 10). For automated checks, use language-specific tools (e.g., `npm audit` for JS, `bandit` for Python, `cargo audit` for Rust).
 - **If critical issues found:** List them, return to implementation
 
 **Stage 2: Spec Compliance** (only if Stage 1 passes)
+
 - Load track's `spec.md`
 - Verify all requirements for this phase are implemented
 - Check acceptance criteria coverage
 - **If gaps found:** List them, return to implementation
 
 **Stage 3: Code Quality** (only if Stage 2 passes)
+
 - Verify code follows project patterns (tech-stack.md)
 - Check error handling is appropriate
 - Verify tests cover real logic
@@ -608,12 +628,14 @@ See `core/agents/reviewer.md` for detailed review process.
 ### Quick Review Alternative
 
 At phase boundaries, offer the lightweight alternative:
-```
+
+```text
 "Phase {N} complete. Review options:
   1. Full three-stage review (recommended) — spec compliance + security + quality
   2. /draft:quick-review — lightweight 4-dimension check (faster)
   Choose [1/2, default: 1]:"
 ```
+
 If quick-review chosen, invoke `/draft:quick-review` with the phase's changed files.
 
 2. Run verification steps from plan (tests, builds)
@@ -632,19 +654,23 @@ If quick-review chosen, invoke `/draft:quick-review` with the phase's changed fi
 After a phase passes review, refresh `metadata.json.impact` so future tracks can detect overlap with this work.
 
 1. **Compute touched files:** From `plan.md`, find the first commit SHA recorded for this track (earliest `[x]` line with `(<sha>)`). Run:
+
    ```bash
    git diff --name-only <first_sha>^..HEAD
    ```
+
    That is the `files_touched` list. Derive `modules_touched` as the unique top-level path segments (e.g. `auth/login.go` → `auth`).
 
 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):
+
    ```bash
-   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"
    "$DRAFT_TOOLS/graph-impact.sh" --repo . --file <path>
    ```
+
    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.
 
 3. **Write metadata.json** with the populated `impact` block and `computed_at` set to the current timestamp.
@@ -658,10 +684,12 @@ When all phases complete:
 1. **Run review (if enabled):**
    - Read `draft/workflow.md` review configuration
    - Check if auto-review enabled:
+
      ```markdown
      ## Review Settings
      - [x] Auto-review at track completion
      ```
+
    - If enabled, run `/draft:review track <track_id>`
    - Check review results:
      - If block-on-failure enabled AND critical issues found → HALT, require fixes
@@ -687,6 +715,7 @@ When all phases complete:
 "Track <track_id> completed!
 
 Summary:
+
 - Phases: N/N
 - Tasks: M/M
 - Duration: [if tracked]
@@ -702,6 +731,7 @@ Next: Run `/draft:status` to see project overview."
 ## Error Handling
 
 **If blocked:**
+
 - Mark task as `[!]` Blocked
 - Add reason in plan.md
 - **REQUIRED:** Follow systematic debugging process (see `core/agents/debugger.md`)
@@ -713,18 +743,22 @@ Next: Run `/draft:status` to see project overview."
 - Document root cause when found
 
 **Recommended:** Instead of inline debugging, invoke `/draft:debug` skill for a structured session:
-```
+
+```text
 "Task blocked: {description}. Run /draft:debug for structured investigation? [Y/n]"
 ```
+
 The debug skill provides: Reproduce → Isolate → Diagnose → Fix methodology with debug report output.
 
 **If test fails unexpectedly:**
+
 - Don't mark complete
 - Follow systematic debugging process above
 - Announce failure details with root cause analysis
 - Show evidence when resolved
 
 **If unsure about implementation:**
+
 - Ask clarifying questions
 - Reference spec.md for requirements
 - Don't proceed with assumptions
@@ -748,6 +782,7 @@ When you encounter a shortcut, workaround, or known-imperfect solution during im
 ```
 
 **Severity levels:**
+
 - **Low** — Cosmetic or minor maintainability issue
 - **Medium** — Will cause problems at scale or in specific scenarios
 - **High** — Actively impeding development or risking production issues
@@ -761,7 +796,8 @@ Only log genuine debt — intentional shortcuts with known consequences. Not eve
 ## Progress Reporting
 
 After each task, report:
-```
+
+```yaml
 Task: [description]
 Status: Complete
 Phase Progress: N/M tasks
@@ -777,34 +813,40 @@ Overall: X% complete
 After announcing track completion, suggest relevant follow-ups based on context:
 
 **If track modifies production code:**
-```
+
+```text
 "Track complete! Consider:
   → /draft:deploy-checklist — Pre-deployment verification"
 ```
 
 **If track added new APIs/services/components:**
-```
+
+```text
   → /draft:documentation — Update documentation for new components"
 ```
 
 **If implementation contains TODO/FIXME/HACK comments:**
-```
+
+```text
   → /draft:tech-debt — Catalog any new technical debt introduced"
 ```
 
 **If new patterns or dependencies not in tech-stack.md:**
-```
+
+```text
   → /draft:adr — Document this design decision"
 ```
 
 ### Jira Sync at Completion
 
 If Jira ticket linked, sync via `core/shared/jira-sync.md`:
+
 - Post comment: "[draft] implementation-complete: All {n} tasks done. Ready for review."
 
 ### Bug Track with rca.md
 
 If implementing a bug track and `draft/tracks/<id>/rca.md` exists:
+
 - Load rca.md as context for the implementation
 - Reference root cause, blast radius, and prevention items during fix
 - After fix: update rca.md "Proposed Fix" section with actual fix details