@drafthq/draft 3.5.3 → 3.7.1

package/skills/review/references/zero-setup-mode.md

@@ -0,0 +1,117 @@
+# Zero-Setup Review Mode
+
+Full contract for running `/draft:review` on a repo that has never been indexed. Loaded when Step 0 detects no `draft/` directory.
+
+## Why this mode exists
+
+`/draft:init` is a multi-phase, token-heavy analysis. Requiring it before the first review puts the expensive step in front of the cheap one, so a new user pays before seeing anything. Zero-setup mode inverts that: review the diff now with whatever can be established from the code itself, then name precisely what indexing would have added.
+
+The mode is a **reduction in evidence, never a reduction in rigor**. Every finding still requires a file, a line, and a reason. A finding you cannot ground in the diff is not reported — degraded mode is not license to guess at structure the graph would have told you.
+
+## Detection
+
+```bash
+ls draft/ 2>/dev/null            # absent  -> zero-setup mode
+ls draft/graph/schema.yaml       # absent  -> graph-less (may still have prose context)
+```
+
+Three states, and they are independent:
+
+| `draft/` | `draft/graph/schema.yaml` | Mode |
+|---|---|---|
+| absent | absent | **zero-setup** — this document |
+| present | absent | **graph-less** — prose context, no structural queries |
+| present | present | full three-stage review |
+
+Never print "Draft not initialized" and stop. That error is reserved for skills that genuinely cannot function without context (`/draft:learn`, `/draft:deep-review`, `/draft:tech-debt`, `/draft:implement`).
+
+## Scope resolution without tracks
+
+Track auto-detection needs `draft/tracks.md`, which does not exist. Resolve scope from git alone, first match wins:
+
+1. Explicit `files <pattern>` or `commits <range>` argument → use it.
+2. Uncommitted changes present (`git diff HEAD --shortstat` non-empty) → review those.
+3. Current branch diverges from the default branch → review `<default>...HEAD`.
+
+   ```bash
+   default="$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')"
+   default="${default:-$(git config --get init.defaultBranch || echo main)}"
+   git diff --shortstat "$default...HEAD"
+   ```
+
+4. Neither → review the last commit (`git show --stat HEAD`), and say that is what you did.
+5. Empty repository → the one legitimate stop. Print: `No changes to review. Make a change, or run /draft:review commits <range>.`
+
+## Stage behavior
+
+| Stage | Zero-setup behavior |
+|---|---|
+| **1. Automated Validation** | Runs. Detect the test/lint/type-check commands from the manifest present in the repo (`package.json` scripts, `Makefile` targets, `pyproject.toml`, `Cargo.toml`, `go.mod`). Run what is discoverable; report each as run/failed/not-found. Never invent a command. |
+| **1.5. HLD/LLD conformance** | Skipped — no design docs exist. |
+| **2. Spec Compliance** | Skipped — no spec exists. Do not substitute the commit message for a spec; say the stage was skipped and why. |
+| **3. Code Quality** | Runs, all four dimensions (security, correctness, performance, maintainability), against plugin guardrails only (`core/guardrails/review-checks.md`, `security.md`, `language-standards.md` for the detected stack). |
+| **Adversarial pass** | Runs, and is still mandatory on zero findings. Fewer inputs make a false "clean" more likely, not less. |
+
+Guardrail citations still apply — `[SEC-03]`, `[RC-012]`. They come from the plugin, not the project, so they are available with no setup.
+
+## What degrades, precisely
+
+State these as limitations in the report rather than silently omitting them:
+
+| Unavailable | Consequence for this review |
+|---|---|
+| Blast radius (`graph-impact.sh`) | Cannot say what else breaks. Severity of a signature change is judged from the diff only, so a breaking change with distant callers may read as Minor. |
+| Caller enumeration (`graph-callers.sh`) | Cannot enumerate downstream callers of a modified public symbol. |
+| Fan-in hotspot ranking (`hotspot-rank.sh`) | Cannot flag "you just edited the most-depended-on file in the repo." |
+| Cycle detection | Cannot detect a newly introduced dependency cycle. |
+| Module boundary check `[RC-013]` | Cannot verify the change respects intended module boundaries. |
+| `draft/guardrails.md` | Project-specific learned conventions and anti-patterns are unknown, so findings that a team has already accepted as intentional may appear as issues. |
+| `tech-stack.md` Accepted Patterns | Deliberate trade-offs are not suppressed — expect a higher false-positive rate. |
+| Spec / acceptance criteria | No verdict on whether the change does what was asked. |
+
+The false-positive caveat is the honest one to surface: without Accepted Patterns and learned conventions, some findings will be things the team decided on purpose.
+
+## Output
+
+**Render the report in the conversation. Write no files.** A user evaluating the tool has not asked for artifacts in their repo, and an unrequested `draft/` write is exactly the friction this mode removes.
+
+Header (replaces the standard git-metadata frontmatter, which assumes a report file):
+
+```text
+Review — zero-setup mode
+Scope:   <what was reviewed, and how it was chosen>
+Context: none (draft/ not present)
+Graph:   unavailable
+Checks:  <test/lint commands run, or "none discoverable">
+```
+
+Then Stage 1 results, Stage 3 findings grouped by severity, and the limitations table above trimmed to what actually mattered for this diff.
+
+If the user asks to save it, write `.draft-review/review-report-<timestamp>.md` (`date +%Y-%m-%dT%H%M`) and tell them the path. Do not create `draft/` — that directory is `/draft:init`'s to own.
+
+## Closing call to action
+
+End every zero-setup review with a concrete, quantified upgrade line. Name real numbers from this run, not a generic pitch:
+
+```text
+Found <N> issues in <M> files (<C> Critical, <I> Important, <m> Minor).
+
+Not checked: blast radius, downstream callers, dependency cycles, module
+boundaries, and your project's own accepted patterns.
+
+  /draft:init      index this repo (one time) — adds the structural checks above
+  /draft:review    re-run with them enabled
+```
+
+If the review found nothing, the CTA is the same but framed on coverage rather than count: say which structural checks never ran, so "clean" is not overclaimed.
+
+## Anti-patterns specific to this mode
+
+| Don't | Instead |
+|---|---|
+| Stop with "Draft not initialized" | Review the diff, then invite indexing |
+| Claim blast radius or hotspot findings without the graph | Say the check did not run |
+| Report "no issues found" without the adversarial pass | Run it — thin input raises the bar, not lowers it |
+| Write into `draft/` to store the report | Render inline; `.draft-review/` only on request |
+| Pitch `/draft:init` generically | Name the specific checks this diff missed |
+| Treat the commit message as a spec | Mark Stage 2 skipped |

package/skills/standup/SKILL.md

@@ -7,7 +7,7 @@ description: Generate standup summary from git history, track progress, and Jira
 
 You are generating a standup summary from recent development activity. This is a **read-only** skill — it makes no changes to the codebase or track files.
 
-## Red Flags — STOP if you're:
+## Red Flags — STOP if you're
 
 - Modifying any files (this is read-only)
 - Fabricating activity that didn't happen
@@ -42,6 +42,7 @@ If `draft/` exists, read and follow `core/shared/draft-context-loading.md`.
 ## Step 1: Parse Arguments
 
 Check for arguments:
+
 - `/draft:standup` — Default: last 24 hours of activity
 - `/draft:standup <days>` — Activity from last N days
 - `/draft:standup weekly` — Full week summary (Monday-Friday)
@@ -54,7 +55,7 @@ Check for arguments:
 **Preferred:** invoke `parse-git-log.sh` — it parses conventional commits into structured JSONL `{sha,type,scope,track_id,subject,author,timestamp,files_changed}`, eliminating ambiguity in `type(track-id): subject` parsing. 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"
@@ -68,6 +69,7 @@ fi
 ```
 
 Parse commit messages for:
+
 - Track IDs (from `type(track-id): description` convention — already extracted as `track_id` in JSONL)
 - Task completions
 - Bug fixes
@@ -76,6 +78,7 @@ Parse commit messages for:
 ### Source 2: Track Progress (if draft context exists)
 
 Read `draft/tracks.md` for active tracks:
+
 - Current status and phase
 - Tasks completed since last standup
 - Blockers (tasks marked `[!]`)
@@ -85,6 +88,7 @@ Read `draft/tracks.md` for active tracks:
   [core/shared/template-contract.md](../../core/shared/template-contract.md).
 
 For each active track, read `plan.md` to determine:
+
 - Tasks completed (count `[x]` with recent commit SHAs)
 - Current task (first `[ ]` or `[~]`)
 - Phase progress
@@ -92,6 +96,7 @@ For each active track, read `plan.md` to determine:
 ### Source 3: Jira Activity (if MCP available)
 
 If Jira MCP is available:
+
 - Query recent ticket transitions (status changes)
 - Check for new comments or assignments
 - Pull sprint board status
@@ -99,6 +104,7 @@ If Jira MCP is available:
 ### Source 4: GitHub Activity (if MCP available)
 
 If GitHub MCP is available:
+
 - Query open reviews authored by user
 - Check for new review comments received
 - Query recently merged changes
@@ -110,6 +116,7 @@ tail -50 ~/.draft/metrics.jsonl 2>/dev/null
 ```
 
 If the file exists and has records in the standup period, enrich the standup with skill activity:
+
 - **implement** records: count tasks completed, note TDD pass/fail rate
 - **review** records: note reviews run and their verdicts
 - **bughunt** records: note bug hunts run and critical counts
@@ -154,6 +161,7 @@ Format using the standard Yesterday/Today/Blockers structure:
 Present the standup summary directly in the conversation. Do not write to any file unless explicitly requested.
 
 If the user asks to save:
+
 - Save to `draft/standup-<date>.md`
 - Symlink: `draft/standup-latest.md`
 

package/skills/status/SKILL.md

@@ -7,7 +7,7 @@ description: Display current progress of Draft tracks and active tasks. Shows ph
 
 Display a comprehensive overview of project progress.
 
-## Red Flags - STOP if you're:
+## Red Flags - STOP if you're
 
 - Reporting status without actually reading the files
 - Making up progress percentages
@@ -44,7 +44,7 @@ Display a comprehensive overview of project progress.
 If `parse-reports.sh` and `freshness-check.sh` are available, gather structured signals to enrich the status output (severity counts per track, stale `draft/` docs). 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"
@@ -66,7 +66,7 @@ Check each track's `metadata.json` `type` field to determine display format.
 
 ### Standard (multi-phase) tracks
 
-```
+```yaml
 ---
                       DRAFT STATUS
 ---
@@ -95,7 +95,7 @@ ACTIVE TRACKS
 
 Quick-mode tracks use flat task numbering (`Task 1:`, `Task 2:`) without phases. Display them with a flat task list instead of the phase-grouped tree:
 
-```
+```json
 [track-id-3] Quick Feature
   Status: [~] In Progress
   Type: quick
@@ -111,7 +111,7 @@ Do **not** show `Phase: X/Y` for quick-mode tracks — they have no phases.
 
 ### Remaining sections (shared by both formats)
 
-```
+```text
 MODULES (if architecture.md exists)
 ---
 Module A [x] Complete (Coverage: 96.2%)
@@ -161,7 +161,7 @@ When `.ai-context.md` or `architecture.md` exists for a track (track-level or pr
 
 ## If No Tracks
 
-```
+```yaml
 ---
                       DRAFT STATUS
 ---
@@ -177,7 +177,7 @@ Get started:
 
 ## If Not Initialized
 
-```
+```text
 Draft not initialized in this project.
 
 Run /draft:init to initialize.

package/skills/tech-debt/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` (e.g. `scan-markers.sh`) is still primary for TODO/FIXME marker discovery — markers are source-text, not graph-derived. The graph governs **prioritization**, the marker scan governs **discovery**.
 
-## 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:
+
 - Flagging intentional design choices as debt (check tech-stack.md accepted patterns first)
 - Cataloging debt without understanding the business context
 - Setting priorities without considering team capacity
@@ -95,7 +96,7 @@ For TODO/FIXME/HACK/XXX/DEPRECATED markers, prefer the deterministic `scan-marke
 ```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"
@@ -236,6 +237,7 @@ Organize findings into three actionable tiers:
 Items that can be fixed in a single sprint or less. Do these first — they deliver the best return on investment.
 
 For each item:
+
 - Specific fix description
 - Estimated time (hours)
 - Suggested assignee pattern (e.g., "whoever touches this module next")
@@ -245,6 +247,7 @@ For each item:
 Items requiring dedicated effort. Create via `/draft:new-track` or route via `/draft:jira` (or `/draft:plan "tech debt remediation"`).
 
 For each item:
+
 - Scope and approach
 - Estimated effort (sprints)
 - Dependencies and sequencing
@@ -279,6 +282,7 @@ ln -sf tech-debt-report-${TIMESTAMP}.md draft/tech-debt-report-latest.md
 ```
 
 Report structure:
+
 1. **Executive Summary** — Total findings by category and priority tier, headline stats
 2. **Priority Matrix** — Table of all findings sorted by priority score
 3. **Category Details** — Per-category findings with file locations and evidence
@@ -298,6 +302,7 @@ Every tech-debt report must end with a `## Next Actions` section listing the sma
 ```
 
 Rules:
+
 - Tech-debt rarely "blocks" merge; mark `Blocker? = yes` only for items that will cause an outage on next deploy.
 - Suggest `/draft:new-track` for items >1 day of work, `/draft:adr` for design re-decisions, `/draft:implement` for surgical cleanups.
 - Cap at 10 actions; full backlog stays in the report body.
@@ -315,6 +320,7 @@ If `draft/graph/schema.yaml` does not exist, set `Graph files queried: NONE` and
 ## Graph Usage Report (append to debt 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
 
 - **Offered by:** `/draft:new-track` (refactor tracks — scope the debt before planning)

package/skills/testing-strategy/SKILL.md

@@ -7,7 +7,7 @@ description: Design test strategies and test plans with coverage targets. Comple
 
 You are designing a testing strategy and test plan for this project or track.
 
-## Red Flags — STOP if you're:
+## Red Flags — STOP if you're
 
 - Writing a strategy without understanding the codebase
 - Setting unrealistic coverage targets (100% is rarely appropriate)
@@ -61,13 +61,16 @@ Read and follow the base procedure in `core/shared/draft-context-loading.md`.
    - CLI tools
 
 2. **Discover existing tests:**
+
    ```bash
    find . -name "*test*" -o -name "*spec*" | head -50
    ```
+
    Identify: test frameworks, test directories, existing coverage config, test runners.
 
 3. **Assess current coverage:**
    Check for existing coverage reports or configuration:
+
    ```bash
    ls coverage/ .nyc_output/ htmlcov/ .coverage 2>/dev/null
    ```
@@ -85,7 +88,7 @@ Read and follow the base procedure in `core/shared/draft-context-loading.md`.
 
 Tailor to the project architecture:
 
-```
+```text
         ┌─────────┐
         │ E2E │ Few, critical paths only
         ├─────────┤
@@ -111,6 +114,7 @@ Adjust the pyramid shape per architecture. A microservices backend may need a wi
 ### Coverage Targets
 
 Set realistic targets based on component criticality:
+
 - **Critical paths** (from .ai-context.md INVARIANTS): 95%+
 - **Business logic**: 85-90%
 - **Utilities/helpers**: 80%
@@ -121,6 +125,7 @@ Set realistic targets based on component criticality:
 ### Test Quality Guidelines
 
 Coverage alone is insufficient. Include guidance on:
+
 - **Assertion density:** At least one meaningful assertion per test (not just "doesn't throw")
 - **Boundary testing:** Edge cases, empty inputs, max values, off-by-one
 - **Error paths:** Test failure modes, not just happy paths
@@ -131,6 +136,7 @@ Coverage alone is insufficient. Include guidance on:
 ## Step 4: Gap Analysis
 
 Compare current state to targets:
+
 1. Run test discovery to count existing tests per module
 2. Identify modules with zero test coverage
 3. Identify critical paths (from INVARIANTS) without integration tests
@@ -157,6 +163,7 @@ Priority test cases to write, ordered by impact:
 7. Performance tests for latency-sensitive paths
 
 For each priority test, specify:
+
 - **What:** Description of the test scenario
 - **Why:** Which invariant, anti-pattern, or flow it protects
 - **How:** Test type (unit/integration/E2E), framework, key assertions
@@ -178,6 +185,7 @@ Include the report header table immediately after frontmatter:
 ```
 
 Save to:
+
 - Project-wide: `draft/testing-strategy.md`
 - Track-scoped: `draft/tracks/<id>/testing-strategy.md`
 

package/skills/tour/SKILL.md

@@ -7,7 +7,8 @@ description: Interactive onboarding walkthrough for a new engineer. Use for "giv
 
 Provide an interactive codebase walk-through based on existing architecture and guardrail constraints.
 
-## Red Flags - STOP if you're:
+## Red Flags - STOP if you're
+
 - Dumping the entire `architecture.md` into the chat window.
 - Giving answers to foundational pattern questions before prompting the developer to guess.
 - Explaining code the developer hasn't explicitly asked to view yet.

package/skills/upload/SKILL.md

@@ -7,11 +7,12 @@ description: Pre-upload gate for track handoff. Verifies review status, HLD appr
 
 Gate track completion before `git upload`, `git push`, or opening a PR for human review.
 
-## Red Flags — STOP if you're:
+## Red Flags — STOP if you're
 
 See [shared red flags](../../core/shared/red-flags.md).
 
 Skill-specific:
+
 - Uploading without a passing `/draft:review` on the track
 - Skipping HLD §Approvals for `criticality ∈ {high, mission-critical}` tracks
 - Treating a deploy checklist with `status: BLOCKED` as passing
@@ -52,7 +53,7 @@ Run the WS-9 chain from [verification-gates.md](../../core/shared/verification-g
 
 ```bash
 TRACK_DIR="draft/tracks/<id>"
-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"
@@ -115,4 +116,4 @@ Update `draft/tracks/<id>/metadata.json`:
 
 ## Graph Usage Report
 
-Emit the canonical footer from [graph-usage-report.md](../../core/shared/graph-usage-report.md) when graph queries were used during validation.
+Emit the canonical footer from [graph-usage-report.md](../../core/shared/graph-usage-report.md) when graph queries were used during validation.