@drafthq/draft 3.5.3 → 3.7.1

package/skills/change/SKILL.md

@@ -7,7 +7,7 @@ description: Handle mid-track requirement changes. Analyzes impact on completed
 
 You are handling a mid-track requirement change using Draft's Context-Driven Development methodology.
 
-## Red Flags - STOP if you're:
+## Red Flags - STOP if you're
 
 - Applying changes to spec.md or plan.md without showing the user what will change first
 - Invalidating `[x]` completed tasks without flagging them explicitly
@@ -38,11 +38,13 @@ Extract from `$ARGUMENTS`:
 ### Default Behavior
 
 If no `track <id>` specified:
+
 - Auto-detect the active `[~]` In Progress track from `draft/tracks.md`
 - If no `[~]` track, find the first `[ ]` Pending track
 - Display: `Auto-detected track: <id> - <name>` before proceeding
 
 If no change description provided:
+
 - Error: "Usage: `/draft:change <description>` or `/draft:change track <id> <description>`"
 
 ---
@@ -73,7 +75,8 @@ For each requirement and acceptance criterion, classify the effect:
 | **Unaffected** | No change needed |
 
 Produce a concise impact list. Example:
-```
+
+```text
 Spec impact:
 - AC #2 "User can export to CSV" → Modified (now also requires JSON format)
 - AC #5 "Export limited to 1000 rows" → Removed (no row limit)
@@ -81,6 +84,7 @@ Spec impact:
 ```
 
 **HLD impact** (only when `hld.md` exists):
+
 - §Architecture / Component Diagram — does the change introduce new modules or alter integration edges?
 - §Detailed Design — does any per-component subsection need updating, or are new components introduced?
 - §Dependencies — new/removed dependent components?
@@ -89,6 +93,7 @@ Spec impact:
 - §Deployment — does the deployment surface change?
 
 **LLD impact** (only when `lld.md` exists):
+
 - §Classes and Interfaces — signatures added/modified/removed?
 - §Data Model — schema changes? New fields? Migration required?
 - §Key Algorithms and Workflows — algorithm changes? New sequence diagrams needed?
@@ -97,7 +102,7 @@ Spec impact:
 
 **Re-approval flag:** If the HLD Approvals table has any signed rows (Date column populated) AND the change touches HLD structural sections (Architecture, Detailed Design, Dependencies, Checklist, IP, Deployment), surface this warning prominently:
 
-```
+```text
 ⚠️ HLD modified after sign-off — Approvals table requires re-circulation.
     Signed rows: [list which roles signed and when]
     Changed sections: [list of HLD sections impacted]
@@ -130,7 +135,7 @@ For each task in `plan.md`, determine if the spec change affects it:
 
 Display a clear summary before proposing any file changes:
 
-```
+```yaml
 Change: [change description]
 Track: <track_id> — <track_name>
 
@@ -178,7 +183,7 @@ Show before/after for each impacted LLD section. Preserve §Approvals verbatim.
 
 ## Step 7: CHECKPOINT
 
-```
+```text
 Apply these changes to spec.md and plan.md? [yes / no / edit]
 ```
 
@@ -208,7 +213,7 @@ Apply these changes to spec.md and plan.md? [yes / no / edit]
 
 4. Announce:
 
-```
+```text
 Changes applied: <track_id>
 
 Updated:
@@ -235,19 +240,22 @@ Next: /draft:implement to continue, or /draft:review to assess current state.
 ## Error Handling
 
 ### Track Not Found
-```
+
+```yaml
 Error: Track '<id>' not found.
 Run /draft:status to see available tracks.
 ```
 
 ### No Active Track
-```
+
+```yaml
 Error: No active track found.
 Use: /draft:change track <id> <description>
 ```
 
 ### No Spec or Plan
-```
+
+```yaml
 Error: Missing spec.md or plan.md for track <id>.
 Cannot perform change analysis without both files.
 ```
@@ -257,11 +265,13 @@ Cannot perform change analysis without both files.
 ## Examples
 
 ### Change description for active track
+
 ```bash
 /draft:change the export format should support JSON in addition to CSV
 ```
 
 ### Targeting a specific track
+
 ```bash
 /draft:change track add-export-feature also require a progress indicator for exports over 500 rows
 ```

package/skills/coverage/SKILL.md

@@ -7,7 +7,7 @@ description: Compute code coverage for active track or module. Targets 95%+ cove
 
 You are computing and reporting code coverage for the active track or a specific module. This complements the TDD workflow — TDD is the process (write test, implement, refactor), coverage is the measurement (how much code do those tests exercise).
 
-## Red Flags - STOP if you're:
+## Red Flags - STOP if you're
 
 - Reporting coverage without actually running the coverage tool
 - Making up coverage percentages
@@ -26,6 +26,7 @@ You are computing and reporting code coverage for the active track or a specific
 5. Check if `draft/tracks/<id>/bughunt-report-latest.md` (track scope) or `draft/bughunt-report-latest.md` (project scope) exists for cross-referencing (see Coverage-Bughunt Cross-Reference below)
 
 If no active track and no argument provided:
+
 - Tell user: "No active track. Provide a path or track ID, or run `/draft:new-track` first."
 
 ## Step 2: Detect Coverage Tool
@@ -33,7 +34,7 @@ If no active track and no argument provided:
 **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)):
 
 ```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"
@@ -54,6 +55,7 @@ If the script is unavailable or returns `framework: unknown`, fall back to the h
 | Ruby | `simplecov` |
 
 **Detection order (fallback path):**
+
 1. Check `tech-stack.md` for explicit testing section
 2. Check config files (`jest.config.*`, `vitest.config.*`, `pytest.ini`, `setup.cfg`, `pyproject.toml`, `.nycrc`)
 3. Check `package.json` scripts for coverage commands
@@ -62,6 +64,7 @@ If the script is unavailable or returns `framework: unknown`, fall back to the h
 ## Step 3: Determine Scope
 
 **Priority order:**
+
 1. If argument provided (path or module name): use as scope filter
 2. If track has `architecture.md` (or project has `.ai-context.md`) with an in-progress module: scope to that module's files
 3. If active track exists: scope to files changed in the track (use `git diff` against base branch)
@@ -75,7 +78,7 @@ Build the coverage command with the appropriate scope/filter flags.
 
 ```bash
 # Re-resolve helpers (this is a separate Bash session from Step 2).
-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"
@@ -84,6 +87,7 @@ DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
 ```
 
 If the script is unavailable or returns `tool: unsupported`:
+
 1. Execute the coverage command. Request machine-readable output when possible: `--json` for Jest, `--cov-report=json` for pytest, `-coverprofile` for Go, `--coverage-output-format json` for dotnet.
 2. Capture full output
 3. If command fails:
@@ -95,7 +99,7 @@ If the script is unavailable or returns `tool: unsupported`:
 
 Parse coverage output and present in a standardized format:
 
-```
+```yaml
 ---
                      COVERAGE REPORT
 ---
@@ -151,7 +155,8 @@ For files below target (using per-module targets when configured — see Per-Mod
    - **Infrastructure** - Framework boilerplate, main entry points. Usually acceptable.
    - **Legacy/Brownfield** - Modules with 0% or very low coverage that need refactoring. Apply Characterization Testing (see below).
 3. **Suggest tests** for testable gaps:
-   ```
+
+   ```text
    SUGGESTED TESTS
    ─────────────────────────────────────────────────────────
    1. Test malformed JWT token handling (jwt.ts:45-52)
@@ -174,7 +179,8 @@ When encountering modules with 0% or very low coverage that need refactoring, do
 5. **Remove approval tests** — Once proper unit test coverage meets the target, retire the Golden Master tests.
 
 **Tool references:**
-- ApprovalTests (https://approvaltests.com/) — available for Java, C#, Python, JS, and more
+
+- ApprovalTests (<https://approvaltests.com/>) — available for Java, C#, Python, JS, and more
 - Verify (.NET) — snapshot testing library
 
 Present characterization testing recommendations in the gap analysis when applicable.
@@ -191,11 +197,11 @@ After measuring line coverage (and branch coverage if applicable), prompt the en
 
 | Language | Tool | Reference |
 |----------|------|-----------|
-| Java | PIT | https://pitest.org/ |
-| JavaScript/TypeScript | Stryker | https://stryker-mutator.io/ |
+| Java | PIT | <https://pitest.org/> |
+| JavaScript/TypeScript | Stryker | <https://stryker-mutator.io/> |
 | Python | mutmut | (Mutation testing tool) |
 | Rust | cargo-mutants | (Mutation testing tool) |
-| C# | Stryker.NET | https://stryker-mutator.io/ |
+| C# | Stryker.NET | <https://stryker-mutator.io/> |
 | Go | go-mutesting | (Mutation testing tool) |
 
 **Reference:** Google's mutation testing program is used by 6,000+ engineers and processes approximately 30% of all code diffs, validating that mutation testing scales to large codebases.
@@ -209,7 +215,8 @@ If a bughunt report exists (`draft/tracks/<id>/bughunt-report-latest.md` or `dra
 1. **Parse bughunt findings** — Extract file paths and line ranges of confirmed or suspected bugs.
 2. **Cross-reference with uncovered code paths** — Identify bughunt findings that fall in uncovered lines.
 3. **Flag as highest-priority test gaps** — Confirmed bugs in uncovered code are the most dangerous gaps. Present them prominently:
-   ```
+
+   ```text
    BUGHUNT CROSS-REFERENCE
    ─────────────────────────────────────────────────────────
    ⚠ CRITICAL: Bug "Race condition in session refresh" (bughunt #3)
@@ -220,6 +227,7 @@ If a bughunt report exists (`draft/tracks/<id>/bughunt-report-latest.md` or `dra
      at src/users/repository.ts:45 — IN UNCOVERED CODE
      → Write a regression test targeting this path
    ```
+
 4. **Prioritize suggested tests** — Tests that cover bughunt-flagged code should appear first in the SUGGESTED TESTS section.
 
 ## Per-Module Coverage Enforcement
@@ -255,7 +263,8 @@ coverage_targets:
 **Classification heuristic:** Infer module risk from directory names and file content when explicit configuration is absent. Flag the inferred classification in the report so the developer can correct it.
 
 In the coverage report, show per-module targets alongside actual coverage:
-```
+
+```text
 PER-FILE BREAKDOWN (module-level targets)
 ---
 src/auth/middleware.ts 96.2% [high_risk: 95%] PASS
@@ -271,6 +280,7 @@ src/generated/api.ts — [generated: excluded]
 **STOP.** Present the full coverage report and gap analysis.
 
 Ask developer:
+
 - Accept current coverage? (if at or above target)
 - Write additional tests for testable gaps?
 - Justify and document acceptable uncovered lines?
@@ -283,17 +293,20 @@ Ask developer:
 After developer approves:
 
 1. **Update plan.md** - Add coverage note to the relevant phase:
+
    ```markdown
    **Coverage:** 96.2% (target: 95%) - PASS
    - Uncovered: defensive null checks in jwt.ts (justified)
    ```
 
 2. **Update architecture context** — update the project-level `draft/architecture.md` with coverage data (not a track-level architecture file), then run the Condensation Subroutine (defined in `core/shared/condensation.md`) to regenerate `draft/.ai-context.md`. The Condensation Subroutine only applies to the project-level `draft/architecture.md` → `draft/.ai-context.md` pipeline:
+
    ```markdown
    - **Status:** [x] Complete (Coverage: 96.2%)
    ```
 
 3. **Update metadata.json** - Add coverage field if not present:
+
    ```json
    {
      "coverage": {
@@ -307,6 +320,7 @@ After developer approves:
 4. **Write detailed coverage report** to `draft/tracks/<id>/coverage-report-<timestamp>.md` (where `<timestamp>` is generated via `date +%Y-%m-%dT%H%M`, e.g., `2026-03-15T1430`) with YAML frontmatter (include `project`, `track_id`, `generated_by: "draft:coverage"`, `generated_at`, `git` metadata matching other skills) and timestamped entries for historical tracking.
 
    After writing the timestamped report, create a symlink pointing to it:
+
    ```bash
    ln -sf coverage-report-<timestamp>.md draft/tracks/<id>/coverage-report-latest.md
    ```
@@ -316,7 +330,8 @@ After developer approves:
 ## Completion
 
 Announce:
-```
+
+```text
 Coverage report complete.
 
 Overall: [percentage]% (target: [target]%)
@@ -335,6 +350,7 @@ Results recorded in:
 ## Re-running Coverage
 
 When coverage is run again on the same track/module:
+
 1. Compare with previous results from metadata.json. If no previous coverage data found in metadata.json, skip delta comparison and report current values only.
 2. Show delta: "Coverage improved from 87.3% to 96.2% (+8.9%)"
 3. Highlight newly covered lines

package/skills/debug/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,11 +29,12 @@ When `draft/graph/schema.yaml` exists, this skill **must** follow the graph-firs
 
 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.
 
-## 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:
+
 - Making code changes before reproducing the bug
 - Guessing at the cause instead of tracing data/control flow
 - Trying multiple fixes simultaneously ("shotgun debugging")
@@ -70,6 +71,7 @@ Debug can run standalone (without draft context) or within a draft track. If `dr
 Read and follow the base procedure in `core/shared/draft-context-loading.md`.
 
 Key context for debugging:
+
 - `.ai-context.md` — Module boundaries, data flows, invariants (crucial for tracing)
 - `tech-stack.md` — Language-specific debugging tools and techniques
 - `guardrails.md` — Known anti-patterns that may be causing the issue
@@ -78,12 +80,14 @@ Key context for debugging:
 ## Step 1: Parse Arguments
 
 Check for arguments:
+
 - `/draft:debug` — Interactive: ask what's broken
 - `/draft:debug <description>` — Start with the described problem
 - `/draft:debug track <id>` — Debug within a specific track context (load spec.md, plan.md)
 - `/draft:debug <JIRA-KEY>` — Pull context from Jira ticket via MCP
 
 If a Jira ticket is provided:
+
 1. Pull ticket via Jira MCP: `get_issue()`, `get_issue_description()`, `get_issue_comments()`
 2. Extract: URLs, log paths, stack traces, reproduction steps, affected services
 3. Use `curl`/`wget` to fetch any URLs mentioned (dashboards, error pages, API responses)
@@ -111,8 +115,10 @@ Reference `core/agents/debugger.md` Phase 1 for detailed investigation technique
 1. **Trace data flow** — Follow data from input to failure point, documenting each hop with `file:line` references
 2. **Trace control flow** — Map the execution path, identify where it diverges from expected behavior
 3. **Differential analysis** — Compare working vs failing cases:
+
    | Aspect | Working Case | Failing Case | Difference |
    |--------|-------------|-------------|------------|
+
 4. **Check boundaries** — Reference `.ai-context.md` module boundaries to scope the investigation
 
 Reference `core/agents/debugger.md` Phase 2 for language-specific debugging techniques.
@@ -143,9 +149,11 @@ Reference `core/agents/debugger.md` Phase 3 and `core/agents/rca.md` for 5 Whys
 ### Test Writing Guardrail
 
 **STOP.** Before writing any test:
-```
+
+```yaml
 ASK: "Root cause confirmed: [summary]. Want me to write a regression test for this fix? [Y/n]"
 ```
+
 - If accepted: write regression test first (fails before fix, passes after)
 - If declined: note "Tests: developer-handled" and proceed to fix
 
@@ -172,6 +180,7 @@ Include the report header table immediately after frontmatter:
 ```
 
 Save to:
+
 - Track-scoped: `draft/tracks/<id>/debug-report.md`
 - Standalone: `draft/debug-report-<timestamp>.md` with symlink `debug-report-latest.md`
 
@@ -194,6 +203,7 @@ If `draft/graph/schema.yaml` does not exist, set `Graph files queried: NONE` and
 ## Graph Usage Report (append to debug 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.
+
 ## Cross-Skill Dispatch
 
 - **Auto-invoked by:** `/draft:new-track` (bug tracks — Offer tier), `/draft:implement` (blocked tasks — Offer tier)