@selesai/code 0.5.9 → 0.5.11

package/dist/extensions/grep-app/index.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import { buildSearchUrl, formatSearchResponse } from "./index.ts";
+
+describe("grep-app extension", () => {
+	it("maps search filters to grep.app parameters", () => {
+		const url = buildSearchUrl({
+			query: "useEffect cleanup",
+			page: 2,
+			caseSensitive: true,
+			useRegex: true,
+			repo: "facebook/react",
+			path: "packages/",
+			language: "TypeScript",
+		});
+
+		expect(Object.fromEntries(url.searchParams)).toEqual({
+			q: "useEffect cleanup",
+			page: "2",
+			case: "true",
+			regexp: "true",
+			"f.repo.pattern": "facebook/react",
+			"f.path.pattern": "packages/",
+			"f.lang": "TypeScript",
+		});
+	});
+
+	it("turns grep.app HTML snippets into readable numbered source", () => {
+		const output = formatSearchResponse(
+			{
+				hits: {
+					total: 42,
+					hits: [
+						{
+							repo: "owner/repo",
+							branch: "main",
+							path: "src/a file.ts",
+							content: {
+								snippet: '<table><tr data-line="7"><td><pre>const x = &lt;mark&gt;;</pre></td></tr></table>',
+							},
+						},
+					],
+				},
+			},
+			3,
+		);
+
+		expect(output).toContain("42 total matches; page 3");
+		expect(output).toContain("L7: const x = <mark>;");
+		expect(output).toContain("https://github.com/owner/repo/blob/main/src/a%20file.ts#L7");
+	});
+});

package/dist/extensions/grep-app/index.ts

@@ -0,0 +1,200 @@
+/** Native Selesai extension inspired by ai-tools-all/grep_app_mcp (ISC). */
+
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	DEFAULT_MAX_BYTES,
+	DEFAULT_MAX_LINES,
+	formatSize,
+	truncateHead,
+	type ExtensionAPI,
+	withFileMutationQueue,
+} from "@selesai/code";
+import { load } from "cheerio";
+import { Type } from "typebox";
+
+const API_URL = "https://grep.app/api/search";
+const RAW_GITHUB_URL = "https://raw.githubusercontent.com";
+
+interface GrepAppHit {
+	repo: string;
+	branch: string;
+	path: string;
+	content: { snippet: string };
+	total_matches?: string;
+}
+
+interface GrepAppResponse {
+	hits: { total: number; hits: GrepAppHit[] };
+}
+
+interface SearchParams {
+	query: string;
+	page?: number;
+	caseSensitive?: boolean;
+	useRegex?: boolean;
+	wholeWords?: boolean;
+	repo?: string;
+	path?: string;
+	language?: string;
+}
+
+export function buildSearchUrl(params: SearchParams): URL {
+	const url = new URL(API_URL);
+	url.searchParams.set("q", params.query);
+	url.searchParams.set("page", String(params.page ?? 1));
+	if (params.caseSensitive) url.searchParams.set("case", "true");
+	if (params.useRegex) url.searchParams.set("regexp", "true");
+	if (params.wholeWords) url.searchParams.set("words", "true");
+	if (params.repo) url.searchParams.set("f.repo.pattern", params.repo);
+	if (params.path) url.searchParams.set("f.path.pattern", params.path);
+	if (params.language) url.searchParams.set("f.lang", params.language);
+	return url;
+}
+
+function snippetLines(snippet: string): Array<{ line: string; text: string }> {
+	const $ = load(snippet);
+	return $("tr")
+		.toArray()
+		.map((row) => ({
+			line: $(row).attr("data-line") ?? "?",
+			text: $(row).find("pre").text().replace(/\s+$/, ""),
+		}));
+}
+
+function encodePath(value: string): string {
+	return value
+		.split("/")
+		.filter(Boolean)
+		.map(encodeURIComponent)
+		.join("/");
+}
+
+export function formatSearchResponse(response: GrepAppResponse, page: number): string {
+	if (response.hits.hits.length === 0) return "No matches found.";
+
+	const results = response.hits.hits.map((hit, index) => {
+		const lines = snippetLines(hit.content.snippet);
+		const firstLine = lines.find((line) => line.line !== "?")?.line;
+		const url = `https://github.com/${hit.repo}/blob/${encodePath(hit.branch)}/${encodePath(hit.path)}${firstLine ? `#L${firstLine}` : ""}`;
+		const body = lines.map(({ line, text }) => `  L${line}: ${text}`).join("\n");
+		return `${index + 1}. ${hit.repo}:${hit.path} (${hit.branch})\n${body}\n  ${url}`;
+	});
+
+	return `grep.app: ${response.hits.total} total matches; page ${page}\n\n${results.join("\n\n")}`;
+}
+
+async function fetchWithBrowser(url: URL | string, signal: AbortSignal | undefined): Promise<string> {
+	const { chromium } = await import("playwright");
+	const browser = await chromium.launch({ headless: true });
+	const abort = () => void browser.close();
+	signal?.addEventListener("abort", abort, { once: true });
+	try {
+		const page = await browser.newPage();
+		await page.goto(String(url), { waitUntil: "networkidle", timeout: 30_000 });
+		await page.waitForFunction(() => document.body.innerText.trimStart().startsWith("{"), undefined, { timeout: 15_000 });
+		return await page.locator("body").innerText();
+	} catch (error) {
+		if (signal?.aborted) throw signal.reason ?? new Error("Cancelled");
+		throw error;
+	} finally {
+		signal?.removeEventListener("abort", abort);
+		await browser.close();
+	}
+}
+
+async function fetchText(url: URL | string, signal: AbortSignal | undefined, browserFallback = false): Promise<string> {
+	const response = await fetch(url, {
+		signal,
+		headers: { Accept: "application/json, text/plain;q=0.9", "User-Agent": "selesai-grep-app-extension" },
+	});
+	if (browserFallback && response.status === 429 && response.headers.get("x-vercel-mitigated") === "challenge") {
+		return fetchWithBrowser(url, signal);
+	}
+	if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);
+	return response.text();
+}
+
+async function truncateOutput(output: string): Promise<{ text: string; fullOutputPath?: string }> {
+	const truncated = truncateHead(output, { maxBytes: DEFAULT_MAX_BYTES, maxLines: DEFAULT_MAX_LINES });
+	if (!truncated.truncated) return { text: output };
+
+	const directory = await mkdtemp(join(tmpdir(), "selesai-grep-app-"));
+	const fullOutputPath = join(directory, "output.txt");
+	await withFileMutationQueue(fullOutputPath, () => writeFile(fullOutputPath, output, "utf8"));
+	return {
+		text: `${truncated.content}\n\n[Output truncated to ${truncated.outputLines} lines / ${formatSize(truncated.outputBytes)}. Full output: ${fullOutputPath}]`,
+		fullOutputPath,
+	};
+}
+
+export default function grepAppExtension(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "grep_app_search",
+		label: "grep.app Search",
+		description: "Search public GitHub code through grep.app. Returns one page (up to 10 files); use page to continue.",
+		promptSnippet: "Search public GitHub code through grep.app",
+		promptGuidelines: ["Use grep_app_search to find real public-code implementations and usage examples across GitHub."],
+		parameters: Type.Object({
+			query: Type.String({ minLength: 1, description: "Code or pattern to search for." }),
+			page: Type.Optional(Type.Integer({ minimum: 1, description: "Result page; defaults to 1." })),
+			caseSensitive: Type.Optional(Type.Boolean({ description: "Match case." })),
+			useRegex: Type.Optional(Type.Boolean({ description: "Treat query as a regular expression." })),
+			wholeWords: Type.Optional(Type.Boolean({ description: "Match whole words. Cannot be combined with useRegex." })),
+			repo: Type.Optional(Type.String({ description: "Repository filter, for example facebook/react." })),
+			path: Type.Optional(Type.String({ description: "File path filter, for example src/components/." })),
+			language: Type.Optional(Type.String({ description: "Language filter, for example TypeScript." })),
+		}),
+		async execute(_toolCallId, params, signal) {
+			if (params.useRegex && params.wholeWords) throw new Error("useRegex and wholeWords cannot both be true.");
+
+			const page = params.page ?? 1;
+			const raw = await fetchText(buildSearchUrl(params), signal, true);
+			let response: GrepAppResponse;
+			try {
+				response = JSON.parse(raw) as GrepAppResponse;
+			} catch {
+				throw new Error("grep.app returned invalid JSON.");
+			}
+			if (!response.hits || !Array.isArray(response.hits.hits)) throw new Error("grep.app returned an unexpected response.");
+
+			const output = await truncateOutput(formatSearchResponse(response, page));
+			return {
+				content: [{ type: "text", text: output.text }],
+				details: { total: response.hits.total, page, resultCount: response.hits.hits.length, fullOutputPath: output.fullOutputPath },
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "grep_app_fetch",
+		label: "GitHub File",
+		description: "Fetch a public GitHub file found via grep.app. Supports line ranges; output is truncated to 50KB or 2000 lines.",
+		promptSnippet: "Fetch a public GitHub file found via grep.app",
+		promptGuidelines: ["Use grep_app_fetch after grep_app_search when the full source context is needed."],
+		parameters: Type.Object({
+			repo: Type.String({ pattern: "^[^/\\s]+/[^/\\s]+$", description: "owner/repository." }),
+			path: Type.String({ minLength: 1, description: "Path inside the repository." }),
+			ref: Type.Optional(Type.String({ minLength: 1, description: "Branch, tag, or commit; defaults to HEAD." })),
+			startLine: Type.Optional(Type.Integer({ minimum: 1, description: "First line; defaults to 1." })),
+			endLine: Type.Optional(Type.Integer({ minimum: 1, description: "Last line; defaults to end of file." })),
+		}),
+		async execute(_toolCallId, params, signal) {
+			const startLine = params.startLine ?? 1;
+			if (params.endLine !== undefined && params.endLine < startLine) throw new Error("endLine must be greater than or equal to startLine.");
+
+			const rawUrl = `${RAW_GITHUB_URL}/${encodePath(params.repo)}/${encodePath(params.ref ?? "HEAD")}/${encodePath(params.path)}`;
+			const source = await fetchText(rawUrl, signal);
+			const allLines = source.split("\n");
+			const endLine = Math.min(params.endLine ?? allLines.length, allLines.length);
+			const selected = allLines.slice(startLine - 1, endLine).map((line, index) => `${startLine + index}: ${line}`).join("\n");
+			const output = await truncateOutput(selected);
+
+			return {
+				content: [{ type: "text", text: output.text || "(empty file or range)" }],
+				details: { repo: params.repo, path: params.path, ref: params.ref ?? "HEAD", startLine, endLine, totalLines: allLines.length, fullOutputPath: output.fullOutputPath },
+			};
+		},
+	});
+}

package/dist/extensions/package.json

@@ -9,6 +9,7 @@
 			"./context-compaction-reminder.ts",
 			"./tool-error-autofix.ts",
 			"./question",
+			"./grep-app",
 			"./handoff-new.ts",
 			"./rtk.ts",
 			"./tokenin-onboarding.ts",

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

@@ -1,7 +1,7 @@
 ---
 name: researcher
-description: Autonomous web researcher that produces a focused sourced brief
-tools: read, web_explore
+description: Autonomous code-first researcher that produces a focused sourced brief
+tools: read, grep_app_search, grep_app_fetch, web_explore
 thinking: medium
 systemPromptMode: replace
 inheritProjectContext: false
@@ -10,9 +10,11 @@ defaultContext: fresh
 skill: ponytail, caveman
 ---
 
-You are a web research subagent. Answer the supplied question with a concise, well-sourced brief. Do not edit project files, write output files, or launch subagents.
+You are a code-first research subagent. Answer the supplied question with a concise, well-sourced brief. Do not edit project files, write output files, or launch subagents.
 
-Use `web_explore` for focused search/fetch/source ranking. Start with 2–4 distinct angles, prioritize primary and official sources, then narrow follow-ups only for material gaps. Do not fetch URLs through shell commands.
+Start with `grep_app_search` for public-code evidence and use `grep_app_fetch` only for the most relevant source files. Search 2–4 distinct angles, prefer original implementations and repository-owned examples, then narrow follow-ups only for material gaps.
+
+Treat `web_explore` as a last resort: use it only when grep.app cannot answer the question, the task requires non-code sources or official documentation, or grep.app fails. If `web_explore` is unavailable, report the gap instead of fetching URLs through shell commands.
 
 Output:
 

package/dist/extensions/workflow/adapter.ts

@@ -226,8 +226,38 @@ async function resumeController(
   try {
     await persistAfter(controller, before);
     const reconcileBefore = checkpoint(controller);
-    const reconciled = await sm.onArtifactMaybe(controller.deps);
-    await persistAfter(controller, reconcileBefore);
+    let reconciled: WorkflowEffect = { kind: "noOp" };
+    try {
+      reconciled = await sm.onArtifactMaybe(controller.deps);
+      await persistRun(controller);
+      // ponytail: when a resumed run has multiple already-written parent-owned
+      // artifacts, one onArtifactMaybe only advances one phase. Keep reconciling
+      // until we either catch up to the durable file state or hit a blocked/
+      // terminal effect, so resume lands on the furthest valid phase.
+      while (sm.snapshot.active && sm.snapshot.autoArmed) {
+        const further = await sm.onArtifactMaybe(controller.deps);
+        if (
+          further.kind === "noOp" ||
+          further.kind === "blocked" ||
+          further.kind === "terminalNeedsArtifacts"
+        ) break;
+        reconciled = further;
+        await persistRun(controller);
+        if (further.kind === "terminalReady") break;
+      }
+    } catch (error) {
+      // Atomic rollback: on any failure during reconciliation, restore both
+      // in-memory state and durable state to the checkpoint before the whole
+      // reconcile sequence. Do not leave the controller at an intermediate
+      // phase while the run file has already advanced further.
+      restoreCheckpoint(controller, reconcileBefore);
+      try {
+        await persistRun(controller);
+      } catch {
+        // Best-effort rollback failed; still report the original error.
+      }
+      throw error;
+    }
     const current = sm.continueCurrent();
     const terminal = config.phases[config.phases.length - 1];
     const terminalReady = reconciled.kind === "terminalReady" || (sm.snapshot.phase === terminal && !sm.snapshot.autoArmed);
@@ -304,7 +334,7 @@ function makeDeps(pi: ExtensionAPI, config: WorkflowConfig): WorkflowDeps {
 
 // ponytail: the git-based skip predicate shared by both modes today.
 // A mode that wants a different skip rule supplies its own SkipRule.
-async function isEmptyProject(pi: ExtensionAPI): Promise<boolean> {
+async function hasNoGitHistory(pi: ExtensionAPI): Promise<boolean> {
   try {
     const result = await pi.exec("git", ["log", "--oneline", "-1"]);
     return result.code !== 0 || !result.stdout.trim();
@@ -482,7 +512,8 @@ function registerSharedArtifactWriter(pi: ExtensionAPI): void {
         };
       }
       // Most workflows pause at a user-controlled artifact boundary. Task's
-      // plan → loop transition queues the builder/review prompt immediately.
+      // plan → reuse → handoff → loop transitions queue the next phase prompt
+      // immediately when continueAfterArtifact is true.
       const queueNextPhase = controller.config.continueAfterArtifact === true && eff.kind === "advanced";
       applyControllerEffect(controller, ctx, eff, { queuePrompt: queueNextPhase });
       if (eff.kind === "blocked" && eff.reason) {
@@ -519,13 +550,13 @@ export function createWorkflowExtension(
   return function workflowExtension(pi: ExtensionAPI): void {
     replaceControllerFor(pi, config.mode);
     const deps = makeDeps(pi, config);
-    // ponytail: default skip rule — reuse is skipped on empty projects (no git
-    // commits). Shared by every mode today; a mode that wants a different rule
-    // supplies its own skipRules in config and we respect them as-is.
+    // ponytail: default skip rule — reuse is skipped when the project has no
+    // git history. Shared by every mode today; a mode that wants a different
+    // rule supplies its own skipRules in config and we respect them as-is.
     const skipRules = config.skipRules ?? [
       {
         phase: "reuse",
-        shouldSkip: async () => isEmptyProject(pi),
+        shouldSkip: async () => hasNoGitHistory(pi),
       },
     ];
     const sm = new WorkflowStateMachine({ ...config, skipRules });

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

@@ -4,11 +4,17 @@ import type {
   WorkflowConfig,
   WorkflowModeRegistration,
 } from "../state-machine.ts";
-import { loopCompleteValidator, planValidator } from "../validators.ts";
+import {
+  handoffValidator,
+  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"];
+// ponytail: task workflow is now plan → reuse → handoff → loop. Each parent-
+// owned artifact (plan.md, reuse.md, handoff.md) advances automatically, and
+// the loop's clean marker makes the workflow terminal-ready. The explicit end
+// tool is the only completion.
+const phases: Phase[] = ["plan", "reuse", "handoff", "loop"];
 
 const prompts: Partial<Record<Phase, (ctx: PromptContext) => string>> = {
   plan: ({ artifactDir, userPrompt }) =>
@@ -24,12 +30,38 @@ Call the subagent tool with { agent: "architect", task: "...", output: false } (
 Inspect that result, verify it ends with exactly one machine-readable line on its own:
   WORKFLOW_PLAN_STATUS: ready
 Then immediately call write_workflow_artifact with the complete validated plan as content. Only that parent tool call writes ${artifactDir}/plan.md and advances the workflow.`,
+  reuse: ({ artifactDir }) =>
+    `You are in the REUSE phase of a TASK workflow (optional).
+
+The adapter automatically skips this phase when the project has no git history, so codebase exploration is only useful when commits already exist. Decide whether exploration is still useful; skip if the task creates something wholly new or there is clearly nothing to reuse.
+
+If unsure, ask the user one focused question: "Should I explore the existing codebase for reusable patterns before implementing?" Then follow their answer.
+
+If YES (or user confirms): call the subagent tool with { agent: "explorer", task: "...", output: false } (do NOT pass a model parameter). Craft the task from ${artifactDir}/plan.md pointing it at relevant areas, patterns, and dependencies. It must return the reuse findings inline; do not tell it to write any artifact. Immediately call write_workflow_artifact with those findings as content for ${artifactDir}/reuse.md.
+
+If NO: call write_workflow_artifact with a brief skip note explaining why.
+
+The workflow advances once ${artifactDir}/reuse.md exists.`,
+  handoff: ({ artifactDir }) =>
+    `You are in the HANDOFF phase of a TASK workflow.
+
+Compile a self-contained handoff document so loop-phase sub-agents understand full project context without re-grilling.
+
+Draw from all prior phases:
+- ${artifactDir}/plan.md
+- ${artifactDir}/reuse.md
+
+Call the subagent tool with { agent: "recapper", task: "...", output: false } (do NOT pass a model parameter). Craft the task pointing the recapper at both artifact files and telling it what the task is about. It must return the complete handoff inline; do not tell it to write any artifact.
+
+Inspect that result, verify it ends with exactly one machine-readable line on its own:
+  WORKFLOW_HANDOFF_STATUS: ready
+Then immediately call write_workflow_artifact with the complete validated handoff as content. Only that parent tool call writes ${artifactDir}/handoff.md and advances the workflow.`,
   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:
+Use read to inspect ${artifactDir}/plan.md, ${artifactDir}/reuse.md, and ${artifactDir}/handoff.md. Using that context, GENERATE YOUR OWN delegation prompt:
 
-Call the subagent tool with { agent: "builder", task: "...", output: false } (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}. The builder must return its completion summary inline.
+Call the subagent tool with { agent: "builder", task: "...", output: false } (do NOT pass a model parameter). Give it plan + reuse + handoff 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}. The builder must return its completion summary inline.
 
 After the builder returns, call the subagent tool with { agent: "commentator", task: "...", output: false }. Craft the review task YOURSELF. The commentator must return its review inline. Each commentator review MUST end with exactly one machine-readable line:
   WORKFLOW_REVIEW_STATUS: clean
@@ -44,19 +76,21 @@ const config: WorkflowConfig = {
   phases,
   phaseArtifacts: {
     plan: "plan.md",
+    reuse: "reuse.md",
+    handoff: "handoff.md",
     loop: "loop-complete.md",
   },
   prompts,
   skipRules: [],
   artifactValidators: {
     plan: planValidator,
+    handoff: handoffValidator,
     loop: loopCompleteValidator,
   },
   closeValidators: { "loop-complete.md": loopCompleteValidator },
   closeArtifacts: ["loop-complete.md"],
   loopMaxIterations: 3,
-  // Task is plan → build. Continue directly into the loop when architect
-  // finishes, rather than requiring a second /workflow-task interaction.
+  // Each parent-owned artifact automatically queues the next phase prompt.
   continueAfterArtifact: true,
   statusKey: "task",
   entryType: "task-phase",
@@ -66,7 +100,8 @@ const config: WorkflowConfig = {
 export const taskMode: WorkflowModeRegistration = {
   config,
   commandName: "workflow-task",
-  commandDescription: "Run the task workflow (plan → build↔review loop)",
+  commandDescription:
+    "Run the task workflow (plan → reuse → handoff → build↔review loop)",
   toolNames: {
     start: "start_task_workflow",
     resume: "resume_task_workflow",

package/docs/workflows.md

@@ -120,17 +120,18 @@ That's it. The loader picks it up at boot (`package.json` loads only `./extensio
 
 ## Built-in modes
 
-### `task` — rapid plan + build/review loop
+### `task` — plan → codebase exploration → handoff → 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.
+Task now follows the same phase shape as the other modes, minus grilling/research/audit: an architect subagent produces a validated `plan.md`, an optional explorer subagent produces `reuse.md`, a recapper subagent produces a validated `handoff.md`, and 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`
+Lifecycle: `plan → reuse → handoff → 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
-- Its ready plan automatically queues the builder↔review loop
-- No grilling, research, reuse, or handoff phases
+- Valid `plan.md`, `reuse.md`, and `handoff.md` each automatically queue the next phase prompt (the workflow does not pause at those boundaries)
+- No grilling, research, or audit phases
+- `reuse.md` is optional; it is skipped automatically when the project has no git history
 
 ## Config reference
 
@@ -141,11 +142,11 @@ Lifecycle: `plan → loop (build ↔ review) → terminal-ready → end_task_wor
 | `phaseArtifacts` | `Partial<Record<Phase, string>>` | The artifact file each phase must produce before advancing. Omit a phase to skip its gate. |
 | `prompts` | `Partial<Record<Phase, (ctx) => string>>` | Prompt generator per phase. `ctx = { artifactDir, userPrompt }`. |
 | `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). |
+| `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` when the project has no git history). |
 | `statusKey` | `string` | Footer status key. |
 | `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`). |
-| `continueAfterArtifact?` | `boolean` | Queue the next phase prompt after the parent writes a valid artifact. `task` enables this for plan → build. |
+| `continueAfterArtifact?` | `boolean` | Queue the next phase prompt after the parent writes a valid artifact. `task` enables this at every parent-owned artifact boundary (plan, reuse, handoff) so the workflow flows automatically into the loop. |
 
 ### Adapter options
 
@@ -169,7 +170,7 @@ Runs are **never** auto-resumed on session start. At most one run can be attache
 - `/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 `write_workflow_artifact` writes the file 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. A mode can opt out of that pause after a parent artifact write; `task` does so after `plan.md` so the build loop starts immediately. Corrupt records are skipped during discovery.
+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 `write_workflow_artifact` writes the file 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. A mode can opt out of that pause after a parent artifact write; `task` does so at every parent-owned artifact boundary (`plan.md`, `reuse.md`, `handoff.md`) so the build loop starts immediately after a valid handoff. 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.
 

package/package.json

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