@drafthq/draft 2.7.0

package/skills/docs/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: docs
+description: "Primary router for authoring and documentation workflows. Analyzes intent and dispatches primarily to documentation (technical docs, readme, runbook, api, onboarding). Use when the user needs to generate or update project documentation."
+---
+
+# Docs - Authoring & Documentation Router
+
+`/draft:docs` provides a single namespace for all documentation generation and maintenance tasks.
+
+## When to Use
+
+- Generating or refreshing README, API docs, runbooks, or onboarding guides
+- Producing technical documentation from existing architecture and code context
+- Keeping documentation in sync after implementation or review phases
+
+## Routing Logic
+
+Currently focused on the documentation specialist. Future expansion may include additional authoring helpers under the same router.
+
+| User Intent Keywords                        | Dispatches To         | Purpose |
+|---------------------------------------------|-----------------------|---------|
+| write docs, documentation, readme, runbook, api docs, onboarding guide, generate docs | `/draft:documentation` | Technical documentation authoring (readme, runbook, api, onboarding) |
+
+## Dispatch Examples
+
+User: "write a README for the new service"
+
+→ dispatches to `/draft:documentation readme`
+
+User: "generate an API reference and runbook for the billing module"
+
+→ dispatches to `/draft:documentation api runbook`
+
+User: "create onboarding guide for new engineers"
+
+→ dispatches to `/draft:documentation onboarding`
+
+## Notes
+
+The documentation command reads heavily from `draft/architecture.md`, `draft/.ai-context.md`, `draft/product.md`, and `draft/tech-stack.md` (plus graph artifacts when present).
+
+Prefer `/draft:docs` going forward for all authoring requests. The legacy direct form remains for compatibility (see migration guidance).

package/skills/documentation/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: documentation
+description: Technical documentation writing and maintenance. Modes — readme, runbook, api, onboarding. Uses writer agent principles for audience-appropriate, maintainable docs.
+---
+
+# Documentation
+
+You are generating or updating technical documentation for this project using structured writing principles.
+
+## Red Flags — STOP if you're:
+
+- Writing docs without reading the code first
+- Duplicating information that exists elsewhere (link instead)
+- Writing docs for internal implementation details (only public interfaces)
+- Ignoring the target audience (developer vs operator vs new hire)
+- Generating a wall of text without structure or examples
+
+**Write for the reader. Link don't duplicate. Show don't tell.**
+
+---
+
+## Pre-Check
+
+1. Check for Draft context:
+```bash
+ls draft/ 2>/dev/null
+```
+
+If `draft/` doesn't exist, this skill works standalone — generate docs from code analysis.
+
+2. Follow the base procedure in `core/shared/draft-context-loading.md`.
+
+## Step 1: Parse Arguments
+
+- `/draft:documentation readme` — Generate or update project README
+- `/draft:documentation runbook <service>` — Operations runbook for a service
+- `/draft:documentation api <module>` — API documentation for a module
+- `/draft:documentation onboarding` — New developer onboarding guide
+- `/draft:documentation` (no args) — Interactive: ask what type of documentation
+
+## 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
+- Read `draft/workflow.md` — Development workflow, commands
+- 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
+- If GitHub MCP available: check recent deployment changes
+- 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?
+  3. `draft/architecture.md` or `draft/.ai-context.md` — How is it structured?
+  4. `draft/workflow.md` — How do I develop?
+  5. `draft/guardrails.md` — What to watch out for?
+- Scan for setup scripts, Docker configs, environment templates
+
+## Step 3: Apply Writing Principles
+
+Follow these principles (from `core/agents/writer.md`):
+
+1. **Write for the reader** — Identify the audience (developer, operator, new hire) and tailor language, depth, and examples accordingly
+2. **Start with the most useful information** — Lead with what the reader needs most (setup for README, troubleshooting for runbook, endpoints for API)
+3. **Show don't tell** — Use code examples, command snippets, and diagrams over prose descriptions
+4. **Progressive disclosure** — Start simple, add detail progressively. Don't front-load every edge case
+5. **Link don't duplicate** — Reference existing docs, don't copy them. Single source of truth
+6. **Keep current** — Reference source of truth files. Note: "Generated from draft context on {date}"
+
+## Step 4: Generate Document
+
+### README Structure
+```markdown
+# {Project Name}
+
+{One-line description from product.md}
+
+## Quick Start
+{Setup commands from Makefile/package.json}
+
+## Architecture
+{High-level diagram from .ai-context.md}
+
+## Development
+{Commands from workflow.md}
+
+## Testing
+{Test commands and conventions}
+
+## Contributing
+{Workflow conventions}
+```
+
+### Runbook Structure
+```markdown
+# Runbook: {Service Name}
+
+## Overview
+{Service purpose, dependencies, SLOs}
+
+## Health Checks
+{Endpoints, expected responses}
+
+## Common Issues
+{Symptoms → diagnosis → resolution}
+
+## Deployment
+{Steps, rollback procedure}
+
+## Monitoring
+{Dashboard URLs, alert descriptions}
+
+## Escalation
+{On-call contacts, escalation paths}
+```
+
+### API Documentation Structure
+```markdown
+# API: {Module Name}
+
+## Overview
+{Purpose, authentication, base URL}
+
+## Endpoints
+
+### {METHOD} {path}
+{Description}
+**Request:** {body/params with examples}
+**Response:** {status codes with examples}
+**Errors:** {error codes and meanings}
+```
+
+### Onboarding Structure
+```markdown
+# Welcome to {Project Name}
+
+## What is this?
+{From product.md — 2-3 sentences}
+
+## Architecture at a Glance
+{Simplified from .ai-context.md}
+
+## Getting Started
+{Setup steps, first 15 minutes}
+
+## Key Concepts
+{Domain terms, important patterns}
+
+## Development Workflow
+{From workflow.md}
+
+## Where to Find Things
+{File structure guide}
+
+## Common Pitfalls
+{From guardrails.md}
+```
+
+## Step 5: Output
+
+Save to:
+- README: `README.md` in project root
+- Runbook: `draft/docs/runbook-<service>.md`
+- API: `draft/docs/api-<module>.md`
+- Onboarding: `draft/docs/onboarding.md`
+
+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).
+
+Present generated doc to user for review before final save.
+
+## Cross-Skill Dispatch
+
+- **Suggested by:** `/draft:init` (after context generation), `/draft:implement` (track completion with new APIs), `/draft:upload` (pre-upload for new APIs), `/draft:decompose` (module API docs)
+- **Jira sync:** If ticket linked, attach doc and post comment via `core/shared/jira-sync.md`
+
+## Error Handling
+
+**If no draft context:** Generate from code analysis alone, note: "Run `/draft:init` for richer documentation"
+**If existing doc found:** Show diff between existing and generated, ask: "Update existing doc or create new? [update/new]"

package/skills/draft/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: draft
+description: "Lists Draft's canonical workflow commands, explains the Context-Driven Development flow (init, plan, implement, review), and recommends the appropriate next step. Use when the user asks about available Draft commands, needs help choosing a workflow step, or says 'what can Draft do', 'help', or 'show commands'."
+---
+
+# Draft - Context-Driven Development
+
+Draft is a methodology for structured software development: **Context → Spec & Plan → Implement → Verify**
+
+## 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
+- Not checking `draft/tracks.md` for existing active tracks before creating new ones
+- Skipping the recommended command and going freeform
+- Ignoring existing `.ai-context.md`, `product.md`, `tech-stack.md`, or `workflow.md` context
+
+**Read context first. Follow the workflow.**
+
+---
+
+## Workflow Commands
+
+### Canonical Workflow
+```
+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) |
+|--------|-------|--------------------------|
+| `/draft:plan` | Planning & architecture | new-track, decompose, adr, tech-debt, change |
+| `/draft:ops` | Operations & lifecycle | deploy-checklist, incident-response, standup, status, revert |
+| `/draft:docs` | Authoring | documentation |
+| `/draft:discover` | Investigation & quality | debug, bughunt, quick/deep-review, coverage, testing-strategy, learn, index, tour, impact, assist-review |
+| `/draft:jira` | Jira integration (preview, create, review) | - |
+
+### Specialist Commands (leaf skills, invoked via routers or directly)
+
+---
+
+### 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
+
+#### 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`
+
+#### 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)
+
+#### 4. Setup & Documentation
+* `/draft` - Display this command overview and help reference
+* `/draft:index` - Aggregate multi-service context in monorepo structures
+* `/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) |
+
+---
+
+## Core Workflow: Validation & Recovery Loop
+
+To maintain code quality and delivery velocity, the Core Workflow operates as a closed-loop feedback system with explicit validation checkpoints and recovery actions.
+
+```mermaid
+flowchart TD
+    A[Start: /draft:init] --> B[Plan: /draft:plan /new-track]
+    B --> C{Plan Valid?}
+    C -- "No (Revise Plan)" --> B
+    C -- "Yes (Approve Spec)" --> D[Implement: /draft:implement]
+
+    D --> E{Tests Pass & Spec Met?}
+    E -- "No (Debug/Fix)" --> D
+    E -- "Yes (Verify)" --> F[Review: /draft:review]
+
+    F --> G{Quality Gates Passed?}
+    G -- "No (Reject)" --> H[Analyze Feedback & Recover]
+    H -- "If Blocked" --> I[Mark Blocked [!] / ADR / Decompose]
+    H -- "If Scope Drifted" --> J[Run /draft:change]
+    H -- "If Code Defects" --> D
+
+    G -- "Yes (Ship)" --> K[Ops: /draft:ops /deploy-checklist]
+```
+
+### Validation Checkpoints & Recovery Actions
+
+| Checkpoint | Criteria | Recovery |
+|---|---|---|
+| **1. Planning** | Track ID in `draft/tracks.md`; `scope_includes`/`scope_excludes` set; acceptance criteria stated; task checklist in `plan.md` with `[ ]` markers. | Requirements or design drifted → `/draft:change`. |
+| **2. Implementation / TDD** | Code compiles; unit + integration tests pass; coverage ≥95% for changed lines. | Blocked by external/architectural constraints → mark task `[!]`, then `/draft:adr` or `/draft:decompose`. Build/test failure → `/draft:debug` (do not bypass). |
+| **3. Quality Gate / Review** | All change-scoped gates in `/draft:review` pass; when TDD is on, coverage gate auto-runs. | Review failed → fix flagged items, run `/draft:bughunt` if structural issues suspected, then re-run `/draft:review`. |
+
+---
+
+## Actionability: Command Invocation Examples
+
+### Example 1: `/draft:status`
+Parses active tracks, phases, tasks, and module mappings:
+
+```
+PROJECT: Bookshelf API Service
+
+[track-042] OAuth2 Integration  —  [~] In Progress  (Phase 2/3, 4/9 tasks)
+  [x] 1.1 Design OAuth database schema
+  [x] 1.2 Generate migration files
+  [~] 2.1 Implement token generation endpoint   ← CURRENT
+  [ ] 2.2 Add authorization middleware
+  [!] 2.3 Integrate third-party providers       (Blocked: API key pending)
+```
+
+### Example 2: `/draft:implement`
+Reads `plan.md`, picks the current incomplete task, and continues it (TDD-aware):
+
+```
+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)
+Test failed as expected → proceeding to implementation.
+```
+
+---
+
+## Status Markers
+
+Used throughout `plan.md` files and referenced by the validation checkpoints above:
+
+| Marker | Meaning |
+|--------|---------|
+| `[ ]` | Pending |
+| `[~]` | In Progress |
+| `[x]` | Completed |
+| `[!]` | Blocked |
+
+---
+
+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.
+
+---
+
+## Need Help?
+
+- Run `/draft` (this command) for a high-level overview.
+- Run `/draft:status` to inspect current tracks and task completion rates.
+- Check `draft/tracks/<track_id>/spec.md` for functional requirements.
+- Check `draft/tracks/<track_id>/plan.md` for technical task details.

package/skills/draft/context-files.md

@@ -0,0 +1,57 @@
+# Draft Context Files Reference
+
+When the `draft/` directory exists at the root of a project, the files within it serve as the codebase's central nervous system. These context files establish shared understanding, guardrails, and track progress between the developer, the team, and AI agents.
+
+## The Core Context Directory
+
+All context files reside in `draft/` at your project root:
+
+```
+draft/
+├── architecture.md       # Full human engineering reference (Source of Truth)
+├── .ai-context.md        # Token-optimized AI context (derived automatically)
+├── product.md            # Product vision, goals, and business requirements
+├── tech-stack.md         # Technical stack, constraints, and dependencies
+├── workflow.md           # TDD instructions, commit styles, and workflows
+├── guardrails.md         # Team conventions, rules, and discovered anti-patterns
+└── tracks.md             # Active feature and bug track registry
+```
+
+---
+
+## 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/intent-mapping.md

@@ -0,0 +1,37 @@
+# Draft Intent Mapping Guide
+
+Draft commands can be invoked using natural language. If you describe your goal or ask a question, Draft will map your intent to the correct canonical or specialist command.
+
+## Natural Language Intent Mapping
+
+| What you say or want to do... | Resolved Draft Command | Primary Purpose |
+|:---|:---|:---|
+| "set up the project", "initialize draft", "start setup" | `/draft:init` | Bootstrap Draft in a new project |
+| "plan this feature", "scope this work", "start a track" | `/draft:plan` | Planning coordinator (routes to new-track/change) |
+| "new feature", "add search", "create new task list" | `/draft:plan` | Parent intent routing to `/draft:new-track` |
+| "decompose this", "break into modules", "split service" | `/draft:decompose` | Model decomposition with dependency mapping |
+| "requirements changed", "scope drift", "update spec" | `/draft:change` | Safely update active plan and spec |
+| "document decision", "create ADR", "architectural choice" | `/draft:adr` | Record permanent engineering decisions |
+| "continue planning", "next planning step" | `/draft:plan` | Keep planning in an active session |
+| "start implementing", "begin coding", "write some code" | `/draft:implement` | Canonical implementation workflow |
+| "continue task", "implement next step", "keep coding" | `/draft:implement` | Continue work on the active task checklist |
+| "what is the progress", "track status", "show task list" | `/draft:status` | View progress, active phases, and blocked items |
+| "check coverage", "coverage report", "test coverage" | `/draft:coverage` | Measure code coverage (target 95%+) |
+| "undo changes", "revert commit", "rollback implementation" | `/draft:revert` | Git-aware safety rollback for active tasks |
+| "review my code", "check quality", "run review" | `/draft:review` | Canonical change-scoped review |
+| "quick review", "fast check", "sanity check" | `/draft:quick-review` | Parent-routed lightweight review for files/diffs |
+| "hunt bugs", "find defects", "check for crashes" | `/draft:bughunt` | Exhaustive codebase-wide bug sweep |
+| "deep review", "production readiness audit", "acid audit" | `/draft:deep-review` | Module-scoped ACID compliance and resilience audit |
+| "review handoff", "prepare for PR", "create review handoff" | `/draft:review assist` | Generate detailed review context for humans/agents |
+| "learn patterns", "update guardrails", "discover conventions" | `/draft:learn` | Discover coding conventions and update guardrails |
+| "debug this issue", "investigate test failure", "fix crash" | `/draft:debug` | Structured 4-stage debugging workflow |
+| "deploy checklist", "release checks", "pre-flight checks" | `/draft:deploy-checklist` | Pre-deployment verification checklist |
+| "test strategy", "design test suite", "testing targets" | `/draft:testing-strategy` | Design standard testing plan |
+| "tech debt analysis", "catalog debt", "code debt" | `/draft:tech-debt` | Technical debt audit across 6 dimensions |
+| "weekly standup", "what did I do today", "activity summary" | `/draft:standup` | Summarize recent Git and file contributions |
+| "incident", "production outage", "mitigate bug" | `/draft:incident-response` | Triage, mitigation, and postmortem incident flow |
+| "write docs", "create readme", "api documentation" | `/draft:documentation` | Generate professional, structured docs |
+| "preview jira", "export jira issues", "jira draft" | `/draft:jira-preview` | Generate Jira markdown export from plan |
+| "create jira", "push to jira board" | `/draft:jira-create` | Create actual Jira issues via MCP integrations |
+| "index services", "aggregate context", "monorepo setup" | `/draft:index` | Aggregate multi-service context at the root |
+| "build graph", "refresh graph", "rebuild the knowledge graph", "index this repo's structure" | `/draft:graph` | Initialize/refresh the `draft/graph/` snapshot (optionally `draft graph <path>`) |

package/skills/draft/quality-guide.md

@@ -0,0 +1,51 @@
+# Draft Quality Gate & Review Decision Guide
+
+This guide helps you choose the most effective quality control and review commands for your codebase. Draft provides an **audit spectrum** that scales from quick, change-scoped checks to deep, service-wide production readiness reviews.
+
+## The Quality Audit Spectrum
+
+| Command | Scope | Analysis Time | Primary Objective | Key Outputs |
+|:---|:---|:---|:---|:---|
+| `/draft:quick-review` | File / PR / Diff | ~2 min | "Are there any obvious issues or regressions in this change?" | 4-dimension findings (Style, Bugs, Security, Performance) with severity rankings. |
+| `/draft:review` | Change-scoped (Track, Diff, Commits) | ~10 min | "Does this track implementation meet the spec, coverage targets, and quality gates?" | Three-stage review report with verification verdict, automatic coverage verification, and quality gate sign-off. |
+| `/draft:bughunt` | Codebase-scoped (Repo, paths, or active track) | ~20 min | "What deep, hidden, or structural bugs exist in this code?" | Exhaustive 14-dimension bug report, verification protocol, and automated regression tests (when a framework exists). |
+| `/draft:deep-review` | Module-scoped (Single service or component) | ~30 min | "Is this component resilient, secure, observable, and fully ready for production?" | Production-grade audit across ACID compliance, reliability, observability, and concrete implementation specifications. |
+
+---
+
+## 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.
+
+---
+
+## Relationship to Built-in Bug Hunt Agents
+
+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.
+
+For maximum quality assurance, run built-in scanners in parallel with Draft commands!