@tianhai/pi-workflow-kit 0.4.1 → 0.5.0

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

@@ -0,0 +1,251 @@
+# /workflow-next Handoff State Design
+
+Date: 2026-04-09
+Status: approved
+
+## Summary
+
+Fix `/workflow-next` so that, for the same feature, a fresh handoff session preserves prior completed workflow history instead of showing earlier phases as `pending` again.
+
+The command should become a strict forward-only handoff for the immediate next phase. It must not allow same-phase handoff, backward handoff, or direct jumps across multiple phases.
+
+## Problem
+
+Today `/workflow-next` creates a new session and pre-fills the editor with the next skill, but it does not explicitly seed the new session with a derived workflow state for the same feature.
+
+As a result, the new session may start from an empty workflow tracker state:
+
+- `brainstorm: pending`
+- `plan: pending`
+- `execute: pending`
+- `finalize: pending`
+
+When the prefilled skill is then detected, the tracker advances only to the requested phase. Earlier phases remain `pending`, even when they were already completed in the previous session.
+
+## Goals
+
+- Preserve prior completed workflow phases across `/workflow-next` handoff for the same feature.
+- Preserve earlier-phase artifact paths and prompted flags.
+- Keep TDD, debug, and verification state fresh in the new session.
+- Make `/workflow-next` a strict immediate-next handoff command.
+- Reject invalid handoffs before creating a new session.
+- Rename the persisted state file to reflect current naming.
+
+## Non-goals
+
+- Allow arbitrary phase switching.
+- Allow skipping phases through `/workflow-next`.
+- Carry over TDD/debug/verification runtime state into the new session.
+- Change the existing slash-command UX beyond stricter validation and correct state seeding.
+
+## Decisions
+
+### 1. Preserve derived workflow-only state
+
+When `/workflow-next <phase>` is used for the same feature, the new session will receive a derived workflow snapshot.
+
+Rules:
+
+- all phases before the requested phase are `complete`
+- the requested phase is `active`
+- all phases after the requested phase are `pending`
+- `currentPhase` is the requested phase
+- earlier-phase artifacts are preserved
+- earlier-phase prompted flags are preserved
+
+This snapshot is derived from the current workflow state, not reconstructed from filenames alone.
+
+### 2. Do not preserve execution-local monitor state
+
+The new session must start with fresh:
+
+- TDD state
+- debug state
+- verification state
+
+Only workflow lineage is preserved.
+
+### 3. `/workflow-next` is immediate-next only
+
+Allowed transitions:
+
+- `brainstorm -> plan`
+- `plan -> execute`
+- `execute -> finalize`
+
+Only when the current phase status is exactly `complete`.
+
+Disallowed transitions:
+
+- same-phase handoff
+- backward handoff
+- direct jumps such as `brainstorm -> execute` or `plan -> finalize`
+- moving forward when the current phase is `pending`, `active`, or `skipped`
+
+Skipped phases do not qualify for `/workflow-next`.
+
+### 4. Hard-fail invalid handoffs
+
+Invalid requests must show an error and stop before opening a new session.
+
+Examples:
+
+- `Cannot hand off to execute from brainstorm. /workflow-next only supports the immediate next phase.`
+- `Cannot hand off to plan because brainstorm is not complete.`
+- `Cannot hand off to plan from plan. Use /workflow-reset for a new task or continue in this session.`
+
+### 5. Rename persisted state file
+
+Rename the local state file from:
+
+- `.pi/superpowers-state.json`
+
+To:
+
+- `.pi/workflow-kit-state.json`
+
+Migration behavior:
+
+- reconstruction first checks `.pi/workflow-kit-state.json`
+- if absent, it falls back to `.pi/superpowers-state.json`
+- persistence writes only `.pi/workflow-kit-state.json`
+
+This preserves compatibility for existing users while moving to clearer naming.
+
+## Proposed implementation
+
+## Helper module
+
+Add a small helper module under `extensions/workflow-monitor/`, for example:
+
+- `workflow-next-state.ts`
+
+Responsibilities:
+
+### `validateNextWorkflowPhase(currentState, requestedPhase)`
+
+Input:
+
+- current workflow state
+- requested target phase
+
+Behavior:
+
+- require a current phase to exist
+- require the requested phase to be the immediate next phase
+- require `currentState.phases[currentState.currentPhase] === "complete"`
+- return either success or a precise error message
+
+### `deriveWorkflowHandoffState(currentState, requestedPhase)`
+
+Input:
+
+- current workflow state
+- requested target phase
+
+Behavior:
+
+- produce a new workflow snapshot for the handoff session
+- mark prior phases `complete`
+- mark the requested phase `active`
+- leave later phases `pending`
+- preserve artifacts and prompted flags for earlier phases
+- set `currentPhase` to the requested phase
+
+## `/workflow-next` handler changes
+
+Update `extensions/workflow-monitor.ts` so the handler:
+
+1. parses `phase` and optional artifact path
+2. validates the phase value against the known set
+3. reads `handler.getWorkflowState()`
+4. calls `validateNextWorkflowPhase(...)`
+5. if invalid, notifies with an error and returns
+6. creates the new session
+7. seeds the new session with a fresh snapshot containing:
+   - derived `workflow`
+   - default `tdd`
+   - default `debug`
+   - default `verification`
+8. pre-fills the editor text as today
+
+The prefilled text remains useful, but the session no longer depends on skill detection to reconstruct earlier history.
+
+## Persistence flow
+
+### Current
+
+State is persisted in two places:
+
+- session custom entry (`superpowers_state`)
+- local JSON file under `.pi/`
+
+### New behavior
+
+Keep the same general persistence model, but:
+
+- continue using the full snapshot shape for session persistence
+- write the renamed local file
+- allow reconstruction from either the new or legacy filename
+
+## Testing
+
+Add or update tests for:
+
+### Workflow-next validation
+
+- allows `brainstorm -> plan` only when `brainstorm` is `complete`
+- allows `plan -> execute` only when `plan` is `complete`
+- allows `execute -> finalize` only when `execute` is `complete`
+- rejects same-phase handoff
+- rejects backward handoff
+- rejects direct jumps
+- rejects handoff when current phase is `active`
+- rejects handoff when current phase is `pending`
+- rejects handoff when current phase is `skipped`
+
+### Derived state
+
+- preserves prior completed phases in the new session
+- preserves artifacts for earlier phases
+- preserves prompted flags for earlier phases
+- marks requested phase `active`
+- leaves later phases `pending`
+- resets TDD/debug/verification state in the new session
+
+### State-file migration
+
+- `getStateFilePath()` returns `.pi/workflow-kit-state.json`
+- reconstruction reads the new file when present
+- reconstruction falls back to `.pi/superpowers-state.json` when the new file is absent
+- persistence writes only the new filename
+
+## Risks and mitigations
+
+### Risk: session seeding API constraints
+
+Depending on the pi session API, the new session may not directly expose a way to append a custom state entry before user submission.
+
+Mitigation:
+
+- if direct session seeding is supported, use it
+- otherwise encode the derived workflow state into the handoff path using the existing persistence/reconstruction mechanism with minimal, well-scoped changes
+- verify behavior with an integration test around `/workflow-next`
+
+### Risk: invalidating existing expectations
+
+Tests and current behavior explicitly allow advancing to a later phase from empty state without backfilling earlier phases.
+
+Mitigation:
+
+- limit the stricter semantics to `/workflow-next`
+- keep generic workflow tracker behavior unchanged unless a separate design chooses otherwise
+
+## Acceptance criteria
+
+- Using `/workflow-next` for the immediate next phase of the same feature preserves prior completed phases in the fresh session.
+- Earlier completed phases do not regress to `pending` in the new session.
+- Artifacts and prompted flags for earlier phases are preserved.
+- TDD/debug/verification state is fresh in the new session.
+- Same-phase, backward, and direct-jump handoffs are rejected.
+- The local state file is renamed to `.pi/workflow-kit-state.json` with fallback support for the legacy filename.

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/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,
           };