@tianhai/pi-workflow-kit 0.4.1 → 0.5.1

package/docs/plans/completed/2026-04-09-workflow-next-handoff-state-implementation.md

@@ -0,0 +1,253 @@
+# /workflow-next Handoff State Implementation Plan
+
+> **REQUIRED SUB-SKILL:** Use the executing-tasks skill to implement this plan task-by-task.
+
+**Goal:** Make `/workflow-next` preserve prior completed workflow history for same-feature handoffs, enforce immediate-next-only transitions, and rename the persisted local state file with legacy fallback.
+
+**Architecture:** Add a small workflow-next state helper that validates allowed handoffs and derives the workflow snapshot for the new session. Update the workflow monitor to seed the new session through `ctx.newSession({ setup })` with derived workflow state plus fresh monitor state, and add focused tests for validation, state derivation, and file migration behavior.
+
+**Tech Stack:** TypeScript, Vitest, pi extension API (`ctx.newSession({ setup })`, `SessionManager.appendCustomEntry`)
+
+---
+
+## Verification
+
+All tasks completed. Final test results:
+- `tests/extension/workflow-monitor/workflow-next-command.test.ts` — 17/17 pass
+- `tests/extension/workflow-monitor/state-persistence.test.ts` — 25/25 pass
+- `tests/extension/workflow-monitor/` (full suite) — 360/360 pass
+
+No regressions. All acceptance criteria met.
+
+
+---
+
+### Task 1: Add failing tests for workflow-next handoff validation and state seeding
+
+**Type:** code
+**TDD scenario:** Modifying tested code — run existing tests first
+
+**Files:**
+- Modify: `tests/extension/workflow-monitor/workflow-next-command.test.ts`
+- Test: `tests/extension/workflow-monitor/workflow-next-command.test.ts`
+
+**Step 1: Write the failing tests**
+
+Add tests covering:
+- allows `plan -> execute` only when `plan` is complete
+- rejects same-phase handoff
+- rejects backward handoff
+- rejects direct jump handoff
+- rejects handoff when current phase is active
+- seeds new session setup with derived workflow state preserving earlier completed phases, artifacts, and prompted flags
+- resets TDD/debug/verification state in the seeded session snapshot
+
+**Step 2: Run test to verify it fails**
+
+Run: `npx vitest run tests/extension/workflow-monitor/workflow-next-command.test.ts`
+Expected: FAIL with missing validation and missing setup-state assertions
+
+**Step 3: Write minimal implementation support in test scaffolding only if needed**
+
+If needed, extend the fake `ctx.newSession` stub in the test so it records the `setup` callback and lets the test invoke it with a fake session manager that captures appended custom entries.
+
+**Step 4: Run test to verify it still fails for the intended production behavior gap**
+
+Run: `npx vitest run tests/extension/workflow-monitor/workflow-next-command.test.ts`
+Expected: FAIL only on the new assertions tied to unimplemented production code
+
+**Step 5: Commit**
+
+```bash
+git add tests/extension/workflow-monitor/workflow-next-command.test.ts
+git commit -m "test: cover workflow-next handoff validation"
+```
+
+### Task 2: Add failing tests for state-file rename and legacy fallback
+
+**Type:** code
+**TDD scenario:** Modifying tested code — run existing tests first
+
+**Files:**
+- Modify: `tests/extension/workflow-monitor/state-persistence.test.ts`
+- Test: `tests/extension/workflow-monitor/state-persistence.test.ts`
+
+**Step 1: Write the failing tests**
+
+Add tests covering:
+- `getStateFilePath()` returns `.pi/workflow-kit-state.json`
+- `reconstructState()` prefers `.pi/workflow-kit-state.json` when present
+- `reconstructState()` falls back to `.pi/superpowers-state.json` when the new file is absent
+- extension persistence writes the new filename only
+
+**Step 2: Run test to verify it fails**
+
+Run: `npx vitest run tests/extension/workflow-monitor/state-persistence.test.ts`
+Expected: FAIL because current code still uses `.pi/superpowers-state.json`
+
+**Step 3: Keep test fixtures minimal**
+
+Reuse existing `withTempCwd()` and fake pi helpers. When testing persistence wiring, assert against files under `.pi/` in the temp directory rather than broad repo state.
+
+**Step 4: Run test to verify it still fails for the intended production behavior gap**
+
+Run: `npx vitest run tests/extension/workflow-monitor/state-persistence.test.ts`
+Expected: FAIL only on filename/migration assertions
+
+**Step 5: Commit**
+
+```bash
+git add tests/extension/workflow-monitor/state-persistence.test.ts
+git commit -m "test: cover workflow state file migration"
+```
+
+### Task 3: Implement workflow-next handoff validation and derived state helper
+
+**Type:** code
+**TDD scenario:** New feature — full TDD cycle
+
+**Files:**
+- Create: `extensions/workflow-monitor/workflow-next-state.ts`
+- Modify: `extensions/workflow-monitor.ts`
+- Test: `tests/extension/workflow-monitor/workflow-next-command.test.ts`
+
+**Step 1: Write the helper module with pure functions**
+
+Implement functions such as:
+- `getImmediateNextPhase(currentPhase)`
+- `validateWorkflowNextRequest(currentState, requestedPhase)`
+- `deriveWorkflowHandoffState(currentState, requestedPhase)`
+
+Behavior:
+- require an existing current phase
+- require current phase status to be exactly `complete`
+- allow only the immediate next phase
+- reject same/backward/direct-jump handoffs with precise messages
+- derive workflow state with earlier phases `complete`, target `active`, later `pending`
+- preserve earlier-phase artifacts and prompted flags
+
+**Step 2: Update `/workflow-next` to use the helper and seed session state**
+
+In `extensions/workflow-monitor.ts`:
+- import the helper functions
+- validate before calling `ctx.newSession(...)`
+- use `ctx.newSession({ parentSession, setup })`
+- inside `setup`, append a `superpowers_state` custom entry containing:
+  - derived `workflow`
+  - fresh `tdd` from `TDD_DEFAULTS`
+  - fresh `debug` from `DEBUG_DEFAULTS`
+  - fresh `verification` from `VERIFICATION_DEFAULTS`
+  - `savedAt: Date.now()`
+- keep the editor prefill behavior unchanged
+
+**Step 3: Run targeted tests**
+
+Run: `npx vitest run tests/extension/workflow-monitor/workflow-next-command.test.ts`
+Expected: PASS
+
+**Step 4: Review for YAGNI and edge cases**
+
+Verify:
+- helper stays pure and focused
+- no generic tracker semantics are changed outside `/workflow-next`
+- invalid requests exit before session creation
+
+**Step 5: Commit**
+
+```bash
+git add extensions/workflow-monitor/workflow-next-state.ts extensions/workflow-monitor.ts tests/extension/workflow-monitor/workflow-next-command.test.ts
+git commit -m "feat: preserve workflow state across workflow-next"
+```
+
+### Task 4: Implement state-file rename with legacy fallback
+
+**Type:** code
+**TDD scenario:** Modifying tested code — run existing tests first
+
+**Files:**
+- Modify: `extensions/workflow-monitor.ts`
+- Test: `tests/extension/workflow-monitor/state-persistence.test.ts`
+
+**Step 1: Update state file path helpers**
+
+In `extensions/workflow-monitor.ts`:
+- change `getStateFilePath()` to return `.pi/workflow-kit-state.json`
+- add a legacy-path helper for `.pi/superpowers-state.json` if needed
+- update `reconstructState()` to check new path first, then legacy path
+
+**Step 2: Keep persistence write path singular**
+
+Ensure `persistState()` writes only the new path and does not continue writing the legacy file.
+
+**Step 3: Run targeted tests**
+
+Run: `npx vitest run tests/extension/workflow-monitor/state-persistence.test.ts`
+Expected: PASS
+
+**Step 4: Verify no unintended regressions in reconstruction logic**
+
+Confirm the existing session-entry reconstruction behavior still works when no file exists.
+
+**Step 5: Commit**
+
+```bash
+git add extensions/workflow-monitor.ts tests/extension/workflow-monitor/state-persistence.test.ts
+git commit -m "refactor: rename workflow state file"
+```
+
+### Task 5: Update user-facing docs for the new workflow-next contract
+
+**Type:** non-code
+
+**Files:**
+- Modify: `README.md`
+- Modify: `docs/developer-usage-guide.md`
+- Modify: `docs/workflow-phases.md`
+
+**Acceptance criteria:**
+- Criterion 1: `/workflow-next` docs describe immediate-next-only handoff semantics.
+- Criterion 2: docs mention that the command preserves prior completed workflow history for the same feature.
+- Criterion 3: docs do not claim arbitrary phase jumps are supported.
+
+**Implementation notes:**
+- Keep examples aligned with allowed transitions only.
+- Mention the stricter behavior near existing `/workflow-next` examples rather than adding a long new section.
+- If the local state file is mentioned anywhere, rename it to `.pi/workflow-kit-state.json`.
+
+**Verification:**
+- Review each acceptance criterion one-by-one.
+- Confirm wording matches the implemented behavior and test coverage.
+
+### Task 6: Run focused verification and capture final status
+
+**Type:** code
+**TDD scenario:** Trivial change — use judgment
+
+**Files:**
+- Modify: `docs/plans/2026-04-09-workflow-next-handoff-state-implementation.md`
+- Test: `tests/extension/workflow-monitor/workflow-next-command.test.ts`
+- Test: `tests/extension/workflow-monitor/state-persistence.test.ts`
+
+**Step 1: Run focused verification**
+
+Run:
+- `npx vitest run tests/extension/workflow-monitor/workflow-next-command.test.ts`
+- `npx vitest run tests/extension/workflow-monitor/state-persistence.test.ts`
+
+Expected: PASS
+
+**Step 2: Run a broader confidence check**
+
+Run: `npx vitest run tests/extension/workflow-monitor`
+Expected: PASS
+
+**Step 3: Update the implementation plan artifact with verification notes if useful**
+
+Add a short note under the plan or in a small completion section summarizing which test commands passed.
+
+**Step 4: Commit**
+
+```bash
+git add docs/plans/2026-04-09-workflow-next-handoff-state-implementation.md
+git commit -m "test: verify workflow-next handoff changes"
+```

package/extensions/constants.ts

@@ -7,3 +7,9 @@
  * This tool id intentionally remains unchanged across the rebrand.
  */
 export const PLAN_TRACKER_TOOL_NAME = "plan_tracker";
+
+/**
+ * Custom entry type written by workflow-monitor's /workflow-reset so that
+ * plan-tracker's reconstructState picks up an empty task list.
+ */
+export const PLAN_TRACKER_CLEARED_TYPE = "plan_tracker_cleared";

package/extensions/plan-tracker.ts

@@ -10,7 +10,7 @@ import { StringEnum } from "@mariozechner/pi-ai";
 import type { ExtensionAPI, ExtensionContext, Theme } from "@mariozechner/pi-coding-agent";
 import { Text } from "@mariozechner/pi-tui";
 import { type Static, Type } from "@sinclair/typebox";
-import { PLAN_TRACKER_TOOL_NAME } from "./constants.js";
+import { PLAN_TRACKER_CLEARED_TYPE, PLAN_TRACKER_TOOL_NAME } from "./constants.js";
 
 export type TaskStatus = "pending" | "in_progress" | "complete" | "blocked";
 export type TaskPhase =
@@ -208,6 +208,12 @@ export default function (pi: ExtensionAPI) {
     const entries = ctx.sessionManager.getBranch();
     for (let i = entries.length - 1; i >= 0; i--) {
       const entry = entries[i];
+      // Check for explicit clear signal (written by /workflow-reset)
+      // biome-ignore lint/suspicious/noExplicitAny: pi SDK session entry type
+      if (entry.type === "custom" && (entry as any).customType === PLAN_TRACKER_CLEARED_TYPE) {
+        tasks = [];
+        break;
+      }
       if (entry.type !== "message") continue;
       const msg = entry.message;
       if (msg.role !== "toolResult" || msg.toolName !== PLAN_TRACKER_TOOL_NAME) continue;

package/extensions/subagent/index.ts

@@ -153,6 +153,8 @@ interface SingleResult {
   stderr: string;
   usage: UsageStats;
   model?: string;
+  modelProvider?: string;
+  modelSource?: "agent" | "parent" | "default";
   stopReason?: string;
   errorMessage?: string;
   step?: number;
@@ -165,6 +167,32 @@ interface SubagentDetails {
   results: SingleResult[];
 }
 
+interface ParentModelInfo {
+  id: string;
+  provider: string;
+}
+
+interface ResolvedModelSelection {
+  model: string;
+  provider?: string;
+  source: "agent" | "parent" | "default";
+}
+
+function resolveModelSelection(
+  agentModel: string | undefined,
+  parentModel: ParentModelInfo | undefined,
+): ResolvedModelSelection {
+  if (agentModel) {
+    return { model: agentModel, provider: undefined, source: "agent" };
+  }
+
+  if (parentModel?.id) {
+    return { model: parentModel.id, provider: parentModel.provider, source: "parent" };
+  }
+
+  return { model: DEFAULT_MODEL, provider: undefined, source: "default" };
+}
+
 function getFinalOutput(messages: Message[]): string {
   for (let i = messages.length - 1; i >= 0; i--) {
     const msg = messages[i];
@@ -177,6 +205,36 @@ function getFinalOutput(messages: Message[]): string {
   return "";
 }
 
+function buildModelArgs(selection: ResolvedModelSelection): string[] {
+  const args: string[] = [];
+  if (selection.provider) args.push("--provider", selection.provider);
+  args.push("--model", selection.model);
+  return args;
+}
+
+function formatModelSelection(
+  result: Pick<SingleResult, "model" | "modelProvider" | "modelSource">,
+): string | undefined {
+  if (!result.model) return undefined;
+  const modelLabel = result.modelProvider ? `${result.modelProvider}/${result.model}` : result.model;
+  switch (result.modelSource) {
+    case "parent":
+      return `${modelLabel} (inherited from parent session)`;
+    case "agent":
+      return `${modelLabel} (pinned by agent config)`;
+    case "default":
+      return `${modelLabel} (default fallback)`;
+    default:
+      return modelLabel;
+  }
+}
+
+function buildFailureMessage(prefix: string, result: SingleResult): string {
+  const errorMsg = result.errorMessage || result.stderr || getFinalOutput(result.messages) || "(no output)";
+  const modelSelection = formatModelSelection(result);
+  return modelSelection ? `${prefix}: ${errorMsg}\nModel: ${modelSelection}` : `${prefix}: ${errorMsg}`;
+}
+
 // biome-ignore lint/suspicious/noExplicitAny: pi SDK message content type
 type DisplayItem = { type: "text"; text: string } | { type: "toolCall"; name: string; args: Record<string, any> };
 
@@ -227,7 +285,7 @@ function collectSummary(messages: Message[]): { filesChanged: string[]; testsRan
   return { filesChanged: Array.from(files), testsRan };
 }
 
-export const __internal = { collectSummary };
+export const __internal = { collectSummary, resolveModelSelection };
 
 async function mapWithConcurrencyLimit<TIn, TOut>(
   items: TIn[],
@@ -265,6 +323,7 @@ async function runSingleAgent(
   task: string,
   cwd: string | undefined,
   step: number | undefined,
+  parentModel: ParentModelInfo | undefined,
   signal: AbortSignal | undefined,
   onUpdate: OnUpdateCallback | undefined,
   makeDetails: (results: SingleResult[]) => SubagentDetails,
@@ -288,8 +347,8 @@ async function runSingleAgent(
   }
 
   const args: string[] = ["--mode", "json", "-p", "--no-session"];
-  if (agent.model) args.push("--model", agent.model);
-  else args.push("--model", DEFAULT_MODEL);
+  const selectedModel = resolveModelSelection(agent.model, parentModel);
+  args.push(...buildModelArgs(selectedModel));
   if (agent.tools && agent.tools.length > 0) args.push("--tools", agent.tools.join(","));
   if (agent.extensions) {
     for (const ext of agent.extensions) {
@@ -307,7 +366,9 @@ async function runSingleAgent(
     messages: [],
     stderr: "",
     usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
-    model: agent.model,
+    model: selectedModel.model,
+    modelProvider: selectedModel.provider,
+    modelSource: selectedModel.source,
     step,
   };
 
@@ -596,6 +657,7 @@ export default function (pi: ExtensionAPI) {
           projectAgentsDir: discovery.projectAgentsDir,
           results,
         });
+      const parentModel = ctx.model ? { id: ctx.model.id, provider: ctx.model.provider } : undefined;
 
       if (modeCount !== 1) {
         const available = agents.map((a) => `${a.name} (${a.source})`).join(", ") || "none";
@@ -665,6 +727,7 @@ export default function (pi: ExtensionAPI) {
             taskWithContext,
             step.cwd,
             i + 1,
+            parentModel,
             signal,
             chainUpdate,
             makeDetails("chain"),
@@ -675,9 +738,10 @@ export default function (pi: ExtensionAPI) {
 
           const isError = result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
           if (isError) {
-            const errorMsg = result.errorMessage || result.stderr || getFinalOutput(result.messages) || "(no output)";
             return {
-              content: [{ type: "text", text: `Chain stopped at step ${i + 1} (${step.agent}): ${errorMsg}` }],
+              content: [
+                { type: "text", text: buildFailureMessage(`Chain stopped at step ${i + 1} (${step.agent})`, result) },
+              ],
               details: makeDetails("chain")(results),
               isError: true,
             };
@@ -737,6 +801,7 @@ export default function (pi: ExtensionAPI) {
             t.task,
             t.cwd,
             undefined,
+            parentModel,
             signal,
             // Per-task update callback
             (partial) => {
@@ -779,6 +844,7 @@ export default function (pi: ExtensionAPI) {
           params.task,
           params.cwd,
           undefined,
+          parentModel,
           signal,
           onUpdate,
           makeDetails("single"),
@@ -800,9 +866,8 @@ export default function (pi: ExtensionAPI) {
         };
         const isError = result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
         if (isError) {
-          const errorMsg = result.errorMessage || result.stderr || getFinalOutput(result.messages) || "(no output)";
           return {
-            content: [{ type: "text", text: `Agent ${result.stopReason || "failed"}: ${errorMsg}` }],
+            content: [{ type: "text", text: buildFailureMessage(`Agent ${result.stopReason || "failed"}`, result) }],
             details: stableDetails,
             isError: true,
           };

package/extensions/workflow-monitor/workflow-next-completions.ts

@@ -0,0 +1,68 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { AutocompleteItem } from "@mariozechner/pi-tui";
+
+const WORKFLOW_NEXT_PHASES = ["brainstorm", "plan", "execute", "finalize"] as const;
+const ARTIFACT_SUFFIX_BY_PHASE = {
+  brainstorm: null,
+  plan: "-design.md",
+  execute: "-implementation.md",
+  finalize: "-implementation.md",
+} as const;
+
+type WorkflowNextPhase = (typeof WORKFLOW_NEXT_PHASES)[number];
+
+function getPhaseCompletions(prefix: string): AutocompleteItem[] | null {
+  const normalized = prefix.replace(/^\s+/, "");
+  const firstToken = normalized.split(/\s+/, 1)[0] ?? "";
+  const completingFirstArg = normalized.length === 0 || !/\s/.test(normalized);
+
+  if (completingFirstArg || !WORKFLOW_NEXT_PHASES.includes(firstToken as WorkflowNextPhase)) {
+    const phasePrefix = completingFirstArg ? normalized : firstToken;
+    const items = WORKFLOW_NEXT_PHASES.filter((phase) => phase.startsWith(phasePrefix)).map((phase) => ({
+      value: phase,
+      label: phase,
+    }));
+    return items.length > 0 ? items : null;
+  }
+
+  return null;
+}
+
+function listArtifactsForPhase(phase: WorkflowNextPhase, typedPrefix: string): AutocompleteItem[] | null {
+  const suffix = ARTIFACT_SUFFIX_BY_PHASE[phase];
+  if (!suffix) return null;
+
+  const plansDir = path.join(process.cwd(), "docs", "plans");
+  if (!fs.existsSync(plansDir)) return null;
+
+  try {
+    const items = fs
+      .readdirSync(plansDir)
+      .filter((name) => name.endsWith(suffix))
+      .map((name) => path.join("docs", "plans", name))
+      .filter((relPath) => relPath.startsWith(typedPrefix))
+      .map((relPath) => ({ value: `${phase} ${relPath}`, label: relPath }));
+
+    return items.length > 0 ? items : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function getWorkflowNextCompletions(prefix: string): Promise<AutocompleteItem[] | null> {
+  const phaseCompletions = getPhaseCompletions(prefix);
+  if (phaseCompletions) return phaseCompletions;
+
+  const normalized = prefix.replace(/^\s+/, "");
+  const match = normalized.match(/^(\S+)(?:\s+(.*))?$/);
+  const phase = match?.[1] as WorkflowNextPhase | undefined;
+  const artifactPrefix = match?.[2] ?? "";
+  const startingSecondArg = /\s$/.test(prefix) || artifactPrefix.length > 0;
+
+  if (phase && WORKFLOW_NEXT_PHASES.includes(phase) && startingSecondArg) {
+    return listArtifactsForPhase(phase, artifactPrefix);
+  }
+
+  return null;
+}

package/extensions/workflow-monitor/workflow-next-state.ts

@@ -0,0 +1,112 @@
+/**
+ * Pure helper functions for /workflow-next handoff validation and derived state.
+ *
+ * These functions have no side effects and no dependencies on the extension runtime,
+ * making them straightforward to test and reason about.
+ */
+
+import { type Phase, type PhaseStatus, WORKFLOW_PHASES, type WorkflowTrackerState } from "./workflow-tracker";
+
+/** Map of each phase to its immediate next phase (null for finalize). */
+const NEXT_PHASE: Record<Phase, Phase | null> = {
+  brainstorm: "plan",
+  plan: "execute",
+  execute: "finalize",
+  finalize: null,
+};
+
+/**
+ * Validate whether a `/workflow-next` request is allowed.
+ *
+ * Rules:
+ * - A current phase must exist in the workflow state.
+ * - The current phase must have status exactly "complete".
+ * - The requested phase must be the immediate next phase.
+ *
+ * Returns `null` if the handoff is valid, or an error message string.
+ */
+export function validateNextWorkflowPhase(currentState: WorkflowTrackerState, requestedPhase: Phase): string | null {
+  const current = currentState.currentPhase;
+
+  if (!current) {
+    return "No workflow phase is active. Start a workflow first or use /workflow-reset.";
+  }
+
+  const next = NEXT_PHASE[current];
+  if (next === null) {
+    return `Cannot hand off: ${current} is the final phase. Use /workflow-reset for a new task.`;
+  }
+
+  const currentStatus = currentState.phases[current];
+
+  // Same-phase handoff
+  if (requestedPhase === current) {
+    return `Cannot hand off to ${requestedPhase} from ${current}. Use /workflow-reset for a new task or continue in this session.`;
+  }
+
+  // Backward handoff
+  const currentIdx = WORKFLOW_PHASES.indexOf(current);
+  const requestedIdx = WORKFLOW_PHASES.indexOf(requestedPhase);
+  if (requestedIdx < currentIdx) {
+    return `Cannot hand off to ${requestedPhase} from ${current}: backward transitions are not allowed.`;
+  }
+
+  // Current phase not complete
+  if (currentStatus !== "complete") {
+    return `Cannot hand off to ${requestedPhase} because ${current} is not complete (status: ${currentStatus}).`;
+  }
+
+  // Direct jump (skipping intermediate phases)
+  if (requestedPhase !== next) {
+    return `Cannot hand off to ${requestedPhase} from ${current}. /workflow-next only supports the immediate next phase: ${next}.`;
+  }
+
+  return null;
+}
+
+/**
+ * Derive the workflow state snapshot for a new session created by `/workflow-next`.
+ *
+ * Rules:
+ * - All phases before the requested phase are marked "complete".
+ * - The requested phase is marked "active".
+ * - All phases after the requested phase are marked "pending".
+ * - currentPhase is set to the requested phase.
+ * - Artifacts and prompted flags are preserved for earlier phases.
+ */
+export function deriveWorkflowHandoffState(
+  currentState: WorkflowTrackerState,
+  requestedPhase: Phase,
+): WorkflowTrackerState {
+  const requestedIdx = WORKFLOW_PHASES.indexOf(requestedPhase);
+
+  const newPhases = { ...currentState.phases };
+  const newArtifacts = { ...currentState.artifacts };
+  const newPrompted = { ...currentState.prompted };
+
+  for (let i = 0; i < WORKFLOW_PHASES.length; i++) {
+    const phase = WORKFLOW_PHASES[i]!;
+
+    if (i < requestedIdx) {
+      // Earlier phases: mark complete, preserve artifacts/prompted
+      newPhases[phase] = "complete";
+    } else if (i === requestedIdx) {
+      // Target phase: active
+      newPhases[phase] = "active";
+      newArtifacts[phase] = currentState.artifacts[phase] ?? null;
+      newPrompted[phase] = false;
+    } else {
+      // Later phases: pending, clear artifacts/prompted
+      newPhases[phase] = "pending";
+      newArtifacts[phase] = null;
+      newPrompted[phase] = false;
+    }
+  }
+
+  return {
+    phases: newPhases as Record<Phase, PhaseStatus>,
+    currentPhase: requestedPhase,
+    artifacts: newArtifacts as Record<Phase, string | null>,
+    prompted: newPrompted as Record<Phase, boolean>,
+  };
+}

package/extensions/workflow-monitor/workflow-tracker.ts

@@ -194,15 +194,37 @@ export class WorkflowTracker {
     if (!PLANS_DIR_RE.test(path)) return false;
 
     if (DESIGN_RE.test(path)) {
-      const changedArtifact = this.recordArtifact("brainstorm", path);
-      const changedPhase = this.advanceTo("brainstorm");
-      return changedArtifact || changedPhase;
+      // Only advance if we haven't already passed the brainstorm phase.
+      // Writing a design doc during plan/execute/finalize (e.g., updating
+      // the plan) must NOT reset workflow state.
+      const curIdx = this.state.currentPhase ? WORKFLOW_PHASES.indexOf(this.state.currentPhase) : -1;
+      if (curIdx > WORKFLOW_PHASES.indexOf("brainstorm")) {
+        return this.recordArtifact("brainstorm", path);
+      }
+      let changed = false;
+      changed = this.recordArtifact("brainstorm", path) || changed;
+      // Activating and immediately completing: the design doc is the
+      // deliverable that signals brainstorm is done. Do NOT mark prompted
+      // so the agent_end boundary prompt still fires to offer session handoff.
+      changed = this.advanceTo("brainstorm") || changed;
+      changed = this.completeCurrent() || changed;
+      return changed;
     }
 
     if (IMPLEMENTATION_RE.test(path)) {
-      const changedArtifact = this.recordArtifact("plan", path);
-      const changedPhase = this.advanceTo("plan");
-      return changedArtifact || changedPhase;
+      // Only advance if we haven't already passed the plan phase.
+      const curIdx = this.state.currentPhase ? WORKFLOW_PHASES.indexOf(this.state.currentPhase) : -1;
+      if (curIdx > WORKFLOW_PHASES.indexOf("plan")) {
+        return this.recordArtifact("plan", path);
+      }
+      let changed = false;
+      changed = this.recordArtifact("plan", path) || changed;
+      // Activating and immediately completing: the implementation plan
+      // is the deliverable that signals plan phase is done. Do NOT mark
+      // prompted so the agent_end boundary prompt still fires.
+      changed = this.advanceTo("plan") || changed;
+      changed = this.completeCurrent() || changed;
+      return changed;
     }
 
     return false;