@drafthq/draft 3.4.0 → 3.5.1

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "draft",
       "source": "./",
       "description": "Context-Driven Development: draft specs and plans before implementation. Structured workflows for features and fixes.",
-      "version": "3.4.0",
+      "version": "3.5.1",
       "author": {
         "name": "mayurpise"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "draft",
   "description": "Context-Driven Development: draft specs and plans before implementation. Structured workflows for features and fixes.",
-  "version": "3.4.0",
+  "version": "3.5.1",
   "author": {
     "name": "mayurpise"
   },

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "draft",
   "displayName": "Draft",
   "description": "Context-Driven Development: draft specs and plans before implementation. Structured workflows for features and fixes.",
-  "version": "3.4.0",
+  "version": "3.5.1",
   "skills": "./skills/",
   "agents": "./core/agents/",
   "author": {

package/core/templates/okf/concept.md

@@ -52,3 +52,12 @@ so a focused task knows exactly which source files to open.
 ## See also
 
 - [Related concept](../systems/other.md)
+
+<!-- okf:concept-template v1
+A stub or redirect-only page (e.g. "see architecture.md", an unreplaced
+{PLACEHOLDER} token, or a body below the per-type minimum) FAILS
+okf-validate-quality.sh and therefore does NOT satisfy okf-coverage-check.sh —
+the bundle will not be promoted. Diagram types (Subsystem/Module/Feature/
+Entrypoint) require ≥1 valid Mermaid block and ≥2 x-grounded-paths.
+-->
+

package/integrations/agents/AGENTS.md

@@ -336,6 +336,16 @@ DRAFT_INIT_MODE="${DRAFT_INIT_MODE:-auto}"
 
 The tier-gated default rests on **maintainability/readability** (one navigable concept per file, cleaner PRs, a generated `architecture.md` preserved for linear onboarding) — not on the A/B benchmark, which was accuracy-parity (`docs/audit/okf-benchmark.md`). `monolith` is **retained, not retired**: it is the tier-1/2 default, the A/B baseline, and the fallback. If `DRAFT_INIT_MODE` is unset, do not commit to a mode until **Step 1.4.5** has computed the tier.
 
+**OKF Completeness Verification (blocking — tier 3+ `okf` mode).** Completeness is enforced by tooling, not honor system, so the wiki is generated completely for every module/sub-module/component on every run. Before promoting `draft.tmp/` → `draft/`, ALL must hold (see `references/okf-emitter.md` for the pipeline):
+
+1. `okf-plan-concepts.sh` ran and the expected/required/deferred counts were logged **before** any page was written (the concept boundary is a tool output, not an in-context guess).
+2. Every `required` entry in `concept-plan.json` has a non-stub page.
+3. `okf-validate-all.sh … --plan … --strict` exits 0 (structure + per-type quality + coverage all pass).
+4. `systems/coverage.md` was generated by tooling (verify the `<!-- okf:coverage-generated -->` marker) — no required package with `fan_in ≥ floor` is **MISSING**.
+5. On any failure: **do not** atomic-rename; surface `.state/validation-report.json`.
+
+> **Red flag:** writing concept pages without first running `okf-plan-concepts.sh`, or finishing generation while any `required` plan entry is unwritten, is a **completeness failure** — not a stylistic one.
+
 ### Route Explicit Modes Before Initialization
 
 If the user explicitly invoked a specialist mode, route directly:
@@ -3291,7 +3301,10 @@ esac
 Everything else in `draft init` (5-phase analysis, graph snapshot, `.state/`
 hashing, scope detection, atomic staging) is **reused unchanged**. This mode adds
 a decomposition + serialization stage. It introduces **no new LLM analysis
-engine** and exactly **one** new deterministic helper, `okf-validate.sh`.
+engine**; its deterministic helpers are `okf-plan-concepts.sh` (expected-concept
+set), `okf-validate.sh` (structure), `okf-validate-quality.sh` (per-type
+anti-stub), `okf-coverage-check.sh` (completeness), and `okf-validate-all.sh`
+(the single promotion gate that runs all three), plus `okf-render-views.sh`.
 
 ## Target layout
 
@@ -3384,25 +3397,64 @@ Derive concepts from the graph, not by hand:
 
 ```
 1. Survey        → existing draft init 5-phase + graph snapshot (graph-snapshot.sh)
-2. Plan          → derive the concept list (above) from graph clusters +
-                   entrypoints + features. Topo-sort by dependency so pages that
-                   others link to (overview, core subsystems) generate FIRST —
-                   forward cross-links resolve.
-3. Generate      → per concept, pull grounding from the graph and write the page:
+2. Plan          → DETERMINISTIC. okf-plan-concepts.sh derives the expected-concept
+                   set from the graph (every package with fan_in ≥ floor → required
+                   Subsystem/Module; entrypoints → required; below-floor / allow-defer
+                   → deferred with a reason) and writes draft.tmp/.state/concept-plan.json.
+                     okf-plan-concepts.sh --repo . [--scope PATH] \
+                       [--manifest FILE] [--min-fan-in 2] [--allow-defer GLOB]... \
+                       --out draft.tmp/.state/concept-plan.json
+                   This replaces the old in-context concept enumeration — the boundary
+                   of the work is now a tool output, not an LLM judgment, so modules
+                   cannot be silently dropped. LOG the counts (expected/required/
+                   deferred) BEFORE writing any page. `generated_order` is topo-ish
+                   (required + high-fan-in first) so forward cross-links resolve.
+3. Generate      → iterate concept-plan.generated_order; write ONE page per REQUIRED
+                   entry, grounding each from the graph:
                      x-callers        ← graph-callers.sh --symbol <c>
                      x-grounded-paths  ← graph-impact.sh  --symbol <c>  (blast radius)
                      x-hotspot-score   ← hotspot-rank.sh
                      overview diagrams ← mermaid-from-graph.sh
                    Record each source path → page in .state/path-to-concept.json.
+                   Loop post-condition: every required concept_id has an output file.
+                   ⚠ Writing pages via shell heredoc without reading x-grounded-paths
+                   sources, or finishing while any required entry is unwritten, is a
+                   completeness failure — not a stylistic one.
 4. Render views  → ai-context.md (synopsis + Concept Map), architecture.md
-                   (concatenated view), wiki/log.md  (see M4).
-5. Validate      → okf-validate.sh draft/wiki \
-                     --path-index draft/.state/path-to-concept.json
-                   FAIL the build (do not atomic-rename) on any dangle, missing
-                   field, bad type, or path-index gap.
-6. Emit          → mv draft.tmp/ draft/ ; update .state/.
+                   (concatenated view + coverage banner), wiki/log.md  (see M4).
+5. Validate      → the promotion gate. Run all layers via the orchestrator:
+                     5a. okf-validate-all.sh draft.tmp/wiki \
+                           --repo . \
+                           --plan draft.tmp/.state/concept-plan.json \
+                           --path-index draft.tmp/.state/path-to-concept.json \
+                           --strict --report draft.tmp/.state/validation-report.json
+                   It runs, in order: okf-validate.sh (structure + reverse index),
+                   okf-validate-quality.sh (per-type anti-stub / depth / mermaid lint),
+                   okf-coverage-check.sh (every required plan entry → real page).
+                   ANY layer failing ⇒ exit non-zero ⇒ DO NOT atomic-rename.
+                   coverage.md (systems/coverage.md) is regenerated by the coverage
+                   layer; it is tool-owned (marker <!-- okf:coverage-generated -->) —
+                   never hand-author it except deferral reasons in the manifest.
+6. Emit          → mv draft.tmp/ draft/  ONLY IF step 5 exit 0 ; update .state/.
+                   On failure keep draft.tmp/ and surface validation-report.json.
+```
+
+### Validation report schema (`.state/validation-report.json`)
+
+```json
+{ "valid": false, "bundle": "draft.tmp/wiki",
+  "layers": { "structure": "pass", "quality": "pass", "coverage": "fail" } }
 ```
 
+### Component manifest (optional — `--manifest FILE`)
+
+When the graph engine is unavailable (or a repo wants an authoritative list), pass
+a plain-text manifest: one component name per line, `#` comments and blanks ignored.
+Every listed component becomes a REQUIRED concept; `--allow-defer GLOB` still moves
+matches to deferred. Without a manifest the plan comes from the graph, and only if
+both are unavailable does it fall back to a heuristic top-level-dir scan (which it
+marks `degraded: true`).
+
 Page bodies are LLM-narrated for readability **but** the graph-derived
 frontmatter and the `Blast radius`/`Used by` sections are deterministic. To keep
 incremental carry-forward byte-identical (open decision 2), cache the narrated
@@ -3456,17 +3508,22 @@ section `index.md` tables are the injection slots for the routing tables.
 `draft init refresh` under `okf` mode:
 
 ```
-1. Diff hashes.json vs working tree     → changed source paths
-2. path-to-concept.json                 → affected concept pages
-3. Regenerate ONLY affected concepts; carry the rest verbatim (cached narration)
-4. Re-render ai-context.md / architecture.md / log.md (cheap; always regenerated)
-5. Re-validate: okf-validate.sh on the bundle + path-index (cross-links touching
-   changed concepts must still resolve)
-6. Append log.md; update hashes.json + path-to-concept.json
+1. Re-derive the plan: okf-plan-concepts.sh (modules added since last run become
+   REQUIRED — a new package can't slip through a refresh either)
+2. Diff hashes.json vs working tree     → changed source paths
+3. path-to-concept.json                 → affected concept pages
+4. Regenerate ONLY affected concepts; carry the rest verbatim (cached narration)
+5. Re-render ai-context.md / architecture.md / log.md (cheap; always regenerated)
+6. Re-validate (full gate): okf-validate-all.sh on the bundle with --plan and
+   --path-index. Refresh re-runs structure + quality + coverage — a changed
+   concept must still clear the quality bar, and a newly-required module must
+   still be present.
+7. Append log.md; update hashes.json + path-to-concept.json
 ```
 
 A 1-file change regenerates only the concept(s) that file grounds. Unchanged
-concepts are byte-identical across runs.
+concepts are byte-identical across runs. The full gate still runs, so refresh
+cannot promote a bundle that a newly-added module left incomplete.
 
 ## Backward compatibility (§9)
 
@@ -22687,6 +22744,15 @@ so a focused task knows exactly which source files to open.
 
 - [Related concept](../systems/other.md)
 
+<!-- okf:concept-template v1
+A stub or redirect-only page (e.g. "see architecture.md", an unreplaced
+{PLACEHOLDER} token, or a body below the per-type minimum) FAILS
+okf-validate-quality.sh and therefore does NOT satisfy okf-coverage-check.sh —
+the bundle will not be promoted. Diagram types (Subsystem/Module/Feature/
+Entrypoint) require ≥1 valid Mermaid block and ≥2 x-grounded-paths.
+-->
+
+
 </core-file>
 
 ---

package/integrations/copilot/.github/copilot-instructions.md

@@ -336,6 +336,16 @@ DRAFT_INIT_MODE="${DRAFT_INIT_MODE:-auto}"
 
 The tier-gated default rests on **maintainability/readability** (one navigable concept per file, cleaner PRs, a generated `architecture.md` preserved for linear onboarding) — not on the A/B benchmark, which was accuracy-parity (`docs/audit/okf-benchmark.md`). `monolith` is **retained, not retired**: it is the tier-1/2 default, the A/B baseline, and the fallback. If `DRAFT_INIT_MODE` is unset, do not commit to a mode until **Step 1.4.5** has computed the tier.
 
+**OKF Completeness Verification (blocking — tier 3+ `okf` mode).** Completeness is enforced by tooling, not honor system, so the wiki is generated completely for every module/sub-module/component on every run. Before promoting `draft.tmp/` → `draft/`, ALL must hold (see `references/okf-emitter.md` for the pipeline):
+
+1. `okf-plan-concepts.sh` ran and the expected/required/deferred counts were logged **before** any page was written (the concept boundary is a tool output, not an in-context guess).
+2. Every `required` entry in `concept-plan.json` has a non-stub page.
+3. `okf-validate-all.sh … --plan … --strict` exits 0 (structure + per-type quality + coverage all pass).
+4. `systems/coverage.md` was generated by tooling (verify the `<!-- okf:coverage-generated -->` marker) — no required package with `fan_in ≥ floor` is **MISSING**.
+5. On any failure: **do not** atomic-rename; surface `.state/validation-report.json`.
+
+> **Red flag:** writing concept pages without first running `okf-plan-concepts.sh`, or finishing generation while any `required` plan entry is unwritten, is a **completeness failure** — not a stylistic one.
+
 ### Route Explicit Modes Before Initialization
 
 If the user explicitly invoked a specialist mode, route directly:
@@ -3291,7 +3301,10 @@ esac
 Everything else in `draft init` (5-phase analysis, graph snapshot, `.state/`
 hashing, scope detection, atomic staging) is **reused unchanged**. This mode adds
 a decomposition + serialization stage. It introduces **no new LLM analysis
-engine** and exactly **one** new deterministic helper, `okf-validate.sh`.
+engine**; its deterministic helpers are `okf-plan-concepts.sh` (expected-concept
+set), `okf-validate.sh` (structure), `okf-validate-quality.sh` (per-type
+anti-stub), `okf-coverage-check.sh` (completeness), and `okf-validate-all.sh`
+(the single promotion gate that runs all three), plus `okf-render-views.sh`.
 
 ## Target layout
 
@@ -3384,25 +3397,64 @@ Derive concepts from the graph, not by hand:
 
 ```
 1. Survey        → existing draft init 5-phase + graph snapshot (graph-snapshot.sh)
-2. Plan          → derive the concept list (above) from graph clusters +
-                   entrypoints + features. Topo-sort by dependency so pages that
-                   others link to (overview, core subsystems) generate FIRST —
-                   forward cross-links resolve.
-3. Generate      → per concept, pull grounding from the graph and write the page:
+2. Plan          → DETERMINISTIC. okf-plan-concepts.sh derives the expected-concept
+                   set from the graph (every package with fan_in ≥ floor → required
+                   Subsystem/Module; entrypoints → required; below-floor / allow-defer
+                   → deferred with a reason) and writes draft.tmp/.state/concept-plan.json.
+                     okf-plan-concepts.sh --repo . [--scope PATH] \
+                       [--manifest FILE] [--min-fan-in 2] [--allow-defer GLOB]... \
+                       --out draft.tmp/.state/concept-plan.json
+                   This replaces the old in-context concept enumeration — the boundary
+                   of the work is now a tool output, not an LLM judgment, so modules
+                   cannot be silently dropped. LOG the counts (expected/required/
+                   deferred) BEFORE writing any page. `generated_order` is topo-ish
+                   (required + high-fan-in first) so forward cross-links resolve.
+3. Generate      → iterate concept-plan.generated_order; write ONE page per REQUIRED
+                   entry, grounding each from the graph:
                      x-callers        ← graph-callers.sh --symbol <c>
                      x-grounded-paths  ← graph-impact.sh  --symbol <c>  (blast radius)
                      x-hotspot-score   ← hotspot-rank.sh
                      overview diagrams ← mermaid-from-graph.sh
                    Record each source path → page in .state/path-to-concept.json.
+                   Loop post-condition: every required concept_id has an output file.
+                   ⚠ Writing pages via shell heredoc without reading x-grounded-paths
+                   sources, or finishing while any required entry is unwritten, is a
+                   completeness failure — not a stylistic one.
 4. Render views  → ai-context.md (synopsis + Concept Map), architecture.md
-                   (concatenated view), wiki/log.md  (see M4).
-5. Validate      → okf-validate.sh draft/wiki \
-                     --path-index draft/.state/path-to-concept.json
-                   FAIL the build (do not atomic-rename) on any dangle, missing
-                   field, bad type, or path-index gap.
-6. Emit          → mv draft.tmp/ draft/ ; update .state/.
+                   (concatenated view + coverage banner), wiki/log.md  (see M4).
+5. Validate      → the promotion gate. Run all layers via the orchestrator:
+                     5a. okf-validate-all.sh draft.tmp/wiki \
+                           --repo . \
+                           --plan draft.tmp/.state/concept-plan.json \
+                           --path-index draft.tmp/.state/path-to-concept.json \
+                           --strict --report draft.tmp/.state/validation-report.json
+                   It runs, in order: okf-validate.sh (structure + reverse index),
+                   okf-validate-quality.sh (per-type anti-stub / depth / mermaid lint),
+                   okf-coverage-check.sh (every required plan entry → real page).
+                   ANY layer failing ⇒ exit non-zero ⇒ DO NOT atomic-rename.
+                   coverage.md (systems/coverage.md) is regenerated by the coverage
+                   layer; it is tool-owned (marker <!-- okf:coverage-generated -->) —
+                   never hand-author it except deferral reasons in the manifest.
+6. Emit          → mv draft.tmp/ draft/  ONLY IF step 5 exit 0 ; update .state/.
+                   On failure keep draft.tmp/ and surface validation-report.json.
+```
+
+### Validation report schema (`.state/validation-report.json`)
+
+```json
+{ "valid": false, "bundle": "draft.tmp/wiki",
+  "layers": { "structure": "pass", "quality": "pass", "coverage": "fail" } }
 ```
 
+### Component manifest (optional — `--manifest FILE`)
+
+When the graph engine is unavailable (or a repo wants an authoritative list), pass
+a plain-text manifest: one component name per line, `#` comments and blanks ignored.
+Every listed component becomes a REQUIRED concept; `--allow-defer GLOB` still moves
+matches to deferred. Without a manifest the plan comes from the graph, and only if
+both are unavailable does it fall back to a heuristic top-level-dir scan (which it
+marks `degraded: true`).
+
 Page bodies are LLM-narrated for readability **but** the graph-derived
 frontmatter and the `Blast radius`/`Used by` sections are deterministic. To keep
 incremental carry-forward byte-identical (open decision 2), cache the narrated
@@ -3456,17 +3508,22 @@ section `index.md` tables are the injection slots for the routing tables.
 `draft init refresh` under `okf` mode:
 
 ```
-1. Diff hashes.json vs working tree     → changed source paths
-2. path-to-concept.json                 → affected concept pages
-3. Regenerate ONLY affected concepts; carry the rest verbatim (cached narration)
-4. Re-render ai-context.md / architecture.md / log.md (cheap; always regenerated)
-5. Re-validate: okf-validate.sh on the bundle + path-index (cross-links touching
-   changed concepts must still resolve)
-6. Append log.md; update hashes.json + path-to-concept.json
+1. Re-derive the plan: okf-plan-concepts.sh (modules added since last run become
+   REQUIRED — a new package can't slip through a refresh either)
+2. Diff hashes.json vs working tree     → changed source paths
+3. path-to-concept.json                 → affected concept pages
+4. Regenerate ONLY affected concepts; carry the rest verbatim (cached narration)
+5. Re-render ai-context.md / architecture.md / log.md (cheap; always regenerated)
+6. Re-validate (full gate): okf-validate-all.sh on the bundle with --plan and
+   --path-index. Refresh re-runs structure + quality + coverage — a changed
+   concept must still clear the quality bar, and a newly-required module must
+   still be present.
+7. Append log.md; update hashes.json + path-to-concept.json
 ```
 
 A 1-file change regenerates only the concept(s) that file grounds. Unchanged
-concepts are byte-identical across runs.
+concepts are byte-identical across runs. The full gate still runs, so refresh
+cannot promote a bundle that a newly-added module left incomplete.
 
 ## Backward compatibility (§9)
 
@@ -22687,6 +22744,15 @@ so a focused task knows exactly which source files to open.
 
 - [Related concept](../systems/other.md)
 
+<!-- okf:concept-template v1
+A stub or redirect-only page (e.g. "see architecture.md", an unreplaced
+{PLACEHOLDER} token, or a body below the per-type minimum) FAILS
+okf-validate-quality.sh and therefore does NOT satisfy okf-coverage-check.sh —
+the bundle will not be promoted. Diagram types (Subsystem/Module/Feature/
+Entrypoint) require ≥1 valid Mermaid block and ≥2 x-grounded-paths.
+-->
+
+
 </core-file>
 
 ---

package/integrations/copilot/.github/copilot-instructions.md.7iDz8X

@@ -0,0 +1,91 @@
+# Draft - Context-Driven Development
+
+You are operating with the Draft methodology for Context-Driven Development.
+
+**Measure twice, code once.**
+
+## Core Workflow
+
+**Context -> Spec & Plan -> Implement**
+
+Every feature follows this lifecycle:
+1. **Setup** - Initialize project context (once per project)
+2. **New Track** - Create specification and plan
+3. **Implement** - Execute tasks with TDD workflow
+4. **Verify** - Confirm acceptance criteria met
+
+## Project Context Files
+
+When `draft/` exists in the project, always consider:
+- `draft/.ai-context.md` - Source of truth for AI agents (dense codebase understanding)
+- `draft/architecture.md` - Human-readable engineering guide (derived from .ai-context.md)
+- `draft/product.md` - Product vision and goals
+- `draft/tech-stack.md` - Technical constraints
+- `draft/workflow.md` - TDD and commit preferences
+- `draft/tracks.md` - Active work items
+
+## Available Commands
+
+| Command | Purpose |
+|---------|---------|
+| `draft` | Show overview and available commands |
+| `draft init` | Initialize project (run once) |
+| `draft index [--init-missing]` | Aggregate monorepo service contexts |
+| `draft new-track <description>` | Create feature/bug track |
+| `draft decompose` | Module decomposition with dependency mapping |
+| `draft implement` | Execute tasks from plan |
+| `draft coverage` | Code coverage report (target 95%+) |
+| `draft bughunt [--track <id>]` | Systematic bug discovery |
+| `draft review [--track <id>]` | Three-stage code review |
+| `draft deep-review [module]` | Exhaustive production-grade module audit |
+| `draft learn [promote\|migrate]` | Discover coding patterns, update guardrails |
+| `draft adr [title]` | Architecture Decision Records |
+| `draft status` | Show progress overview |
+| `draft revert` | Git-aware rollback |
+| `draft change <description>` | Handle mid-track requirement changes |
+| `draft jira-preview [track-id]` | Generate jira-export.md for review |
+| `draft jira-create [track-id]` | Create Jira issues from export via MCP |
+
+## Intent Mapping
+
+Recognize these natural language patterns:
+
+| User Says | Action |
+|-----------|--------|
+| "set up the project" | Run init |
+| "index services", "aggregate context" | Run index |
+| "new feature", "add X" | Create new track |
+| "break into modules", "decompose" | Run decompose |
+| "start implementing" | Execute implement |
+| "check coverage", "test coverage" | Run coverage |
+| "hunt bugs", "find bugs" | Run bug hunt |
+| "review code", "review track", "check quality" | Run review |
+| "deep review", "production audit", "module audit" | Run deep-review |
+| "learn patterns", "update guardrails", "discover conventions" | Run learn |
+| "what's the status" | Show status |
+| "undo", "revert" | Run revert |
+| "requirements changed", "scope changed", "update the spec" | Run change |
+| "preview jira", "export to jira" | Run jira-preview |
+| "create jira", "push to jira" | Run jira-create |
+| "document decision", "create ADR" | Create architecture decision record |
+| "help", "what commands" | Show draft overview |
+| "the plan" | Read active track's plan.md |
+| "the spec" | Read active track's spec.md |
+
+## Tracks
+
+A **track** is a high-level unit of work (feature, bug fix, refactor). Each track contains:
+- `spec.md` - Requirements and acceptance criteria
+- `plan.md` - Phased task breakdown
+- `metadata.json` - Status and timestamps
+
+Located at: `draft/tracks/<track-id>/`
+
+## Status Markers
+
+Recognize and use these throughout plan.md:
+- `[ ]` - Pending
+- `[~]` - In Progress
+- `[x]` - Completed
+- `[!]` - Blocked
+

package/integrations/copilot/.github/copilot-instructions.md.DoBdtd

@@ -0,0 +1,91 @@
+# Draft - Context-Driven Development
+
+You are operating with the Draft methodology for Context-Driven Development.
+
+**Measure twice, code once.**
+
+## Core Workflow
+
+**Context -> Spec & Plan -> Implement**
+
+Every feature follows this lifecycle:
+1. **Setup** - Initialize project context (once per project)
+2. **New Track** - Create specification and plan
+3. **Implement** - Execute tasks with TDD workflow
+4. **Verify** - Confirm acceptance criteria met
+
+## Project Context Files
+
+When `draft/` exists in the project, always consider:
+- `draft/.ai-context.md` - Source of truth for AI agents (dense codebase understanding)
+- `draft/architecture.md` - Human-readable engineering guide (derived from .ai-context.md)
+- `draft/product.md` - Product vision and goals
+- `draft/tech-stack.md` - Technical constraints
+- `draft/workflow.md` - TDD and commit preferences
+- `draft/tracks.md` - Active work items
+
+## Available Commands
+
+| Command | Purpose |
+|---------|---------|
+| `draft` | Show overview and available commands |
+| `draft init` | Initialize project (run once) |
+| `draft index [--init-missing]` | Aggregate monorepo service contexts |
+| `draft new-track <description>` | Create feature/bug track |
+| `draft decompose` | Module decomposition with dependency mapping |
+| `draft implement` | Execute tasks from plan |
+| `draft coverage` | Code coverage report (target 95%+) |
+| `draft bughunt [--track <id>]` | Systematic bug discovery |
+| `draft review [--track <id>]` | Three-stage code review |
+| `draft deep-review [module]` | Exhaustive production-grade module audit |
+| `draft learn [promote\|migrate]` | Discover coding patterns, update guardrails |
+| `draft adr [title]` | Architecture Decision Records |
+| `draft status` | Show progress overview |
+| `draft revert` | Git-aware rollback |
+| `draft change <description>` | Handle mid-track requirement changes |
+| `draft jira-preview [track-id]` | Generate jira-export.md for review |
+| `draft jira-create [track-id]` | Create Jira issues from export via MCP |
+
+## Intent Mapping
+
+Recognize these natural language patterns:
+
+| User Says | Action |
+|-----------|--------|
+| "set up the project" | Run init |
+| "index services", "aggregate context" | Run index |
+| "new feature", "add X" | Create new track |
+| "break into modules", "decompose" | Run decompose |
+| "start implementing" | Execute implement |
+| "check coverage", "test coverage" | Run coverage |
+| "hunt bugs", "find bugs" | Run bug hunt |
+| "review code", "review track", "check quality" | Run review |
+| "deep review", "production audit", "module audit" | Run deep-review |
+| "learn patterns", "update guardrails", "discover conventions" | Run learn |
+| "what's the status" | Show status |
+| "undo", "revert" | Run revert |
+| "requirements changed", "scope changed", "update the spec" | Run change |
+| "preview jira", "export to jira" | Run jira-preview |
+| "create jira", "push to jira" | Run jira-create |
+| "document decision", "create ADR" | Create architecture decision record |
+| "help", "what commands" | Show draft overview |
+| "the plan" | Read active track's plan.md |
+| "the spec" | Read active track's spec.md |
+
+## Tracks
+
+A **track** is a high-level unit of work (feature, bug fix, refactor). Each track contains:
+- `spec.md` - Requirements and acceptance criteria
+- `plan.md` - Phased task breakdown
+- `metadata.json` - Status and timestamps
+
+Located at: `draft/tracks/<track-id>/`
+
+## Status Markers
+
+Recognize and use these throughout plan.md:
+- `[ ]` - Pending
+- `[~]` - In Progress
+- `[x]` - Completed
+- `[!]` - Blocked
+