gsd-pi 2.17.0 → 2.19.0

package/dist/resources/extensions/gsd/complexity-classifier.ts

@@ -0,0 +1,322 @@
+// GSD Extension — Complexity Classifier
+// Classifies unit complexity for dynamic model routing.
+// Pure heuristics + adaptive learning — no LLM calls. Sub-millisecond classification.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { gsdRoot } from "./paths.js";
+import { getAdaptiveTierAdjustment } from "./routing-history.js";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export type ComplexityTier = "light" | "standard" | "heavy";
+
+export interface ClassificationResult {
+  tier: ComplexityTier;
+  reason: string;
+  downgraded: boolean;   // true if budget pressure lowered the tier
+}
+
+export interface TaskMetadata {
+  fileCount?: number;
+  dependencyCount?: number;
+  isNewFile?: boolean;
+  tags?: string[];
+  estimatedLines?: number;
+  codeBlockCount?: number;      // number of fenced code blocks in plan
+  complexityKeywords?: string[]; // detected complexity signals
+}
+
+// ─── Unit Type → Default Tier Mapping ────────────────────────────────────────
+
+const UNIT_TYPE_TIERS: Record<string, ComplexityTier> = {
+  // Tier 1 — Light: structured summaries, completion, UAT
+  "complete-slice": "light",
+  "run-uat": "light",
+
+  // Tier 2 — Standard: research, routine planning
+  "research-milestone": "standard",
+  "research-slice": "standard",
+  "plan-milestone": "standard",
+  "plan-slice": "standard",
+
+  // Tier 3 — Heavy: execution, replanning (requires deep reasoning)
+  "execute-task": "standard",   // default standard, upgraded by metadata
+  "replan-slice": "heavy",
+  "reassess-roadmap": "heavy",
+};
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Classify unit complexity to determine which model tier to use.
+ *
+ * @param unitType    The type of unit being dispatched
+ * @param unitId      The unit ID (e.g. "M001/S01/T01")
+ * @param basePath    Project base path (for reading task plans)
+ * @param budgetPct   Current budget usage as fraction (0.0-1.0+), or undefined if no budget
+ * @param metadata    Optional pre-parsed task metadata
+ */
+export function classifyUnitComplexity(
+  unitType: string,
+  unitId: string,
+  basePath: string,
+  budgetPct?: number,
+  metadata?: TaskMetadata,
+): ClassificationResult {
+  // Hook units default to light
+  if (unitType.startsWith("hook/")) {
+    const result: ClassificationResult = { tier: "light", reason: "hook unit", downgraded: false };
+    return applyBudgetPressure(result, budgetPct);
+  }
+
+  // Start with the default tier for this unit type
+  let tier = UNIT_TYPE_TIERS[unitType] ?? "standard";
+  let reason = `unit type: ${unitType}`;
+
+  // For execute-task, analyze task metadata for complexity signals
+  if (unitType === "execute-task") {
+    const taskAnalysis = analyzeTaskComplexity(unitId, basePath, metadata);
+    tier = taskAnalysis.tier;
+    reason = taskAnalysis.reason;
+  }
+
+  // For plan-slice, check if the slice has many tasks (complex planning)
+  if (unitType === "plan-slice" || unitType === "plan-milestone") {
+    const planAnalysis = analyzePlanComplexity(unitId, basePath);
+    if (planAnalysis) {
+      tier = planAnalysis.tier;
+      reason = planAnalysis.reason;
+    }
+  }
+
+  // Adaptive learning: check if history suggests bumping the tier
+  const tags = metadata?.tags ?? extractTaskMetadata(unitId, basePath).tags;
+  const adaptiveAdjustment = getAdaptiveTierAdjustment(unitType, tier, tags);
+  if (adaptiveAdjustment && tierOrdinal(adaptiveAdjustment) > tierOrdinal(tier)) {
+    reason = `${reason} (adaptive: high failure rate at ${tier})`;
+    tier = adaptiveAdjustment;
+  }
+
+  const result: ClassificationResult = { tier, reason, downgraded: false };
+  return applyBudgetPressure(result, budgetPct);
+}
+
+/**
+ * Get a short label for the tier (for dashboard display).
+ */
+export function tierLabel(tier: ComplexityTier): string {
+  switch (tier) {
+    case "light": return "L";
+    case "standard": return "S";
+    case "heavy": return "H";
+  }
+}
+
+/**
+ * Get the tier ordering value (for comparison).
+ */
+export function tierOrdinal(tier: ComplexityTier): number {
+  switch (tier) {
+    case "light": return 0;
+    case "standard": return 1;
+    case "heavy": return 2;
+  }
+}
+
+// ─── Task Complexity Analysis ────────────────────────────────────────────────
+
+interface TaskAnalysis {
+  tier: ComplexityTier;
+  reason: string;
+}
+
+function analyzeTaskComplexity(
+  unitId: string,
+  basePath: string,
+  metadata?: TaskMetadata,
+): TaskAnalysis {
+  // Try to read task plan for complexity signals
+  const meta = metadata ?? extractTaskMetadata(unitId, basePath);
+
+  // Heavy signals
+  if (meta.dependencyCount && meta.dependencyCount >= 3) {
+    return { tier: "heavy", reason: `${meta.dependencyCount} dependencies` };
+  }
+  if (meta.fileCount && meta.fileCount >= 6) {
+    return { tier: "heavy", reason: `${meta.fileCount} files to modify` };
+  }
+  if (meta.estimatedLines && meta.estimatedLines >= 500) {
+    return { tier: "heavy", reason: `~${meta.estimatedLines} lines estimated` };
+  }
+
+  // Heavy signals from complexity keywords (Phase 4)
+  if (meta.complexityKeywords && meta.complexityKeywords.length >= 2) {
+    return { tier: "heavy", reason: `complex: ${meta.complexityKeywords.join(", ")}` };
+  }
+  if (meta.codeBlockCount && meta.codeBlockCount >= 5) {
+    return { tier: "heavy", reason: `${meta.codeBlockCount} code blocks in plan` };
+  }
+
+  // Standard signals from single complexity keyword
+  if (meta.complexityKeywords && meta.complexityKeywords.length === 1) {
+    return { tier: "standard", reason: `${meta.complexityKeywords[0]} task` };
+  }
+
+  // Light signals (simple tasks)
+  if (meta.tags?.some(t => /^(docs?|readme|comment|config|typo|rename)$/i.test(t))) {
+    return { tier: "light", reason: `simple task: ${meta.tags.join(", ")}` };
+  }
+  if (meta.fileCount !== undefined && meta.fileCount <= 1 && !meta.isNewFile) {
+    return { tier: "light", reason: "single file modification" };
+  }
+
+  // Standard by default
+  return { tier: "standard", reason: "standard execution task" };
+}
+
+function analyzePlanComplexity(
+  unitId: string,
+  basePath: string,
+): TaskAnalysis | null {
+  // Check if this is a milestone-level plan (more complex) vs single slice
+  const parts = unitId.split("/");
+  if (parts.length === 1) {
+    // Milestone-level planning is always at least standard
+    return { tier: "standard", reason: "milestone-level planning" };
+  }
+
+  // For slice planning, try to read the context/research to gauge complexity
+  // If research exists and is large, bump to heavy
+  const [mid, sid] = parts;
+  const researchPath = join(gsdRoot(basePath), mid, "slices", sid, "RESEARCH.md");
+  try {
+    if (existsSync(researchPath)) {
+      const content = readFileSync(researchPath, "utf-8");
+      const lineCount = content.split("\n").length;
+      if (lineCount > 200) {
+        return { tier: "heavy", reason: `complex slice: ${lineCount}-line research` };
+      }
+    }
+  } catch {
+    // Non-fatal
+  }
+
+  return null; // Use default tier
+}
+
+/**
+ * Extract task metadata from the task plan file on disk.
+ */
+function extractTaskMetadata(unitId: string, basePath: string): TaskMetadata {
+  const meta: TaskMetadata = {};
+  const parts = unitId.split("/");
+  if (parts.length !== 3) return meta;
+
+  const [mid, sid, tid] = parts;
+  const taskPlanPath = join(gsdRoot(basePath), mid, "slices", sid, "tasks", `${tid}-PLAN.md`);
+
+  try {
+    if (!existsSync(taskPlanPath)) return meta;
+    const content = readFileSync(taskPlanPath, "utf-8");
+    const lines = content.split("\n");
+
+    // Count files mentioned in "Files:" or "- Files:" lines
+    const fileLines = lines.filter(l => /^\s*-?\s*files?\s*:/i.test(l));
+    if (fileLines.length > 0) {
+      // Count comma-separated or bullet-pointed files
+      const allFiles = new Set<string>();
+      for (const line of fileLines) {
+        const filesStr = line.replace(/^\s*-?\s*files?\s*:\s*/i, "");
+        const files = filesStr.split(/[,;]/).map(f => f.trim()).filter(Boolean);
+        files.forEach(f => allFiles.add(f));
+      }
+      meta.fileCount = allFiles.size;
+    }
+
+    // Check for "new file" or "create" keywords
+    meta.isNewFile = lines.some(l => /\b(create|new file|scaffold|bootstrap)\b/i.test(l));
+
+    // Look for tags/labels in frontmatter or content
+    const tags: string[] = [];
+    if (content.match(/\b(refactor|migration|architect)/i)) tags.push("refactor");
+    if (content.match(/\b(test|spec|coverage)\b/i)) tags.push("test");
+    if (content.match(/\b(doc|readme|comment|jsdoc)\b/i)) tags.push("docs");
+    if (content.match(/\b(config|env|setting)\b/i)) tags.push("config");
+    if (content.match(/\b(rename|typo|spelling)\b/i)) tags.push("rename");
+    meta.tags = tags;
+
+    // Try to extract estimated lines from content
+    const estimateMatch = content.match(/~?\s*(\d+)\s*lines?\b/i);
+    if (estimateMatch) {
+      meta.estimatedLines = parseInt(estimateMatch[1], 10);
+    }
+
+    // Phase 4: Deeper introspection signals
+
+    // Count fenced code blocks (```) — more code blocks = more complex implementation
+    const codeBlockMatches = content.match(/^```/gm);
+    meta.codeBlockCount = codeBlockMatches ? Math.floor(codeBlockMatches.length / 2) : 0;
+
+    // Detect complexity keywords that suggest harder tasks
+    const complexityKeywords: string[] = [];
+    if (content.match(/\b(migration|migrate|schema change)\b/i)) complexityKeywords.push("migration");
+    if (content.match(/\b(architect|design pattern|system design)\b/i)) complexityKeywords.push("architecture");
+    if (content.match(/\b(security|auth|encrypt|credential|vulnerability)\b/i)) complexityKeywords.push("security");
+    if (content.match(/\b(performance|optimize|cache|index)\b/i)) complexityKeywords.push("performance");
+    if (content.match(/\b(concurrent|parallel|race condition|mutex|lock)\b/i)) complexityKeywords.push("concurrency");
+    if (content.match(/\b(backward.?compat|breaking change|deprecat)\b/i)) complexityKeywords.push("compatibility");
+    meta.complexityKeywords = complexityKeywords;
+  } catch {
+    // Non-fatal — metadata extraction is best-effort
+  }
+
+  return meta;
+}
+
+// ─── Budget Pressure ─────────────────────────────────────────────────────────
+
+/**
+ * Apply budget pressure to a classification result.
+ * As budget usage increases, more aggressively downgrade tiers.
+ *
+ * - <50%:   Normal classification (no change)
+ * - 50-75%: Tier 2 → Tier 1 where possible
+ * - 75-90%: Only heavy tasks keep configured model
+ * - >90%:   Everything except replan-slice gets cheapest model
+ */
+function applyBudgetPressure(
+  result: ClassificationResult,
+  budgetPct?: number,
+): ClassificationResult {
+  if (budgetPct === undefined || budgetPct < 0.5) return result;
+
+  const original = result.tier;
+
+  if (budgetPct >= 0.9) {
+    // >90%: almost everything goes to light
+    if (result.tier !== "heavy") {
+      result.tier = "light";
+    } else {
+      // Even heavy gets downgraded to standard
+      result.tier = "standard";
+    }
+  } else if (budgetPct >= 0.75) {
+    // 75-90%: only heavy stays, everything else goes to light
+    if (result.tier === "standard") {
+      result.tier = "light";
+    }
+  } else {
+    // 50-75%: standard → light
+    if (result.tier === "standard") {
+      result.tier = "light";
+    }
+  }
+
+  if (result.tier !== original) {
+    result.downgraded = true;
+    result.reason = `${result.reason} (budget pressure: ${Math.round(budgetPct * 100)}%)`;
+  }
+
+  return result;
+}

package/dist/resources/extensions/gsd/dashboard-overlay.ts

@@ -39,6 +39,9 @@ function unitLabel(type: string): string {
     case "execute-task": return "Execute";
     case "complete-slice": return "Complete";
     case "reassess-roadmap": return "Reassess";
+    case "triage-captures": return "Triage";
+    case "quick-task": return "Quick Task";
+    case "replan-slice": return "Replan";
     default: return type;
   }
 }
@@ -345,6 +348,13 @@ export class GSDDashboardOverlay {
       lines.push(blank());
     }
 
+    // Pending captures badge — only shown when captures are waiting for triage
+    if (this.dashData.pendingCaptureCount > 0) {
+      const count = this.dashData.pendingCaptureCount;
+      lines.push(row(th.fg("warning", `📌 ${count} pending capture${count === 1 ? "" : "s"} awaiting triage`)));
+      lines.push(blank());
+    }
+
     if (this.loading) {
       lines.push(centered(th.fg("dim", "Loading dashboard…")));
       return lines;

package/dist/resources/extensions/gsd/dispatch-guard.ts

@@ -5,7 +5,7 @@ import { readFileSync } from "node:fs";
 import { readdirSync } from "node:fs";
 import { resolveMilestoneFile, milestonesDir } from "./paths.js";
 import { parseRoadmapSlices } from "./roadmap-slices.js";
-import { extractMilestoneSeq, milestoneIdSort } from "./guided-flow.js";
+import { findMilestoneIds } from "./guided-flow.js";
 
 const SLICE_DISPATCH_TYPES = new Set([
   "research-slice",
@@ -43,24 +43,12 @@ export function getPriorSliceCompletionBlocker(base: string, _mainBranch: string
   const [targetMid, targetSid] = unitId.split("/");
   if (!targetMid || !targetSid) return null;
 
-  const targetSeq = extractMilestoneSeq(targetMid);
-  if (targetSeq === 0) return null;
-
-  // Scan actual milestone directories instead of iterating by number
-  let milestoneIds: string[];
-  try {
-    milestoneIds = readdirSync(milestonesDir(base), { withFileTypes: true })
-      .filter(d => d.isDirectory())
-      .map(d => {
-        const match = d.name.match(/^(M\d+(?:-[a-z0-9]{6})?)/);
-        return match ? match[1] : null;
-      })
-      .filter((id): id is string => id !== null)
-      .sort(milestoneIdSort)
-      .filter(id => extractMilestoneSeq(id) <= targetSeq);
-  } catch {
-    return null;
-  }
+  // Use findMilestoneIds to respect custom queue order.
+  // Only check milestones that come BEFORE the target in queue order.
+  const allIds = findMilestoneIds(base);
+  const targetIdx = allIds.indexOf(targetMid);
+  if (targetIdx < 0) return null;
+  const milestoneIds = allIds.slice(0, targetIdx + 1);
 
   for (const mid of milestoneIds) {
     // Read from disk (working tree) — always has the latest state

package/dist/resources/extensions/gsd/docs/preferences-reference.md

@@ -80,9 +80,9 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
 
 - `skill_rules`: situational rules with a human-readable `when` trigger and one or more of `use`, `prefer`, or `avoid`.
 
-- `custom_instructions`: extra durable instructions related to skill use.
+- `custom_instructions`: extra durable instructions related to skill use. For operational project knowledge (recurring rules, gotchas, patterns), use `.gsd/KNOWLEDGE.md` instead — it's injected into every agent prompt automatically and agents can append to it during execution.
 
-- `models`: per-stage model selection for auto-mode. Keys: `research`, `planning`, `execution`, `completion`. Values can be:
+- `models`: per-stage model selection for auto-mode. Keys: `research`, `planning`, `execution`, `execution_simple`, `completion`, `subagent`. Values can be:
   - Simple string: `"claude-sonnet-4-6"` — single model, no fallbacks
   - Provider-qualified string: `"bedrock/claude-sonnet-4-6"` — targets a specific provider when the same model ID exists across multiple providers
   - Object with fallbacks: `{ model: "claude-opus-4-6", fallbacks: ["glm-5", "minimax-m2.5"] }` — tries fallbacks in order if primary fails
@@ -108,10 +108,75 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `pre_merge_check`: boolean or `"auto"` — run pre-merge checks before merging a worktree back to the integration branch. `true` always runs, `false` never runs, `"auto"` runs when CI is detected. Default: `false`.
   - `commit_type`: string — override the conventional commit type prefix. Must be one of: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `ci`, `build`, `style`. Default: inferred from diff content.
   - `main_branch`: string — the primary branch name for new git repos (e.g., `"main"`, `"master"`, `"trunk"`). Also used by `getMainBranch()` as the preferred branch when auto-detection is ambiguous. Default: `"main"`.
+  - `merge_strategy`: `"squash"` or `"merge"` — controls how worktree branches are merged back. `"squash"` combines all commits into one; `"merge"` preserves individual commits. Default: `"squash"`.
+  - `isolation`: `"worktree"` or `"branch"` — controls auto-mode git isolation strategy. `"worktree"` creates a milestone worktree for isolated work; `"branch"` works directly in the project root (useful for submodule-heavy repos). Default: `"worktree"`.
   - `commit_docs`: boolean — when `false`, prevents GSD from committing `.gsd/` planning artifacts to git. The `.gsd/` folder is added to `.gitignore` and kept local-only. Useful for teams where only some members use GSD, or when company policy requires a clean repository. Default: `true`.
 
 - `unique_milestone_ids`: boolean — when `true`, generates milestone IDs in `M{seq}-{rand6}` format (e.g. `M001-eh88as`) instead of plain sequential `M001`. Prevents ID collisions in team workflows where multiple contributors create milestones concurrently. Both formats coexist — existing `M001`-style milestones remain valid. Default: `false`.
 
+- `budget_ceiling`: number — maximum dollar amount to spend on auto-mode. When reached, behavior is controlled by `budget_enforcement`. Default: no limit.
+
+- `budget_enforcement`: `"warn"`, `"pause"`, or `"halt"` — action taken when `budget_ceiling` is reached.
+  - `warn` — log a warning but continue execution.
+  - `pause` — pause auto-mode and wait for user confirmation.
+  - `halt` — stop auto-mode immediately.
+  - Default: `"pause"`.
+
+- `context_pause_threshold`: number (0-100) — context window usage percentage at which auto-mode should pause to suggest checkpointing. Set to `0` to disable. Default: `0` (disabled).
+
+- `token_profile`: `"budget"`, `"balanced"`, or `"quality"` — coordinates model selection, phase skipping, and context compression. `budget` skips research/reassessment and uses cheaper models; `balanced` (default) runs all phases; `quality` prefers higher-quality models. See token-optimization docs.
+
+- `phases`: fine-grained control over which phases run. Usually set by `token_profile`, but can be overridden. Keys:
+  - `skip_research`: boolean — skip milestone-level research. Default: `false`.
+  - `skip_reassess`: boolean — skip roadmap reassessment after each slice. Default: `false`.
+  - `skip_slice_research`: boolean — skip per-slice research. Default: `false`.
+
+- `remote_questions`: route interactive questions to Slack/Discord for headless auto-mode. Keys:
+  - `channel`: `"slack"` or `"discord"` — channel type.
+  - `channel_id`: string or number — channel ID.
+  - `timeout_minutes`: number — question timeout in minutes (clamped 1-30).
+  - `poll_interval_seconds`: number — poll interval in seconds (clamped 2-30).
+
+- `notifications`: configures desktop notification behavior during auto-mode. Keys:
+  - `enabled`: boolean — master toggle for all notifications. Default: `true`.
+  - `on_complete`: boolean — notify when a unit completes. Default: `true`.
+  - `on_error`: boolean — notify on errors. Default: `true`.
+  - `on_budget`: boolean — notify when budget thresholds are reached. Default: `true`.
+  - `on_milestone`: boolean — notify when a milestone finishes. Default: `true`.
+  - `on_attention`: boolean — notify when manual attention is needed. Default: `true`.
+
+- `uat_dispatch`: boolean — when `true`, enables UAT (User Acceptance Testing) dispatch mode. Default: `false`.
+
+- `post_unit_hooks`: array — hooks that fire after a unit completes. Each entry has:
+  - `name`: string — unique hook identifier.
+  - `after`: string[] — unit types that trigger this hook (e.g., `["execute-task"]`).
+  - `prompt`: string — prompt sent to the LLM. Supports `{milestoneId}`, `{sliceId}`, `{taskId}` substitutions.
+  - `max_cycles`: number — max times this hook fires per trigger (default: 1, max: 10).
+  - `model`: string — optional model override.
+  - `artifact`: string — expected output file name (relative to task/slice dir). Hook is skipped if file already exists (idempotent).
+  - `retry_on`: string — if this file is produced instead of the artifact, re-run the trigger unit then re-run hooks.
+  - `agent`: string — agent definition file to use for hook execution.
+  - `enabled`: boolean — toggle without removing (default: `true`).
+
+- `pre_dispatch_hooks`: array — hooks that fire before a unit is dispatched. Each entry has:
+  - `name`: string — unique hook identifier.
+  - `before`: string[] — unit types to intercept.
+  - `action`: `"modify"`, `"skip"`, or `"replace"` — what to do with the unit.
+  - `prepend`: string — text prepended to unit prompt (for `"modify"` action).
+  - `append`: string — text appended to unit prompt (for `"modify"` action).
+  - `prompt`: string — replacement prompt (for `"replace"` action; required when action is `"replace"`).
+  - `unit_type`: string — override unit type label (for `"replace"` action).
+  - `skip_if`: string — for `"skip"` action: only skip if this file exists (relative to unit dir).
+  - `model`: string — optional model override when this hook fires.
+  - `enabled`: boolean — toggle without removing (default: `true`).
+
+  **Action validation:**
+  - `"modify"` requires at least one of `prepend` or `append`.
+  - `"replace"` requires `prompt`.
+  - `"skip"` is valid with no additional fields.
+
+  **Known unit types for `before`/`after`:** `research-milestone`, `plan-milestone`, `research-slice`, `plan-slice`, `execute-task`, `complete-slice`, `replan-slice`, `reassess-roadmap`, `run-uat`.
+
 ---
 
 ## Best Practices
@@ -277,3 +342,137 @@ git:
 ```
 
 All git fields are optional. Omit any field to use the default behavior. Project-level preferences override global preferences on a per-field basis.
+
+---
+
+## Budget & Cost Control Example
+
+```yaml
+---
+version: 1
+budget_ceiling: 10.00
+budget_enforcement: pause
+context_pause_threshold: 80
+---
+```
+
+Sets a $10 budget ceiling. Auto-mode pauses when the ceiling is reached. Context window pauses at 80% usage for checkpointing.
+
+---
+
+## Notifications Example
+
+```yaml
+---
+version: 1
+notifications:
+  enabled: true
+  on_complete: false
+  on_error: true
+  on_budget: true
+  on_milestone: true
+  on_attention: true
+---
+```
+
+Disables per-unit completion notifications (noisy in long runs) while keeping error, budget, milestone, and attention notifications enabled.
+
+---
+
+## Post-Unit Hooks Example
+
+```yaml
+---
+version: 1
+post_unit_hooks:
+  - name: code-review
+    after:
+      - execute-task
+    prompt: "Review the code changes in {sliceId}/{taskId} for quality, security, and test coverage."
+    max_cycles: 1
+    artifact: REVIEW.md
+---
+```
+
+Runs an automated code review after each task execution. Skips if `REVIEW.md` already exists (idempotent).
+
+---
+
+## Pre-Dispatch Hooks Examples
+
+**Modify — inject instructions before every task:**
+
+```yaml
+---
+version: 1
+pre_dispatch_hooks:
+  - name: enforce-standards
+    before:
+      - execute-task
+    action: modify
+    prepend: "Follow our TypeScript coding standards and always run linting."
+---
+```
+
+**Skip — skip per-slice research when a research file already exists:**
+
+```yaml
+---
+version: 1
+pre_dispatch_hooks:
+  - name: skip-existing-research
+    before:
+      - research-slice
+    action: skip
+    skip_if: RESEARCH.md
+---
+```
+
+**Replace — substitute a custom prompt for task execution:**
+
+```yaml
+---
+version: 1
+pre_dispatch_hooks:
+  - name: tdd-execute
+    before:
+      - execute-task
+    action: replace
+    prompt: "Implement the task using strict TDD. Write failing tests first, then implement, then refactor."
+    model: claude-opus-4-6
+---
+```
+
+---
+
+## Token Profile & Phases Example
+
+```yaml
+---
+version: 1
+token_profile: budget
+phases:
+  skip_research: true
+  skip_reassess: true
+  skip_slice_research: false
+---
+```
+
+Uses the `budget` profile to minimize token usage, with explicit override to keep slice-level research enabled.
+
+---
+
+## Remote Questions Example
+
+```yaml
+---
+version: 1
+remote_questions:
+  channel: slack
+  channel_id: "C0123456789"
+  timeout_minutes: 15
+  poll_interval_seconds: 10
+---
+```
+
+Routes interactive questions to a Slack channel for headless auto-mode sessions. Questions time out after 15 minutes if unanswered.