@drafthq/draft 3.5.3 → 3.7.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.5.3",
+      "version": "3.7.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.5.3",
+  "version": "3.7.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.5.3",
+  "version": "3.7.1",
   "skills": "./skills/",
   "agents": "./core/agents/",
   "author": {

package/README.md

@@ -40,6 +40,8 @@ Three stages, one command:
 2. **Spec compliance** — checks the diff against the agreed spec, not vibes
 3. **Code quality** — flags hotspots, blast radius, and missing test coverage using a tree-sitter knowledge graph of your repo
 
+No setup required for the first run: on an un-indexed repo it reviews the diff and names the structural checks it skipped, so you see findings before you spend anything.
+
 Free. No API keys. No paid tier. No vendor lock-in. Catches the 3 bugs you missed before they hit your reviewer.
 
 > *Demo coming soon — for now, [watch the 8-minute walkthrough](https://www.youtube.com/watch?v=gBSwFEFVd7Y).*
@@ -76,35 +78,44 @@ Flags: `--global` / `--project` to pick scope, `--dry-run` to preview, `--force`
 Then, in Claude Code (after restarting):
 
 ```bash
-/draft:init       # 5-phase codebase analysis (one-time)
-/draft:review     # ← run this on every branch before you push
+/draft:review     # ← start here. No setup, no indexing. Reviews your current diff.
+/draft:init       # once you've seen what it catches: index the repo (one-time)
+/draft:review     # same command, now with blast radius + hotspots + cycle detection
 ```
 
+`/draft:review` runs on an un-indexed repo and tells you exactly which structural checks it had to skip. Indexing is the upgrade, not the entry fee.
+
 Run `/draft` for the full command map.
 
 <details>
 <summary><strong>Other ways to install →</strong></summary>
 
 ### Claude Code — native marketplace
+
 ```bash
 /plugin marketplace add drafthq/draft
 /plugin install draft
 ```
 
 ### Cursor — from GitHub
+
 Cursor requires `.cursor-plugin/plugin.json`; the `draft install cursor` command also registers the plugin via the shared Claude plugin registry that Cursor reads on many builds. To add from source instead, use *Settings > Rules, Skills, Subagents > Rules > New > Add from Github*:
-```
+
+```text
 https://github.com/drafthq/draft.git
 ```
 
 ### GitHub Copilot
+
 Copilot reads a committed instructions file — copy it directly (not a `draft install` host):
+
 ```bash
 mkdir -p .github && curl -o .github/copilot-instructions.md \
   https://raw.githubusercontent.com/drafthq/draft/main/integrations/copilot/.github/copilot-instructions.md
 ```
 
 ### Gemini
+
 ```bash
 curl -o .gemini.md https://raw.githubusercontent.com/drafthq/draft/main/integrations/gemini/.gemini.md
 ```
@@ -113,53 +124,19 @@ curl -o .gemini.md https://raw.githubusercontent.com/drafthq/draft/main/integrat
 
 ---
 
-## Beyond `/draft:review` — 32 more commands
+## The five commands
 
-`/draft:review` is the wedge. Once Draft has indexed your repo, you also get spec-driven planning, TDD-enforced implementation, exhaustive bug hunting, deep architectural audits, and 32 more commands covering the full development lifecycle.
-
----
+| Command | What it does |
+|---------|--------------|
+| **`/draft:review`** | 3-stage review of your diff. **Works with zero setup** — run it first. |
+| **`/draft:init`** | Index the repo once. Adds blast radius, caller lookup, hotspot ranking, and cycle detection to every later review. |
+| **`/draft:new-track`** | Turn an idea into a spec + plan before any code is written. |
+| **`/draft:implement`** | Execute the plan task-by-task under TDD with verification gates. |
+| **`/draft:graph`** | Build or refresh the knowledge-graph snapshot on its own. |
 
-## What You Get
+That is the whole loop. 28 more specialist commands — bug hunting, ACID audits, ADRs, tech debt, incident response, Jira, coverage, standups — sit behind five intent routers (`/draft:plan`, `/draft:discover`, `/draft:ops`, `/draft:docs`, `/draft:jira`).
 
-| Command | What It Does |
-|---------|--------------|
-| **`/draft`** | Overview, intent mapping, and command reference |
-| **`/draft:plan`** | Router for planning, architecture, and track management |
-| **`/draft:ops`** | Router for operations, deployment, incident, and lifecycle |
-| **`/draft:docs`** | Router for authoring and documentation workflows |
-| **`/draft:discover`** | Router for discovery, debugging, investigation, and quality |
-| **`/draft:init`** | Analyze codebase, create context files + state tracking |
-| **`/draft:graph`** | Build / refresh the knowledge-graph snapshot |
-| **`/draft:new-track`** | Collaborative spec + plan with AI |
-| **`/draft:decompose`** | Module decomposition with dependency mapping |
-| **`/draft:implement`** | TDD workflow with checkpoints |
-| **`/draft:coverage`** | Code coverage report (target 95%+) |
-| **`/draft:review`** | 3-stage review (validation + spec compliance + code quality) |
-| **`/draft:deep-review`** | Enterprise-grade module lifecycle and ACID audit |
-| **`/draft:bughunt`** | Exhaustive 14-dimension defect discovery with taint tracking |
-| **`/draft:learn`** | Discover coding patterns, update guardrails |
-| **`/draft:adr`** | Architecture Decision Records |
-| **`/draft:status`** | Show progress overview |
-| **`/draft:revert`** | Git-aware rollback |
-| **`/draft:change`** | Handle mid-track requirement changes |
-| **`/draft:debug`** | Structured debugging: reproduce, isolate, diagnose, fix |
-| **`/draft:quick-review`** | Lightweight 4-dimension code review |
-| **`/draft:deploy-checklist`** | Pre-deployment verification with rollback triggers |
-| **`/draft:upload`** | Pre-upload handoff gate (review, HLD, checklist, validators) |
-| **`/draft:testing-strategy`** | Test plan design with coverage targets |
-| **`/draft:tech-debt`** | Technical debt analysis across 6 dimensions |
-| **`/draft:standup`** | Git activity standup summary (read-only) |
-| **`/draft:incident-response`** | Incident lifecycle: triage, communicate, mitigate, postmortem |
-| **`/draft:documentation`** | Technical docs: readme, runbook, api, onboarding |
-| **`/draft:integrations`** | External system exports and syncs (jira preview / create) |
-| **`/draft:jira`** | Unified Jira workflows (preview / create / review) |
-| **`/draft:tour`** | Interactive architecture mentorship and codebase walk-through |
-| **`/draft:impact`** | ROI analytics tracking friction and timeline metrics |
-| **`/draft:assist-review`** | Summarize intent and highlight structural PR risks for reviewers |
-
-[See full command reference →](core/methodology.md#command-workflows)
-
-> **Recommended next step after install:** run `/draft:init` to index your repo, then `/draft:review` on any branch with AI-generated changes. Once you've seen what it catches, explore the rest.
+[Full command reference →](docs/COMMANDS.md) · run `/draft` for the interactive intent map
 
 ---
 
@@ -193,7 +170,7 @@ Skills also call into **shell helpers** under `scripts/tools/` for mechanical wo
 
 ## How It Works
 
-```
+```text
 ┌─────────────────────────────────────────────────────────────┐
 │                        /draft:init                          │
 │    5-phase codebase analysis + signal detection + state     │
@@ -249,7 +226,7 @@ Both modes produce the same `product.md`, `tech-stack.md`, `workflow.md`,
 
 AI tools are fast but unstructured. Draft applies Context-Driven Development to impose clear boundaries: explicit context, phased execution, and built-in verification, ensuring outputs remain aligned, predictable, and production-ready.
 
-```
+```text
 product.md       →  "Build a task manager"
 tech-stack.md    →  "React, TypeScript, Tailwind"
 architecture.md  →  Comprehensive: 10-section graph-primary engineering reference, Mermaid diagrams (source of truth). Mature brownfield projects with strong existing agent docs (CLAUDE.md, INVARIANTS.md, etc.) receive early Context Quality Audit, graph fidelity dashboard, and explicit Relationship + Gaps sections (no blind duplication).
@@ -270,11 +247,13 @@ Each layer narrows the solution space. By the time AI writes code, decisions are
 ## Contributing
 
 ### Source of Truth
+
 1. `core/methodology.md` — Master methodology
 2. `skills/<name>/SKILL.md` — Command implementations
 3. `integrations/` — Auto-generated (don't edit)
 
 ### Update Workflow
+
 ```bash
 # 1. Edit core/methodology.md or skills/*/SKILL.md
 # 2. Rebuild integrations

package/bin/README.md

@@ -13,7 +13,7 @@ CMM_VERSION=latest scripts/fetch-memory-engine.sh   # or a specific tag / latest
 
 This installs the binary to the **Draft-managed location**:
 
-```
+```text
 ~/.cache/draft/bin/codebase-memory-mcp
 ```
 
@@ -57,3 +57,49 @@ Structural graph data (architecture, hotspots, module deps, service routes) is q
 ## Offline / air-gapped distributions
 
 To ship the engine in-tree, place the binary at `bin/<os>-<arch>/codebase-memory-mcp` (resolution step 4). This is optional and not the default; the managed fetch is preferred.
+
+---
+
+## Trust story
+
+Draft's differentiator depends on a binary published by a third party ([DeusData](https://github.com/DeusData)). That is a real supply-chain dependency and deserves a stated position rather than an implied one.
+
+### What is actually guaranteed
+
+| Property | Status |
+|---|---|
+| Version pinned | Yes — `DEFAULT_VERSION` in `scripts/fetch-memory-engine.sh`. Bumps are deliberate commits, never floating. `CMM_VERSION` overrides per-install. |
+| SHA-256 verified | Yes when the release publishes `checksums.txt` and lists the archive. A **mismatch is always fatal.** |
+| Missing checksum | **Warns and installs by default.** Set `DRAFT_STRICT_VERIFY=1` to make an unverifiable download fatal instead. |
+| Signature / attestation | **No.** There is no code signing or SLSA provenance today. Verification is checksum-only. |
+| Source available | Yes — the engine is open source at [DeusData/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp). |
+| Reproducible build | Not verified by Draft. We check the archive matches the publisher's checksum, not that the checksum matches the source. |
+
+Be explicit about the residual risk: a checksum proves the download matches what the publisher released. It does not prove the publisher released what the source says.
+
+### What the engine does at runtime
+
+- Reads the repository you point it at and writes a SQLite graph under its own cache.
+- Runs entirely locally. No API key, no telemetry endpoint, no outbound calls during indexing or querying.
+- Network is used exactly once, by `fetch-memory-engine.sh`, to download the release archive.
+
+Draft invokes it only through `codebase-memory-mcp cli <tool> '<json>'` (see `_lib.sh:memory_cli`). It is never given credentials and never writes into your source tree.
+
+### If you cannot run an unvetted binary
+
+Three supported postures, in increasing strictness:
+
+1. **Strict verification** — `DRAFT_STRICT_VERIFY=1 scripts/fetch-memory-engine.sh`. Refuses to install anything it cannot checksum.
+2. **Vendor it yourself** — review the source, build the binary in your own pipeline, and place it at `bin/<os>-<arch>/codebase-memory-mcp` (resolution step 4) or point `DRAFT_MEMORY_BIN` at it. Draft never re-downloads when a binary already resolves.
+3. **Run without it** — `DRAFT_MEMORY_DISABLE=1`, or `draft install <host> --no-graph`. Every graph-backed skill degrades to a documented reduced-context mode; `/draft:review` still runs (see `skills/review/references/zero-setup-mode.md`). You lose blast radius, caller enumeration, hotspot ranking, and cycle detection — nothing silently returns wrong answers.
+
+### Contingency if the upstream project stalls
+
+The dependency is bounded by design, which is what makes this survivable:
+
+- **The interface is small.** Draft consumes a documented CLI (`cli <tool> '<json>'`), not a library. The entire coupling lives in `scripts/tools/_lib.sh` (`memory_cli`, `memory_ensure_index`, `memory_project_for_repo`) and `_graph_queries.sh`. Swapping engines means reimplementing those, not rewriting skills.
+- **Skills never call the engine directly.** They call `graph-*.sh` wrappers, all of which already fail loud with `source: "unavailable"`. An engine that disappears degrades the product; it does not break it.
+- **Pinning buys time.** A stalled upstream keeps working at the pinned version; only new language support would be lost.
+- **The graph contract is replaceable.** The queries are ordinary Cypher-shaped structural lookups (callers, callees, fan-in, cycles, routes) over a tree-sitter/LSP index — reproducible on another indexer.
+
+If upstream goes unmaintained, the migration path is: fork at the pinned tag for continuity, then reimplement `_lib.sh`'s three wrappers against a replacement indexer. No skill markdown changes.

package/cli/src/hosts/cursor.js

@@ -48,6 +48,9 @@ module.exports = {
       targetSummary: `${base} (${ctx.scope})`,
       actions,
       graph: true,
+      // The actual install root (scope/CURSOR_HOME aware) — used for the
+      // plugin-root marker instead of re-deriving a default path.
+      pluginRoot: base,
       // Runs after the file copies: register + enable the plugin in the shared
       // Claude registry. On a dry run it computes the merges and writes nothing.
       postInstall(c) {

package/cli/src/installer.js

@@ -10,9 +10,13 @@ const { writePluginRootMarker } = require('./lib/marker');
 // before we even reach the real (separately-timed) install steps.
 const CHECK_TIMEOUT_MS = 10000;
 
+// On Windows, npm global CLIs are .cmd shims that CreateProcess can't resolve
+// without a shell; elsewhere a shell is unnecessary overhead.
+const USE_SHELL = process.platform === 'win32';
+
 function hasBinary(name) {
   // ENOENT on the error means the binary is not on PATH.
-  const r = spawnSync(name, ['--version'], { stdio: 'ignore', timeout: CHECK_TIMEOUT_MS });
+  const r = spawnSync(name, ['--version'], { stdio: 'ignore', timeout: CHECK_TIMEOUT_MS, shell: USE_SHELL });
   return !(r.error && r.error.code === 'ENOENT');
 }
 
@@ -25,7 +29,7 @@ function execAction(act, ctx) {
   const printable = `${act.cmd} ${act.args.join(' ')}`;
   log.plan(`${ctx.dryRun ? 'would run' : 'running'}: ${printable}`);
   if (ctx.dryRun) return 0;
-  const r = spawnSync(act.cmd, act.args, { stdio: 'inherit', timeout: STEP_TIMEOUT_MS });
+  const r = spawnSync(act.cmd, act.args, { stdio: 'inherit', timeout: STEP_TIMEOUT_MS, shell: USE_SHELL });
   if (r.error) {
     if (r.error.code === 'ETIMEDOUT') {
       log.error(`timed out after ${Math.round(STEP_TIMEOUT_MS / 1000)}s: ${printable}`);
@@ -79,7 +83,7 @@ function install(host, ctx) {
   // failure writes nothing.
   for (const act of plan.actions) {
     if (act.kind === 'exec') continue;
-    if (!fsx.exists(act.src)) {
+    if (act.src && !fsx.exists(act.src)) {
       log.error(`Bundled asset missing: ${act.src}`);
       log.error('Reinstall @drafthq/draft — the package looks incomplete.');
       return 1;
@@ -123,7 +127,7 @@ function install(host, ctx) {
   // Record the install path so skills can locate scripts/tools/ from the user's
   // project cwd (best-effort; graph skills glob-fallback if the marker is absent).
   if (!ctx.dryRun) {
-    const root = writePluginRootMarker(host.id);
+    const root = writePluginRootMarker(host.id, plan.pluginRoot);
     if (root) log.note(`Recorded plugin path for graph tooling: ${root}`);
   }
 

package/cli/src/lib/cursor-registry.js

@@ -24,11 +24,21 @@ function readJson(filePath, fallback) {
   }
 }
 
+// The temp file is a fresh inode, so renaming it over the destination discards
+// the destination's permissions. settings.json can carry env secrets and is often
+// deliberately 0600 — a plain write would silently widen it to the umask default.
 function writeJsonAtomic(filePath, data) {
   const dir = path.dirname(filePath);
   fs.mkdirSync(dir, { recursive: true });
   const tmp = `${filePath}.tmp.${process.pid}`;
+  let mode;
+  try {
+    mode = fs.statSync(filePath).mode & 0o777;
+  } catch {
+    /* new file — let the umask decide, exactly as a plain write would */
+  }
   fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', 'utf8');
+  if (mode !== undefined) fs.chmodSync(tmp, mode);
   fs.renameSync(tmp, filePath);
 }
 

package/cli/src/lib/fsx.js

@@ -18,6 +18,9 @@ function ensureDir(dir) {
 
 function copyTree(src, dest) {
   ensureDir(path.dirname(dest));
+  // Mirror, don't merge: dests are fully draft-owned bundled dirs, and a
+  // merge-copy would keep files deleted by newer releases around forever.
+  fs.rmSync(dest, { recursive: true, force: true });
   fs.cpSync(src, dest, { recursive: true });
 }
 

package/cli/src/lib/marker.js

@@ -14,9 +14,14 @@ const os = require('os');
 const path = require('path');
 
 // Resolve the installed draft plugin root for a given host, or null if unknown.
-function resolvePluginRoot(hostId) {
+// hintRoot: the root the just-executed install plan actually wrote to — it
+// already accounts for scope (--project) and env overrides (CURSOR_HOME) that
+// the per-host defaults below cannot see.
+function resolvePluginRoot(hostId, hintRoot) {
   const home = os.homedir();
 
+  if (hintRoot && fs.existsSync(path.join(hintRoot, 'scripts', 'tools'))) return hintRoot;
+
   if (hostId === 'claude-code') {
     // 1. Claude Code's own registry holds the authoritative installPath.
     const reg = path.join(home, '.claude', 'plugins', 'installed_plugins.json');
@@ -77,9 +82,9 @@ function compareVersions(a, b) {
 }
 
 // Write ~/.cache/draft/plugin-root for the host. Returns the path written, or null.
-function writePluginRootMarker(hostId) {
+function writePluginRootMarker(hostId, hintRoot) {
   try {
-    const root = resolvePluginRoot(hostId);
+    const root = resolvePluginRoot(hostId, hintRoot);
     if (!root) return null;
     const dest = path.join(os.homedir(), '.cache', 'draft', 'plugin-root');
     fs.mkdirSync(path.dirname(dest), { recursive: true });

package/core/agents/architect.md

@@ -25,6 +25,7 @@ You are an architecture agent for Draft-based development. You guide developers
 ### Module Definition Format
 
 For each module, define:
+
 - **Name** - Short, descriptive (e.g., `auth`, `scheduler`, `parser`)
 - **Responsibility** - One sentence describing what it owns
 - **Files** - Expected source files
@@ -39,7 +40,8 @@ Output format: Use the template at `core/templates/ai-context.md` for project-wi
 Represent API surfaces using the conventions of the project's primary language:
 
 **TypeScript:**
-```
+
+```text
 - API Surface:
   - `createUser(data: CreateUserInput): Promise<User>`
   - `deleteUser(id: string): Promise<void>`
@@ -48,7 +50,8 @@ Represent API surfaces using the conventions of the project's primary language:
 ```
 
 **Python:**
-```
+
+```text
 - API Surface:
   - `create_user(data: CreateUserInput) -> User`
   - `delete_user(user_id: str) -> None`
@@ -57,7 +60,8 @@ Represent API surfaces using the conventions of the project's primary language:
 ```
 
 **Go:**
-```
+
+```text
 - API Surface:
   - `func CreateUser(data CreateUserInput) (*User, error)`
   - `func DeleteUser(id string) error`
@@ -66,7 +70,8 @@ Represent API surfaces using the conventions of the project's primary language:
 ```
 
 **Rust:**
-```
+
+```text
 - API Surface:
   - `pub fn create_user(data: CreateUserInput) -> Result<User, Error>`
   - `pub fn delete_user(id: &str) -> Result<(), Error>`
@@ -79,6 +84,7 @@ Use the project's primary language from `draft/tech-stack.md`. Include function
 ### Ingredients
 
 Each module typically contains some combination of:
+
 - **API** - Public interface exposed to other modules
 - **Control Flow** - Core logic and decision paths
 - **Execution State** - Intermediate data structures used during processing
@@ -97,7 +103,7 @@ Each module typically contains some combination of:
 
 ### Dependency Diagram Format
 
-```
+```json
 [auth] ──> [database]
    │ │
    └──> [config] <──┘
@@ -128,18 +134,21 @@ When modules form a circular dependency (A → B → A), apply this decision pro
 **Example:**
 
 Before (cycle):
-```
+
+```json
 [user-service] ──> [notification-service]
        ↑ │
        └────────────────────┘
 ```
+
 `user-service` imports `sendNotification` from `notification-service`.
 `notification-service` imports `getUserPreferences` from `user-service`.
 
 Analysis: Both modules need user preference data. Extract it.
 
 After (resolved):
-```
+
+```json
 [user-preferences] (new - extracted shared concern)
        ↑ ↑
        │ │
@@ -149,6 +158,7 @@ After (resolved):
 ```
 
 New module `user-preferences`:
+
 - **Responsibility:** Owns user notification/display preference data and access
 - **API Surface:** `getUserPreferences(userId): Preferences`
 - **Files:** `user-preferences.ts`, `user-preferences.test.ts`
@@ -178,6 +188,7 @@ Stories flow through three stages:
 1. **Placeholder** — During `/draft:decompose`, each module in `.ai-context.md` (or track-level `architecture.md`) gets a Story field set to `[placeholder - filled during /draft:implement]`. This signals that the module exists but its algorithm hasn't been documented yet.
 
 2. **Written** — During `/draft:implement` (with architecture mode), before coding each module's first file, write the Story as a code comment at the top of the file. Present it to the developer for approval. Once approved, update the module's Story field in `.ai-context.md` (or `architecture.md`) with a one-line summary referencing the file:
+
    ```markdown
    - **Story:** Documented in `src/auth.ts:1-12` — validates token, resolves user, checks permissions
    ```
@@ -188,7 +199,7 @@ Stories flow through three stages:
 
 ### Story Format
 
-```
+```text
 // Story: [Module/File Name]
 //
 // Input: [what this module/function receives]
@@ -238,7 +249,7 @@ Define the intermediate state variables your code will use during processing. Th
 
 ### Execution State Format
 
-```
+```text
 ## Execution State: [Module Name]
 
 ### Input State
@@ -332,6 +343,7 @@ function validateEntries(
 ### Escalation
 
 If module boundaries are unclear after analysis:
+
 1. Document what you know
 2. List the ambiguous boundaries
 3. Ask developer to clarify responsibility ownership

package/core/agents/debugger.md

@@ -29,6 +29,7 @@ Before investigating, follow the context loading procedure in `core/shared/draft
 4. **Document findings** - Write down what you observe
 
 **Red Flags - STOP if you're:**
+
 - Tempted to make a "quick fix"
 - Guessing at the cause
 - Changing code "to see what happens"
@@ -47,6 +48,7 @@ Before investigating, follow the context loading procedure in `core/shared/draft
 4. **Narrow the scope** - What's the smallest change that breaks it?
 
 **Questions to answer:**
+
 - Is this a data problem or code problem?
 - Is this a timing/race condition?
 - Is this an environment difference?
@@ -81,6 +83,7 @@ Select techniques appropriate to the language and failure type. Not all techniqu
 4. **Run the test** - Execute and compare to prediction
 
 **If hypothesis is wrong:**
+
 - Return to Phase 2
 - Do NOT try another random fix
 - Update your understanding
@@ -146,6 +149,7 @@ Do NOT guess at performance bottlenecks. Profile first.
 5. **Re-profile** — confirm the hot path is resolved and no new bottleneck appeared
 
 **Anti-patterns for performance debugging:**
+
 - Optimizing without profiling data
 - Optimizing code that isn't on the hot path
 - Micro-optimizing when the bottleneck is I/O
@@ -167,6 +171,7 @@ Do NOT guess at performance bottlenecks. Profile first.
 ## When to Escalate
 
 If after 3 hypothesis cycles you haven't found root cause:
+
 1. Document all findings
 2. List what you've eliminated
 3. Ask for external input

package/core/agents/ops.md

@@ -37,6 +37,7 @@ You are an operations agent. When assessing production readiness, managing incid
 ## Operational Checklists
 
 ### Pre-Deploy Assessment
+
 1. Rollback plan documented and tested?
 2. Database migrations reversible?
 3. Feature flags in place for new features?
@@ -46,6 +47,7 @@ You are an operations agent. When assessing production readiness, managing incid
 7. On-call engineer aware and available?
 
 ### Incident Response Framework
+
 1. **Detect** — Alert fires or user report received
 2. **Triage** — Assess severity, assign incident commander
 3. **Communicate** — Notify stakeholders, open war room (if SEV1/2)
@@ -57,6 +59,7 @@ You are an operations agent. When assessing production readiness, managing incid
 ### Rollback Decision Framework
 
 Initiate rollback if ANY of these are true:
+
 - Error rate exceeds 2x baseline
 - p95 latency exceeds 3x baseline
 - Data corruption detected
@@ -67,7 +70,8 @@ Initiate rollback if ANY of these are true:
 ## Communication Templates
 
 ### Stakeholder Update (During Incident)
-```
+
+```json
 [SEV{N}] {Service Name} — {1-line summary}
 Status: {Investigating | Mitigating | Monitoring | Resolved}
 Impact: {user-facing impact description}
@@ -76,7 +80,8 @@ Next update: {time of next update}
 ```
 
 ### Post-Incident Summary
-```
+
+```yaml
 Incident: {title}
 Duration: {start} → {end} ({total time})
 Impact: {users affected, SLO impact}

package/core/agents/planner.md

@@ -50,12 +50,14 @@ Organize plans into phases:
 ## Task Granularity
 
 Good task:
+
 - Completable in a focused session
 - Has clear success criteria
 - Produces testable output
 - Fits in single commit
 
 Bad task:
+
 - "Implement the feature"
 - Multi-day scope
 - Vague completion criteria
@@ -63,11 +65,13 @@ Bad task:
 ## Dependency Mapping
 
 Identify:
+
 - Which tasks must complete before others
 - Parallel execution opportunities
 - External blockers
 
 Format in plan.md:
+
 ```markdown
 - [ ] Task 2.1: Add validation
   - Depends on: Task 1.1, Task 1.2
@@ -76,6 +80,7 @@ Format in plan.md:
 ## Risk Identification
 
 Flag in spec.md:
+
 - Technical unknowns
 - External dependencies
 - Performance concerns
@@ -128,6 +133,7 @@ Each criterion must be:
 | **Complete** | Covers both success and failure paths | Include error scenarios |
 
 **Anti-patterns:**
+
 - "System works correctly" (too vague)
 - "Code is clean" (subjective)
 - "Performance is good" (not measurable — use "Response time < 200ms at p95")
@@ -152,6 +158,7 @@ When recommending technical approaches, cite sources from `core/knowledge-base.m
 ## Escalation
 
 If requirements are ambiguous after analysis:
+
 1. Document what is clear
 2. List specific ambiguities with options
 3. Present to developer with trade-off analysis