@tianhai/pi-workflow-kit 0.5.0 → 0.5.3

package/docs/plans/2026-04-10-brainstorming-boundary-enforcement-design.md

@@ -0,0 +1,60 @@
+# Brainstorming Skill Boundary Enforcement
+
+**Date:** 2026-04-10
+**Status:** approved
+
+## Problem
+
+The brainstorming skill's boundaries are advisory only — a quiet `## Boundaries` bullet list mid-file that the model reads then ignores once a task "feels" straightforward. There is no structural enforcement (pi doesn't implement `allowed-tools`, no tool-blocking extension API).
+
+In practice, `/skill:brainstorming` was invoked, the skill was loaded, and the agent immediately jumped to reading code, diagnosing the bug, and editing source files — violating every boundary.
+
+## Design
+
+Two changes to `skills/brainstorming/SKILL.md`:
+
+### 1. Add `allowed-tools` frontmatter
+
+```yaml
+allowed-tools: read bash
+```
+
+Pi doesn't parse this field yet, but:
+- It's part of the Agent Skills spec (experimental)
+- Future pi versions may inject it into the system prompt
+- Serves as machine-readable declaration of intent
+- Zero cost today
+
+### 2. Replace quiet Boundaries section with prominent top-of-file block
+
+Move from a mid-file `## Boundaries` section to a visually distinct blockquote immediately after the `# Heading`, before the Overview:
+
+```markdown
+> ⚠️ **BOUNDARY — DO NOT VIOLATE**
+>
+> This skill is **read-only exploration**. You MUST NOT use `edit` or `write` tools.
+> The only tools allowed are `read` and `bash` (for investigation only).
+>
+> - ✅ Read code and docs: yes
+> - ✅ Write to `docs/plans/`: yes (design documents only)
+> - ❌ Edit or create any other files: **absolutely no**
+>
+> If you find yourself reaching for `edit` or `write`, **stop**. Present what
+> you found as a design section and ask the user to approve it first.
+```
+
+Key improvements over current form:
+- **Blockquote + warning emoji** — visually distinct from normal content
+- **"DO NOT VIOLATE"** — strong language models respond to
+- **Names forbidden tools explicitly** (`edit`, `write`) — no ambiguity
+- **Recovery instruction** — "stop, present what you found" — constructive next step
+- **Positioned at the top** — seen before the Overview, not buried mid-file
+
+## Out of scope
+
+- Extension-level enforcement (requires pi core changes to support tool call interception)
+- Changing other skills' boundaries (this is a pattern, but brainstorming is the most frequently violated)
+
+## Testing
+
+Manual verification: invoke `/skill:brainstorming`, confirm the model does not reach for `edit`/`write` during exploration.

package/docs/plans/completed/2026-04-09-cleanup-legacy-state-and-enforce-think-phases-design.md

@@ -0,0 +1,56 @@
+# Cleanup legacy state file and enforce thinking-phase boundaries
+
+Date: 2026-04-09
+
+## Problem
+
+1. **Legacy state file still read:** `workflow-monitor.ts` still has `getLegacyStateFilePath()` and a fallback read path for `.pi/superpowers-state.json`. The new filename (`workflow-kit-state.json`) is correct for writes, but the old one is still checked on read.
+
+2. **Brainstorm/plan phases not enforced:** When the agent writes code during brainstorm or plan phase, the extension only warns (strike-based escalation allows first offense). The agent can ignore the warning and proceed with implementation work.
+
+3. **`/workflow-next` tab completions lose the phase word:** When selecting a file artifact completion (e.g. `docs/plans/2026-04-09-foo-design.md`), pi replaces the entire argument prefix including the phase word. `/workflow-next plan des` → select file → `/workflow-next docs/plans/...` ("plan" gone).
+
+Note: Tab key does not trigger slash command argument completions at all (pi-side behavior — falls through to file path completion when `force=true`). Argument suggestions only appear on typing. This cannot be fixed on our side.
+
+## Scope
+
+Three changes:
+
+### 1. Remove `superpowers-state.json` legacy fallback
+
+**`extensions/workflow-monitor.ts`:**
+- Remove `getLegacyStateFilePath()` function
+- In `reconstructState()`, remove the `else if (stateFilePath === undefined)` branch that reads the legacy filename
+
+**`tests/extension/workflow-monitor/state-persistence.test.ts`:**
+- Update two tests in `"file-based state persistence"` describe that write/read `superpowers-state.json` to use `workflow-kit-state.json`
+- Fix test name `"getStateFilePath returns .pi/superpowers-state.json in cwd"`
+- Remove the `"state file rename to .pi/workflow-kit-state.json with legacy fallback"` describe block (4 tests) — this migration behavior no longer exists
+
+### 2. Enforce brainstorm/plan phase boundaries
+
+**`extensions/workflow-monitor.ts`:**
+- Replace the `maybeEscalate("process", ctx)` call + `pendingProcessWarnings.set(...)` with an immediate `{ blocked: true, reason: ... }` return that includes a reminder about what the agent should be doing instead
+- Remove `"process"` from `ViolationBucket` type and `strikes` record (only `"practice"` remains, still used by TDD)
+- Remove `pendingProcessWarnings` map (no longer needed)
+
+### 3. Fix phase word lost on artifact completion selection
+
+**`extensions/workflow-monitor/workflow-next-completions.ts`:**
+- In `listArtifactsForPhase`, prepend the phase to `item.value` so pi's prefix replacement preserves it:
+  - `value: "plan docs/plans/2026-04-09-foo-design.md"` (replaces "plan des" → keeps "plan")
+  - `label: "docs/plans/2026-04-09-foo-design.md"` (display stays clean)
+- Applies to all phases with artifacts: plan, execute, finalize
+
+### Tests
+
+**`tests/extension/workflow-monitor/workflow-next-completions.test.ts`:**
+- Update artifact completion tests to expect `value` with phase prefix (e.g. `"plan docs/plans/..."`)
+
+## What stays the same
+
+- `persistState()` already writes only to `.pi/workflow-kit-state.json` — no changes
+- `maybeEscalate()` stays (still used for `"practice"` / TDD violations)
+- The `isThinkingPhase` check (`phase === "brainstorm" || phase === "plan"`) already covers both phases — same treatment
+- `docs/plans/` writes remain allowed during brainstorm/plan phases
+- Tab not triggering argument completions is a pi-side issue — not in scope

package/docs/plans/completed/2026-04-09-cleanup-legacy-state-and-enforce-think-phases-implementation.md

@@ -0,0 +1,196 @@
+# Cleanup legacy state, enforce thinking phases, fix autocomplete
+
+> **REQUIRED SUB-SKILL:** Use the executing-tasks skill to implement this plan task-by-task.
+
+**Goal:** Remove legacy `superpowers-state.json` fallback, block non-plans writes during brainstorm/plan phases, and fix artifact completions losing the phase word.
+
+**Architecture:** Three independent changes in `workflow-monitor.ts` and `workflow-next-completions.ts` with corresponding test updates. Each change is self-contained.
+
+**Tech Stack:** TypeScript, Node.js, vitest, pi extension API
+
+---
+
+### Task 1: Remove `superpowers-state.json` legacy fallback
+
+**Type:** code
+**TDD scenario:** Modifying tested code — run existing tests first
+
+**Files:**
+- Modify: `extensions/workflow-monitor.ts:67-100`
+- Modify: `tests/extension/workflow-monitor/state-persistence.test.ts:274-500`
+
+**Step 1: Run existing state persistence tests**
+
+Run: `npx vitest run tests/extension/workflow-monitor/state-persistence.test.ts`
+Expected: All tests pass
+
+**Step 2: Remove `getLegacyStateFilePath` and legacy fallback in source**
+
+In `extensions/workflow-monitor.ts`:
+
+1. Delete the `getLegacyStateFilePath` function (3 lines).
+2. In `reconstructState`, simplify the file-read block — remove the `else if (stateFilePath === undefined)` branch that tries the legacy filename. The remaining code becomes:
+
+```typescript
+if (stateFilePath !== false) {
+  try {
+    const statePath = stateFilePath ?? getStateFilePath();
+    if (fs.existsSync(statePath)) {
+      const raw = fs.readFileSync(statePath, "utf-8");
+      fileData = JSON.parse(raw);
+    }
+  } catch (err) {
+    log.warn(
+      `Failed to read state file, falling back to session entries: ${err instanceof Error ? err.message : err}`,
+    );
+  }
+}
+```
+
+**Step 3: Update tests**
+
+In `tests/extension/workflow-monitor/state-persistence.test.ts`:
+
+1. Fix test name on line 274: `"getStateFilePath returns .pi/superpowers-state.json in cwd"` → `"getStateFilePath returns .pi/workflow-kit-state.json in cwd"`
+2. On line 318: change `"superpowers-state.json"` → `"workflow-kit-state.json"`
+3. On line 337: change `"superpowers-state.json"` → `"workflow-kit-state.json"`
+4. Delete the entire `describe("state file rename to .pi/workflow-kit-state.json with legacy fallback", () => { ... })` block (4 tests, from line ~404 to ~530)
+
+**Step 4: Run tests**
+
+Run: `npx vitest run tests/extension/workflow-monitor/state-persistence.test.ts`
+Expected: All tests pass
+
+**Step 5: Run full test suite**
+
+Run: `npx vitest run`
+Expected: All tests pass
+
+**Step 6: Commit**
+
+```bash
+git add extensions/workflow-monitor.ts tests/extension/workflow-monitor/state-persistence.test.ts
+git commit -m "refactor: remove superpowers-state.json legacy fallback"
+```
+
+---
+
+### Task 2: Enforce brainstorm/plan phase boundaries (block immediately)
+
+**Type:** code
+**TDD scenario:** Modifying tested code — update existing tests first
+
+**Files:**
+- Modify: `extensions/workflow-monitor.ts:135-520`
+- Modify: `tests/extension/workflow-monitor/phase-aware-write-enforcement.test.ts`
+
+**Step 1: Run existing enforcement tests**
+
+Run: `npx vitest run tests/extension/workflow-monitor/phase-aware-write-enforcement.test.ts`
+Expected: All tests pass
+
+**Step 2: Update source — block immediately instead of escalating**
+
+In `extensions/workflow-monitor.ts`:
+
+1. Remove `pendingProcessWarnings` map declaration (line ~135).
+2. Change `ViolationBucket` type from `"process" | "practice"` to `"practice"`.
+3. Change `strikes` from `{ process: 0, practice: 0 }` to `{ practice: 0 }`.
+4. Change `sessionAllowed` type to `Partial<Record<"practice", boolean>>`.
+5. In `maybeEscalate`, change parameter type from `ViolationBucket` to `"practice"`.
+6. In `tool_result` handler, remove the `pendingProcessWarnings.get(toolCallId)` / `.delete(toolCallId)` block (3 lines).
+7. In `tool_call` handler (~line 506-516), replace the `maybeEscalate("process", ctx)` + `pendingProcessWarnings.set(...)` block with:
+
+```typescript
+return {
+  blocked: true,
+  reason:
+    `⚠️ PROCESS VIOLATION: Wrote ${filePath} during ${phase} phase.\n` +
+    "During brainstorming/planning you may only write to docs/plans/. " +
+    "Read code and docs to understand the problem, then discuss the design before implementing.",
+};
+```
+
+**Step 3: Update tests**
+
+In `tests/extension/workflow-monitor/phase-aware-write-enforcement.test.ts`:
+
+1. The first test (`"warns when writing outside docs/plans during brainstorm"`) currently checks for an injected warning in the tool result. After the change, the write is blocked in `on_tool_call` before it executes, so `on_tool_result` is never reached. Replace the test to check that `onToolCall` returns `{ blocked: true }` with a `reason` containing `"PROCESS VIOLATION"` and `"brainstorm"`. Remove the `onToolResult` call and its assertion.
+
+2. Add a new test: `"blocks immediately on first violation during plan phase"` — same pattern as brainstorm but with `currentPhase: "plan"`, verify `{ blocked: true, reason: expect.stringContaining("PROCESS VIOLATION") }`.
+
+3. The test `"second process violation hard-blocks (interactive)"` is no longer relevant — blocking is immediate now. Delete it.
+
+**Step 4: Run enforcement tests**
+
+Run: `npx vitest run tests/extension/workflow-monitor/phase-aware-write-enforcement.test.ts`
+Expected: All tests pass
+
+**Step 5: Run full test suite**
+
+Run: `npx vitest run`
+Expected: All tests pass
+
+**Step 6: Commit**
+
+```bash
+git add extensions/workflow-monitor.ts tests/extension/workflow-monitor/phase-aware-write-enforcement.test.ts
+git commit -m "feat: block writes outside docs/plans immediately during brainstorm/plan phases"
+```
+
+---
+
+### Task 3: Fix artifact completions losing the phase word
+
+**Type:** code
+**TDD scenario:** Modifying tested code — update existing tests first
+
+**Files:**
+- Modify: `extensions/workflow-monitor/workflow-next-completions.ts:50-60`
+- Modify: `tests/extension/workflow-monitor/workflow-next-command.test.ts`
+
+**Step 1: Run existing completion tests**
+
+Run: `npx vitest run tests/extension/workflow-monitor/workflow-next-command.test.ts`
+Expected: All tests pass
+
+**Step 2: Update source — prepend phase to artifact values**
+
+In `extensions/workflow-monitor/workflow-next-completions.ts`, in `listArtifactsForPhase`, the function needs the `phase` parameter included in `item.value`. Change the final `.map()`:
+
+```typescript
+// Before:
+.map((relPath) => ({ value: relPath, label: relPath }));
+
+// After:
+.map((relPath) => ({ value: `${phase} ${relPath}`, label: relPath }));
+```
+
+This ensures pi's `applyCompletion` replaces the full prefix (e.g. `"plan des"`) with `"plan docs/plans/..."` — preserving the phase word.
+
+**Step 3: Update tests**
+
+In `tests/extension/workflow-monitor/workflow-next-command.test.ts`, update these tests to expect `value` with the phase prefix:
+
+1. `"suggests only design artifacts for plan phase"` — change `value: "docs/plans/..."` to `value: "plan docs/plans/..."`, keep `label` unchanged.
+
+2. `"filters plan artifact suggestions by typed prefix"` — same value change.
+
+3. `"suggests only implementation artifacts for execute and finalize"` — change execute value to `"execute docs/plans/..."` and finalize value to `"finalize docs/plans/..."`.
+
+**Step 4: Run completion tests**
+
+Run: `npx vitest run tests/extension/workflow-monitor/workflow-next-command.test.ts`
+Expected: All tests pass
+
+**Step 5: Run full test suite**
+
+Run: `npx vitest run`
+Expected: All tests pass
+
+**Step 6: Commit**
+
+```bash
+git add extensions/workflow-monitor/workflow-next-completions.ts tests/extension/workflow-monitor/workflow-next-command.test.ts
+git commit -m "fix: preserve phase word in /workflow-next artifact completions"
+```

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;
@@ -230,6 +236,12 @@ export default function (pi: ExtensionAPI) {
     }
   };
 
+  // Listen for clear signal from workflow-monitor's /workflow-reset command.
+  // This allows cross-extension communication without a callTool API.
+  pi.events.on("plan_tracker:clear", () => {
+    tasks = [];
+  });
+
   // Reconstruct state + widget on session events
   // session_start covers startup, reload, new, resume, fork (pi v0.65.0+)
   pi.on("session_start", async (_event, ctx) => {

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

@@ -88,6 +88,7 @@ export interface WorkflowHandler {
   restoreWorkflowStateFromBranch(branch: SessionEntry[]): void;
   markWorkflowPrompted(phase: Phase): boolean;
   completeCurrentWorkflowPhase(): boolean;
+  completeWorkflowPhase(phase: Phase): boolean;
   advanceWorkflowTo(phase: Phase): boolean;
   skipWorkflowPhases(phases: Phase[]): boolean;
   handleSkillFileRead(path: string): boolean;
@@ -323,6 +324,10 @@ export function createWorkflowHandler(): WorkflowHandler {
       return tracker.completeCurrent();
     },
 
+    completeWorkflowPhase(phase: Phase) {
+      return tracker.completePhase(phase);
+    },
+
     advanceWorkflowTo(phase) {
       return tracker.advanceTo(phase);
     },

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

@@ -42,7 +42,7 @@ function listArtifactsForPhase(phase: WorkflowNextPhase, typedPrefix: string): A
       .filter((name) => name.endsWith(suffix))
       .map((name) => path.join("docs", "plans", name))
       .filter((relPath) => relPath.startsWith(typedPrefix))
-      .map((relPath) => ({ value: relPath, label: relPath }));
+      .map((relPath) => ({ value: `${phase} ${relPath}`, label: relPath }));
 
     return items.length > 0 ? items : null;
   } catch {

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

@@ -12,9 +12,31 @@ export interface WorkflowTrackerState {
   prompted: Record<Phase, boolean>;
 }
 
-export type TransitionBoundary = "design_committed" | "plan_ready" | "execution_complete";
+export type TransitionBoundary =
+  | "design_reviewable"
+  | "plan_reviewable"
+  | "design_committed"
+  | "plan_ready"
+  | "execution_complete";
 
 export function computeBoundaryToPrompt(state: WorkflowTrackerState): TransitionBoundary | null {
+  // Reviewable: current phase has its deliverable artifact but hasn't been
+  // user-confirmed as complete. Prompt the user to review before moving on.
+  if (
+    state.currentPhase === "brainstorm" &&
+    state.artifacts.brainstorm &&
+    state.phases.brainstorm === "active" &&
+    !state.prompted.brainstorm
+  ) {
+    return "design_reviewable";
+  }
+  if (state.currentPhase === "plan" && state.artifacts.plan && state.phases.plan === "active" && !state.prompted.plan) {
+    return "plan_reviewable";
+  }
+
+  // Committed: phase is complete but user hasn't been prompted for
+  // transition options yet (e.g. phases completed via skip-confirmation
+  // "mark complete" or execute phase auto-completing on all tasks terminal).
   if (state.phases.brainstorm === "complete" && !state.prompted.brainstorm) {
     return "design_committed";
   }
@@ -96,24 +118,32 @@ export class WorkflowTracker {
 
     if (current) {
       const curIdx = WORKFLOW_PHASES.indexOf(current);
-      if (nextIdx <= curIdx) {
-        // Backward or same-phase navigation = new task. Reset everything.
+      if (nextIdx === curIdx) {
+        // Same-phase navigation is a no-op. This prevents accidental resets
+        // when plan_tracker init is called while already in execute, or when
+        // a skill is re-invoked during its own phase.
+        return false;
+      }
+      if (nextIdx < curIdx) {
+        // Backward navigation = intentional new task. Reset everything.
         this.reset();
         // Fall through to activate the target phase below.
       } else {
-        // Forward advance: auto-complete the current phase.
-        if (this.state.phases[current] === "active") {
-          this.state.phases[current] = "complete";
+        // Forward advance: do NOT auto-complete the current phase.
+        // Phase completion requires explicit user confirmation via
+        // boundary prompts or skip-confirmation "mark complete".
+        // However, refuse to jump over unresolved intermediate phases.
+        for (let i = curIdx + 1; i < nextIdx; i++) {
+          const intermediate = WORKFLOW_PHASES[i]!;
+          const status = this.state.phases[intermediate];
+          if (status !== "complete" && status !== "skipped") {
+            // Can't advance past an unresolved intermediate phase.
+            return false;
+          }
         }
       }
     }
 
-    for (const p of WORKFLOW_PHASES) {
-      if (p !== phase && this.state.phases[p] === "active") {
-        this.state.phases[p] = "complete";
-      }
-    }
-
     this.state.currentPhase = phase;
     if (this.state.phases[phase] === "pending") {
       this.state.phases[phase] = "active";
@@ -138,6 +168,10 @@ export class WorkflowTracker {
   completeCurrent(): boolean {
     const phase = this.state.currentPhase;
     if (!phase) return false;
+    return this.completePhase(phase);
+  }
+
+  completePhase(phase: Phase): boolean {
     if (this.state.phases[phase] === "complete") return false;
     this.state.phases[phase] = "complete";
     return true;
@@ -194,21 +228,42 @@ 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;
+      // Activate brainstorm phase but do NOT auto-complete.
+      // User confirms completion via the reviewable boundary prompt at agent_end.
+      changed = this.advanceTo("brainstorm") || 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;
+      // Activate plan phase but do NOT auto-complete.
+      // User confirms completion via the reviewable boundary prompt at agent_end.
+      changed = this.advanceTo("plan") || changed;
+      return changed;
     }
 
     return false;
   }
 
   onPlanTrackerInit(): boolean {
+    // Guard: don't advance if already in execute (prevents accidental resets).
+    // Also refuse to jump over unresolved phases (e.g., plan still active).
+    if (this.state.currentPhase === "execute") return false;
     return this.advanceTo("execute");
   }
 

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

@@ -1,6 +1,6 @@
 import type { Phase, TransitionBoundary } from "./workflow-tracker";
 
-export type TransitionChoice = "next" | "fresh" | "skip" | "discuss";
+export type TransitionChoice = "next" | "fresh" | "skip" | "revise" | "discuss";
 
 export interface TransitionPrompt {
   boundary: TransitionBoundary;
@@ -17,8 +17,36 @@ const BASE_OPTIONS: TransitionPrompt["options"] = [
   { choice: "discuss", label: "Discuss" },
 ];
 
+// Reviewable options: shown when a phase has its artifact but hasn't
+// been user-confirmed as complete. Includes explicit approval + revision.
+const REVIEWABLE_OPTIONS: TransitionPrompt["options"] = [
+  { choice: "next", label: "✓ Looks good, next step (this session)" },
+  { choice: "fresh", label: "✓ Looks good, fresh session → next step" },
+  { choice: "skip", label: "Skip phase" },
+  { choice: "revise", label: "✗ Needs more work" },
+  { choice: "discuss", label: "Discuss" },
+];
+
 export function getTransitionPrompt(boundary: TransitionBoundary, artifactPath: string | null): TransitionPrompt {
   switch (boundary) {
+    // Reviewable: phase has artifact but user hasn't confirmed completion
+    case "design_reviewable":
+      return {
+        boundary,
+        title: `Design written${artifactPath ? `: ${artifactPath}` : ""}. Ready to proceed?`,
+        nextPhase: "plan",
+        artifactPath,
+        options: REVIEWABLE_OPTIONS,
+      };
+    case "plan_reviewable":
+      return {
+        boundary,
+        title: `Plan written${artifactPath ? `: ${artifactPath}` : ""}. Ready to proceed?`,
+        nextPhase: "execute",
+        artifactPath,
+        options: REVIEWABLE_OPTIONS,
+      };
+    // Committed: phase already complete, user chooses how to proceed
     case "design_committed":
       return {
         boundary,
@@ -53,3 +81,8 @@ export function getTransitionPrompt(boundary: TransitionBoundary, artifactPath:
       };
   }
 }
+
+/** Whether a boundary represents a phase that still needs user confirmation. */
+export function isReviewableBoundary(boundary: TransitionBoundary): boolean {
+  return boundary === "design_reviewable" || boundary === "plan_reviewable";
+}

package/extensions/workflow-monitor.ts

@@ -8,14 +8,12 @@
  * - Register workflow_reference tool for on-demand reference content
  */
 
-import * as fs from "node:fs";
 import * as path from "node:path";
 import { StringEnum } from "@mariozechner/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
 import { Text } from "@mariozechner/pi-tui";
 import { Type } from "@sinclair/typebox";
-import { PLAN_TRACKER_TOOL_NAME } from "./constants.js";
-import { log } from "./lib/logging.js";
+import { PLAN_TRACKER_CLEARED_TYPE, PLAN_TRACKER_TOOL_NAME } from "./constants.js";
 import type { PlanTrackerDetails } from "./plan-tracker.js";
 import { getCurrentGitRef } from "./workflow-monitor/git";
 import { loadReference, REFERENCE_TOPICS } from "./workflow-monitor/reference-tool";
@@ -47,7 +45,7 @@ import {
   WORKFLOW_TRACKER_ENTRY_TYPE,
   type WorkflowTrackerState,
 } from "./workflow-monitor/workflow-tracker";
-import { getTransitionPrompt } from "./workflow-monitor/workflow-transitions";
+import { getTransitionPrompt, isReviewableBoundary } from "./workflow-monitor/workflow-transitions";
 
 type SelectOption<T extends string> = { label: string; value: T };
 
@@ -64,75 +62,32 @@ async function selectValue<T extends string>(
 
 const SUPERPOWERS_STATE_ENTRY_TYPE = "superpowers_state";
 
-function getLegacyStateFilePath(): string {
-  return path.join(process.cwd(), ".pi", "superpowers-state.json");
-}
-
-export function getStateFilePath(): string {
-  return path.join(process.cwd(), ".pi", "workflow-kit-state.json");
-}
-
-export function reconstructState(ctx: ExtensionContext, handler: WorkflowHandler, stateFilePath?: string | false) {
+export function reconstructState(ctx: ExtensionContext, handler: WorkflowHandler) {
   handler.resetState();
 
-  // Read both file-based and session-based state, then pick the newer one.
-  let fileData: (Record<string, unknown> & { savedAt?: number }) | null = null;
-  let sessionData: (Record<string, unknown> & { savedAt?: number }) | null = null;
-
-  if (stateFilePath !== false) {
-    try {
-      const newPath = stateFilePath ?? getStateFilePath();
-      if (fs.existsSync(newPath)) {
-        const raw = fs.readFileSync(newPath, "utf-8");
-        fileData = JSON.parse(raw);
-      } else if (stateFilePath === undefined) {
-        // Legacy fallback: try the old filename only when no explicit path is given.
-        const legacyPath = getLegacyStateFilePath();
-        if (fs.existsSync(legacyPath)) {
-          const raw = fs.readFileSync(legacyPath, "utf-8");
-          fileData = JSON.parse(raw);
-        }
-      }
-    } catch (err) {
-      log.warn(
-        `Failed to read state file, falling back to session entries: ${err instanceof Error ? err.message : err}`,
-      );
-    }
-  }
-
-  // Scan session branch for most recent superpowers state entry
+  // Scan session branch for most recent superpowers state entry.
+  // The session branch IS the single source of truth — no file-based
+  // persistence needed since pi's journal survives restarts and reloads.
   const entries = ctx.sessionManager.getBranch();
   for (let i = entries.length - 1; i >= 0; i--) {
     const entry = entries[i];
     // biome-ignore lint/suspicious/noExplicitAny: pi SDK session entry type
     if (entry.type === "custom" && (entry as any).customType === SUPERPOWERS_STATE_ENTRY_TYPE) {
       // biome-ignore lint/suspicious/noExplicitAny: pi SDK session entry type
-      sessionData = (entry as any).data;
-      break;
+      handler.setFullState((entry as any).data);
+      return;
     }
     // Migration fallback: old-format workflow-only entries
     // biome-ignore lint/suspicious/noExplicitAny: pi SDK session entry type
     if (entry.type === "custom" && (entry as any).customType === WORKFLOW_TRACKER_ENTRY_TYPE) {
       // biome-ignore lint/suspicious/noExplicitAny: pi SDK session entry type
-      sessionData = { workflow: (entry as any).data };
-      break;
+      handler.setFullState({ workflow: (entry as any).data });
+      return;
     }
   }
 
-  // Pick the newer source when both are available; otherwise use whichever exists.
-  if (fileData && sessionData) {
-    const fileSavedAt = fileData.savedAt ?? 0;
-    const sessionSavedAt = sessionData.savedAt ?? 0;
-    const winner = fileSavedAt >= sessionSavedAt ? fileData : sessionData;
-    handler.setFullState(winner);
-  } else if (fileData) {
-    handler.setFullState(fileData);
-  } else if (sessionData) {
-    handler.setFullState(sessionData);
-  } else {
-    // No entries found — reset to fresh defaults
-    handler.setFullState({});
-  }
+  // No entries found — reset to fresh defaults
+  handler.setFullState({});
 }
 
 export default function (pi: ExtensionAPI) {
@@ -143,10 +98,9 @@ export default function (pi: ExtensionAPI) {
   const pendingViolations = new Map<string, Violation>();
   const pendingVerificationViolations = new Map<string, VerificationViolation>();
   const pendingBranchGates = new Map<string, string>();
-  const pendingProcessWarnings = new Map<string, string>();
 
-  type ViolationBucket = "process" | "practice";
-  const strikes: Record<ViolationBucket, number> = { process: 0, practice: 0 };
+  type ViolationBucket = "practice";
+  const strikes: Record<ViolationBucket, number> = { practice: 0 };
   const sessionAllowed: Partial<Record<ViolationBucket, boolean>> = {};
 
   async function maybeEscalate(bucket: ViolationBucket, ctx: ExtensionContext): Promise<"allow" | "block"> {
@@ -180,14 +134,6 @@ export default function (pi: ExtensionAPI) {
   const persistState = () => {
     const stateWithTimestamp = { ...handler.getFullState(), savedAt: Date.now() };
     pi.appendEntry(SUPERPOWERS_STATE_ENTRY_TYPE, stateWithTimestamp);
-    // Also persist to file for cross-session survival
-    try {
-      const statePath = getStateFilePath();
-      fs.mkdirSync(path.dirname(statePath), { recursive: true });
-      fs.writeFileSync(statePath, JSON.stringify(stateWithTimestamp, null, 2));
-    } catch (err) {
-      log.warn(`Failed to persist state file: ${err instanceof Error ? err.message : err}`);
-    }
   };
 
   const phaseToSkill: Record<string, string> = {
@@ -219,6 +165,8 @@ export default function (pi: ExtensionAPI) {
   }
 
   const boundaryToPhase: Record<TransitionBoundary, keyof typeof phaseToSkill> = {
+    design_reviewable: "brainstorm",
+    plan_reviewable: "plan",
     design_committed: "brainstorm",
     plan_ready: "plan",
     execution_complete: "execute",
@@ -230,10 +178,7 @@ export default function (pi: ExtensionAPI) {
     pendingViolations.clear();
     pendingVerificationViolations.clear();
     pendingBranchGates.clear();
-    pendingProcessWarnings.clear();
-    strikes.process = 0;
     strikes.practice = 0;
-    delete sessionAllowed.process;
     delete sessionAllowed.practice;
     branchNoticeShown = false;
     branchConfirmed = false;
@@ -290,12 +235,19 @@ export default function (pi: ExtensionAPI) {
       const missingSkill = phaseToSkill[missing] ?? missing;
       const options = [
         { label: `Do ${missing} now`, value: "do_now" as const },
+        { label: `Mark ${missing} as complete`, value: "mark_complete" as const },
         { label: `Skip ${missing}`, value: "skip" as const },
         { label: "Cancel", value: "cancel" as const },
       ];
       const choice = await selectValue(ctx, `Phase "${missing}" is unresolved. What would you like to do?`, options);
 
-      if (choice === "skip") {
+      if (choice === "mark_complete") {
+        handler.completeWorkflowPhase(missing as Phase);
+        handler.handleInputText(text);
+        persistState();
+        updateWidget(ctx);
+        return;
+      } else if (choice === "skip") {
         handler.skipWorkflowPhases([missing]);
         handler.handleInputText(text);
         persistState();
@@ -337,12 +289,17 @@ export default function (pi: ExtensionAPI) {
       const skill = phaseToSkill[phase] ?? phase;
       const options = [
         { label: `Do ${phase} now`, value: "do_now" as const },
+        { label: `Mark ${phase} as complete`, value: "mark_complete" as const },
         { label: `Skip ${phase}`, value: "skip" as const },
         { label: "Cancel", value: "cancel" as const },
       ];
       const choice = await selectValue(ctx, `Phase "${phase}" is unresolved. What would you like to do?`, options);
 
-      if (choice === "skip") {
+      if (choice === "mark_complete") {
+        handler.completeWorkflowPhase(phase as Phase);
+        persistState();
+        updateWidget(ctx);
+      } else if (choice === "skip") {
         handler.skipWorkflowPhases([phase]);
         persistState();
         updateWidget(ctx);
@@ -369,12 +326,18 @@ export default function (pi: ExtensionAPI) {
       const missingSkill = phaseToSkill[missing] ?? missing;
       const options = [
         { label: `Do ${missing} now`, value: "do_now" as const },
+        { label: `Mark ${missing} as complete`, value: "mark_complete" as const },
         { label: `Skip ${missing}`, value: "skip" as const },
         { label: "Cancel", value: "cancel" as const },
       ];
       const choice = await selectValue(ctx, `Phase "${missing}" is unresolved. What would you like to do?`, options);
 
-      if (choice === "skip") {
+      if (choice === "mark_complete") {
+        handler.completeWorkflowPhase(missing as Phase);
+        persistState();
+        updateWidget(ctx);
+        return "allowed";
+      } else if (choice === "skip") {
         handler.skipWorkflowPhases([missing]);
         persistState();
         updateWidget(ctx);
@@ -413,12 +376,17 @@ export default function (pi: ExtensionAPI) {
       const skill = phaseToSkill[phase] ?? phase;
       const options = [
         { label: `Do ${phase} now`, value: "do_now" as const },
+        { label: `Mark ${phase} as complete`, value: "mark_complete" as const },
         { label: `Skip ${phase}`, value: "skip" as const },
         { label: "Cancel", value: "cancel" as const },
       ];
       const choice = await selectValue(ctx, `Phase "${phase}" is unresolved. What would you like to do?`, options);
 
-      if (choice === "skip") {
+      if (choice === "mark_complete") {
+        handler.completeWorkflowPhase(phase as Phase);
+        persistState();
+        updateWidget(ctx);
+      } else if (choice === "skip") {
         handler.skipWorkflowPhases([phase]);
         persistState();
         updateWidget(ctx);
@@ -514,16 +482,13 @@ export default function (pi: ExtensionAPI) {
         const isPlansWrite = resolved.startsWith(plansRoot);
 
         if (isThinkingPhase && !isPlansWrite) {
-          const escalation = await maybeEscalate("process", ctx);
-          if (escalation === "block") {
-            return { blocked: true };
-          }
-
-          pendingProcessWarnings.set(
-            toolCallId,
-            `⚠️ PROCESS VIOLATION: Wrote ${filePath} during ${phase} phase.\n` +
-              "During brainstorming/planning you may only write to docs/plans/. Stop and return to docs/plans/ or advance workflow phases intentionally.",
-          );
+          return {
+            blocked: true,
+            reason:
+              `⚠️ PROCESS VIOLATION: Wrote ${filePath} during ${phase} phase.\n` +
+              "During brainstorming/planning you may only write to docs/plans/. " +
+              "Read code and docs to understand the problem, then discuss the design before implementing.",
+          };
         }
 
         changed = handler.handleFileWritten(filePath) || changed;
@@ -615,12 +580,6 @@ export default function (pi: ExtensionAPI) {
         }
       }
       pendingViolations.delete(toolCallId);
-
-      const processWarning = pendingProcessWarnings.get(toolCallId);
-      if (processWarning) {
-        injected.push(processWarning);
-      }
-      pendingProcessWarnings.delete(toolCallId);
     }
 
     // Handle bash results (test runs, commits, investigation)
@@ -674,18 +633,13 @@ export default function (pi: ExtensionAPI) {
 
     const boundaryPhase = boundaryToPhase[boundary];
     const prompt = getTransitionPrompt(boundary, latestState.artifacts[boundaryPhase]);
+    const reviewable = isReviewableBoundary(boundary);
 
     const options = prompt.options.map((o) => o.label);
     const pickedLabel = await ctx.ui.select(prompt.title, options);
 
     const selected = prompt.options.find((o) => o.label === pickedLabel)?.choice ?? null;
 
-    const marked = handler.markWorkflowPrompted(boundaryPhase);
-    if (marked) {
-      persistState();
-      updateWidget(ctx);
-    }
-
     const nextSkill = phaseToSkill[prompt.nextPhase] ?? "writing-plans";
     const nextInSession = `/skill:${nextSkill}`;
     const fresh = `/workflow-next ${prompt.nextPhase}${prompt.artifactPath ? ` ${prompt.artifactPath}` : ""}`;
@@ -694,42 +648,56 @@ export default function (pi: ExtensionAPI) {
       "- Does this work require documentation updates? (README, CHANGELOG, API docs, inline docs)\n" +
       "- What was learned during this implementation? (surprises, codebase knowledge, things to do differently)\n\n";
 
-    if (selected === "next") {
-      const advanced = prompt.nextPhase === "finalize" ? handler.advanceWorkflowTo("finalize") : false;
-      if (advanced) {
-        persistState();
-        updateWidget(ctx);
+    if (selected === "next" || selected === "fresh") {
+      // For reviewable boundaries: mark current phase complete first.
+      // For committed boundaries: phase is already complete.
+      if (reviewable) {
+        handler.completeCurrentWorkflowPhase();
       }
-      ctx.ui.setEditorText(prompt.nextPhase === "finalize" ? finishReminder + nextInSession : nextInSession);
-    } else if (selected === "fresh") {
-      const advanced = prompt.nextPhase === "finalize" ? handler.advanceWorkflowTo("finalize") : false;
-      if (advanced) {
-        persistState();
-        updateWidget(ctx);
+
+      // Advance to the next phase
+      handler.advanceWorkflowTo(prompt.nextPhase);
+      handler.markWorkflowPrompted(boundaryPhase);
+      persistState();
+      updateWidget(ctx);
+
+      if (selected === "next") {
+        ctx.ui.setEditorText(prompt.nextPhase === "finalize" ? finishReminder + nextInSession : nextInSession);
+      } else {
+        ctx.ui.setEditorText(prompt.nextPhase === "finalize" ? finishReminder + fresh : fresh);
       }
-      ctx.ui.setEditorText(prompt.nextPhase === "finalize" ? finishReminder + fresh : fresh);
     } else if (selected === "skip") {
-      // Explicit user-confirmed skip: mark the next phase as skipped, then move on.
-      handler.skipWorkflowPhases([prompt.nextPhase]);
-
-      const nextIdx = WORKFLOW_PHASES.indexOf(prompt.nextPhase);
-      const phaseAfterSkip = WORKFLOW_PHASES[nextIdx + 1] ?? null;
-
-      if (phaseAfterSkip) {
-        const currentState = handler.getWorkflowState();
-        const currentIdx = currentState?.currentPhase ? WORKFLOW_PHASES.indexOf(currentState.currentPhase) : -1;
-        const afterSkipIdx = WORKFLOW_PHASES.indexOf(phaseAfterSkip);
-        if (afterSkipIdx > currentIdx) {
-          handler.advanceWorkflowTo(phaseAfterSkip);
+      if (reviewable) {
+        // Skip the current phase (the one with the artifact) and advance to next.
+        handler.skipWorkflowPhases([boundaryPhase]);
+        handler.advanceWorkflowTo(prompt.nextPhase);
+      } else {
+        // Committed boundary: skip the NEXT phase and advance past it.
+        handler.skipWorkflowPhases([prompt.nextPhase]);
+        const nextIdx = WORKFLOW_PHASES.indexOf(prompt.nextPhase);
+        const phaseAfterSkip = WORKFLOW_PHASES[nextIdx + 1] ?? null;
+
+        if (phaseAfterSkip && handler.advanceWorkflowTo(phaseAfterSkip)) {
           const skipSkill = phaseToSkill[phaseAfterSkip] ?? "writing-plans";
           ctx.ui.setEditorText(`/skill:${skipSkill}`);
         }
       }
 
+      handler.markWorkflowPrompted(boundaryPhase);
       persistState();
       updateWidget(ctx);
+    } else if (selected === "revise") {
+      // Reviewable only: user wants to keep working. Don't set prompted
+      // so the review prompt fires again at the next agent_end.
+      // Don't advance, don't modify phase state.
     } else if (selected === "discuss") {
-      // Don't advance phase. Set editor text to prompt discussion.
+      // For reviewable: don't set prompted (prompt fires again after discussion).
+      // For committed: set prompted (phase is already done, user just wants to chat).
+      if (!reviewable) {
+        handler.markWorkflowPrompted(boundaryPhase);
+        persistState();
+        updateWidget(ctx);
+      }
       ctx.ui.setEditorText(
         `Let's discuss before moving to the next step.\n` +
           `We're at: ${prompt.title}\n` +
@@ -822,8 +790,13 @@ export default function (pi: ExtensionAPI) {
     description: "Reset workflow tracker to fresh state for a new task",
     async handler(_args, ctx) {
       handler.resetState();
+      // Emit a clear signal so plan-tracker also reconstructs to empty on next
+      // session reload. Also notify plan-tracker in real time via the shared
+      // event bus so its in-memory state and widget update immediately.
+      pi.appendEntry(PLAN_TRACKER_CLEARED_TYPE, { clearedAt: Date.now() });
       persistState();
       updateWidget(ctx);
+      pi.events.emit("plan_tracker:clear");
       if (ctx.hasUI) {
         ctx.ui.notify("Workflow reset. Ready for a new task.", "info");
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tianhai/pi-workflow-kit",
-  "version": "0.5.0",
+  "version": "0.5.3",
   "description": "Workflow skills and enforcement extensions for pi",
   "keywords": [
     "pi-package"

package/skills/brainstorming/SKILL.md

@@ -1,23 +1,31 @@
 ---
 name: brainstorming
 description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
+allowed-tools: read bash
 ---
 
 > **Related skills:** Consider `/skill:using-git-worktrees` to set up an isolated workspace, then `/skill:writing-plans` for implementation planning.
 
 # Brainstorming Ideas Into Designs
 
+> ⚠️ **BOUNDARY — DO NOT VIOLATE**
+>
+> This skill is **read-only exploration**. You MUST NOT use `edit` or `write` tools.
+> The only tools allowed are `read` and `bash` (for investigation only).
+>
+> - ✅ Read code and docs: yes
+> - ✅ Write to `docs/plans/`: yes (design documents only)
+> - ❌ Edit or create any other files: **absolutely no**
+>
+> If you find yourself reaching for `edit` or `write`, **stop**. Present what
+> you found as a design section and ask the user to approve it first.
+
 ## Overview
 
 Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
 
 Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design in small sections (200-300 words), checking after each section whether it looks right so far.
 
-## Boundaries
-- Read code and docs: yes
-- Write to docs/plans/: yes
-- Edit or create any other files: no
-
 ## The Process
 
 **Before anything else — check git state:**