@tianhai/pi-workflow-kit 0.4.1 → 0.5.1

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

@@ -0,0 +1,334 @@
+# /workflow-next Autocomplete Implementation Plan
+
+> **REQUIRED SUB-SKILL:** Use the executing-tasks skill to implement this plan task-by-task.
+
+**Goal:** Add argument autocomplete to `/workflow-next` for workflow phases and workflow-specific plan artifacts without changing command execution, validation, or session creation behavior.
+
+**Architecture:** Add a small stateless helper module under `extensions/workflow-monitor/` that parses the raw argument prefix and returns `AutocompleteItem[] | null` from pi's `getArgumentCompletions` hook. Keep `extensions/workflow-monitor.ts` as the command registration entry point and leave the existing `/workflow-next` handler logic unchanged so autocomplete stays UX-only.
+
+**Tech Stack:** TypeScript, Node.js `fs`/`path`, pi extension command API, Vitest
+
+---
+
+Reference design artifact: `docs/plans/2026-04-09-workflow-next-autocomplete-design.md`
+
+### Task 1: Add phase autocomplete for `/workflow-next`
+
+**Type:** code
+**TDD scenario:** New feature — full TDD cycle
+
+**Files:**
+- Create: `extensions/workflow-monitor/workflow-next-completions.ts`
+- Modify: `extensions/workflow-monitor.ts:1-38`
+- Modify: `extensions/workflow-monitor.ts:813-851`
+- Test: `tests/extension/workflow-monitor/workflow-next-command.test.ts:1-102`
+
+**Step 1: Write the failing test**
+
+```ts
+function getWorkflowNextCommand() {
+  let command: any;
+  const fakePi: any = {
+    on() {},
+    registerTool() {},
+    appendEntry() {},
+    registerCommand(name: string, opts: any) {
+      if (name === "workflow-next") command = opts;
+    },
+  };
+
+  workflowMonitorExtension(fakePi);
+  expect(command).toBeTruthy();
+  return command;
+}
+
+test("returns all workflow phases when no args are typed", async () => {
+  const command = getWorkflowNextCommand();
+  const items = await command.getArgumentCompletions("");
+  expect(items).toEqual([
+    { value: "brainstorm", label: "brainstorm" },
+    { value: "plan", label: "plan" },
+    { value: "execute", label: "execute" },
+    { value: "finalize", label: "finalize" },
+  ]);
+});
+
+test("keeps suggesting phases until the first arg is an exact valid phase", async () => {
+  const command = getWorkflowNextCommand();
+  const items = await command.getArgumentCompletions("pla docs/plans/");
+  expect(items).toEqual([{ value: "plan", label: "plan" }]);
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `npx vitest run tests/extension/workflow-monitor/workflow-next-command.test.ts -t "returns all workflow phases when no args are typed"`
+Expected: FAIL with `command.getArgumentCompletions is not a function` or an equivalent assertion failure because `/workflow-next` does not expose completions yet.
+
+**Step 3: Write minimal implementation**
+
+```ts
+// extensions/workflow-monitor/workflow-next-completions.ts
+import type { AutocompleteItem } from "@mariozechner/pi-tui";
+
+const WORKFLOW_NEXT_PHASES = ["brainstorm", "plan", "execute", "finalize"] as const;
+
+export async function getWorkflowNextCompletions(prefix: string): Promise<AutocompleteItem[] | null> {
+  const normalized = prefix.replace(/^\s+/, "");
+  const [firstToken = ""] = normalized.split(/\s+/, 1);
+  const completingFirstArg = normalized.length === 0 || !/\s/.test(normalized);
+
+  if (completingFirstArg || !WORKFLOW_NEXT_PHASES.includes(firstToken as (typeof WORKFLOW_NEXT_PHASES)[number])) {
+    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;
+}
+
+// extensions/workflow-monitor.ts
+pi.registerCommand("workflow-next", {
+  description: "Start a fresh session for the next workflow phase (optionally referencing an artifact path)",
+  getArgumentCompletions: getWorkflowNextCompletions,
+  async handler(args, ctx) {
+    // existing handler body stays unchanged
+  },
+});
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `npx vitest run tests/extension/workflow-monitor/workflow-next-command.test.ts -t "workflow phases"`
+Expected: PASS for the new phase-autocomplete assertions and PASS for the existing kickoff/validation tests.
+
+**Step 5: Commit**
+
+```bash
+git add tests/extension/workflow-monitor/workflow-next-command.test.ts extensions/workflow-monitor.ts extensions/workflow-monitor/workflow-next-completions.ts
+git commit -m "feat: add workflow-next phase autocomplete"
+```
+
+### Task 2: Add `plan` artifact suggestions for design docs
+
+**Type:** code
+**TDD scenario:** New feature — full TDD cycle
+
+**Files:**
+- Modify: `extensions/workflow-monitor/workflow-next-completions.ts`
+- Test: `tests/extension/workflow-monitor/workflow-next-command.test.ts:1-102`
+
+**Step 1: Write the failing test**
+
+```ts
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { withTempCwd } from "./test-helpers";
+
+test("suggests only design artifacts for plan phase", async () => {
+  const tempDir = withTempCwd();
+  const plansDir = path.join(tempDir, "docs", "plans");
+  fs.mkdirSync(plansDir, { recursive: true });
+  fs.writeFileSync(path.join(plansDir, "2026-04-09-alpha-design.md"), "");
+  fs.writeFileSync(path.join(plansDir, "2026-04-09-alpha-implementation.md"), "");
+
+  const command = getWorkflowNextCommand();
+  const items = await command.getArgumentCompletions("plan ");
+
+  expect(items).toEqual([
+    {
+      value: "docs/plans/2026-04-09-alpha-design.md",
+      label: "docs/plans/2026-04-09-alpha-design.md",
+    },
+  ]);
+});
+
+test("filters plan artifact suggestions by typed prefix", async () => {
+  const tempDir = withTempCwd();
+  const plansDir = path.join(tempDir, "docs", "plans");
+  fs.mkdirSync(plansDir, { recursive: true });
+  fs.writeFileSync(path.join(plansDir, "2026-04-09-alpha-design.md"), "");
+  fs.writeFileSync(path.join(plansDir, "2026-04-09-beta-design.md"), "");
+
+  const command = getWorkflowNextCommand();
+  const items = await command.getArgumentCompletions("plan docs/plans/2026-04-09-al");
+
+  expect(items).toEqual([
+    {
+      value: "docs/plans/2026-04-09-alpha-design.md",
+      label: "docs/plans/2026-04-09-alpha-design.md",
+    },
+  ]);
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `npx vitest run tests/extension/workflow-monitor/workflow-next-command.test.ts -t "design artifacts for plan phase"`
+Expected: FAIL because phase completion works, but second-argument artifact completion still returns `null`.
+
+**Step 3: Write minimal implementation**
+
+```ts
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { AutocompleteItem } from "@mariozechner/pi-tui";
+
+function listPlanArtifacts(suffix: string, typedPrefix: string): AutocompleteItem[] | null {
+  const plansDir = path.join(process.cwd(), "docs", "plans");
+  if (!fs.existsSync(plansDir)) return null;
+
+  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: relPath, label: relPath }));
+
+  return items.length > 0 ? items : null;
+}
+
+export async function getWorkflowNextCompletions(prefix: string): Promise<AutocompleteItem[] | null> {
+  // keep task-1 phase behavior
+  const match = prefix.replace(/^\s+/, "").match(/^(\S+)(?:\s+(.*))?$/);
+  const phase = match?.[1] ?? "";
+  const artifactPrefix = match?.[2] ?? "";
+  const startingSecondArg = /\s$/.test(prefix) || artifactPrefix.length > 0;
+
+  if (phase === "plan" && startingSecondArg) {
+    return listPlanArtifacts("-design.md", artifactPrefix);
+  }
+
+  return previousPhaseLogic(prefix);
+}
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `npx vitest run tests/extension/workflow-monitor/workflow-next-command.test.ts -t "plan"`
+Expected: PASS for the new `plan` artifact tests and PASS for the phase completion tests from Task 1.
+
+**Step 5: Commit**
+
+```bash
+git add tests/extension/workflow-monitor/workflow-next-command.test.ts extensions/workflow-monitor/workflow-next-completions.ts
+git commit -m "feat: add workflow-next plan artifact autocomplete"
+```
+
+### Task 3: Complete execute/finalize artifact mapping and quiet failure behavior
+
+**Type:** code
+**TDD scenario:** New feature — full TDD cycle
+
+**Files:**
+- Modify: `extensions/workflow-monitor/workflow-next-completions.ts`
+- Test: `tests/extension/workflow-monitor/workflow-next-command.test.ts:1-102`
+
+**Step 1: Write the failing test**
+
+```ts
+test("suggests only implementation artifacts for execute and finalize", async () => {
+  const tempDir = withTempCwd();
+  const plansDir = path.join(tempDir, "docs", "plans");
+  fs.mkdirSync(plansDir, { recursive: true });
+  fs.writeFileSync(path.join(plansDir, "2026-04-09-alpha-design.md"), "");
+  fs.writeFileSync(path.join(plansDir, "2026-04-09-alpha-implementation.md"), "");
+
+  const command = getWorkflowNextCommand();
+
+  await expect(command.getArgumentCompletions("execute ")).resolves.toEqual([
+    {
+      value: "docs/plans/2026-04-09-alpha-implementation.md",
+      label: "docs/plans/2026-04-09-alpha-implementation.md",
+    },
+  ]);
+
+  await expect(command.getArgumentCompletions("finalize ")).resolves.toEqual([
+    {
+      value: "docs/plans/2026-04-09-alpha-implementation.md",
+      label: "docs/plans/2026-04-09-alpha-implementation.md",
+    },
+  ]);
+});
+
+test("returns null for brainstorm artifact completion", async () => {
+  const command = getWorkflowNextCommand();
+  await expect(command.getArgumentCompletions("brainstorm ")).resolves.toBeNull();
+});
+
+test("returns null when docs/plans is missing or has no matching files", async () => {
+  withTempCwd();
+  const command = getWorkflowNextCommand();
+  await expect(command.getArgumentCompletions("execute ")).resolves.toBeNull();
+
+  const plansDir = path.join(process.cwd(), "docs", "plans");
+  fs.mkdirSync(plansDir, { recursive: true });
+  fs.writeFileSync(path.join(plansDir, "2026-04-09-alpha-design.md"), "");
+  await expect(command.getArgumentCompletions("execute ")).resolves.toBeNull();
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `npx vitest run tests/extension/workflow-monitor/workflow-next-command.test.ts -t "implementation artifacts for execute and finalize"`
+Expected: FAIL because only `plan` artifact completion exists and `execute`/`finalize` still return `null`.
+
+**Step 3: Write minimal implementation**
+
+```ts
+const ARTIFACT_SUFFIX_BY_PHASE = {
+  brainstorm: null,
+  plan: "-design.md",
+  execute: "-implementation.md",
+  finalize: "-implementation.md",
+} as const;
+
+function listArtifactsForPhase(phase: keyof typeof ARTIFACT_SUFFIX_BY_PHASE, typedPrefix: string) {
+  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: relPath, label: relPath }));
+
+    return items.length > 0 ? items : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function getWorkflowNextCompletions(prefix: string): Promise<AutocompleteItem[] | null> {
+  // keep task-1 phase completion logic for empty / partial / invalid first tokens
+  // switch to artifact mode only after an exact valid phase plus second-arg context
+  if (phaseIsExactlyValid && startingSecondArg) {
+    return listArtifactsForPhase(phase, artifactPrefix);
+  }
+
+  return phaseSuggestionsOrNull;
+}
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `npx vitest run tests/extension/workflow-monitor/workflow-next-command.test.ts`
+Expected: PASS for all `/workflow-next` tests, including kickoff behavior, invalid-phase validation, phase autocomplete, artifact autocomplete, and quiet-null cases.
+
+Then run: `npm test`
+Expected: PASS across the full Vitest suite with no regressions in the workflow monitor extension.
+
+**Step 5: Commit**
+
+```bash
+git add tests/extension/workflow-monitor/workflow-next-command.test.ts extensions/workflow-monitor/workflow-next-completions.ts
+git commit -m "feat: finish workflow-next artifact autocomplete"
+```

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.