@selesai/code 0.9.13 → 0.9.14

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to `@selesai/code` will be documented in this file.
 
+## [0.9.14] - 2026-08-26
+
+### Changed
+- **Adaptive workflow skill.** Replaced fixed `/workflow-*` commands with the bundled `$workflow` skill, which selects only the required pi-subagents planning, research, writing, review, and fix stages.
+- **Workflow artifacts.** Built-in workflow roles persist named reports for the next stage, while the parent keeps one writer and final acceptance.
+- **Question flexibility.** Select and multi-select questions now permit an Other answer by default; set `allowOther: false` to restrict choices.
+- **Tool bootstrap.** The standard read-only tool catalog activates after the first durable tool call. Preview-export tools remain hidden without disabling Markdown preview rendering.
+
 ## [0.9.13] - 2026-08-26
 
 ### Changed

package/README.md

@@ -60,18 +60,13 @@ Run parallel commentator agents for correctness, tests, and unnecessary complexi
 Have the builder implement this plan, then review the result.
 ```
 
-### Durable workflows
+### Adaptive implementation workflow
 
-Selesai includes a workflow engine with four modes:
+Selesai's `workflow` skill is a parent-directed implementation policy, not a fixed slash-command pipeline. It chooses the smallest useful flow for the task: direct implementation for a trivial change; optional reconnaissance or research for uncertainty; one writer; then only the review, fix, and validation passes the risk warrants.
 
-| Mode | Flow | Best for |
-| --- | --- | --- |
-| `prototype` | grill → research → plan → reuse → handoff → build/review loop → audit | New prototypes that need discovery and external research |
-| `quicktype` | grill → plan → reuse → handoff → build/review loop → audit | Quicker prototype: same flow without research |
-| `task` | plan → reuse → handoff → build/review loop | Direct implementation work |
-| `loop` | build/review loop | Work with an already-agreed plan |
+The parent remains the decision-maker and keeps one writer per checkout. Reviewers inspect the shared working-tree diff directly, while the parent selectively passes synthesized findings to a scoped fix worker. A handoff artifact is optional—use one only for cross-session continuity, a milestone boundary, or a durable user-facing record.
 
-Workflows persist their state and phase artifacts on disk, can be resumed explicitly, and require an explicit close step. Users start and resume them directly with `/workflow-prototype`, `/workflow-quicktype`, `/workflow-task`, or `/workflow-loop`; the agent cannot initiate a workflow.
+Invoke it inline with `$workflow`, or ask Selesai to orchestrate an implementation. Material architecture or product decisions are resolved before implementation, using an oracle or Council Mode when appropriate.
 
 ### Web research
 
@@ -140,7 +135,7 @@ Skills are shipped with Selesai and loaded at boot. They include:
 - `handoff` and `handoff-text` for session continuity
 - `improve-codebase` for architecture and maintainability reviews
 - `ponytail-review`, `ponytail-audit`, `ponytail-gain`, `ponytail-debt`, and `ponytail-help`
-- `workflow-creation` for building durable workflow modes
+- `workflow` for adaptive implementation orchestration
 
 Invoke one inline with `$skill-name` (for example, `$grill-me`).
 

package/dist/extensions/enable-readonly-tools.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it, vi } from "vitest";
+
+const { createFindToolDefinition, createGrepToolDefinition, createLsToolDefinition } = vi.hoisted(() => ({
+	createFindToolDefinition: vi.fn(() => ({ name: "find" })),
+	createGrepToolDefinition: vi.fn(() => ({ name: "grep" })),
+	createLsToolDefinition: vi.fn(() => ({ name: "ls" })),
+}));
+
+vi.mock("@selesai/code", () => ({
+	createFindToolDefinition,
+	createGrepToolDefinition,
+	createLsToolDefinition,
+}));
+
+import enableReadonlyTools from "./enable-readonly-tools.ts";
+
+function setup() {
+	let handler!: (event: { toolName: string; isError: boolean }, ctx: { cwd: string }) => void;
+	const active = new Set(["read", "bash", "edit", "write"]);
+	const pi = {
+		on: vi.fn((_event: string, registeredHandler: typeof handler) => {
+			handler = registeredHandler;
+		}),
+		registerTool: vi.fn((tool: { name: string }) => active.add(tool.name)),
+	};
+	enableReadonlyTools(pi as any);
+	return { active, handler, pi };
+}
+
+describe("enable-readonly-tools", () => {
+	it("does not activate readonly tools after failed or unrelated calls", () => {
+		const { active, handler, pi } = setup();
+
+		handler({ toolName: "read", isError: true }, { cwd: "/project" });
+		handler({ toolName: "extension-tool", isError: false }, { cwd: "/project" });
+
+		expect(pi.registerTool).not.toHaveBeenCalled();
+		expect([...active]).toEqual(["read", "bash", "edit", "write"]);
+	});
+
+	it.each(["read", "bash", "edit", "write"])("activates once after a successful %s call", (toolName) => {
+		const { active, handler, pi } = setup();
+
+		handler({ toolName, isError: false }, { cwd: "/project" });
+		expect(pi.registerTool).toHaveBeenCalledTimes(3);
+		expect([...active]).toEqual(["read", "bash", "edit", "write", "grep", "find", "ls"]);
+
+		handler({ toolName: "bash", isError: false }, { cwd: "/other" });
+		expect(pi.registerTool).toHaveBeenCalledTimes(3);
+		expect(createGrepToolDefinition).toHaveBeenCalledWith("/project");
+	});
+});

package/dist/extensions/enable-readonly-tools.ts

@@ -0,0 +1,20 @@
+import {
+	createFindToolDefinition,
+	createGrepToolDefinition,
+	createLsToolDefinition,
+	type ExtensionAPI,
+} from "@selesai/code";
+
+const bootstrapTools = new Set(["read", "bash", "edit", "write"]);
+
+export default function (pi: ExtensionAPI) {
+	let enabled = false;
+
+	pi.on("tool_execution_end", (event, ctx) => {
+		if (enabled || event.isError || !bootstrapTools.has(event.toolName)) return;
+		enabled = true;
+		pi.registerTool(createGrepToolDefinition(ctx.cwd));
+		pi.registerTool(createFindToolDefinition(ctx.cwd));
+		pi.registerTool(createLsToolDefinition(ctx.cwd));
+	});
+}

package/dist/extensions/package.json

@@ -8,6 +8,8 @@
 			"./agent-browser.ts",
 		"./copy-turn.ts",
 			"./context-compaction-reminder.ts",
+			"./enable-readonly-tools.ts",
+			"./preview-tools-disabled.ts",
 			"./pi-intercom/index.ts",
 			"./ponytail/index.js",
 			"./question",
@@ -18,7 +20,6 @@
 			"./rtk.ts",
 			"./tokenin-onboarding.ts",
 			"./undo.ts",
-			"./workflow",
 			"./pi-subagents",
 			"./pi-web-agent",
 			"./web-agent-onboarding.ts",

package/dist/extensions/pi-powerline-footer/guide.ts

@@ -26,25 +26,11 @@ export interface GuidePreferencesUpdate {
 // or prompt from the root README without reproducing the README in the overlay.
 export const GUIDE_FEATURES: readonly GuideFeature[] = [
   {
-    id: "workflow-task",
+    id: "workflow",
     section: "Start here",
-    title: "Task",
-    example: '/workflow-task "<goal>"',
-    introducedIn: "0.5.13",
-  },
-  {
-    id: "workflow-quicktype",
-    section: "Start here",
-    title: "Quicktype",
-    example: '/workflow-quicktype "<goal>"',
-    introducedIn: "0.5.13",
-  },
-  {
-    id: "workflow-prototype",
-    section: "Start here",
-    title: "Prototype",
-    example: '/workflow-prototype "<goal>"',
-    introducedIn: "0.5.13",
+    title: "Workflow",
+    example: '"Use $workflow to orchestrate this implementation."',
+    introducedIn: "0.9.14",
   },
   {
     id: "settings",
@@ -101,8 +87,7 @@ export const GUIDE_DISMISS_HINT = "Press any key to continue";
 
 export const GUIDE_COMPACT_LINES = [
   "/guide full · /settings",
-  '/workflow-task "<goal>" · /workflow-quicktype "<goal>"',
-  '/workflow-prototype "<goal>"',
+  '"Use $workflow to orchestrate this implementation."',
   '"Ask the researcher to research <topic>."',
   "/skill:* · /undo · /handoff-new <next focus>",
 ] as const;

package/dist/extensions/pi-powerline-footer/tests/guide.test.ts

@@ -49,15 +49,14 @@ test("full and compact guide content expose README commands and examples", () =>
   const compact = GUIDE_COMPACT_LINES.join("\n");
 
   assert.match(full, /\/settings/);
-  assert.match(full, /\/workflow-task/);
-  assert.match(full, /\/workflow-prototype/);
+  assert.match(full, /\$workflow/);
   assert.match(full, /Ask the architect to challenge this plan/);
   assert.match(full, /Ask the researcher to research <topic> and cite sources/);
   assert.match(full, /\/skill:\*/);
   assert.match(full, /\/handoff-new Next: fix <problem>; start with a coding plan/);
   assert.doesNotMatch(full, /question\(|\/intercom|powerline/);
   assert.match(compact, /\/settings/);
-  assert.match(compact, /\/workflow-task/);
+  assert.match(compact, /\$workflow/);
   assert.match(compact, /Ask the researcher to research <topic>/);
 });
 

package/dist/extensions/pi-subagents/agents/architect.md

@@ -8,6 +8,7 @@ inheritProjectContext: true
 inheritSkills: false
 skill: ponytail, planger
 defaultContext: fork
+output: plan.md
 ---
 
 ## Goal
@@ -20,7 +21,7 @@ Create implementation plans that can be executed by a small coding model with:
 - Weak architectural understanding
 - No ability to infer missing steps
 
-Assume the executor only knows what is written in the plan. Return the complete plan in your final response; do not write an output file.
+Assume the executor only knows what is written in the plan. Return the complete plan in your final response. The runtime persists it as `plan.md` so the next workflow stage can read it.
 
 # Core Principles
 

package/dist/extensions/pi-subagents/agents/builder.md

@@ -9,9 +9,11 @@ inheritSkills: false
 skill: ponytail, implanger
 inheritProjectContext: true
 defaultContext: fresh
+output: implementation.md
+defaultReads: context.md, research.md, plan.md, implementation.md, review.md
 ---
 
-You are `builder`, the sole writer for the delegated task. The main agent and user remain the decision authority.
+You are `builder`, the sole writer for the delegated task. The main agent and user remain the decision authority. The runtime persists your final report as `implementation.md` for review and fix stages.
 
 Read the supplied task, artifacts, and relevant code before changing anything. Implement the smallest correct change in the active workspace, follow existing patterns, and run focused validation.
 

package/dist/extensions/pi-subagents/agents/commentator.md

@@ -8,11 +8,13 @@ inheritProjectContext: true
 inheritSkills: false
 defaultContext: fresh
 skill: ponytail, planger
+output: review.md
+defaultReads: context.md, research.md, plan.md, implementation.md
 completionGuard: false
 acceptanceRole: read-only
 ---
 
-You are a review-only subagent. Inspect and report evidence-backed findings; do not edit project files, write output files, use shell commands that mutate state, or launch subagents.
+You are a review-only subagent. Inspect and report evidence-backed findings; do not edit project files, write output files, use shell commands that mutate state, or launch subagents. The runtime persists your final report as `review.md` for a scoped fix stage.
 
 Review the supplied target directly. If the task names a progress file, read it first and scope your review to its latest round entry: inspect the diff restricted to the files that entry lists (`git diff -- <files>`). Older entries are already reviewed—re-inspect only files the latest entry repeats. If no progress file is named, or it is missing or empty, review the full uncommitted diff. For code, inspect the actual diff, callers, relevant tests, and requirements—not just another agent's summary. Use `bash` only for read-only inspection or test commands.
 

package/dist/extensions/pi-subagents/agents/explorer.md

@@ -7,10 +7,11 @@ inheritProjectContext: true
 inheritSkills: false
 skill: ponytail
 defaultContext: fresh
+output: context.md
 acceptanceRole: read-only
 ---
 
-You are a codebase reconnaissance subagent. Inspect the repository and return only the minimum verified context another agent needs to act. Do not edit project files, write output files, or launch subagents.
+You are a codebase reconnaissance subagent. Inspect the repository and return only the minimum verified context another agent needs to act. Do not edit project files or launch subagents. The runtime persists your final response as `context.md` for the next stage.
 
 Use targeted `grep`, `find`, `ls`, and `read`. Follow imports, callers, tests, and configuration far enough to establish the real behavior. Do not guess.
 

package/dist/extensions/pi-subagents/agents/recapper.md

@@ -7,10 +7,11 @@ inheritProjectContext: true
 inheritSkills: false
 skill: ponytail
 defaultContext: fork
+output: handoff.md
 acceptanceRole: read-only
 ---
 
-Create a concise, self-contained handoff for a fresh agent. Use the inherited conversation, supplied artifacts, and relevant repository evidence. Do not edit project files, write output files, or launch subagents.
+Create a concise, self-contained handoff for a fresh agent. Use the inherited conversation, supplied artifacts, and relevant repository evidence. Do not edit project files or launch subagents. The runtime persists your final response as `handoff.md`.
 
 Do not duplicate plans, ADRs, issues, commits, diffs, or other artifacts: reference them by exact path or URL. Redact secrets and personal data. If the task names a next focus, tailor the handoff to it.
 

package/dist/extensions/pi-subagents/agents/researcher.md

@@ -12,7 +12,7 @@ defaultProgress: true
 
 You are a research subagent.
 
-Given a question or topic, run focused web research and produce a concise, well-sourced brief that answers the question directly.
+Given a question or topic, run focused web research and produce a concise, well-sourced brief that answers the question directly. The runtime persists the final response as `research.md` for the next stage.
 
 Working rules:
 - Break the problem into 2-4 distinct research angles.

package/dist/extensions/pi-subagents/agents/reviewer.md

@@ -6,9 +6,11 @@ thinking: high
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: false
+output: review.md
+defaultReads: context.md, research.md, plan.md, implementation.md
 ---
 
-You are a disciplined review subagent. Your job is to inspect, evaluate, and report findings with evidence. You do not guess; you verify from the code, tests, docs, or requirements.
+You are a disciplined review subagent. Your job is to inspect, evaluate, and report findings with evidence. You do not guess; you verify from the code, tests, docs, or requirements. The runtime persists your final report as `review.md` for a scoped fix stage.
 
 ## Review types you handle
 

package/dist/extensions/pi-subagents/agents/worker.md

@@ -8,7 +8,8 @@ inheritProjectContext: true
 inheritSkills: false
 tools: read, grep, find, ls, bash, edit, write, contact_supervisor
 defaultContext: fork
-defaultReads: context.md, plan.md
+output: implementation.md
+defaultReads: context.md, research.md, plan.md, implementation.md, review.md
 defaultProgress: true
 ---
 

package/dist/extensions/preview-tools-disabled.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it, vi } from "vitest";
+
+import disablePreviewTools from "./preview-tools-disabled.ts";
+
+function setup(active: string[]) {
+	let handler!: () => void;
+	const getActiveTools = vi.fn(() => active);
+	const setActiveTools = vi.fn();
+	const pi = {
+		on: vi.fn((_event: string, registeredHandler: () => void) => {
+			handler = registeredHandler;
+		}),
+		getActiveTools,
+		setActiveTools,
+	};
+	disablePreviewTools(pi as any);
+	return { handler, getActiveTools, setActiveTools };
+}
+
+describe("preview-tools-disabled", () => {
+	it("keeps a session without preview_export unchanged", () => {
+		const { handler, getActiveTools, setActiveTools } = setup(["read", "bash", "edit", "write"]);
+
+		handler();
+
+		expect(getActiveTools).toHaveBeenCalledTimes(1);
+		expect(setActiveTools).not.toHaveBeenCalled();
+	});
+
+	it("removes preview_export and keeps every other active tool", () => {
+		const { handler, setActiveTools } = setup(["read", "bash", "edit", "write", "preview_export", "web_explore"]);
+
+		handler();
+
+		expect(setActiveTools).toHaveBeenCalledWith(["read", "bash", "edit", "write", "web_explore"]);
+	});
+});

package/dist/extensions/preview-tools-disabled.ts

@@ -0,0 +1,11 @@
+import type { ExtensionAPI } from "@selesai/code";
+
+const DISABLED_TOOL_NAMES = new Set(["preview_export"]);
+
+export default function (pi: ExtensionAPI) {
+	pi.on("session_start", () => {
+		const active = pi.getActiveTools();
+		const next = active.filter((name) => !DISABLED_TOOL_NAMES.has(name));
+		if (next.length !== active.length) pi.setActiveTools(next);
+	});
+}

package/dist/extensions/question/batch.ts

@@ -70,7 +70,7 @@ export function prepareQuestions(value: unknown): { questions: PreparedQuestion[
 			...common,
 			type: raw.type,
 			options: preparedOptions.options,
-			allowOther: raw.allowOther ?? false,
+			allowOther: raw.allowOther ?? true,
 		});
 	}
 	return { questions };

package/dist/extensions/question/schemas.ts

@@ -20,14 +20,14 @@ const SelectQuestionSchema = Type.Object({
 	...QuestionBase,
 	type: StringEnum(["select"] as const),
 	options: Type.Array(OptionSchema, { minItems: 1, description: "Available choices" }),
-	allowOther: Type.Optional(Type.Boolean({ description: "Allow a custom Other text answer" })),
+	allowOther: Type.Optional(Type.Boolean({ description: "Allow a custom Other text answer (default: true)" })),
 }, { additionalProperties: false });
 
 const MultiSelectQuestionSchema = Type.Object({
 	...QuestionBase,
 	type: StringEnum(["multiselect"] as const),
 	options: Type.Array(OptionSchema, { minItems: 1, description: "Available choices" }),
-	allowOther: Type.Optional(Type.Boolean({ description: "Allow custom Other text alongside selected values" })),
+	allowOther: Type.Optional(Type.Boolean({ description: "Allow custom Other text alongside selected values (default: true)" })),
 }, { additionalProperties: false });
 
 const TextQuestionSchema = Type.Object({

package/dist/extensions/question/tests/batch.test.ts

@@ -22,7 +22,7 @@ describe("question batch helpers", () => {
 					{ value: "red", label: "Red", description: undefined },
 					{ value: "blue", label: "Blue", description: undefined },
 				],
-				allowOther: false,
+				allowOther: true,
 			},
 			{
 				id: "notes",
@@ -70,7 +70,7 @@ describe("question batch helpers", () => {
 			context: "ctx",
 			type: "multiselect",
 			options: [{ value: "a", label: "A", description: "desc" }],
-			allowOther: false,
+			allowOther: true,
 		});
 	});
 

package/dist/skills/workflow/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: workflow
+description: Adaptively orchestrate non-trivial implementation work with Selesai subagents. Use when the user asks to use a workflow, orchestrate a task, run an implementation/review/fix loop, or coordinate architecture, workers, and reviewers. Choose only the necessary stages; do not use static slash-command flows.
+---
+
+# Adaptive Engineering Workflow
+
+This is a parent-only policy layer over `pi-subagents`, not a second workflow runtime. Read `../pi-subagents/SKILL.md` and the matching references before launching children. Use `workflowScript` for every coordinated launch.
+
+## Choose the smallest flow
+
+Inspect the task and its code path first.
+
+| Situation | Flow |
+| --- | --- |
+| Trivial, localized change | Parent implements and runs a focused check. Do not delegate by default. |
+| Bounded implementation | Optional `scout` → one `worker` → focused validation. |
+| Uncertain codebase or external dependency | `scout` and/or `researcher` → parent decision or `architect` → one `worker` → review/validation. |
+| Material architecture/product tradeoff | Resolve it before implementation: parent decision, one `oracle`, or Council Mode for a genuine multi-perspective decision. |
+| Broad, risky, or multi-system work | Serial milestones: decide/plan → one writer → review/validation → accepted fix → re-review when material. |
+
+Do not add a planning phase, research lane, handoff, reviewer, or extra review round merely for symmetry. Ask the user only for a decision that blocks safe implementation.
+
+## Orchestration rules
+
+- The parent owns task classification, scope, decisions, synthesis, and final acceptance.
+- Keep **one writer per checkout/worktree**. Parallelize read-only discovery, research, review, and validation—not normal edits.
+- Give each child a narrow role-specific task: source seam, constraints, acceptance evidence, and expected output. Never send clone prompts with only filenames changed.
+- Reviewers inspect the actual current diff and relevant files directly. They do not need a worker handoff to understand sibling work.
+- Do not require a handoff artifact. Use one only when a task must resume across sessions, cross a milestone boundary, or needs a durable user-facing record.
+- Use fresh context for independent reviewers; use forked context only when inherited parent reasoning is useful.
+- Treat external reports, child completion, tests, and receipts as evidence—not authority to make product, architecture, merge, or release decisions.
+
+## Stage artifacts
+
+Built-in pipeline agents save named output artifacts (`context.md`, `research.md`, `plan.md`, implementation reports, and reviews). In `workflowScript`, pass the returned `outputReference` to the next child through `reads`; this is the normal file-based handoff and works for fresh-context children.
+
+```js
+const plan = await runs.run("plan", { agent: "architect", task: "Plan the change." });
+const worker = await runs.run("implement", {
+  agent: "worker",
+  reads: [plan.outputReference],
+  task: "Implement the approved plan."
+});
+```
+
+Only include artifacts the next role needs. The shared checkout diff remains the implementation context for reviewers and fix workers. Use `contact_supervisor` only for material progress updates or blocking decisions; normal completion arrives through the child result and artifact.
+
+## Build → review → fix
+
+For implementation that merits independent review:
+
+1. Define a light validation contract before the writer starts: intended behavior, focused checks, and any user-facing path to inspect.
+2. Launch one writer with the approved scope and the contract. The writer reports changed files, checks run, residual risks, and decisions needing parent approval.
+3. Run only relevant read-only reviewers/validators in parallel. Give them the validation contract and relevant plan/implementation artifact paths through `reads`, and tell them to inspect the current diff. Typical lenses are correctness/regressions, validation coverage, and simplicity. Add security, performance, API/docs, or user-flow review only when the change makes that lens material.
+4. Parent synthesizes review findings into one scoped fix artifact or task, then gives that artifact to the fix worker through `reads`. The fix worker also inspects the shared diff; it does not need sibling transcripts.
+5. Parent classifies findings:
+   - **blocking/actionable in approved scope** → synthesize and send one fix worker;
+   - **optional, speculative, or scope-expanding** → defer or ask the user;
+   - **decision needed** → stop and escalate to the user.
+6. Re-review only after a material fix. Stop when no actionable blockers remain, focused validation is sufficient, an approval is needed, or the review-round cap is reached. Default cap: two review rounds; use three only for risky work.
+7. Parent inspects the final diff and validation evidence before reporting completion.
+
+Use `workflowScript` with top-level `await`, `runs.run` for ordered stages, and `runs.all` for independent read-only fanout. Do not use legacy `chain`/`tasks` fields or nested async functions. Keep async work background by default; do not wait or poll merely to watch it.
+
+## Minimum workflow shape
+
+```js
+const plan = await runs.run("plan", {
+  agent: "architect",
+  task: "Plan the requested change. Return files, implementation order, acceptance checks, and non-goals."
+});
+const worker = await runs.run("implement", {
+  agent: "worker",
+  reads: [plan.outputReference],
+  task: "Implement the approved plan. Return changed files, checks run, residual risks, and decisions needing approval."
+});
+const reviews = await runs.all([
+  { key: "correctness", agent: "reviewer", reads: [plan.outputReference, worker.outputReference], task: "Inspect the current diff for correctness and regressions. Do not edit." },
+  { key: "simplicity", agent: "reviewer", reads: [plan.outputReference, worker.outputReference], task: "Inspect the current diff for unnecessary complexity. Do not edit." }
+]);
+return { plan: plan.outputReference, worker: worker.outputReference, reviews: reviews.map(result => result.outputReference) };
+```
+
+The parent reads and synthesizes that result before launching any fix worker. Pass the synthesized finding list in that fix worker's task. Do not encode an unbounded auto-loop in a slash command or a child prompt.

package/docs/workflows.md

@@ -1,57 +1,18 @@
-# Workflows
+# Adaptive implementation workflow
 
-Selesai's built-in workflows are thin slash-command adapters over the **pi-subagents** orchestration runtime. They do not have a separate state machine, artifact protocol, or `workflow.json` format.
+Selesai uses the built-in [`workflow`](../src/skills/workflow/SKILL.md) skill for implementation orchestration. It is guidance for the parent agent, built on `pi-subagents`' `workflowScript` runtime; it is not a separate extension, slash-command system, or durable workflow engine.
 
-## Run a workflow
+Invoke it inline with `$workflow`, or ask Selesai to orchestrate the implementation.
 
-```text
-/workflow-task <goal>
-/workflow-prototype <goal>
-/workflow-quicktype <goal>
-/workflow-loop <goal>
-```
+## Policy
 
-Each command starts an async pi-subagents mission. Recover a completed, paused, or confusing run with the pi-subagents mission and status controls (`/subagents`, `/subagents-doctor`, or the corresponding `subagent` tool actions); there is no `/workflow-* resume` command.
+The parent first inspects the task and chooses the smallest flow that can safely finish it:
 
-## Built-in modes
+- localized changes stay local or use one worker and focused validation;
+- uncertain code or external dependencies add scoped discovery/research;
+- architecture or product tradeoffs are settled before implementation, with an oracle or Council Mode only when warranted;
+- substantial work uses one writer, independent read-only review/validation, a scoped fix worker for accepted findings, and another review only after material changes.
 
-| Command | Shape |
-| --- | --- |
-| `/workflow-task` | plan → reuse → handoff → build/review/fix loop |
-| `/workflow-prototype` | parallel research + codebase exploration → plan → handoff → build/review/fix loop → audit |
-| `/workflow-quicktype` | plan → reuse → handoff → build/review/fix loop → audit |
-| `/workflow-loop` | direct build/review/fix loop for an already-agreed plan |
+Reviewers inspect the shared checkout's actual diff. Sibling transcripts are not shared automatically, so the parent passes a concise synthesis to a later fix worker. Handoffs are optional and reserved for cross-session continuity, milestone boundaries, or durable records.
 
-The prototype mode uses `runs.all` for its independent research and codebase-exploration work. All modes use `runs.run` for ordered handoffs. The build/review/fix loop uses `workflowScript` because its next step depends on the reviewer result; a blocking review gets a scoped fix round, while `clean` plus no remaining work ends the run.
-
-## Extending workflows
-
-The extension seam is `src/extensions/workflow/modes.ts`.
-
-Add one `WorkflowMode` entry to `WORKFLOW_MODES`:
-
-```ts
-{
-  command: "workflow-rigorous",
-  description: "Run the rigorous workflow.",
-  launch: (goal) => ({
-    workflowScript: `const goal = ${JSON.stringify(goal)};
-return runs.run("plan", { agent: "architect", task: "Plan: " + goal });`,
-  }),
-}
-```
-
-`launch(goal)` returns pi-subagents public execution fields. Prefer the native execution shapes where the mode is static:
-
-- `chain` for a fixed ordered sequence, including human checkpoints.
-- `tasks` for independent, read-only parallel work.
-- `workflowScript` only when the orchestration is conditional, iterative, needs dynamic fan-out, or combines native run operations.
-
-`extension.ts` automatically registers every entry in `WORKFLOW_MODES`; no new command plumbing is needed. The mode owns task wording and execution shape. The extension owns only argument validation, async launch, agent scope, and mission creation.
-
-## Constraints
-
-- `workflowScript`, `chain`, and `tasks` are alternative top-level pi-subagents execution modes. A mode that needs an auto-loop and preceding/following phases should use `workflowScript` and call `runs.run` / `runs.all` within it.
-- Keep one writer at a time. Parallel lanes should be research or review unless they are isolated in worktrees.
-- Workflow progress ledgers are under `.pi-subagents/progress/` and are local runtime artifacts, not durable workflow state.
-- The outer mission and pi-subagents run artifacts are the recovery record.
+`pi-subagents` missions and receipts provide recovery evidence for delegated work. They do not turn a static flow into the source of truth or replace parent acceptance.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@selesai/code",
-	"version": "0.9.13",
+	"version": "0.9.14",
 	"description": "Maintained, extension-first Pi coding agent with built-in workflows, subagents, web research, questions, skills, and an enhanced terminal UI.",
 	"type": "module",
 	"repository": {
@@ -52,13 +52,14 @@
 		"clean": "shx rm -rf dist",
 		"dev": "tsx src/cli.ts",
 		"dev:print": "tsx src/cli.ts --print",
-		"test": "vitest run src/extensions/undo.test.ts src/extensions/custom-provider-ollama/index.test.ts src/extensions/agent-browser.test.ts src/extensions/context-compaction-reminder.test.ts src/extensions/copy-turn.test.ts src/extensions/grep-app/index.test.ts src/extensions/inline-skills.test.ts src/extensions/rtk.test.ts src/extensions/model-prompt-injector/index.test.ts src/extensions/web-agent-onboarding.test.ts src/extensions/handoff-new.test.ts src/extensions/question/tests src/extensions/ponytail/test src/__tests__/tokenin-onboarding.test.ts src/__tests__/workflow-modes.test.ts src/__tests__/model-registry-defaults.test.ts src/cli/args.test.ts",
-		"test:coverage": "vitest run --coverage src/extensions/undo.test.ts src/extensions/custom-provider-ollama/index.test.ts src/extensions/agent-browser.test.ts src/extensions/context-compaction-reminder.test.ts src/extensions/copy-turn.test.ts src/extensions/grep-app/index.test.ts src/extensions/inline-skills.test.ts src/extensions/rtk.test.ts src/extensions/model-prompt-injector/index.test.ts src/extensions/web-agent-onboarding.test.ts src/extensions/handoff-new.test.ts src/extensions/question/tests src/extensions/ponytail/test src/__tests__/tokenin-onboarding.test.ts src/__tests__/workflow-modes.test.ts src/__tests__/model-registry-defaults.test.ts src/cli/args.test.ts",
+		"test": "vitest run src/extensions/undo.test.ts src/extensions/custom-provider-ollama/index.test.ts src/extensions/agent-browser.test.ts src/extensions/context-compaction-reminder.test.ts src/extensions/copy-turn.test.ts src/extensions/grep-app/index.test.ts src/extensions/inline-skills.test.ts src/extensions/rtk.test.ts src/extensions/model-prompt-injector/index.test.ts src/extensions/web-agent-onboarding.test.ts src/extensions/handoff-new.test.ts src/extensions/question/tests src/extensions/ponytail/test src/__tests__/tokenin-onboarding.test.ts src/__tests__/model-registry-defaults.test.ts src/cli/args.test.ts",
+		"test:coverage": "vitest run --coverage src/extensions/undo.test.ts src/extensions/custom-provider-ollama/index.test.ts src/extensions/agent-browser.test.ts src/extensions/context-compaction-reminder.test.ts src/extensions/copy-turn.test.ts src/extensions/grep-app/index.test.ts src/extensions/inline-skills.test.ts src/extensions/rtk.test.ts src/extensions/model-prompt-injector/index.test.ts src/extensions/web-agent-onboarding.test.ts src/extensions/handoff-new.test.ts src/extensions/question/tests src/extensions/ponytail/test src/__tests__/tokenin-onboarding.test.ts src/__tests__/model-registry-defaults.test.ts src/cli/args.test.ts",
 		"prepare": "npm run build",
 		"build": "npm run clean && tsgo -p tsconfig.build.json && shx chmod +x dist/cli.js dist/rpc-entry.js && npm run copy-assets",
 		"copy-assets": "shx mkdir -p dist/modes/interactive/theme && shx cp src/modes/interactive/theme/*.json dist/modes/interactive/theme/ && shx mkdir -p dist/modes/interactive/assets && shx cp src/modes/interactive/assets/*.png dist/modes/interactive/assets/ && shx mkdir -p dist/core/export-html/vendor && shx cp src/core/export-html/template.html src/core/export-html/template.css src/core/export-html/template.js dist/core/export-html/ && shx cp src/core/export-html/vendor/*.js dist/core/export-html/vendor/ && shx mkdir -p dist/defaults && shx cp src/defaults/* dist/defaults/ && shx mkdir -p dist/extensions && node scripts/copy-extensions.mjs && shx mkdir -p dist/themes && shx cp -r src/themes/. dist/themes/ && shx mkdir -p dist/skills && shx cp -r src/skills/. dist/skills/"
 	},
 	"dependencies": {
+		"acorn": "8.18.0",
 		"@ast-grep/cli": "0.45.0",
 		"@earendil-works/pi-agent-core": "0.84.3",
 		"@earendil-works/pi-ai": "0.84.3",

package/dist/extensions/workflow/extension.ts

@@ -1,26 +0,0 @@
-// ponytail: thin slash-command adapter for the pi-subagents workflow runtime.
-
-import type { ExtensionAPI } from "@selesai/code";
-import { launchSlashSubagent } from "../pi-subagents/src/slash/slash-commands.ts";
-import { WORKFLOW_MODES, type WorkflowMode } from "./modes.ts";
-
-export default function workflowModesExtension(pi: ExtensionAPI): void {
-	const register = (mode: WorkflowMode) => pi.registerCommand(mode.command, {
-		description: mode.description,
-		handler: async (args, ctx) => {
-			const goal = args.trim();
-			if (!goal) {
-				ctx.ui.notify(`${mode.description}\nUsage: /${mode.command} <goal>`, "info");
-				return;
-			}
-			launchSlashSubagent(pi, ctx, {
-				...mode.launch(goal),
-				async: true,
-				agentScope: "both",
-				mission: { title: goal },
-			});
-		},
-	});
-
-	for (const mode of WORKFLOW_MODES) register(mode);
-}

package/dist/extensions/workflow/modes.ts

@@ -1,107 +0,0 @@
-// ponytail: workflow mode registry over pi-subagents' public workflowScript seam.
-// A mode returns launch parameters; the extension owns slash-command plumbing.
-
-import type { SubagentParamsLike } from "../pi-subagents/src/runs/foreground/subagent-executor.ts";
-
-export interface WorkflowMode {
-	command: string;
-	description: string;
-	launch(goal: string): Pick<SubagentParamsLike, "workflowScript" | "chain" | "tasks" | "concurrency">;
-}
-
-function js(value: string): string {
-	return JSON.stringify(value);
-}
-
-// A loop depends on the previous review's output, so it belongs in pi-subagents'
-// scripted workflow runtime rather than a fixed native chain.
-const AUTO_LOOP = String.raw`
-const autoLoop = async (goal, context, progressFile) => {
-  emit({ phase: 'start', goal });
-  let round = 1;
-  let previousReview = '';
-  let completed = 0;
-  while (true) {
-    try {
-      const build = await runs.run('build-' + round, {
-        agent: 'builder',
-        timeoutMs: 45 * 60 * 1000,
-        task: 'Implement the next bounded step of the approved work in the workspace and run relevant checks. Work on one small, self-contained slice this round; do not attempt the whole plan.\n\nSource of truth (handoff/plan):\n' + context + '\n\nGoal:\n' + goal + (round > 1 ? '\n\nPrevious review (its findings were addressed in the fix round; use its "Remaining work" notes to pick your next slice, do not re-apply findings):\n' + previousReview : '') + '\n\nRead the progress file first for prior-round context.\n\nProgress ledger: append a "## Round ' + round + '" entry to the progress file at ' + progressFile + ' before finishing. List every file you changed and a short summary of the work.',
-      });
-      const review = await runs.run('review-' + round, {
-        agent: 'commentator',
-        timeoutMs: 15 * 60 * 1000,
-        task: 'Independently review the builder work for this round and report concrete evidence (what you inspected and what you ran). Do not modify the workspace.\n\nAcceptance criteria (source of truth):\n' + context + '\n\nProgress file (scope your review to its latest round entry; also re-check the files from the immediately preceding fix entry if one exists; fall back to the full uncommitted diff if it is missing or empty):\n' + progressFile + '\n\nBuilder completion summary:\n' + build.output + '\n\nIf the plan is not yet complete, add a "Remaining work:" section listing the next concrete step(s). End with exactly one line: WORKFLOW_REVIEW_STATUS: clean OR WORKFLOW_REVIEW_STATUS: blocking.',
-      });
-      const hasRemainingWork = /Remaining work\s*:\s*\S/i.test(review.output);
-      if (/WORKFLOW_REVIEW_STATUS\s*:\s*clean/i.test(review.output) && !hasRemainingWork) {
-        return { result: 'clean', rounds: completed + 1 };
-      }
-      previousReview = review.output;
-      await runs.run('fix-' + round, {
-        agent: 'builder',
-        timeoutMs: 45 * 60 * 1000,
-        task: 'Address ONLY the findings from the review below. The "Remaining work:" section (if present) is for the next round; do not act on it. If the review is clean but has Remaining work, make no changes and record that fact.\n\nProgress ledger: append a "## Round ' + round + ' fix" entry to the progress file at ' + progressFile + ' before finishing. List every file you changed and a short summary of the fixes.\n\nReviewer findings:\n' + review.output,
-      });
-      completed += 1;
-      round += 1;
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      if (/Run fan-out limit reached/i.test(message)) {
-        return { result: 'budget', rounds: completed, note: 'Run fan-out budget exhausted before the goal was reached. The progress file is current.' };
-      }
-      throw error;
-    }
-  }
-};`;
-
-const PROGRESS_DIR = ".pi-subagents/progress/";
-
-export function buildLoopScript(goal: string): string {
-	return String.raw`const goal = ${js(goal)};
-${AUTO_LOOP}
-return await autoLoop(goal, goal, ${js(PROGRESS_DIR + "loop.md")});`;
-}
-
-export function buildTaskScript(goal: string): string {
-	return String.raw`const goal = ${js(goal)};
-const plan = await runs.run('plan', { agent: 'architect', task: 'Produce a concrete implementation plan for: ' + goal + '. Cover what to build, how, in what order, which files and components, and the finished result. Return inline.' });
-const reuse = await runs.run('reuse', { agent: 'explorer', task: 'Explore the codebase for reusable patterns relevant to: ' + plan.output + '. Point at relevant areas and dependencies; skip cleanly if wholly new. Return inline.' });
-const handoff = await runs.run('handoff', { agent: 'recapper', task: 'Compile a self-contained handoff from the plan and reuse findings so fresh agents understand the goal, constraints, and acceptance criteria without re-planning.\n\nPlan:\n' + plan.output + '\n\nReuse findings:\n' + reuse.output + '\n\nReturn inline.' });
-${AUTO_LOOP}
-return await autoLoop(goal, handoff.output, ${js(PROGRESS_DIR + "task.md")});`;
-}
-
-export function buildPrototypeScript(goal: string): string {
-	return String.raw`const goal = ${js(goal)};
-const discovery = await runs.all([
-  { key: 'research', agent: 'researcher', task: 'Research the external, fast-changing knowledge this task depends on (libraries, SDKs, APIs, unfamiliar alternatives). Task: ' + goal + '. Synthesize actionable findings with sources. Return inline.' },
-  { key: 'explore', agent: 'explorer', task: 'Map existing code, dependencies, and reusable patterns relevant to: ' + goal + '. Return inline.' },
-]);
-const research = discovery.find(result => result.key === 'research');
-const reuse = discovery.find(result => result.key === 'explore');
-const plan = await runs.run('plan', { agent: 'architect', task: 'Produce a concrete build plan from the research and codebase findings.\n\nResearch:\n' + research.output + '\n\nCodebase findings:\n' + reuse.output + '\n\nRequest:\n' + goal + '\n\nReturn inline.' });
-const handoff = await runs.run('handoff', { agent: 'recapper', task: 'Compile a self-contained handoff from the plan and reuse findings.\n\nPlan:\n' + plan.output + '\n\nReuse:\n' + reuse.output + '\n\nReturn inline.' });
-${AUTO_LOOP}
-const loop = await autoLoop(goal, handoff.output, ${js(PROGRESS_DIR + "prototype.md")});
-const audit = await runs.run('audit', { agent: 'commentator', task: 'Final audit of the uncommitted changes for correctness, plan adherence, and over-engineering (cut bloat, dead flexibility, reinvented stdlib). Plan:\n' + plan.output + '\n\nReport concrete evidence. Do not modify the workspace.' });
-return { ...loop, audited: true };`;
-}
-
-export function buildQuicktypeScript(goal: string): string {
-	return String.raw`const goal = ${js(goal)};
-const plan = await runs.run('plan', { agent: 'architect', task: 'Produce a concrete build plan for: ' + goal + '. Cover what to build, how, in what order, which components, and the finished result. Return inline.' });
-const reuse = await runs.run('reuse', { agent: 'explorer', task: 'Explore the codebase for reusable patterns relevant to: ' + plan.output + '. Return inline.' });
-const handoff = await runs.run('handoff', { agent: 'recapper', task: 'Compile a self-contained handoff from the plan and reuse findings.\n\nPlan:\n' + plan.output + '\n\nReuse:\n' + reuse.output + '\n\nReturn inline.' });
-${AUTO_LOOP}
-const loop = await autoLoop(goal, handoff.output, ${js(PROGRESS_DIR + "quicktype.md")});
-const audit = await runs.run('audit', { agent: 'commentator', task: 'Final audit of the uncommitted changes for correctness, plan adherence, and over-engineering (cut bloat, dead flexibility, reinvented stdlib). Plan:\n' + plan.output + '\n\nReport concrete evidence. Do not modify the workspace.' });
-return { ...loop, audited: true };`;
-}
-
-export const WORKFLOW_MODES: readonly WorkflowMode[] = [
-	{ command: "workflow-task", description: "Run the task workflow (plan → reuse → handoff → build/review/fix loop).", launch: (goal) => ({ workflowScript: buildTaskScript(goal) }) },
-	{ command: "workflow-prototype", description: "Run the prototype workflow (parallel research/reuse → plan → handoff → loop → audit).", launch: (goal) => ({ workflowScript: buildPrototypeScript(goal) }) },
-	{ command: "workflow-quicktype", description: "Run the quicker prototype workflow (plan → reuse → handoff → loop → audit).", launch: (goal) => ({ workflowScript: buildQuicktypeScript(goal) }) },
-	{ command: "workflow-loop", description: "Run a direct build/review/fix loop for an already-agreed plan.", launch: (goal) => ({ workflowScript: buildLoopScript(goal) }) },
-];

package/dist/extensions/workflow/package.json

@@ -1,17 +0,0 @@
-{
-	"name": "@selesai/workflow",
-	"version": "0.0.1",
-	"private": true,
-	"description": "Selesai workflow engine + modes (prototype, quick). Loaded as a bundled pi extension package.",
-	"type": "module",
-	"pi": {
-		"extensions": [
-			"./extension.ts"
-		]
-	},
-	"peerDependencies": {
-		"@selesai/code": "*",
-		"@earendil-works/pi-tui": "*",
-		"typebox": "*"
-	}
-}

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

@@ -1,73 +0,0 @@
----
-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.
-disable-model-invocation: true
----
-
-# 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 slash-command name; users start/resume through that command, while the shared end tool selects the mode;
-- 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`; only a user-invoked mode command with 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_workflow({ mode })` 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.