@selesai/code 0.3.10 → 0.4.0

package/dist/extensions/workflow/extension.ts

@@ -7,10 +7,11 @@ import type { ExtensionAPI } from "@selesai/code";
 import { __resetWorkflowRegistryForTests, createWorkflowExtension } from "./adapter.ts";
 import { prototypeMode } from "./modes/prototype.ts";
 import { quickMode } from "./modes/quick.ts";
+import { taskMode } from "./modes/task.ts";
 
 export { __resetWorkflowRegistryForTests };
 
-const MODES = [prototypeMode, quickMode] as const;
+const MODES = [prototypeMode, quickMode, taskMode] as const;
 
 export default function workflowModesExtension(pi: ExtensionAPI): void {
   for (const mode of MODES) {

package/dist/extensions/workflow/modes/prototype.ts

@@ -120,12 +120,12 @@ Use read to inspect ${artifactDir}/plan.md, ${artifactDir}/handoff.md, ${artifac
 
 Call the subagent tool with { agent: "builder", task: "..." } (do NOT pass a model parameter). Give it plan + handoff + any research/reuse context, tailored to this task. Instruct it to implement every task in plan.md in order. All code changes go in the workspace, never in ${artifactDir}.
 
-After the builder returns, the workflow engine will automatically prompt you to call the commentator. Craft the review task YOURSELF based on what matters for this task. Each commentator review MUST end with exactly one machine-readable line:
+After the builder returns, call the commentator. Craft the review task YOURSELF based on what matters for this task. Each commentator review MUST end with exactly one machine-readable line:
   WORKFLOW_REVIEW_STATUS: clean
   OR
   WORKFLOW_REVIEW_STATUS: blocking
 
-If a review is blocking, the engine prompts you to call the builder again with the issues. This repeats up to ${loopMaxIterations ?? 3} round(s). When a review is clean, the engine writes loop-complete.md and advances to audit. Do NOT write loop-complete.md yourself.`,
+If a review is blocking, call the builder again with the recorded issues. This repeats up to ${loopMaxIterations ?? 3} round(s). When a review is clean, the engine writes loop-complete.md and advances to audit. Do NOT write loop-complete.md yourself.`,
   audit: ({ artifactDir }) =>
     `You are in the AUDIT (review) phase.
 
@@ -137,7 +137,7 @@ Review uncommitted changes for correctness, plan adherence, and over-engineering
 2. If ${artifactDir}/review.md lists actionable issues, call the subagent tool with { agent: "builder", task: "..." } (do NOT pass a model parameter). Instruct it to fix every issue in the workspace, never in ${artifactDir}.
 3. Re-dispatch the commentator until ${artifactDir}/review.md ends with WORKFLOW_REVIEW_STATUS: clean.
 
-The workflow closes only once ${artifactDir}/review.md exists AND ends with the WORKFLOW_REVIEW_STATUS: clean marker.`,
+Once ${artifactDir}/review.md exists and ends with the WORKFLOW_REVIEW_STATUS: clean marker, call end_workflow to complete the workflow.`,
 };
 
 const config: WorkflowConfig = {
@@ -171,11 +171,11 @@ const config: WorkflowConfig = {
 
 export const prototypeMode: WorkflowModeRegistration = {
   config,
-  commandName: "prototype",
+  commandName: "workflow-prototype",
   commandDescription:
     "Run the prototype workflow (grill → research → plan → reuse → handoff → loop → audit)",
-  toolNames: { start: "start_workflow", end: "end_workflow" },
-  toolLabels: { start: "Start Workflow", end: "End Workflow" },
+  toolNames: { start: "start_workflow", resume: "resume_workflow", end: "end_workflow" },
+  toolLabels: { start: "Start Workflow", resume: "Resume Workflow", end: "End Workflow" },
 };
 
 export default prototypeMode;

package/dist/extensions/workflow/modes/quick.ts

@@ -103,12 +103,12 @@ Use read to inspect ${artifactDir}/plan.md, ${artifactDir}/handoff.md, and ${art
 
 Call the subagent tool with { agent: "builder", task: "..." } (do NOT pass a model parameter). Give it plan + handoff + reuse context, tailored to this task. Instruct it to implement every task in plan.md in order. All code changes go in the workspace, never in ${artifactDir}.
 
-After the builder returns, the workflow engine will automatically prompt you to call the commentator. Craft the review task YOURSELF. Each commentator review MUST end with exactly one machine-readable line:
+After the builder returns, call the commentator. Craft the review task YOURSELF. Each commentator review MUST end with exactly one machine-readable line:
   WORKFLOW_REVIEW_STATUS: clean
   OR
   WORKFLOW_REVIEW_STATUS: blocking
 
-If a review is blocking, the engine prompts you to call the builder again with the issues. This repeats up to ${loopMaxIterations ?? 3} round(s). When a review is clean, the engine writes loop-complete.md and advances to audit. Do NOT write loop-complete.md yourself.`,
+If a review is blocking, call the builder again with the recorded issues. This repeats up to ${loopMaxIterations ?? 3} round(s). When a review is clean, the engine writes loop-complete.md and advances to audit. Do NOT write loop-complete.md yourself.`,
   audit: ({ artifactDir }) =>
     `You are in the AUDIT (review) phase.
 
@@ -120,7 +120,7 @@ Review uncommitted changes for correctness, plan adherence, and over-engineering
 2. If ${artifactDir}/review.md lists actionable issues, call the subagent tool with { agent: "builder", task: "..." } (do NOT pass a model parameter). Instruct it to fix every issue in the workspace, never in ${artifactDir}.
 3. Re-run the commentator until ${artifactDir}/review.md ends with WORKFLOW_REVIEW_STATUS: clean.
 
-The workflow closes only once ${artifactDir}/review.md exists AND ends with the WORKFLOW_REVIEW_STATUS: clean marker.`,
+Once ${artifactDir}/review.md exists and ends with the WORKFLOW_REVIEW_STATUS: clean marker, call end_quick_workflow to complete the workflow.`,
 };
 
 const config: WorkflowConfig = {
@@ -151,11 +151,11 @@ const config: WorkflowConfig = {
 
 export const quickMode: WorkflowModeRegistration = {
   config,
-  commandName: "quick",
+  commandName: "workflow-quick",
   commandDescription:
     "Run the quick workflow (grill → plan → reuse → handoff → loop → audit)",
-  toolNames: { start: "start_quick_workflow", end: "end_quick_workflow" },
-  toolLabels: { start: "Start Quick Workflow", end: "End Quick Workflow" },
+  toolNames: { start: "start_quick_workflow", resume: "resume_quick_workflow", end: "end_quick_workflow" },
+  toolLabels: { start: "Start Quick Workflow", resume: "Resume Quick Workflow", end: "End Quick Workflow" },
 };
 
 export default quickMode;

package/dist/extensions/workflow/modes/task.ts

@@ -0,0 +1,79 @@
+import type {
+  Phase,
+  PromptContext,
+  WorkflowConfig,
+  WorkflowModeRegistration,
+} from "../state-machine.ts";
+import { loopCompleteValidator, planValidator } from "../validators.ts";
+
+// ponytail: task workflow is only plan → build↔review; the loop's clean marker
+// makes it terminal-ready, and the explicit end tool is the only completion.
+const phases: Phase[] = ["plan", "loop"];
+
+const prompts: Partial<Record<Phase, (ctx: PromptContext) => string>> = {
+  plan: ({ artifactDir, userPrompt }) =>
+    `You are in the PLAN phase of a TASK workflow.
+
+User request:
+${userPrompt}
+
+Produce a concrete implementation plan: what to build, how, in what order, which files, components, and what the finished result looks like.
+
+Call the subagent tool with { agent: "architect", task: "..." } (do NOT pass a model parameter). Craft the task so the architect plans for THIS request. The architect returns the plan; the workflow saves it to ${artifactDir}/plan.md.
+
+The plan MUST end with exactly one machine-readable line on its own:
+  WORKFLOW_PLAN_STATUS: ready
+The workflow will NOT advance until ${artifactDir}/plan.md contains that marker.`,
+  loop: ({ artifactDir, loopMaxIterations }) =>
+    `You are in the LOOP (orchestration) phase of a TASK workflow. The workflow ENGINE owns the implement→review loop — you do NOT track iterations or decide when the loop is clean.
+
+Use read to inspect ${artifactDir}/plan.md. Using that context, GENERATE YOUR OWN delegation prompt:
+
+Call the subagent tool with { agent: "builder", task: "..." } (do NOT pass a model parameter). Give it the plan context, tailored to this task. Instruct it to implement every task in plan.md in order. All code changes go in the workspace, never in ${artifactDir}.
+
+After the builder returns, call the commentator. Craft the review task YOURSELF. Each commentator review MUST end with exactly one machine-readable line:
+  WORKFLOW_REVIEW_STATUS: clean
+  OR
+  WORKFLOW_REVIEW_STATUS: blocking
+
+If a review is blocking, call the builder again with the recorded issues. This repeats up to ${loopMaxIterations ?? 3} round(s). When a review is clean, the engine writes loop-complete.md and the workflow becomes terminal-ready. Do NOT write loop-complete.md yourself. Call end_task_workflow to complete the workflow.`,
+};
+
+const config: WorkflowConfig = {
+  mode: "task",
+  phases,
+  phaseArtifacts: {
+    plan: "plan.md",
+    loop: "loop-complete.md",
+  },
+  prompts,
+  skipRules: [],
+  artifactValidators: {
+    plan: planValidator,
+    loop: loopCompleteValidator,
+  },
+  closeValidators: { "loop-complete.md": loopCompleteValidator },
+  closeArtifacts: ["loop-complete.md"],
+  loopMaxIterations: 3,
+  statusKey: "task",
+  entryType: "task-phase",
+  footerLabel: "task",
+};
+
+export const taskMode: WorkflowModeRegistration = {
+  config,
+  commandName: "workflow-task",
+  commandDescription: "Run the task workflow (plan → build↔review loop)",
+  toolNames: {
+    start: "start_task_workflow",
+    resume: "resume_task_workflow",
+    end: "end_task_workflow",
+  },
+  toolLabels: {
+    start: "Start Task Workflow",
+    resume: "Resume Task Workflow",
+    end: "End Task Workflow",
+  },
+};
+
+export default taskMode;

package/dist/extensions/workflow/run-state.ts

@@ -0,0 +1,124 @@
+import { mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
+import { basename, dirname, relative, resolve } from "node:path";
+import { withFileMutationQueue } from "@selesai/code";
+
+import type { Phase } from "./state-machine.ts";
+
+export const WORKFLOW_STATE_FILENAME = "workflow.json";
+
+export interface LoopState {
+  reviewRound: number;
+  maxIterations: number;
+  stage: "building" | "reviewing" | "clean" | "maxed";
+  reviewPath?: string;
+}
+
+export interface PersistedWorkflowRun {
+  version: 1;
+  id: string;
+  mode: string;
+  status: "active" | "completed";
+  goal: string;
+  artifactDir: string;
+  phase: Phase;
+  autoArmed: boolean;
+  loopState?: LoopState;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export type WorkflowModes = Record<string, readonly Phase[]>;
+export interface ListedWorkflowRun { statePath: string; run: PersistedWorkflowRun }
+
+function isInside(base: string, path: string): boolean {
+  const rel = relative(resolve(base), resolve(path));
+  return rel === "" || (!rel.startsWith("..") && !rel.includes(`..${process.platform === "win32" ? "\\" : "/"}`));
+}
+
+function invalid(message: string): never {
+  throw new Error(`Invalid ${WORKFLOW_STATE_FILENAME}: ${message}`);
+}
+
+function validateLoopState(value: unknown): LoopState | undefined {
+  if (value === undefined) return undefined;
+  if (!value || typeof value !== "object") invalid("loopState must be an object");
+  const loop = value as Record<string, unknown>;
+  if (!Number.isInteger(loop.reviewRound) || (loop.reviewRound as number) < 0) invalid("loopState.reviewRound must be a non-negative integer");
+  if (!Number.isInteger(loop.maxIterations) || (loop.maxIterations as number) < 1) invalid("loopState.maxIterations must be a positive integer");
+  if (!(["building", "reviewing", "clean", "maxed"] as string[]).includes(loop.stage as string)) invalid("loopState.stage is invalid");
+  if (loop.reviewPath !== undefined && (typeof loop.reviewPath !== "string" || !/^loop-review-\d+\.md$/.test(loop.reviewPath))) invalid("loopState.reviewPath is invalid");
+  return loop as unknown as LoopState;
+}
+
+export function validateWorkflowRun(value: unknown, statePath: string, modes: WorkflowModes): PersistedWorkflowRun {
+  if (!value || typeof value !== "object") invalid("record must be an object");
+  const run = value as Record<string, unknown>;
+  if (run.version !== 1) invalid("unsupported version");
+  if (typeof run.id !== "string" || !run.id || run.id !== basename(dirname(resolve(statePath)))) invalid("id must match its containing directory");
+  if (typeof run.mode !== "string" || !modes[run.mode]) invalid("unknown mode");
+  if (run.status !== "active" && run.status !== "completed") invalid("status is invalid");
+  if (typeof run.goal !== "string") invalid("goal must be a string");
+  if (typeof run.artifactDir !== "string" || resolve(run.artifactDir) !== dirname(resolve(statePath))) invalid("artifactDir does not match its containing directory");
+  if (typeof run.phase !== "string" || !modes[run.mode].includes(run.phase)) invalid("phase is not valid for the selected mode");
+  if (typeof run.autoArmed !== "boolean") invalid("autoArmed must be boolean");
+  if (typeof run.createdAt !== "string" || typeof run.updatedAt !== "string") invalid("timestamps must be strings");
+  validateLoopState(run.loopState);
+  return run as unknown as PersistedWorkflowRun;
+}
+
+export async function loadWorkflowRun(statePath: string, modes: WorkflowModes): Promise<PersistedWorkflowRun> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(await readFile(statePath, "utf8"));
+  } catch (error) {
+    throw new Error(`Cannot read ${statePath}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  return validateWorkflowRun(parsed, statePath, modes);
+}
+
+export async function saveWorkflowRun(run: PersistedWorkflowRun): Promise<void> {
+  const statePath = resolve(run.artifactDir, WORKFLOW_STATE_FILENAME);
+  await withFileMutationQueue(statePath, async () => {
+    await mkdir(dirname(statePath), { recursive: true });
+    const tempPath = `${statePath}.${process.pid}.${Date.now()}.tmp`;
+    await writeFile(tempPath, `${JSON.stringify(run, null, 2)}\n`, "utf8");
+    await rename(tempPath, statePath);
+  });
+}
+
+export async function listResumableWorkflowRuns(base: string, modes: WorkflowModes): Promise<ListedWorkflowRun[]> {
+  let entries;
+  try {
+    entries = await readdir(resolve(base), { withFileTypes: true });
+  } catch (error: any) {
+    if (error?.code === "ENOENT") return [];
+    throw error;
+  }
+  const listed: ListedWorkflowRun[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const statePath = resolve(base, entry.name, WORKFLOW_STATE_FILENAME);
+    try {
+      const run = await loadWorkflowRun(statePath, modes);
+      if (run.status === "active") listed.push({ statePath, run });
+    } catch {
+      // A corrupt or unrelated artifact is not a resumable run.
+    }
+  }
+  return listed.sort((a, b) => b.run.updatedAt.localeCompare(a.run.updatedAt));
+}
+
+export async function resolveWorkflowRun(selector: string, base: string, modes: WorkflowModes): Promise<ListedWorkflowRun> {
+  const root = resolve(base);
+  const candidate = resolve(root, selector);
+  if (selector.includes("/") || selector.includes("\\") || selector.endsWith(".json") || selector.startsWith(".")) {
+    if (!isInside(root, candidate)) throw new Error("Workflow run path must be inside the artifacts directory.");
+    const statePath = candidate.endsWith(WORKFLOW_STATE_FILENAME) ? candidate : resolve(candidate, WORKFLOW_STATE_FILENAME);
+    const run = await loadWorkflowRun(statePath, modes);
+    return { statePath, run };
+  }
+  const runs = await listResumableWorkflowRuns(root, modes);
+  const found = runs.find(({ run }) => run.id === selector);
+  if (!found) throw new Error(`No resumable workflow run with id ${selector}.`);
+  return found;
+}

package/dist/extensions/workflow/state-machine.ts

@@ -47,8 +47,8 @@ export interface WorkflowModeRegistration {
   config: WorkflowConfig;
   commandName: string;
   commandDescription: string;
-  toolNames: { start: string; end: string };
-  toolLabels: { start: string; end: string };
+  toolNames: { start: string; resume: string; end: string };
+  toolLabels: { start: string; resume: string; end: string };
 }
 
 export interface WorkflowConfig {
@@ -328,7 +328,7 @@ export class WorkflowStateMachine {
             kind: "terminalNeedsArtifacts",
             phase: this.phase,
             missing: file,
-            promptToQueue: `Terminal phase still needs ${this.artifactDir}/${file}. Write it, then the workflow closes automatically.`,
+            promptToQueue: `Terminal phase still needs ${this.artifactDir}/${file}. Write it, then call the explicit end workflow tool.`, 
           };
         }
         if (sat.reason) {
@@ -337,7 +337,7 @@ export class WorkflowStateMachine {
             phase: this.phase,
             missing: file,
             reason: sat.reason,
-            promptToQueue: `Terminal artifact ${this.artifactDir}/${file} is incomplete: ${sat.reason}. Fix it, then the workflow closes automatically.`,
+            promptToQueue: `Terminal artifact ${this.artifactDir}/${file} is incomplete: ${sat.reason}. Fix it, then call the explicit end workflow tool.`, 
           };
         }
       }
@@ -449,10 +449,6 @@ export class WorkflowStateMachine {
       }
       this.autoArmed = false;
       const out = await this.advancePhase(deps, true);
-      if (out.kind === "terminalReady") {
-        // ponytail: both close artifacts present — close directly.
-        return this.end(deps);
-      }
       if (out.kind === "terminalNeedsArtifacts") {
         // Keep listening: audit/review may land in separate writes.
         this.autoArmed = true;

package/dist/skills/workflow-creation/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: workflow-creation
+description: Creates durable Selesai workflow modes. Use when a user asks to create or change a workflow mode, phased agent flow, or slash-command workflow.
+---
+
+# Durable Workflows
+
+**Durable** means `workflow.json`, not session history, is the run authority. Build on the shared engine in `src/extensions/workflow/`; a mode is configuration, not a second orchestrator.
+
+## 1. Choose the smallest fit
+
+Read `docs/workflows.md`, every file in `src/extensions/workflow/modes/`, and the relevant workflow tests.
+
+- Reuse `prototype`, `quick`, or `task` when its phase graph and terminal gate fit; change only its prompts/configuration.
+- Add a mode only for a materially different graph, artifact contract, or close gate.
+
+Done when the request is mapped to one existing mode or a named new mode with its phase list and terminal artifact.
+
+## 2. Trace the durable seam
+
+Before changing engine-facing behavior, read completely:
+
+- `state-machine.ts` — graph, artifact gates, terminal-ready, completion;
+- `adapter.ts` — tools, event handlers, persistence, reload guards;
+- `run-state.ts` — canonical record and resume validation;
+- `extension.ts` — single extension mounting all modes.
+
+Done when every proposed behavior has one owner: state machine, shared adapter, or mode configuration.
+
+## 3. Implement the mode
+
+For a new mode, add `src/extensions/workflow/modes/<name>.ts`, modeled on `quick.ts`, with only `WorkflowConfig` and `WorkflowModeRegistration`:
+
+- ordered phases, phase artifacts, prompts, validators, close artifacts/validators;
+- unique mode/status/entry identities and start/resume/end tool plus slash-command names;
+- prompts that name exact artifact paths and use `write_workflow_artifact` only for workflow artifacts.
+
+Register the mode once in `MODES` in `extension.ts`; document its lifecycle and commands in `docs/workflows.md`.
+
+Done when the mode file has no filesystem, persistence, event-registration, or controller code.
+
+## 4. Preserve the durable contract
+
+The shared adapter owns UUID artifact directories, atomic saves, resume, loop review state, and reload safety. Do not reimplement them per mode.
+
+- Persisted state changes after start, artifact/loop transition, resume reconciliation, and explicit end.
+- Never auto-resume on `session_start`; an explicit selector attaches a run.
+- Artifact completion advances durable state then stops the parent turn; the user deliberately continues the attached mode.
+- Terminal-ready stays active. Only `end_<mode>_workflow` marks the record completed and terminates.
+- One `ExtensionAPI` hosts all modes: shared writer once, stale reload handlers inert, one attached run total.
+- Builder/reviewer loops use adapter-owned rounds, review files, markers, and max-iteration pause.
+
+Done when the new behavior preserves every applicable invariant above.
+
+## 5. Lock the mode with real seams
+
+Extend the existing fake-Pi tests; do not add another framework. Cover the real mode, not only state-machine units:
+
+- start writes valid `workflow.json`; artifact transition updates it; explicit end completes it;
+- explicit resume reconciles an artifact written before a phase save;
+- loop round/review path resumes when the mode has a loop;
+- terminal-ready does not complete early;
+- extension reload ignores stale handlers; inactive sibling modes do not react.
+
+Run the narrow mode test, then:
+
+```bash
+npx vitest run src/__tests__/state-machine.test.ts src/__tests__/adapter.test.ts src/__tests__/workflow-race.test.ts src/__tests__/workflow-run-state.test.ts src/__tests__/<mode>-workflow.test.ts
+npm run build
+```
+
+Done when those checks pass and the diff contains only the selected mode, shared-engine changes proven necessary by a failing regression, documentation, and tests.

package/docs/workflows.md

@@ -1,6 +1,6 @@
 # Workflows
 
-Selesai ships a workflow engine under `src/extensions/workflow/`. It powers the built-in `prototype` and `quick` workflows and is designed so you can add a new workflow mode as a thin config file — no engine changes.
+Selesai ships a workflow engine under `src/extensions/workflow/`. It powers the built-in `prototype`, `quick`, and `task` workflows and is designed so you can add a new workflow mode as a thin config file — no engine changes.
 
 ## How it fits together
 
@@ -8,15 +8,18 @@ Selesai ships a workflow engine under `src/extensions/workflow/`. It powers the
 src/extensions/workflow/
   package.json          pi package manifest; loads ./extension.ts as the single entry
   state-machine.ts      pure phase state machine (no fs, no pi API)
-  adapter.ts            pi wiring: tools, commands, events, fs, agent continuation
+  adapter.ts            pi wiring: tools, commands, events, fs, durable-state lifecycle
+  run-state.ts          versioned atomic workflow.json load/save/discovery
   extension.ts          single pi extension that mounts every workflow mode
   modes/
     prototype.ts        mode config + registration object (exported as `prototypeMode`)
     quick.ts            mode config + registration object (exported as `quickMode`)
+    task.ts             mode config + registration object (exported as `taskMode`)
 ```
 
 - **`state-machine.ts`** is the deep module. It owns the phase graph, artifact gating, skip rules, the terminal close gate, and the reentrancy guard. It imports nothing external — no `node:fs`, no pi API, no `pi-tui`, no `typebox`. Every method returns a `WorkflowEffect` (a discriminated union in domain vocabulary) that the adapter pattern-matches on.
-- **`adapter.ts`** is the thin glue. One state-machine method per call site (`start` tool, `end` tool, `tool_result` auto-advance, `/<command>`) plus one `applyEffect` switch. It owns all pi/fs wiring and the git-based `reuse` skip predicate. There is no `next` tool — phase advance is automatic once the phase artifact lands, and terminal close is via the `end` tool.
+- **`adapter.ts`** is the thin glue. It owns Pi/fs wiring, durable state, explicit resume, loop review persistence, and the git-based `reuse` skip predicate. An artifact advances durable phase state, then stops at a user-controlled boundary; `/workflow-prototype`, `/workflow-quick`, or `/workflow-task` continues the attached run.
+- **`workflow.json`** in each artifact directory is the canonical, versioned run record. It is atomically replaced after state changes; session custom entries are only pointers for UI/history and never reconstruct an active run.
 - **`extension.ts`** imports each mode's registration object and calls `createWorkflowExtension(config, options)(pi)` for each, so one extension load resolves a single shared writer tool + one start/end tool pair per mode.
 - **A mode file** is pure data: the phase list, the per-phase artifact filenames, the per-phase prompt generators, the terminal close artifacts, and identity strings (tool names, command name, status key, entry type). Prompts are functions that receive `{ artifactDir, userPrompt }` and return a string. Each mode exports a `WorkflowModeRegistration` object (e.g. `prototypeMode`, `quickMode`); it does not call `createWorkflowExtension` itself.
 
@@ -90,10 +93,12 @@ export const rigorousMode: WorkflowModeRegistration = {
     "Run the rigorous workflow (grill → spec → research → plan → reuse → handoff → loop → audit → sign-off)",
   toolNames: {
     start: "start_rigorous_workflow",
+    resume: "resume_rigorous_workflow",
     end: "end_rigorous_workflow",
   },
   toolLabels: {
     start: "Start Rigorous Workflow",
+    resume: "Resume Rigorous Workflow",
     end: "End Rigorous Workflow",
   },
 };
@@ -111,7 +116,21 @@ import { rigorousMode } from "./modes/rigorous.ts";
 const MODES = [prototypeMode, quickMode, rigorousMode] as const;
 ```
 
-That's it. The loader picks it up at boot (`package.json` loads only `./extension.ts`); the two tools (`start_rigorous_workflow`, `end_rigorous_workflow`) and the `/rigorous` command are registered automatically. There is no `next` tool — phases auto-advance as artifacts land and the `end` tool closes the terminal phase.
+That's it. The loader picks it up at boot (`package.json` loads only `./extension.ts`); start/resume/end tools and the `/rigorous` command are registered automatically. There is no `next` tool — phases auto-advance as artifacts land and only the `end` tool completes the terminal phase.
+
+## Built-in modes
+
+### `task` — rapid plan + build/review loop
+
+The simplest workflow: an architect subagent produces a validated `plan.md`, then a builder↔commentator review loop runs (max 3 blocking rounds). A clean review makes the workflow terminal-ready; `end_task_workflow` completes it.
+
+Lifecycle: `plan → loop (build ↔ review) → terminal-ready → end_task_workflow`
+
+- `/workflow-task <goal>` — start a new run
+- `/workflow-task resume` — list and resume active runs
+- `/workflow-task help` — show the lifecycle
+- Phases auto-advance as artifacts land
+- No grilling, research, reuse, or handoff phases
 
 ## Config reference
 
@@ -124,7 +143,7 @@ That's it. The loader picks it up at boot (`package.json` loads only `./extensio
 | `closeArtifacts` | `string[]` | Files that must exist before `end()` succeeds. Config-owned, no built-in default. |
 | `skipRules?` | `{ phase, shouldSkip }[]` | Optional per-phase skip rules. `shouldSkip` is a boolean predicate; when true the engine skips to the next phase. Omit to use the adapter's default (skip `reuse` on empty projects). |
 | `statusKey` | `string` | Footer status key. |
-| `entryType` | `string` | Persisted entry custom-type, used for session resume. |
+| `entryType` | `string` | Session-history custom-type. It stores a pointer only; `workflow.json` is canonical. |
 | `footerLabel` | `string` | Label shown in the footer (`● label · step/total phase`). |
 
 ### Adapter options
@@ -133,11 +152,26 @@ The second argument to `createWorkflowExtension`:
 
 | Field | Description |
 |---|---|
-| `toolNames` | `{ start, end }` — the two registered tool names. There is no `next` tool; phases auto-advance as artifacts land. |
+| `toolNames` | `{ start, resume, end }` — registered tool names. Artifacts advance phase state; the user explicitly continues the attached run. |
 | `toolLabels` | Human-readable labels for the tools. |
 | `commandName` | The `/<command>` name users type to kick off the workflow. |
 | `commandDescription` | Description shown in the command list. |
 
+## Durable runs and explicit resume
+
+Each started workflow receives a UUID artifact directory under `.selesai/artifacts/` and an adjacent `workflow.json`. It stores the mode, phase, armed state, loop round/review path, and timestamps. Writes use a temporary sibling file plus rename, so a crash cannot partially overwrite the canonical record.
+
+Runs are **never** auto-resumed on session start. At most one run can be attached to a Pi instance, but older active runs remain resumable:
+
+- `resume_workflow({ run: "<id-or-path>" })` / `resume_quick_workflow(...)` / `resume_task_workflow(...)`
+- `/workflow-prototype resume <id-or-artifact-dir-or-workflow.json>` / `/workflow-quick resume ...` / `/workflow-task resume ...`
+- `/workflow-prototype resume`, `/workflow-quick resume`, or `/workflow-task resume` lists active runs (and offers a UI picker when available).
+- `/workflow-prototype help`, `/workflow-quick help`, or `/workflow-task help` shows the start, resume, continue, and explicit-completion lifecycle.
+
+Resume validates the selected file is under the artifacts base, belongs to that mode, is active, and matches its containing directory. It reconciles the current expected artifact once before emitting the current prompt, covering a crash after an artifact write but before the phase-state write. Artifact writes do not inject the next phase prompt or launch the next subagent; they terminate the parent turn and wait for the user to continue. Corrupt records are skipped during discovery.
+
+A valid terminal artifact makes a workflow **terminal-ready**; it does not complete the run. Call the mode-specific `end_*_workflow` tool to write `status: "completed"`, append the done entry, and terminate. This is the only completion path.
+
 ## How transitions work
 
 Every state-machine method returns a `WorkflowEffect` — a discriminated union the adapter switches on:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@selesai/code",
-	"version": "0.3.10",
+	"version": "0.4.0",
 	"description": "Selesai coding agent",
 	"type": "module",
 	"piConfig": {