@tianhai/pi-workflow-kit 0.5.1 → 0.6.0

package/ROADMAP.md

@@ -1,16 +0,0 @@
-# Roadmap
-
-Short-term priorities for `pi-workflow-kit`:
-
-- keep the simplified 4-phase workflow coherent across skills, extensions, and docs
-- improve `executing-tasks` ergonomics for real feature delivery
-- continue tightening workflow-monitor tests around phase transitions and handoffs
-- improve README and reference docs so package behavior is easy to trust
-- expand examples for non-code tasks and finalize flows
-
-Longer-term possibilities:
-
-- richer plan parsing helpers for typed task extraction
-- deeper TUI support for active-task detail
-- more bundled subagents for targeted review and maintenance tasks
-- optional reporting/export of workflow state

package/agents/code-reviewer.md

@@ -1,18 +0,0 @@
----
-name: code-reviewer
-description: "Production readiness review: quality, security, testing (read-only)"
-tools: read, bash, find, grep, ls
----
-
-You are a code quality reviewer.
-
-Review for:
-- correctness, error handling
-- maintainability
-- security and footguns
-- test coverage quality
-
-Return:
-- Strengths
-- Issues (Critical/Important/Minor)
-- Clear verdict (ready or not)

package/agents/config.ts

@@ -1,5 +0,0 @@
-/**
- * Canonical model configuration for bundled agents.
- * Change this one constant to update the default model for all bundled agents.
- */
-export const DEFAULT_MODEL = "claude-sonnet-4-5";

package/agents/implementer.md

@@ -1,26 +0,0 @@
----
-name: implementer
-description: Implement tasks via TDD and commit small changes
-tools: read, write, edit, bash, plan_tracker, workflow_reference
-extensions: ../extensions/workflow-monitor, ../extensions/plan-tracker
----
-
-You are an implementation subagent.
-
-## TDD Approach
-
-Determine which scenario applies before writing code:
-
-**New files / new features:** Full TDD. Write a failing test first, verify it fails, implement minimal code to pass, refactor.
-
-**Modifying code with existing tests:** Run existing tests first to confirm green. Make your change. Run tests again. If the change isn't covered by existing tests, add a test. If it is, you're done.
-
-**Trivial changes (typo, config, rename):** Use judgment. Run relevant tests after if they exist.
-
-**If you see a ⚠️ TDD warning:** Pause. Consider which scenario applies. If existing tests cover your change, run them and proceed. If not, write a test first.
-
-## Rules
-- Keep changes minimal and scoped to the task.
-- Run the narrowest test(s) first, then the full suite when appropriate.
-- Commit when the task's tests pass.
-- Report: what changed, tests run, files changed, any concerns.

package/agents/spec-reviewer.md

@@ -1,13 +0,0 @@
----
-name: spec-reviewer
-description: Verify implementation matches the plan/spec (read-only)
-tools: read, bash, find, grep, ls
----
-
-You are a spec compliance reviewer.
-
-Check the implementation against the provided requirements.
-- Identify missing requirements.
-- Identify scope creep / unrequested changes.
-- Point to exact files/lines and provide concrete fixes.
-Return a clear verdict: ✅ compliant / ❌ not compliant.

package/agents/worker.md

@@ -1,17 +0,0 @@
----
-name: worker
-description: General-purpose worker for isolated tasks
-tools: read, write, edit, bash, plan_tracker, workflow_reference
-extensions: ../extensions/workflow-monitor, ../extensions/plan-tracker
----
-
-You are a general-purpose subagent. Follow the task exactly.
-
-## TDD (when changing production code)
-
-- New files: write a failing test first, then implement.
-- Modifying existing code: run existing tests first, make your change, run again. Add tests if not covered.
-- Trivial changes: run relevant tests after if they exist.
-- If you see a ⚠️ TDD warning, pause and decide which scenario applies before proceeding.
-
-Prefer small, test-backed changes.

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

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

@@ -1,196 +0,0 @@
-# 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/docs/plans/completed/2026-04-09-workflow-next-autocomplete-design.md

@@ -1,185 +0,0 @@
-# /workflow-next Autocomplete Design
-
-Date: 2026-04-09
-
-## Summary
-
-Add argument autocomplete to the `/workflow-next` extension command so the workflow phase is easier to enter and the optional artifact argument is easier to discover.
-
-The command should support:
-- phase autocomplete for `brainstorm`, `plan`, `execute`, and `finalize`
-- workflow-aware artifact suggestions after a valid phase is entered
-- strict phase-to-artifact mapping:
-  - `plan` → `docs/plans/*-design.md`
-  - `execute` → `docs/plans/*-implementation.md`
-  - `finalize` → `docs/plans/*-implementation.md`
-  - `brainstorm` → no artifact suggestions
-
-This is a UX-only improvement. It must not change workflow tracking, session creation, or `/workflow-next` validation behavior.
-
-## Goals
-
-- Make `/workflow-next` faster and less error-prone to use
-- Surface valid workflow phases directly in slash-command autocomplete
-- Suggest likely plan artifacts without requiring users to remember exact filenames
-- Keep runtime behavior unchanged outside command completion
-
-## Non-goals
-
-- Infer suggestions from workflow tracker state
-- Change `/workflow-next` command semantics or validation
-- Add artifact suggestions for `brainstorm`
-- Implement broad filesystem completion beyond workflow-specific plan artifacts
-
-## Recommended Approach
-
-Keep command registration in `extensions/workflow-monitor.ts`, but extract completion logic into a focused helper module, e.g.:
-
-- `extensions/workflow-monitor/workflow-next-completions.ts`
-
-This helper should be stateless and filesystem-based. It should accept the raw argument prefix and return command completion items using pi's `getArgumentCompletions` hook.
-
-This keeps the command registration simple while making the completion logic independently testable and easier to maintain than inline logic inside the already-large workflow monitor extension.
-
-## Architecture
-
-### Command registration
-
-The existing `/workflow-next` command remains the single public entry point.
-
-Enhance its registration with `getArgumentCompletions(prefix)`.
-
-Responsibilities stay split as follows:
-- `handler(args, ctx)` remains the source of truth for execution and validation
-- `getArgumentCompletions(prefix)` provides UX hints only
-- completion helper handles parsing, matching, and file discovery
-
-### Completion helper
-
-The helper module should expose a small API, such as:
-- a list of valid workflow phases
-- a function that returns completion items for a raw argument prefix
-
-Internally it should:
-1. determine whether the user is completing the first argument or second argument
-2. return filtered phase suggestions when completing the first argument
-3. after an exact valid phase is present, return artifact suggestions based on strict phase mapping
-4. return `null` when no suggestions are appropriate
-
-## Components
-
-### 1. Phase completion
-
-Supported phases:
-- `brainstorm`
-- `plan`
-- `execute`
-- `finalize`
-
-Behavior:
-- empty prefix returns all phases
-- partial first token returns phases filtered by prefix
-- invalid first token still returns matching phase suggestions when possible
-- phase completion applies only to the first argument
-
-### 2. Artifact completion
-
-Artifact suggestions activate only after the first token exactly matches a valid phase and the user begins the second argument.
-
-Strict mapping:
-- `plan` → only files under `docs/plans/` ending in `-design.md`
-- `execute` → only files under `docs/plans/` ending in `-implementation.md`
-- `finalize` → only files under `docs/plans/` ending in `-implementation.md`
-- `brainstorm` → no artifact suggestions
-
-Returned suggestions should use relative paths such as:
-- `docs/plans/2026-04-09-feature-design.md`
-- `docs/plans/2026-04-09-feature-implementation.md`
-
-### 3. Filesystem discovery
-
-Artifact completion should scan `docs/plans/` in the current working directory and filter matching filenames by suffix and typed prefix.
-
-The logic should be conservative:
-- if `docs/plans/` does not exist, return `null`
-- if no files match the required suffix, return `null`
-- if a typed artifact prefix narrows the set, return only matching entries
-
-No workflow-state coupling is needed.
-
-## Data flow
-
-1. User types `/workflow-next ...`
-2. pi invokes `getArgumentCompletions(prefix)` for the command
-3. the completion helper parses the raw argument prefix
-4. helper decides between phase mode and artifact mode
-5. helper returns:
-   - phase suggestions, or
-   - matching artifact path suggestions, or
-   - `null`
-6. user selects a suggestion
-7. existing `/workflow-next` handler runs unchanged when the command is submitted
-
-This preserves a clean separation: autocomplete assists input, while the handler remains authoritative for correctness.
-
-## Error handling
-
-The completion path should fail quietly.
-
-Expected behavior:
-- missing `docs/plans/` → no suggestions
-- unreadable directory or filesystem error → no suggestions
-- `brainstorm` second argument → no suggestions
-- invalid phase token → stay in phase suggestion mode instead of trying artifact inference
-
-The command handler should continue to enforce valid usage and show the existing error message for invalid submitted phases.
-
-## Testing strategy
-
-Add focused tests around `/workflow-next` command registration and completion behavior.
-
-Primary test coverage:
-- no args returns all four phases
-- partial phase like `pl` returns `plan`
-- `plan ` suggests only `docs/plans/*-design.md`
-- `execute ` suggests only `docs/plans/*-implementation.md`
-- `finalize ` suggests only `docs/plans/*-implementation.md`
-- `brainstorm ` returns no artifact suggestions
-- artifact prefix filtering works for partial paths
-- invalid first token stays in phase-suggestion mode
-- missing `docs/plans/` returns `null`
-- no matching files returns `null`
-
-Implementation detail for tests:
-- extend `tests/extension/workflow-monitor/workflow-next-command.test.ts`
-- capture the registered command object, not just the handler
-- create temporary `docs/plans/` fixtures in a temp cwd
-- assert returned completion items directly
-
-## Risks and trade-offs
-
-### Chosen trade-off
-
-Use strict workflow-specific suggestions instead of broad generic path completion.
-
-Benefits:
-- better guidance for the intended workflow
-- faster selection of the right artifact files
-- lower cognitive load for users
-
-Cost:
-- more custom logic than plain phase-only completion
-- artifact matching rules must stay aligned with workflow naming conventions
-
-### Why not use workflow state
-
-State-aware suggestions could be smarter, but they would add coupling to session state and create more edge cases. For this improvement, filesystem-based suggestions are sufficient and easier to reason about.
-
-## Acceptance criteria
-
-- `/workflow-next` autocompletes phase names
-- after a valid phase, artifact suggestions follow the strict mapping above
-- suggestions are filtered by the typed prefix
-- `brainstorm` does not suggest artifacts
-- invalid submitted phases are still rejected by the handler
-- existing `/workflow-next` behavior is otherwise unchanged