gsd-pi 2.19.0 → 2.20.0

package/dist/resources/extensions/gsd/commands.ts

@@ -8,6 +8,7 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent
 import { AuthStorage } from "@gsd/pi-coding-agent";
 import { existsSync, readFileSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
+import { enableDebug, isDebugEnabled } from "./debug-logger.js";
 import { fileURLToPath } from "node:url";
 import { deriveState } from "./state.js";
 import { GSDDashboardOverlay } from "./dashboard-overlay.js";
@@ -36,12 +37,13 @@ import {
 import { loadPrompt } from "./prompt-loader.js";
 
 import { handleRemote } from "../remote-questions/remote-command.js";
+import { handleQuick } from "./quick.js";
 import { handleHistory } from "./history.js";
 import { handleUndo } from "./undo.js";
 import { handleExport } from "./export.js";
 import { nativeBranchList, nativeDetectMainBranch, nativeBranchListMerged, nativeBranchDelete, nativeForEachRef, nativeUpdateRef } from "./native-git-bridge.js";
 
-function dispatchDoctorHeal(pi: ExtensionAPI, scope: string | undefined, reportText: string, structuredIssues: string): void {
+export function dispatchDoctorHeal(pi: ExtensionAPI, scope: string | undefined, reportText: string, structuredIssues: string): void {
   const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(process.env.HOME ?? "~", ".pi", "GSD-WORKFLOW.md");
   const workflow = readFileSync(workflowPath, "utf-8");
   const prompt = loadPrompt("doctor-heal", {
@@ -66,13 +68,13 @@ function projectRoot(): string {
 
 export function registerGSDCommand(pi: ExtensionAPI): void {
   pi.registerCommand("gsd", {
-    description: "GSD — Get Shit Done: /gsd next|auto|stop|pause|status|visualize|queue|capture|triage|history|undo|skip|export|cleanup|prefs|config|hooks|doctor|migrate|remote|steer|knowledge",
+    description: "GSD — Get Shit Done: /gsd help|next|auto|stop|pause|status|visualize|queue|quick|capture|triage|history|undo|skip|export|cleanup|mode|prefs|config|hooks|run-hook|skill-health|doctor|migrate|remote|steer|knowledge",
     getArgumentCompletions: (prefix: string) => {
       const subcommands = [
-        "next", "auto", "stop", "pause", "status", "visualize", "queue", "discuss",
+        "help", "next", "auto", "stop", "pause", "status", "visualize", "queue", "quick", "discuss",
         "capture", "triage",
-        "history", "undo", "skip", "export", "cleanup", "prefs",
-        "config", "hooks", "doctor", "migrate", "remote", "steer", "knowledge",
+        "history", "undo", "skip", "export", "cleanup", "mode", "prefs",
+        "config", "hooks", "run-hook", "skill-health", "doctor", "migrate", "remote", "steer", "inspect", "knowledge",
       ];
       const parts = prefix.trim().split(/\s+/);
 
@@ -84,11 +86,18 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
 
       if (parts[0] === "auto" && parts.length <= 2) {
         const flagPrefix = parts[1] ?? "";
-        return ["--verbose"]
+        return ["--verbose", "--debug"]
           .filter((f) => f.startsWith(flagPrefix))
           .map((f) => ({ value: `auto ${f}`, label: f }));
       }
 
+      if (parts[0] === "mode" && parts.length <= 2) {
+        const subPrefix = parts[1] ?? "";
+        return ["global", "project"]
+          .filter((cmd) => cmd.startsWith(subPrefix))
+          .map((cmd) => ({ value: `mode ${cmd}`, label: cmd }));
+      }
+
       if (parts[0] === "prefs" && parts.length <= 2) {
         const subPrefix = parts[1] ?? "";
         return ["global", "project", "status", "wizard", "setup"]
@@ -161,6 +170,11 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
     async handler(args: string, ctx: ExtensionCommandContext) {
       const trimmed = (typeof args === "string" ? args : "").trim();
 
+      if (trimmed === "help" || trimmed === "h" || trimmed === "?") {
+        showHelp(ctx);
+        return;
+      }
+
       if (trimmed === "status") {
         await handleStatus(ctx);
         return;
@@ -171,6 +185,15 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
         return;
       }
 
+      if (trimmed === "mode" || trimmed.startsWith("mode ")) {
+        const modeArgs = trimmed.replace(/^mode\s*/, "").trim();
+        const scope = modeArgs === "project" ? "project" : "global";
+        const path = scope === "project" ? getProjectGSDPreferencesPath() : getGlobalGSDPreferencesPath();
+        await ensurePreferencesFile(path, ctx, scope);
+        await handlePrefsMode(ctx, scope);
+        return;
+      }
+
       if (trimmed === "prefs" || trimmed.startsWith("prefs ")) {
         await handlePrefs(trimmed.replace(/^prefs\s*/, "").trim(), ctx);
         return;
@@ -187,12 +210,16 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
           return;
         }
         const verboseMode = trimmed.includes("--verbose");
+        const debugMode = trimmed.includes("--debug");
+        if (debugMode) enableDebug(projectRoot());
         await startAuto(ctx, pi, projectRoot(), verboseMode, { step: true });
         return;
       }
 
       if (trimmed === "auto" || trimmed.startsWith("auto ")) {
         const verboseMode = trimmed.includes("--verbose");
+        const debugMode = trimmed.includes("--debug");
+        if (debugMode) enableDebug(projectRoot());
         await startAuto(ctx, pi, projectRoot(), verboseMode);
         return;
       }
@@ -277,6 +304,11 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
         return;
       }
 
+      if (trimmed === "quick" || trimmed.startsWith("quick ")) {
+        await handleQuick(trimmed.replace(/^quick\s*/, "").trim(), ctx, pi);
+        return;
+      }
+
       if (trimmed === "config") {
         await handleConfig(ctx);
         return;
@@ -288,6 +320,32 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
         return;
       }
 
+      // ─── Skill Health ────────────────────────────────────────────
+      if (trimmed === "skill-health" || trimmed.startsWith("skill-health ")) {
+        await handleSkillHealth(trimmed.replace(/^skill-health\s*/, "").trim(), ctx);
+        return;
+      }
+
+      if (trimmed.startsWith("run-hook ")) {
+        await handleRunHook(trimmed.replace(/^run-hook\s*/, "").trim(), ctx, pi);
+        return;
+      }
+      if (trimmed === "run-hook") {
+        ctx.ui.notify(`Usage: /gsd run-hook <hook-name> <unit-type> <unit-id>
+
+Unit types:
+  execute-task   - Task execution (unit-id: M001/S01/T01)
+  plan-slice     - Slice planning (unit-id: M001/S01)
+  research-milestone - Milestone research (unit-id: M001)
+  complete-slice - Slice completion (unit-id: M001/S01)
+  complete-milestone - Milestone completion (unit-id: M001)
+
+Examples:
+  /gsd run-hook code-review execute-task M001/S01/T01
+  /gsd run-hook lint-check plan-slice M001/S01`, "warning");
+        return;
+      }
+
       if (trimmed.startsWith("steer ")) {
         await handleSteer(trimmed.replace(/^steer\s+/, "").trim(), ctx, pi);
         return;
@@ -317,6 +375,11 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
         return;
       }
 
+      if (trimmed === "inspect") {
+        await handleInspect(ctx);
+        return;
+      }
+
       if (trimmed === "") {
         // Bare /gsd defaults to step mode
         await startAuto(ctx, pi, projectRoot(), false, { step: true });
@@ -324,13 +387,57 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
       }
 
       ctx.ui.notify(
-        `Unknown: /gsd ${trimmed}. Use /gsd next|auto|stop|pause|status|visualize|queue|capture|triage|discuss|history|undo|skip <unit>|export|cleanup|prefs|config|hooks|doctor|migrate|remote|steer <change>|knowledge <type> <entry>.`,
+        `Unknown: /gsd ${trimmed}. Run /gsd help for available commands.`,
         "warning",
       );
     },
   });
 }
 
+function showHelp(ctx: ExtensionCommandContext): void {
+  const lines = [
+    "GSD — Get Shit Done\n",
+    "WORKFLOW",
+    "  /gsd               Run next unit in step mode (same as /gsd next)",
+    "  /gsd next           Execute next task, then pause  [--dry-run] [--verbose]",
+    "  /gsd auto           Run all queued units continuously  [--verbose]",
+    "  /gsd stop           Stop auto-mode gracefully",
+    "  /gsd pause          Pause auto-mode (preserves state, /gsd auto to resume)",
+    "  /gsd discuss        Start guided milestone/slice discussion",
+    "",
+    "VISIBILITY",
+    "  /gsd status         Show progress dashboard  (Ctrl+Alt+G)",
+    "  /gsd visualize      Interactive 7-tab TUI (progress, deps, metrics, timeline, agent, changes, export)",
+    "  /gsd queue          Show queued/dispatched units and execution order",
+    "  /gsd history        View execution history  [--cost] [--phase] [--model] [N]",
+    "",
+    "COURSE CORRECTION",
+    "  /gsd steer <desc>   Apply user override to active work",
+    "  /gsd capture <text> Quick-capture a thought to CAPTURES.md",
+    "  /gsd triage         Classify and route pending captures",
+    "  /gsd skip <unit>    Prevent a unit from auto-mode dispatch",
+    "  /gsd undo           Revert last completed unit  [--force]",
+    "",
+    "PROJECT KNOWLEDGE",
+    "  /gsd knowledge <type> <text>   Add rule, pattern, or lesson to KNOWLEDGE.md",
+    "",
+    "CONFIGURATION",
+    "  /gsd mode           Set workflow mode (solo/team)  [global|project]",
+    "  /gsd prefs          Manage preferences  [global|project|status|wizard|setup]",
+    "  /gsd config         Set API keys for external tools",
+    "  /gsd hooks          Show post-unit hook configuration",
+    "",
+    "MAINTENANCE",
+    "  /gsd doctor         Diagnose and repair .gsd/ state  [audit|fix|heal] [scope]",
+    "  /gsd export         Export milestone/slice results  [--json|--markdown]",
+    "  /gsd cleanup        Remove merged branches or snapshots  [branches|snapshots]",
+    "  /gsd migrate        Upgrade .gsd/ structures to new format",
+    "  /gsd remote         Control remote auto-mode  [slack|discord|status|disconnect]",
+    "  /gsd inspect        Show SQLite DB diagnostics (schema, row counts, recent entries)",
+  ];
+  ctx.ui.notify(lines.join("\n"), "info");
+}
+
 async function handleStatus(ctx: ExtensionCommandContext): Promise<void> {
   const basePath = projectRoot();
   const state = await deriveState(basePath);
@@ -433,6 +540,36 @@ async function handlePrefs(args: string, ctx: ExtensionCommandContext): Promise<
   ctx.ui.notify("Usage: /gsd prefs [global|project|status|wizard|setup]", "info");
 }
 
+async function handlePrefsMode(ctx: ExtensionCommandContext, scope: "global" | "project"): Promise<void> {
+  const path = scope === "project" ? getProjectGSDPreferencesPath() : getGlobalGSDPreferencesPath();
+  const existing = scope === "project" ? loadProjectGSDPreferences() : loadGlobalGSDPreferences();
+  const prefs: Record<string, unknown> = existing?.preferences ? { ...existing.preferences } : {};
+
+  await configureMode(ctx, prefs);
+
+  // Serialize and save
+  prefs.version = prefs.version || 1;
+  const frontmatter = serializePreferencesToFrontmatter(prefs);
+
+  let body = "\n# GSD Skill Preferences\n\nSee `~/.gsd/agent/extensions/gsd/docs/preferences-reference.md` for full field documentation and examples.\n";
+  if (existsSync(path)) {
+    const existingContent = readFileSync(path, "utf-8");
+    const closingIdx = existingContent.indexOf("\n---", existingContent.indexOf("---"));
+    if (closingIdx !== -1) {
+      const afterFrontmatter = existingContent.slice(closingIdx + 4);
+      if (afterFrontmatter.trim()) {
+        body = afterFrontmatter;
+      }
+    }
+  }
+
+  const content = `---\n${frontmatter}---${body}`;
+  await saveFile(path, content);
+  await ctx.waitForIdle();
+  await ctx.reload();
+  ctx.ui.notify(`Saved ${scope} preferences to ${path}`, "info");
+}
+
 async function handleDoctor(args: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {
   const trimmed = args.trim();
   const parts = trimmed ? trimmed.split(/\s+/) : [];
@@ -471,19 +608,220 @@ async function handleDoctor(args: string, ctx: ExtensionCommandContext, pi: Exte
   }
 }
 
+// ─── Inspect ──────────────────────────────────────────────────────────────────
+
+export interface InspectData {
+  schemaVersion: number | null;
+  counts: { decisions: number; requirements: number; artifacts: number };
+  recentDecisions: Array<{ id: string; decision: string; choice: string }>;
+  recentRequirements: Array<{ id: string; status: string; description: string }>;
+}
+
+export function formatInspectOutput(data: InspectData): string {
+  const lines: string[] = [];
+  lines.push("=== GSD Database Inspect ===");
+  lines.push(`Schema version: ${data.schemaVersion ?? "unknown"}`);
+  lines.push("");
+  lines.push(`Decisions:    ${data.counts.decisions}`);
+  lines.push(`Requirements: ${data.counts.requirements}`);
+  lines.push(`Artifacts:    ${data.counts.artifacts}`);
+
+  if (data.recentDecisions.length > 0) {
+    lines.push("");
+    lines.push("Recent decisions:");
+    for (const d of data.recentDecisions) {
+      lines.push(`  ${d.id}: ${d.decision} → ${d.choice}`);
+    }
+  }
+
+  if (data.recentRequirements.length > 0) {
+    lines.push("");
+    lines.push("Recent requirements:");
+    for (const r of data.recentRequirements) {
+      lines.push(`  ${r.id} [${r.status}]: ${r.description}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+async function handleInspect(ctx: ExtensionCommandContext): Promise<void> {
+  try {
+    const { isDbAvailable, _getAdapter } = await import("./gsd-db.js");
+
+    if (!isDbAvailable()) {
+      ctx.ui.notify("No GSD database available. Run /gsd auto to create one.", "info");
+      return;
+    }
+
+    const adapter = _getAdapter();
+    if (!adapter) {
+      ctx.ui.notify("No GSD database available. Run /gsd auto to create one.", "info");
+      return;
+    }
+
+    const versionRow = adapter.prepare("SELECT MAX(version) as v FROM schema_version").get();
+    const schemaVersion = versionRow ? (versionRow["v"] as number | null) : null;
+
+    const dCount = adapter.prepare("SELECT count(*) as cnt FROM decisions").get();
+    const rCount = adapter.prepare("SELECT count(*) as cnt FROM requirements").get();
+    const aCount = adapter.prepare("SELECT count(*) as cnt FROM artifacts").get();
+
+    const recentDecisions = adapter
+      .prepare("SELECT id, decision, choice FROM decisions ORDER BY seq DESC LIMIT 5")
+      .all() as Array<{ id: string; decision: string; choice: string }>;
+
+    const recentRequirements = adapter
+      .prepare("SELECT id, status, description FROM requirements ORDER BY id DESC LIMIT 5")
+      .all() as Array<{ id: string; status: string; description: string }>;
+
+    const data: InspectData = {
+      schemaVersion,
+      counts: {
+        decisions: (dCount?.["cnt"] as number) ?? 0,
+        requirements: (rCount?.["cnt"] as number) ?? 0,
+        artifacts: (aCount?.["cnt"] as number) ?? 0,
+      },
+      recentDecisions,
+      recentRequirements,
+    };
+
+    ctx.ui.notify(formatInspectOutput(data), "info");
+  } catch (err) {
+    process.stderr.write(`gsd-db: /gsd inspect failed: ${err instanceof Error ? err.message : String(err)}\n`);
+    ctx.ui.notify("Failed to inspect GSD database. Check stderr for details.", "error");
+  }
+}
+
+// ─── Skill Health ─────────────────────────────────────────────────────────────
+
+async function handleSkillHealth(args: string, ctx: ExtensionCommandContext): Promise<void> {
+  const {
+    generateSkillHealthReport,
+    formatSkillHealthReport,
+    formatSkillDetail,
+  } = await import("./skill-health.js");
+
+  const basePath = projectRoot();
+
+  // /gsd skill-health <skill-name> — detail view
+  if (args && !args.startsWith("--")) {
+    const detail = formatSkillDetail(basePath, args);
+    ctx.ui.notify(detail, "info");
+    return;
+  }
+
+  // Parse flags
+  const staleMatch = args.match(/--stale\s+(\d+)/);
+  const staleDays = staleMatch ? parseInt(staleMatch[1], 10) : undefined;
+  const decliningOnly = args.includes("--declining");
+
+  const report = generateSkillHealthReport(basePath, staleDays);
+
+  if (decliningOnly) {
+    if (report.decliningSkills.length === 0) {
+      ctx.ui.notify("No skills flagged for declining performance.", "info");
+      return;
+    }
+    const filtered = {
+      ...report,
+      skills: report.skills.filter(s => s.flagged),
+    };
+    ctx.ui.notify(formatSkillHealthReport(filtered), "info");
+    return;
+  }
+
+  ctx.ui.notify(formatSkillHealthReport(report), "info");
+}
+
 // ─── Preferences Wizard ───────────────────────────────────────────────────────
 
-async function handlePrefsWizard(
-  ctx: ExtensionCommandContext,
-  scope: "global" | "project",
-): Promise<void> {
-  const path = scope === "project" ? getProjectGSDPreferencesPath() : getGlobalGSDPreferencesPath();
-  const existing = scope === "project" ? loadProjectGSDPreferences() : loadGlobalGSDPreferences();
-  const prefs: Record<string, unknown> = existing?.preferences ? { ...existing.preferences } : {};
+/** Build short summary strings for each preference category. */
+function buildCategorySummaries(prefs: Record<string, unknown>): Record<string, string> {
+  // Mode
+  const mode = prefs.mode as string | undefined;
+  const modeSummary = mode ?? "(not set)";
+
+  // Models
+  const models = prefs.models as Record<string, string> | undefined;
+  let modelsSummary = "(not configured)";
+  if (models && Object.keys(models).length > 0) {
+    const parts = Object.entries(models).map(([phase, model]) => `${phase}: ${model}`);
+    modelsSummary = parts.join(", ");
+  }
+
+  // Timeouts
+  const autoSup = prefs.auto_supervisor as Record<string, unknown> | undefined;
+  let timeoutsSummary = "(defaults)";
+  if (autoSup && Object.keys(autoSup).length > 0) {
+    const soft = autoSup.soft_timeout_minutes ?? "20";
+    const idle = autoSup.idle_timeout_minutes ?? "10";
+    const hard = autoSup.hard_timeout_minutes ?? "30";
+    timeoutsSummary = `soft: ${soft}m, idle: ${idle}m, hard: ${hard}m`;
+  }
+
+  // Git
+  const git = prefs.git as Record<string, unknown> | undefined;
+  let gitSummary = "(defaults)";
+  if (git && Object.keys(git).length > 0) {
+    const branch = git.main_branch ?? "main";
+    const push = git.auto_push ? "on" : "off";
+    gitSummary = `main: ${branch}, push: ${push}`;
+  }
+
+  // Skills
+  const discovery = prefs.skill_discovery as string | undefined;
+  const uat = prefs.uat_dispatch;
+  let skillsSummary = "(not configured)";
+  if (discovery || uat !== undefined) {
+    const parts: string[] = [];
+    if (discovery) parts.push(`discovery: ${discovery}`);
+    if (uat !== undefined) parts.push(`uat: ${uat}`);
+    skillsSummary = parts.join(", ");
+  }
+
+  // Budget
+  const ceiling = prefs.budget_ceiling;
+  const enforcement = prefs.budget_enforcement as string | undefined;
+  let budgetSummary = "(no limit)";
+  if (ceiling !== undefined) {
+    budgetSummary = `$${ceiling}`;
+    if (enforcement) budgetSummary += ` / ${enforcement}`;
+  } else if (enforcement) {
+    budgetSummary = enforcement;
+  }
+
+  // Notifications
+  const notif = prefs.notifications as Record<string, boolean> | undefined;
+  let notifSummary = "(defaults)";
+  if (notif && Object.keys(notif).length > 0) {
+    const allKeys = ["enabled", "on_complete", "on_error", "on_budget", "on_milestone", "on_attention"];
+    const enabledCount = allKeys.filter(k => notif[k] !== false).length;
+    notifSummary = `${enabledCount}/${allKeys.length} enabled`;
+  }
+
+  // Advanced
+  const uniqueIds = prefs.unique_milestone_ids;
+  let advancedSummary = "(defaults)";
+  if (uniqueIds !== undefined) {
+    advancedSummary = `unique IDs: ${uniqueIds ? "on" : "off"}`;
+  }
 
-  ctx.ui.notify(`GSD preferences wizard (${scope}) — press Escape at any prompt to skip it.`, "info");
+  return {
+    mode: modeSummary,
+    models: modelsSummary,
+    timeouts: timeoutsSummary,
+    git: gitSummary,
+    skills: skillsSummary,
+    budget: budgetSummary,
+    notifications: notifSummary,
+    advanced: advancedSummary,
+  };
+}
+
+// ─── Category configuration functions ────────────────────────────────────────
 
-  // ─── Models ──────────────────────────────────────────────────────────────
+async function configureModels(ctx: ExtensionCommandContext, prefs: Record<string, unknown>): Promise<void> {
   const modelPhases = ["research", "planning", "execution", "completion"] as const;
   const models: Record<string, string> = (prefs.models as Record<string, string>) ?? {};
 
@@ -506,7 +844,6 @@ async function handlePrefsWizard(
       }
     }
   } else {
-    // No authenticated models available — fall back to text input
     for (const phase of modelPhases) {
       const current = models[phase] ?? "";
       const input = await ctx.ui.input(
@@ -526,8 +863,9 @@ async function handlePrefsWizard(
   if (Object.keys(models).length > 0) {
     prefs.models = models;
   }
+}
 
-  // ─── Auto-supervisor timeouts ────────────────────────────────────────────
+async function configureTimeouts(ctx: ExtensionCommandContext, prefs: Record<string, unknown>): Promise<void> {
   const autoSup: Record<string, unknown> = (prefs.auto_supervisor as Record<string, unknown>) ?? {};
   const timeoutFields = [
     { key: "soft_timeout_minutes", label: "Soft timeout (minutes)", defaultVal: "20" },
@@ -556,8 +894,9 @@ async function handlePrefsWizard(
   if (Object.keys(autoSup).length > 0) {
     prefs.auto_supervisor = autoSup;
   }
+}
 
-  // ─── Git settings ───────────────────────────────────────────────────────
+async function configureGit(ctx: ExtensionCommandContext, prefs: Record<string, unknown>): Promise<void> {
   const git: Record<string, unknown> = (prefs.git as Record<string, unknown>) ?? {};
 
   // main_branch
@@ -658,7 +997,7 @@ async function handlePrefsWizard(
     git.isolation = isolationChoice;
   }
 
-  // ─── Git commit_docs ────────────────────────────────────────────────────
+  // commit_docs
   const currentCommitDocs = git.commit_docs;
   const commitDocsChoice = await ctx.ui.select(
     `Track .gsd/ planning docs in git${currentCommitDocs !== undefined ? ` (current: ${currentCommitDocs})` : ""}:`,
@@ -671,8 +1010,10 @@ async function handlePrefsWizard(
   if (Object.keys(git).length > 0) {
     prefs.git = git;
   }
+}
 
-  // ─── Skill discovery mode ───────────────────────────────────────────────
+async function configureSkills(ctx: ExtensionCommandContext, prefs: Record<string, unknown>): Promise<void> {
+  // Skill discovery mode
   const currentDiscovery = (prefs.skill_discovery as string) ?? "";
   const discoveryChoice = await ctx.ui.select(
     `Skill discovery mode${currentDiscovery ? ` (current: ${currentDiscovery})` : ""}:`,
@@ -682,17 +1023,18 @@ async function handlePrefsWizard(
     prefs.skill_discovery = discoveryChoice;
   }
 
-  // ─── Unique milestone IDs ──────────────────────────────────────────────
-  const currentUnique = prefs.unique_milestone_ids;
-  const uniqueChoice = await ctx.ui.select(
-    `Unique milestone IDs${currentUnique !== undefined ? ` (current: ${currentUnique})` : ""}:`,
+  // UAT dispatch
+  const currentUat = prefs.uat_dispatch;
+  const uatChoice = await ctx.ui.select(
+    `UAT dispatch mode${currentUat !== undefined ? ` (current: ${currentUat})` : " (default: false)"}:`,
     ["true", "false", "(keep current)"],
   );
-  if (uniqueChoice && uniqueChoice !== "(keep current)") {
-    prefs.unique_milestone_ids = uniqueChoice === "true";
+  if (uatChoice && uatChoice !== "(keep current)") {
+    prefs.uat_dispatch = uatChoice === "true";
   }
+}
 
-  // ─── Budget & cost control ────────────────────────────────────────────
+async function configureBudget(ctx: ExtensionCommandContext, prefs: Record<string, unknown>): Promise<void> {
   const currentCeiling = prefs.budget_ceiling;
   const ceilingStr = currentCeiling !== undefined ? String(currentCeiling) : "";
   const ceilingInput = await ctx.ui.input(
@@ -738,8 +1080,9 @@ async function handlePrefsWizard(
       ctx.ui.notify(`Invalid context pause threshold "${val}" — must be 0-100. Keeping previous value.`, "warning");
     }
   }
+}
 
-  // ─── Notifications ────────────────────────────────────────────────────
+async function configureNotifications(ctx: ExtensionCommandContext, prefs: Record<string, unknown>): Promise<void> {
   const notif: Record<string, boolean> = (prefs.notifications as Record<string, boolean>) ?? {};
   const notifFields = [
     { key: "enabled", label: "Notifications enabled (master toggle)", defaultVal: true },
@@ -764,15 +1107,88 @@ async function handlePrefsWizard(
   if (Object.keys(notif).length > 0) {
     prefs.notifications = notif;
   }
+}
 
-  // ─── UAT dispatch ─────────────────────────────────────────────────────
-  const currentUat = prefs.uat_dispatch;
-  const uatChoice = await ctx.ui.select(
-    `UAT dispatch mode${currentUat !== undefined ? ` (current: ${currentUat})` : " (default: false)"}:`,
+async function configureMode(ctx: ExtensionCommandContext, prefs: Record<string, unknown>): Promise<void> {
+  const currentMode = prefs.mode as string | undefined;
+  const modeChoice = await ctx.ui.select(
+    `Workflow mode${currentMode ? ` (current: ${currentMode})` : ""}:`,
+    [
+      "solo — auto-push, squash, simple IDs (personal projects)",
+      "team — unique IDs, push branches, pre-merge checks (shared repos)",
+      "(none) — configure everything manually",
+      "(keep current)",
+    ],
+  );
+  const modeStr = typeof modeChoice === "string" ? modeChoice : "";
+  if (modeStr && modeStr !== "(keep current)") {
+    if (modeStr.startsWith("solo")) {
+      prefs.mode = "solo";
+      ctx.ui.notify(
+        "Mode: solo — defaults: auto_push=true, push_branches=false, pre_merge_check=false, merge_strategy=squash, isolation=worktree, commit_docs=true, unique_milestone_ids=false",
+        "info",
+      );
+    } else if (modeStr.startsWith("team")) {
+      prefs.mode = "team";
+      ctx.ui.notify(
+        "Mode: team — defaults: auto_push=false, push_branches=true, pre_merge_check=true, merge_strategy=squash, isolation=worktree, commit_docs=true, unique_milestone_ids=true",
+        "info",
+      );
+    } else {
+      delete prefs.mode;
+    }
+  }
+}
+
+async function configureAdvanced(ctx: ExtensionCommandContext, prefs: Record<string, unknown>): Promise<void> {
+  const currentUnique = prefs.unique_milestone_ids;
+  const uniqueChoice = await ctx.ui.select(
+    `Unique milestone IDs${currentUnique !== undefined ? ` (current: ${currentUnique})` : ""}:`,
     ["true", "false", "(keep current)"],
   );
-  if (uatChoice && uatChoice !== "(keep current)") {
-    prefs.uat_dispatch = uatChoice === "true";
+  if (uniqueChoice && uniqueChoice !== "(keep current)") {
+    prefs.unique_milestone_ids = uniqueChoice === "true";
+  }
+}
+
+// ─── Main wizard with category menu ─────────────────────────────────────────
+
+async function handlePrefsWizard(
+  ctx: ExtensionCommandContext,
+  scope: "global" | "project",
+): Promise<void> {
+  const path = scope === "project" ? getProjectGSDPreferencesPath() : getGlobalGSDPreferencesPath();
+  const existing = scope === "project" ? loadProjectGSDPreferences() : loadGlobalGSDPreferences();
+  const prefs: Record<string, unknown> = existing?.preferences ? { ...existing.preferences } : {};
+
+  ctx.ui.notify(`GSD preferences (${scope}) — pick a category to configure.`, "info");
+
+  while (true) {
+    const summaries = buildCategorySummaries(prefs);
+    const options = [
+      `Workflow Mode   ${summaries.mode}`,
+      `Models          ${summaries.models}`,
+      `Timeouts        ${summaries.timeouts}`,
+      `Git             ${summaries.git}`,
+      `Skills          ${summaries.skills}`,
+      `Budget          ${summaries.budget}`,
+      `Notifications   ${summaries.notifications}`,
+      `Advanced        ${summaries.advanced}`,
+      `── Save & Exit ──`,
+    ];
+
+    const raw = await ctx.ui.select("GSD Preferences", options);
+    const choice = typeof raw === "string" ? raw : "";
+    if (!choice || choice.includes("Save & Exit")) break;
+
+    if (choice.startsWith("Workflow Mode"))      await configureMode(ctx, prefs);
+    else if (choice.startsWith("Models"))        await configureModels(ctx, prefs);
+    else if (choice.startsWith("Timeouts"))      await configureTimeouts(ctx, prefs);
+    else if (choice.startsWith("Git"))           await configureGit(ctx, prefs);
+    else if (choice.startsWith("Skills"))        await configureSkills(ctx, prefs);
+    else if (choice.startsWith("Budget"))        await configureBudget(ctx, prefs);
+    else if (choice.startsWith("Notifications")) await configureNotifications(ctx, prefs);
+    else if (choice.startsWith("Advanced"))      await configureAdvanced(ctx, prefs);
   }
 
   // ─── Serialize to frontmatter ───────────────────────────────────────────
@@ -863,7 +1279,7 @@ function serializePreferencesToFrontmatter(prefs: Record<string, unknown>): stri
 
   // Ordered keys for consistent output
   const orderedKeys = [
-    "version", "always_use_skills", "prefer_skills", "avoid_skills",
+    "version", "mode", "always_use_skills", "prefer_skills", "avoid_skills",
     "skill_rules", "custom_instructions", "models", "skill_discovery",
     "auto_supervisor", "uat_dispatch", "unique_milestone_ids",
     "budget_ceiling", "budget_enforcement", "context_pause_threshold",
@@ -1373,3 +1789,69 @@ async function handleSteer(change: string, ctx: ExtensionCommandContext, pi: Ext
     ctx.ui.notify(`Override registered: "${change}". Update plan documents to reflect this change.`, "info");
   }
 }
+
+async function handleRunHook(args: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {
+  const parts = args.trim().split(/\s+/);
+  if (parts.length < 3) {
+    ctx.ui.notify(`Usage: /gsd run-hook <hook-name> <unit-type> <unit-id>
+
+Unit types:
+  execute-task   - Task execution (unit-id: M001/S01/T01)
+  plan-slice     - Slice planning (unit-id: M001/S01)
+  research-milestone - Milestone research (unit-id: M001)
+  complete-slice - Slice completion (unit-id: M001/S01)
+  complete-milestone - Milestone completion (unit-id: M001)
+
+Examples:
+  /gsd run-hook code-review execute-task M001/S01/T01
+  /gsd run-hook lint-check plan-slice M001/S01`, "warning");
+    return;
+  }
+
+  const [hookName, unitType, unitId] = parts;
+  const basePath = projectRoot();
+
+  // Import the hook trigger function
+  const { triggerHookManually, formatHookStatus, getHookStatus } = await import("./post-unit-hooks.js");
+  const { dispatchHookUnit } = await import("./auto.js");
+  
+  // Check if the hook exists
+  const hooks = getHookStatus();
+  const hookExists = hooks.some(h => h.name === hookName);
+  if (!hookExists) {
+    ctx.ui.notify(`Hook "${hookName}" not found. Configured hooks:\n${formatHookStatus()}`, "error");
+    return;
+  }
+
+  // Validate unit ID format
+  const unitIdPattern = /^M\d{3}\/S\d{2,3}\/T\d{2,3}$/;
+  if (!unitIdPattern.test(unitId)) {
+    ctx.ui.notify(`Invalid unit ID format: "${unitId}". Expected format: M004/S04/T03`, "warning");
+    return;
+  }
+
+  // Trigger the hook manually
+  const hookUnit = triggerHookManually(hookName, unitType, unitId, basePath);
+  if (!hookUnit) {
+    ctx.ui.notify(`Failed to trigger hook "${hookName}". The hook may be disabled or not configured for unit type "${unitType}".`, "error");
+    return;
+  }
+
+  ctx.ui.notify(`Manually triggering hook: ${hookName} for ${unitType} ${unitId}`, "info");
+
+  // Dispatch the hook unit directly, bypassing normal pre-dispatch hooks
+  const success = await dispatchHookUnit(
+    ctx,
+    pi,
+    hookName,
+    unitType,
+    unitId,
+    hookUnit.prompt,
+    hookUnit.model,
+    basePath,
+  );
+
+  if (!success) {
+    ctx.ui.notify("Failed to dispatch hook. Auto-mode may have been cancelled.", "error");
+  }
+}