@tianhai/pi-workflow-kit 0.5.1 → 0.6.0

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

@@ -1,334 +0,0 @@
-# /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

@@ -1,251 +0,0 @@
-# /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.