gsd-pi 2.75.0-dev.063e5a3 → 2.75.0-dev.fd2382b9f

package/dist/resources/extensions/gsd/commands-debug.js

@@ -0,0 +1,388 @@
+import { assertValidDebugSessionSlug, createDebugSession, listDebugSessions, loadDebugSession, updateDebugSession, } from "./debug-session-store.js";
+import { loadPrompt } from "./prompt-loader.js";
+const SUBCOMMANDS = new Set(["list", "status", "continue", "--diagnose"]);
+function isValidSlugCandidate(input) {
+    try {
+        assertValidDebugSessionSlug(input);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function formatSessionLine(prefix, session) {
+    return `${prefix} ${session.slug} [mode=${session.mode} status=${session.status} phase=${session.phase}] — ${session.issue} (updated ${new Date(session.updatedAt).toISOString()})`;
+}
+function usageText() {
+    return [
+        "Usage: /gsd debug <issue-text>",
+        "       /gsd debug list",
+        "       /gsd debug status <slug>",
+        "       /gsd debug continue <slug>",
+        "       /gsd debug --diagnose [<slug> | <issue text>]",
+    ].join("\n");
+}
+export function parseDebugCommand(args) {
+    const raw = args.trim();
+    if (!raw)
+        return { type: "usage" };
+    const parts = raw.split(/\s+/).filter(Boolean);
+    const head = parts[0] ?? "";
+    if (head === "list") {
+        // Strict match only; otherwise treat as issue text for deterministic fallback behavior.
+        if (parts.length === 1)
+            return { type: "list" };
+        return { type: "issue-start", issue: raw };
+    }
+    if (head === "status") {
+        if (parts.length === 1)
+            return { type: "error", message: "Missing slug. Usage: /gsd debug status <slug>" };
+        if (parts.length === 2 && isValidSlugCandidate(parts[1]))
+            return { type: "status", slug: parts[1] };
+        return { type: "issue-start", issue: raw };
+    }
+    if (head === "continue") {
+        if (parts.length === 1)
+            return { type: "error", message: "Missing slug. Usage: /gsd debug continue <slug>" };
+        if (parts.length === 2 && isValidSlugCandidate(parts[1]))
+            return { type: "continue", slug: parts[1] };
+        return { type: "issue-start", issue: raw };
+    }
+    if (head === "--diagnose") {
+        if (parts.length === 1)
+            return { type: "diagnose" };
+        if (parts.length === 2 && isValidSlugCandidate(parts[1]))
+            return { type: "diagnose", slug: parts[1] };
+        if (parts.length >= 3)
+            return { type: "diagnose-issue", issue: parts.slice(1).join(" ") };
+        return { type: "error", message: "Invalid diagnose target. Usage: /gsd debug --diagnose [<slug> | <issue text>]" };
+    }
+    if (head.startsWith("-") && !SUBCOMMANDS.has(head)) {
+        return { type: "error", message: `Unknown debug flag: ${head}.\n${usageText()}` };
+    }
+    return { type: "issue-start", issue: raw };
+}
+export async function handleDebug(args, ctx, pi) {
+    const parsed = parseDebugCommand(args);
+    const basePath = process.cwd();
+    if (parsed.type === "usage") {
+        ctx.ui.notify(usageText(), "info");
+        return;
+    }
+    if (parsed.type === "error") {
+        ctx.ui.notify(parsed.message, "warning");
+        return;
+    }
+    if (parsed.type === "issue-start") {
+        const issue = parsed.issue.trim();
+        if (!issue) {
+            ctx.ui.notify(`Issue text is required.\n${usageText()}`, "warning");
+            return;
+        }
+        try {
+            const created = createDebugSession(basePath, { issue });
+            const s = created.session;
+            ctx.ui.notify([
+                `Debug session started: ${s.slug}`,
+                formatSessionLine("Session:", s),
+                `Artifact: ${created.artifactPath}`,
+                `Log: ${s.logPath}`,
+                `Next: /gsd debug status ${s.slug} or /gsd debug continue ${s.slug}`,
+            ].join("\n"), "info");
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            ctx.ui.notify(`Unable to create debug session: ${message}\nTry /gsd debug --diagnose for artifact health details.`, "error");
+        }
+        return;
+    }
+    if (parsed.type === "list") {
+        try {
+            const listed = listDebugSessions(basePath);
+            if (listed.sessions.length === 0 && listed.malformed.length === 0) {
+                ctx.ui.notify("No debug sessions found. Start one with: /gsd debug <issue-text>", "info");
+                return;
+            }
+            const lines = [];
+            if (listed.sessions.length > 0) {
+                lines.push("Debug sessions:");
+                for (const record of listed.sessions) {
+                    lines.push(formatSessionLine("  -", record.session));
+                }
+            }
+            if (listed.malformed.length > 0) {
+                lines.push("");
+                lines.push(`Malformed artifacts: ${listed.malformed.length}`);
+                for (const bad of listed.malformed.slice(0, 5)) {
+                    lines.push(`  - ${bad.artifactPath} :: ${bad.message}`);
+                }
+                if (listed.malformed.length > 5) {
+                    lines.push(`  ... and ${listed.malformed.length - 5} more`);
+                }
+                lines.push("Run /gsd debug --diagnose for remediation guidance.");
+            }
+            ctx.ui.notify(lines.join("\n"), "info");
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            ctx.ui.notify(`Unable to list debug sessions: ${message}\nRun /gsd debug --diagnose for details.`, "warning");
+        }
+        return;
+    }
+    if (parsed.type === "status") {
+        try {
+            const loaded = loadDebugSession(basePath, parsed.slug);
+            if (!loaded) {
+                ctx.ui.notify(`Unknown debug session slug '${parsed.slug}'. Run /gsd debug list to see available sessions.`, "warning");
+                return;
+            }
+            const s = loaded.session;
+            ctx.ui.notify([
+                `Debug session status: ${s.slug}`,
+                `mode=${s.mode}`,
+                `status=${s.status}`,
+                `phase=${s.phase}`,
+                `issue=${s.issue}`,
+                `artifact=${loaded.artifactPath}`,
+                `log=${s.logPath}`,
+                `updated=${new Date(s.updatedAt).toISOString()}`,
+                `lastError=${s.lastError ?? "none"}`,
+            ].join("\n"), "info");
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            ctx.ui.notify(`Unable to load debug session '${parsed.slug}': ${message}\nTry /gsd debug --diagnose ${parsed.slug}`, "warning");
+        }
+        return;
+    }
+    if (parsed.type === "continue") {
+        try {
+            const loaded = loadDebugSession(basePath, parsed.slug);
+            if (!loaded) {
+                ctx.ui.notify(`Unknown debug session slug '${parsed.slug}'. Run /gsd debug list to see available sessions.`, "warning");
+                return;
+            }
+            if (loaded.session.status === "resolved") {
+                ctx.ui.notify(`Session '${parsed.slug}' is resolved. Open a new session with /gsd debug <issue-text> for follow-up work.`, "warning");
+                return;
+            }
+            // Determine checkpoint/TDD/specialist dispatch context before updating session state.
+            const checkpoint = loaded.session.checkpoint;
+            const tddGate = loaded.session.tddGate;
+            const specialistReview = loaded.session.specialistReview;
+            const hasCheckpoint = checkpoint != null && checkpoint.awaitingResponse;
+            const hasTddGate = tddGate != null && tddGate.enabled;
+            let dispatchTemplate = "debug-diagnose";
+            let goal = "find_and_fix";
+            let dispatchModeLabel = "find_and_fix";
+            let checkpointContext = "";
+            let tddContext = "";
+            let specialistContext = "";
+            let tddGateUpdate;
+            if (hasCheckpoint || hasTddGate) {
+                dispatchTemplate = "debug-session-manager";
+                if (hasCheckpoint) {
+                    const cpLines = [
+                        `## Active Checkpoint`,
+                        `- type: ${checkpoint.type}`,
+                        `- summary: ${checkpoint.summary}`,
+                    ];
+                    if (checkpoint.userResponse) {
+                        cpLines.push(`- userResponse:\n\nDATA_START\n${checkpoint.userResponse}\nDATA_END`);
+                    }
+                    else {
+                        cpLines.push(`- awaitingResponse: true`);
+                    }
+                    checkpointContext = cpLines.join("\n");
+                    dispatchModeLabel = `checkpointType=${checkpoint.type}`;
+                }
+                if (hasTddGate) {
+                    if (tddGate.phase === "red") {
+                        goal = "find_and_fix";
+                        const tddLines = [
+                            `## TDD Gate`,
+                            `- phase: red → green`,
+                        ];
+                        if (tddGate.testFile)
+                            tddLines.push(`- testFile: ${tddGate.testFile}`);
+                        if (tddGate.testName)
+                            tddLines.push(`- testName: ${tddGate.testName}`);
+                        if (tddGate.failureOutput)
+                            tddLines.push(`- failureOutput:\n${tddGate.failureOutput}`);
+                        tddLines.push(`The failing test has been confirmed. Proceed to implement the fix that makes this test pass.`);
+                        tddContext = tddLines.join("\n");
+                        tddGateUpdate = { ...tddGate, phase: "green" };
+                        dispatchModeLabel = "tddPhase=red→green";
+                    }
+                    else if (tddGate.phase === "green") {
+                        goal = "find_and_fix";
+                        const tddLines = [
+                            `## TDD Gate`,
+                            `- phase: green`,
+                        ];
+                        if (tddGate.testFile)
+                            tddLines.push(`- testFile: ${tddGate.testFile}`);
+                        if (tddGate.testName)
+                            tddLines.push(`- testName: ${tddGate.testName}`);
+                        tddLines.push(`The test is now passing. Continue verifying the fix.`);
+                        tddContext = tddLines.join("\n");
+                        dispatchModeLabel = "tddPhase=green";
+                    }
+                    else {
+                        // phase === "pending": investigate only, do not fix yet
+                        goal = "find_root_cause_only";
+                        const tddLines = [
+                            `## TDD Gate`,
+                            `- phase: pending`,
+                            `TDD mode is active. Write a failing test that captures this bug first. Do NOT fix the issue yet.`,
+                        ];
+                        if (tddGate.testFile)
+                            tddLines.push(`- testFile: ${tddGate.testFile}`);
+                        tddContext = tddLines.join("\n");
+                        dispatchModeLabel = "tddPhase=pending";
+                    }
+                }
+                else {
+                    // Checkpoint only, no TDD gate — apply fix after human response
+                    goal = "find_and_fix";
+                }
+            }
+            // Build specialistContext from session's specialistReview field (null/undefined → empty string).
+            if (specialistReview != null) {
+                specialistContext = [
+                    `## Prior Specialist Review`,
+                    `- hint: ${specialistReview.hint}`,
+                    `- skill: ${specialistReview.skill ?? ""}`,
+                    `- verdict: ${specialistReview.verdict}`,
+                    `- detail: ${specialistReview.detail}`,
+                ].join("\n");
+                dispatchModeLabel += ` specialistHint=${specialistReview.hint}`;
+            }
+            // Update session state BEFORE dispatch — handler returns after sendMessage.
+            const resumed = updateDebugSession(basePath, parsed.slug, {
+                status: "active",
+                phase: "continued",
+                lastError: null,
+                ...(tddGateUpdate !== undefined ? { tddGate: tddGateUpdate } : {}),
+            });
+            const canDispatch = pi != null && typeof pi.sendMessage === "function";
+            const dispatchNote = canDispatch ? `\ndispatchMode=${dispatchModeLabel}` : "";
+            ctx.ui.notify([
+                `Resumed debug session: ${resumed.session.slug}`,
+                formatSessionLine("Session:", resumed.session),
+                `Log: ${resumed.session.logPath}`,
+                `Next: /gsd debug status ${resumed.session.slug}`,
+            ].join("\n") + dispatchNote, "info");
+            if (canDispatch) {
+                try {
+                    const promptVars = {
+                        goal,
+                        issue: resumed.session.issue,
+                        slug: resumed.session.slug,
+                        mode: resumed.session.mode,
+                        workingDirectory: basePath,
+                    };
+                    if (dispatchTemplate === "debug-session-manager") {
+                        promptVars.checkpointContext = checkpointContext;
+                        promptVars.tddContext = tddContext;
+                        promptVars.specialistContext = specialistContext;
+                    }
+                    const prompt = loadPrompt(dispatchTemplate, promptVars);
+                    pi.sendMessage({ customType: "gsd-debug-continue", content: prompt, display: false }, { triggerTurn: true });
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    ctx.ui.notify(`Continue dispatch failed: ${msg}\nSession '${resumed.session.slug}' is persisted; retry with /gsd debug continue ${resumed.session.slug}`, "warning");
+                }
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            ctx.ui.notify(`Unable to continue debug session '${parsed.slug}': ${message}\nTry /gsd debug --diagnose ${parsed.slug}`, "warning");
+        }
+        return;
+    }
+    if (parsed.type === "diagnose-issue") {
+        const issue = parsed.issue.trim();
+        if (!issue) {
+            ctx.ui.notify(`Issue text is required.\n${usageText()}`, "warning");
+            return;
+        }
+        try {
+            const created = createDebugSession(basePath, { issue, mode: "diagnose" });
+            const s = created.session;
+            ctx.ui.notify([
+                `Diagnose session started: ${s.slug}`,
+                formatSessionLine("Session:", s),
+                `Artifact: ${created.artifactPath}`,
+                `Log: ${s.logPath}`,
+                `dispatchMode=find_root_cause_only`,
+                `Next: /gsd debug status ${s.slug} or /gsd debug --diagnose ${s.slug}`,
+            ].join("\n"), "info");
+            if (pi && typeof pi.sendMessage === "function") {
+                try {
+                    const prompt = loadPrompt("debug-diagnose", {
+                        goal: "find_root_cause_only",
+                        issue: s.issue,
+                        slug: s.slug,
+                        mode: s.mode,
+                        workingDirectory: basePath,
+                    });
+                    pi.sendMessage({ customType: "gsd-debug-diagnose", content: prompt, display: false }, { triggerTurn: true });
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    ctx.ui.notify(`Diagnose dispatch failed: ${msg}\nSession '${s.slug}' is persisted; continue manually with /gsd debug continue ${s.slug}`, "warning");
+                }
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            ctx.ui.notify(`Unable to create diagnose session: ${message}\nTry /gsd debug --diagnose for artifact health details.`, "error");
+        }
+        return;
+    }
+    if (parsed.type === "diagnose") {
+        try {
+            const listed = listDebugSessions(basePath);
+            if (parsed.slug) {
+                const loaded = loadDebugSession(basePath, parsed.slug);
+                if (!loaded) {
+                    ctx.ui.notify(`Diagnose: session '${parsed.slug}' not found.\nRun /gsd debug list to discover valid slugs.`, "warning");
+                    return;
+                }
+                const s = loaded.session;
+                ctx.ui.notify([
+                    `Diagnose session: ${s.slug}`,
+                    `mode=${s.mode}`,
+                    `status=${s.status}`,
+                    `phase=${s.phase}`,
+                    `artifact=${loaded.artifactPath}`,
+                    `log=${s.logPath}`,
+                    `lastError=${s.lastError ?? "none"}`,
+                    `malformedArtifactsInStore=${listed.malformed.length}`,
+                ].join("\n"), "info");
+                return;
+            }
+            const lines = [
+                "Debug session diagnostics:",
+                `healthySessions=${listed.sessions.length}`,
+                `malformedArtifacts=${listed.malformed.length}`,
+            ];
+            if (listed.malformed.length > 0) {
+                lines.push("");
+                lines.push("Malformed artifacts (first 10):");
+                for (const malformed of listed.malformed.slice(0, 10)) {
+                    lines.push(`  - ${malformed.artifactPath}`);
+                    lines.push(`    ${malformed.message}`);
+                }
+                lines.push("Remediation: repair/remove malformed JSON artifacts under .gsd/debug/sessions/.");
+            }
+            ctx.ui.notify(lines.join("\n"), listed.malformed.length > 0 ? "warning" : "info");
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            ctx.ui.notify(`Diagnose failed: ${message}`, "error");
+        }
+    }
+}

package/dist/resources/extensions/gsd/commands-do.js

@@ -32,6 +32,7 @@ const ROUTES = [
     { keywords: ["park", "shelve", "set aside"], command: "park" },
     { keywords: ["widget", "toggle widget"], command: "widget" },
     { keywords: ["logs", "debug logs", "log files"], command: "logs" },
+    { keywords: ["debug", "debug session", "investigate", "troubleshoot", "diagnose issue"], command: "debug" },
 ];
 function matchRoute(input) {
     const lower = input.toLowerCase();

package/dist/resources/extensions/gsd/commands-handlers.js

@@ -5,7 +5,8 @@
  * handleRunHook, handleUpdate, handleSkillHealth
  */
 import { existsSync, readFileSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve as resolvePath, sep } from "node:path";
+import { homedir } from "node:os";
 import { deriveState } from "./state.js";
 import { gsdRoot } from "./paths.js";
 import { appendCapture, hasPendingCaptures, loadPendingCaptures } from "./captures.js";
@@ -17,8 +18,26 @@ import { projectRoot } from "./commands/context.js";
 import { loadPrompt } from "./prompt-loader.js";
 const UPDATE_REGISTRY_URL = "https://registry.npmjs.org/gsd-pi/latest";
 const UPDATE_FETCH_TIMEOUT_MS = 5000;
-function resolveInstallCommand(pkg) {
+// Detects a bun-installed gsd via `process.argv[1]`. Mirrors isBunInstall in
+// src/update-check.ts — duplicated because tsconfig.resources.json rootDir
+// prevents importing from src/. See #4145 for why the runtime-only check
+// (process.versions.bun) is insufficient: bun's global bin shims are plain
+// symlinks, so the target's #!/usr/bin/env node shebang runs the script under
+// Node even when it was installed by bun.
+function isBunInstall(argv1 = process.argv[1]) {
     if ('bun' in process.versions)
+        return true;
+    if (!argv1)
+        return false;
+    const bunBinDirs = [];
+    if (process.env.BUN_INSTALL)
+        bunBinDirs.push(join(process.env.BUN_INSTALL, "bin"));
+    bunBinDirs.push(join(homedir(), ".bun", "bin"));
+    const resolved = resolvePath(argv1);
+    return bunBinDirs.some((dir) => resolved.startsWith(resolvePath(dir) + sep));
+}
+function resolveInstallCommand(pkg) {
+    if (isBunInstall())
         return `bun add -g ${pkg}`;
     return `npm install -g ${pkg}`;
 }

package/dist/resources/extensions/gsd/commands-prefs-wizard.js

@@ -742,7 +742,7 @@ export async function ensurePreferencesFile(path, ctx, scope) {
 /**
  * Handle `/gsd language [code]` — set or clear the global language preference.
  * Without an argument, shows the current setting.
- * Project-level override can be set by editing `.gsd/preferences.md` directly
+ * Project-level override can be set by editing `.gsd/PREFERENCES.md` directly
  * (project language overrides global when both are set).
  */
 export async function handleLanguage(args, ctx) {

package/dist/resources/extensions/gsd/commands-scan.js

@@ -0,0 +1,94 @@
+/**
+ * GSD Command — /gsd scan
+ *
+ * Rapid codebase assessment — lightweight alternative to /gsd map-codebase.
+ * Spawns one focused AI analysis pass and writes structured documents to
+ * .gsd/codebase/ for use by planning and execution phases.
+ *
+ * Usage:
+ *   /gsd scan                   — tech+arch focus (default)
+ *   /gsd scan --focus tech      — technology stack + integrations only
+ *   /gsd scan --focus arch      — architecture + structure only
+ *   /gsd scan --focus quality   — conventions + testing patterns only
+ *   /gsd scan --focus concerns  — technical debt + concerns only
+ *   /gsd scan --focus tech+arch — explicit default (same as no flag)
+ */
+import { existsSync, mkdirSync } from "node:fs";
+import { join, relative } from "node:path";
+import { loadPrompt } from "./prompt-loader.js";
+// ─── Constants ────────────────────────────────────────────────────────────────
+export const DEFAULT_FOCUS = "tech+arch";
+export const VALID_FOCUS_AREAS = ["tech", "arch", "quality", "concerns", "tech+arch"];
+const FOCUS_DOCUMENTS = {
+    tech: ["STACK", "INTEGRATIONS"],
+    arch: ["ARCHITECTURE", "STRUCTURE"],
+    quality: ["CONVENTIONS", "TESTING"],
+    concerns: ["CONCERNS"],
+    "tech+arch": ["STACK", "INTEGRATIONS", "ARCHITECTURE", "STRUCTURE"],
+};
+// ─── Exported functions (exported for testing) ───────────────────────────────
+// Note: checkExistingDocuments reads the filesystem and is not purely functional.
+/**
+ * Parse --focus flag from raw args string.
+ * Returns default focus when flag is missing or the value is invalid.
+ * Shell-injection safe: only well-known values are accepted.
+ */
+export function parseScanArgs(args) {
+    const match = args.match(/--focus\s+([^\s]+)/i);
+    if (!match)
+        return { focus: DEFAULT_FOCUS };
+    const raw = match[1].toLowerCase();
+    if (VALID_FOCUS_AREAS.includes(raw)) {
+        return { focus: raw };
+    }
+    return { focus: DEFAULT_FOCUS };
+}
+/**
+ * Return the list of document names (without extension) to generate for a focus.
+ * Falls back to the default focus documents for unknown values.
+ */
+export function resolveScanDocuments(focus) {
+    return FOCUS_DOCUMENTS[focus] ?? FOCUS_DOCUMENTS[DEFAULT_FOCUS];
+}
+/**
+ * Build absolute output paths for the documents produced by a scan focus.
+ * All documents live under <basePath>/.gsd/codebase/
+ */
+export function buildScanOutputPaths(focus, basePath) {
+    const docs = resolveScanDocuments(focus);
+    return docs.map((doc) => join(basePath, ".gsd", "codebase", `${doc}.md`));
+}
+/**
+ * Return the subset of paths that already exist on disk.
+ */
+export function checkExistingDocuments(paths) {
+    return paths.filter((p) => existsSync(p));
+}
+// ─── Command handler ──────────────────────────────────────────────────────────
+export async function handleScan(args, ctx, pi) {
+    const basePath = process.cwd();
+    const { focus } = parseScanArgs(args);
+    const outputDir = join(basePath, ".gsd", "codebase");
+    const outputPaths = buildScanOutputPaths(focus, basePath);
+    const existing = checkExistingDocuments(outputPaths);
+    if (existing.length > 0) {
+        const names = existing.map((p) => relative(outputDir, p)).join(", ");
+        ctx.ui.notify(`Existing documents will be overwritten: ${names}\nContinuing scan with focus: ${focus}`, "warning");
+    }
+    mkdirSync(outputDir, { recursive: true });
+    const documents = resolveScanDocuments(focus);
+    ctx.ui.notify(`Running codebase scan (focus: ${focus})…`, "info");
+    try {
+        const prompt = loadPrompt("scan", {
+            focus,
+            documents: documents.join(", "),
+            outputDir: outputDir.replaceAll("\\", "/"),
+            workingDirectory: basePath,
+        });
+        pi.sendMessage({ customType: "gsd-scan", content: prompt, display: false }, { triggerTurn: true });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        ctx.ui.notify(`Failed to dispatch scan: ${msg}`, "error");
+    }
+}

package/dist/resources/extensions/gsd/commands-workflow-templates.js

@@ -12,6 +12,7 @@ import { gsdRoot } from "./paths.js";
 import { createGitService, runGit } from "./git-service.js";
 import { isAutoActive, isAutoPaused } from "./auto.js";
 import { getErrorMessage } from "./error-utils.js";
+import { resolvePlugin } from "./workflow-plugins.js";
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 /**
  * Generate a URL-friendly slug from text.
@@ -257,8 +258,19 @@ export async function handleStart(args, ctx, pi) {
     const template = match.template;
     const basePath = process.cwd();
     const date = new Date().toISOString().split("T")[0];
-    // Load the workflow template content
-    const workflowContent = loadWorkflowTemplate(templateId);
+    // Load the workflow template content — prefer a project/global plugin
+    // override if one exists (same name, .md format).
+    let workflowContent = null;
+    const pluginOverride = resolvePlugin(basePath, templateId);
+    if (pluginOverride && pluginOverride.source !== "bundled" && pluginOverride.format === "md") {
+        try {
+            workflowContent = readFileSync(pluginOverride.path, "utf-8");
+        }
+        catch { /* fall through to bundled */ }
+    }
+    if (workflowContent == null) {
+        workflowContent = loadWorkflowTemplate(templateId);
+    }
     if (!workflowContent) {
         ctx.ui.notify(`Template "${templateId}" is registered but its workflow file (${template.file}) hasn't been created yet.`, "warning");
         return;
@@ -406,3 +418,90 @@ export function getTemplateCompletions(prefix) {
         return [];
     }
 }
+// ─── Shared markdown-phase dispatcher (used by /gsd workflow <name>) ────────
+/**
+ * Dispatch a markdown-phase workflow plugin. Mirrors `handleStart`'s execution
+ * branch for resolved templates, but accepts a pre-resolved plugin (from the
+ * unified plugin resolver).
+ *
+ * Writes STATE.json into an artifact dir, creates a git branch, and dispatches
+ * the `workflow-start` prompt.
+ */
+export function dispatchMarkdownPhasePlugin(plugin, description, ctx, pi) {
+    if (plugin.meta.mode !== "markdown-phase")
+        return;
+    if (isAutoActive()) {
+        ctx.ui.notify("Cannot start a markdown-phase workflow while auto-mode is running.\n" +
+            "Run /gsd pause first.", "warning");
+        return;
+    }
+    const templateId = plugin.name;
+    const basePath = process.cwd();
+    const date = new Date().toISOString().split("T")[0];
+    let workflowContent;
+    try {
+        workflowContent = readFileSync(plugin.path, "utf-8");
+    }
+    catch (err) {
+        ctx.ui.notify(`Failed to read template: ${err instanceof Error ? err.message : String(err)}`, "error");
+        return;
+    }
+    // Create artifact directory.
+    let artifactDir = "";
+    if (plugin.meta.artifactDir) {
+        const slug = slugify(description || templateId);
+        const prefix = datePrefix();
+        const num = getNextWorkflowNum(join(basePath, plugin.meta.artifactDir));
+        artifactDir = `${plugin.meta.artifactDir}${prefix}-${num}-${slug}`;
+        mkdirSync(join(basePath, artifactDir), { recursive: true });
+    }
+    // Create git branch unless isolation: none.
+    const git = createGitService(basePath);
+    const skipBranch = git.prefs.isolation === "none";
+    const slug = slugify(description || templateId);
+    const branchName = `gsd/${templateId}/${slug}`;
+    let branchCreated = false;
+    if (!skipBranch) {
+        try {
+            const current = git.getCurrentBranch();
+            if (current !== branchName) {
+                try {
+                    git.autoCommit("workflow-template", templateId, []);
+                }
+                catch { /* nothing to commit */ }
+                runGit(basePath, ["checkout", "-b", branchName]);
+                branchCreated = true;
+            }
+        }
+        catch (err) {
+            ctx.ui.notify(`Could not create branch ${branchName}: ${getErrorMessage(err)}. Working on current branch.`, "warning");
+        }
+    }
+    const actualBranch = branchCreated ? branchName : git.getCurrentBranch();
+    // Write STATE.json.
+    if (artifactDir && plugin.meta.phases && plugin.meta.phases.length > 0) {
+        writeWorkflowState(join(basePath, artifactDir), templateId, plugin.meta.displayName, plugin.meta.phases, description, actualBranch);
+    }
+    const infoLines = [
+        `Starting workflow: ${plugin.meta.displayName}`,
+        `Phases: ${(plugin.meta.phases ?? []).join(" → ")}`,
+    ];
+    if (artifactDir)
+        infoLines.push(`Artifacts: ${artifactDir}`);
+    infoLines.push(`Branch: ${actualBranch}`);
+    ctx.ui.notify(infoLines.join("\n"), "info");
+    const prompt = loadPrompt("workflow-start", {
+        templateId,
+        templateName: plugin.meta.displayName,
+        templateDescription: plugin.meta.description ?? "",
+        phases: (plugin.meta.phases ?? []).join(" → "),
+        complexity: plugin.meta.complexity ?? "medium",
+        artifactDir: artifactDir || "(none)",
+        branch: actualBranch,
+        description: description || "(none provided)",
+        issueRef: "(none)",
+        date,
+        workflowContent,
+    });
+    pi.sendMessage({ customType: "gsd-workflow-template", content: prompt, display: false }, { triggerTurn: true });
+}