@tianhai/pi-workflow-kit 0.4.1 → 0.5.0

package/README.md

@@ -90,7 +90,7 @@ No configuration required after install. Skills and extensions activate automati
 
 ## Upgrading from `pi-superpowers`
 
-If you're currently using [`pi-superpowers`](https://github.com/coctostan/pi-superpowers), `@tianhai/pi-workflow-kit` is intended as a drop-in upgrade: you keep the same skill names and workflow, but you also get **active, runtime enforcement** via extensions.
+If you're currently using `pi-superpowers`, `@tianhai/pi-workflow-kit` is intended as a drop-in upgrade: you keep the same skill names and workflow, but you also get **active, runtime enforcement** via extensions.
 
 ### What stays the same
 - The same core workflow skills (e.g. `/skill:brainstorming`, `/skill:writing-plans`, `/skill:executing-tasks`, etc.)
@@ -232,7 +232,8 @@ At phase boundaries, prompts the agent once (non-enforcing) with options:
 
 When transitioning into **finalize**, the monitor pre-fills the editor with a reminder to consider documentation updates and to capture learnings before merging/shipping.
 
-The `/workflow-next` command starts a new session with artifact context:
+The `/workflow-next` command starts a new session with artifact context and enforces immediate-next-only handoff:
+
 ```
 /workflow-next plan docs/plans/2026-02-10-my-feature-design.md
 /workflow-next execute docs/plans/2026-02-11-my-feature-implementation.md
@@ -241,6 +242,13 @@ The `/workflow-next` command starts a new session with artifact context:
 
 Valid phases: `brainstorm`, `plan`, `execute`, `finalize`.
 
+Handoff rules:
+- Only the **immediate next** phase is allowed (e.g. `plan → execute`, `execute → finalize`).
+- The current phase must be **complete** before handing off.
+- Same-phase, backward, and direct-jump transitions are rejected.
+- Prior completed phases, artifacts, and prompted flags are **preserved** in the new session.
+- TDD, debug, and verification state start **fresh** in the new session.
+
 #### Reference Tool
 
 Serves detailed guidance on demand, keeping skill files lean while making reference content available when the agent needs it:
@@ -306,6 +314,16 @@ A bundled `subagent` tool lets the orchestrating agent spawn isolated subprocess
 
 Agent definitions live in `agents/*.md` and use YAML frontmatter to declare tools, model, extensions, and a system prompt body.
 
+### Model Selection Precedence
+
+When the `subagent` tool launches a child `pi` process, it resolves the model in this order:
+
+1. Agent frontmatter `model:`
+2. The parent session's current provider + model
+3. Bundled fallback `DEFAULT_MODEL`
+
+If a subagent inherits the parent session model, Pi passes both `--provider` and `--model` to the child process to avoid ambiguous cross-provider lookups.
+
 ### Single Agent
 
 ```ts
@@ -350,11 +368,17 @@ extensions: ../extensions/my-guard.ts
 System prompt body here.
 ```
 
+If `model:` is omitted, the agent will inherit the parent session's current model when available, and only fall back to the bundled default if there is no active session model.
+
+### Troubleshooting
+
+If a bundled reviewer or worker unexpectedly asks for the wrong provider credentials, check whether the agent is explicitly pinned with `model:`. Unpinned agents now inherit the parent session's current model, which avoids cases where a non-Anthropic session accidentally launched a Claude-based subagent and failed with an Anthropic API key error.
+
 ## Compared to Superpowers
 
-Based on [Superpowers](https://github.com/obra/superpowers) by Jesse Vincent, ported to pi as [pi-superpowers](https://github.com/coctostan/pi-superpowers), then extended with active enforcement.
+Based on [Superpowers](https://github.com/obra/superpowers) by Jesse Vincent, ported to pi as `pi-superpowers`, then extended with active enforcement.
 
-| | [Superpowers](https://github.com/obra/superpowers) | [pi-superpowers](https://github.com/coctostan/pi-superpowers) | **pi-workflow-kit** |
+| | [Superpowers](https://github.com/obra/superpowers) | `pi-superpowers` | **pi-workflow-kit** |
 |---|---|---|---|
 | **Platform** | Claude Code | pi | pi |
 | **Skills** | 8 workflow skills | Same 12 skills (pi port) → now 8 skills (simplified workflow) | **8 skills** (simplified: 4-phase workflow with unified executing-tasks) |
@@ -485,7 +509,7 @@ pi install npm:@tianhai/pi-workflow-kit
 
 ## Attribution
 
-Skill content adapted from [Superpowers](https://github.com/obra/superpowers) by Jesse Vincent (MIT). This package builds on [pi-superpowers](https://github.com/coctostan/pi-superpowers) with active enforcement extensions, leaner skill files, on-demand reference content, and workflow tracking.
+Skill content adapted from [Superpowers](https://github.com/obra/superpowers) by Jesse Vincent (MIT). This package builds on `pi-superpowers` with active enforcement extensions, leaner skill files, on-demand reference content, and workflow tracking.
 
 ## Migration from `@yinlootan/pi-superpowers-plus`
 

package/docs/developer-usage-guide.md

@@ -120,10 +120,9 @@ Invoke skills directly in the Pi session:
 
 ### Workflow handoff
 
-Start a fresh session for the next phase:
+Start a fresh session for the next phase. `/workflow-next` enforces immediate-next-only transitions and preserves prior completed workflow history (phases, artifacts, prompted flags) across the handoff:
 
 ```text
-/workflow-next brainstorm
 /workflow-next plan docs/plans/2026-04-09-feature-design.md
 /workflow-next execute docs/plans/2026-04-09-feature-implementation.md
 /workflow-next finalize docs/plans/2026-04-09-feature-implementation.md
@@ -426,7 +425,7 @@ pi install npm:@tianhai/pi-workflow-kit
 - Let `plan_tracker` reflect the real lifecycle instead of keeping state only in chat
 - Use `subagent(..., agentScope: "both")` when you want bundled agents
 - Treat workflow monitor warnings as signals to correct process, not as noise
-- Use `/workflow-next` when handing off between large phases or sessions
+- Use `/workflow-next` when handing off between sequential workflow phases
 
 ## Common mistakes to avoid
 
@@ -439,7 +438,7 @@ pi install npm:@tianhai/pi-workflow-kit
 
 ## Migration note
 
-If you previously installed `@yinlootan/pi-superpowers-plus`, replace it with:
+If you previously installed `@yinlootan/pi-superpowers-plus`, replace it with `@tianhai/pi-workflow-kit`:
 
 ```json
 {

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

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

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"
+```