pi-soly 1.13.5 → 1.15.0

package/status.ts

@@ -56,8 +56,8 @@ export function formatStatus(
 	lines.push("  Project state");
 	lines.push("  ─────────────");
 	if (!state.exists) {
-		lines.push("  no .agents/ or .soly/ found in cwd");
-		lines.push("  → run /soly-init to scaffold");
+		lines.push("  no .agents/ found in cwd");
+		lines.push("  → run /soly init to scaffold");
 	} else {
 		lines.push(`  milestone:  ${state.milestone ?? "—"}`);
 		lines.push(`  current:    ${state.currentPosition ?? "ready"}`);

package/tools.ts

@@ -3,11 +3,11 @@
 // =============================================================================
 //
 // Registers three tools the LLM can call:
-//   - soly_read         — read any .soly/ artifact (state/plan/roadmap/...)
+//   - soly_read         — read any .agents/ artifact (state/plan/roadmap/...)
 //   - soly_log_decision — append a row to STATE.md Decisions table
 //   - soly_list_phases  — list all phases with markers
 //
-// All paths are relative to <cwd>/.soly/ (the soly layout — NOT .planning/).
+// All paths are relative to <cwd>/.agents/ (the soly layout — NOT .planning/).
 // =============================================================================
 
 import * as fs from "node:fs";
@@ -17,7 +17,7 @@ import { promisify } from "node:util";
 import { Type } from "typebox";
 import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { readIfExists, splitFrontmatter, atomicWriteFileSync, type SolyState } from "./core.ts";
+import { readIfExists, splitFrontmatter, atomicWriteFileSync, solyDirFor, type SolyState } from "./core.ts";
 import { detectEnv, type EnvSummary } from "./env.ts";
 import type { SolyConfig } from "./config.ts";
 import { buildDocIndex, searchDocs, readSnippet, stripHtml } from "./docs.ts";
@@ -66,7 +66,7 @@ export function registerTools(pi: ExtensionAPI, deps: ToolsDeps): void {
 		name: "soly_read",
 		label: "soly read",
 		description:
-			"Read a .soly/ artifact (state, plan, context, research, roadmap, requirements, project, milestone, task). `phase` targets a specific phase (default: current); `taskId` for the task artifact. Returns the file text.",
+			"Read a .agents/ artifact (state, plan, context, research, roadmap, requirements, project, milestone, task). `phase` targets a specific phase (default: current); `taskId` for the task artifact. Returns the file text.",
 		parameters: Type.Object({
 			artifact: StringEnum([
 				"state",
@@ -129,7 +129,7 @@ export function registerTools(pi: ExtensionAPI, deps: ToolsDeps): void {
 				if (!task) {
 					return {
 						content: [
-							{ type: "text", text: `soly: task ${taskId} not found in .soly/features/*/tasks/` },
+							{ type: "text", text: `soly: task ${taskId} not found in .agents/features/*/tasks/` },
 						],
 						details: { error: "task_not_found", taskId },
 					};
@@ -189,7 +189,7 @@ export function registerTools(pi: ExtensionAPI, deps: ToolsDeps): void {
 		name: "soly_log_decision",
 		label: "soly log decision",
 		description:
-			"Append a one-line decision + rationale to the Decisions table in .soly/STATE.md (creates it if missing). For meaningful choices: scope cuts, library picks, trade-offs. `phase` defaults to current.",
+			"Append a one-line decision + rationale to the Decisions table in .agents/STATE.md (creates it if missing). For meaningful choices: scope cuts, library picks, trade-offs. `phase` defaults to current.",
 		parameters: Type.Object({
 			decision: Type.String({ description: "The decision made (one line)." }),
 			rationale: Type.String({ description: "Why this decision was made (one line)." }),
@@ -329,7 +329,7 @@ export function registerTools(pi: ExtensionAPI, deps: ToolsDeps): void {
 		name: "soly_todos",
 		label: "soly todos",
 		description:
-			"Scan the tree for TODO/FIXME/HACK/XXX/NOTE comments, grouped by file (common source extensions; excludes node_modules/.git/dist/build/.soly). Needs ripgrep on PATH. `paths` overrides root, `limit` caps (default 200).",
+			"Scan the tree for TODO/FIXME/HACK/XXX/NOTE comments, grouped by file (common source extensions; excludes node_modules/.git/dist/build/.agents). Needs ripgrep on PATH. `paths` overrides root, `limit` caps (default 200).",
 		parameters: Type.Object({
 			paths: Type.Optional(
 				Type.Array(Type.String(), {
@@ -356,7 +356,7 @@ export function registerTools(pi: ExtensionAPI, deps: ToolsDeps): void {
 				"--glob=!node_modules/**",
 				"--glob=!dist/**",
 				"--glob=!build/**",
-				"--glob=!.soly/**",
+				"--glob=!.agents/**",
 				"--glob=!coverage/**",
 				"-tts",
 				"-tjs",
@@ -838,7 +838,7 @@ export function registerTools(pi: ExtensionAPI, deps: ToolsDeps): void {
 			canonical_refs: Type.Optional(
 				Type.Array(Type.String(), {
 					description:
-						"MANDATORY. Files the planner needs (intent docs, REQUIREMENTS, contracts), full paths from `.soly/`.",
+						"MANDATORY. Files the planner needs (intent docs, REQUIREMENTS, contracts), full paths from `.agents/`.",
 				}),
 			),
 			deferred_ideas: Type.Optional(
@@ -852,10 +852,10 @@ export function registerTools(pi: ExtensionAPI, deps: ToolsDeps): void {
 		}),
 		async execute(_id, params, _signal, _onUpdate, ctx) {
 			// Locate phase dir
-			const solyDir = path.join(ctx.cwd, ".soly");
+			const solyDir = solyDirFor(ctx.cwd);
 			if (!fs.existsSync(solyDir)) {
 				return {
-					content: [{ type: "text", text: "soly_finish_discuss: no .soly/ in cwd" }],
+					content: [{ type: "text", text: "soly_finish_discuss: no .agents/ in cwd" }],
 					details: { error: "no_soly" },
 				};
 			}
@@ -877,7 +877,7 @@ export function registerTools(pi: ExtensionAPI, deps: ToolsDeps): void {
 					content: [
 						{
 							type: "text",
-							text: `soly_finish_discuss: phase ${phaseNum} not found in .soly/phases/`,
+							text: `soly_finish_discuss: phase ${phaseNum} not found in .agents/phases/`,
 						},
 					],
 					details: { error: "no_phase", phase: phaseNum },
@@ -1021,11 +1021,11 @@ export function registerTools(pi: ExtensionAPI, deps: ToolsDeps): void {
 			),
 		}),
 		async execute(_id, params, _signal, _onUpdate, ctx) {
-			const solyDir = path.join(ctx.cwd, ".soly");
+			const solyDir = solyDirFor(ctx.cwd);
 			const phasesRoot = path.join(solyDir, "phases");
 			if (!fs.existsSync(phasesRoot)) {
 				return {
-					content: [{ type: "text", text: "soly_save_discuss_checkpoint: no .soly/phases/ in cwd" }],
+					content: [{ type: "text", text: "soly_save_discuss_checkpoint: no .agents/phases/ in cwd" }],
 					details: { error: "no_phases" },
 				};
 			}

package/util.ts

@@ -16,7 +16,7 @@ import type { ProgressInfo, RuleFrontmatter } from "./core.ts";
 // Frontmatter parsers
 // ============================================================================
 
-// Simple parser for .soly/rules/ frontmatter.
+// Simple parser for .agents/rules/ frontmatter.
 export function parseRuleFrontmatter(raw: string): {
   meta: RuleFrontmatter;
   body: string;
@@ -68,7 +68,7 @@ export function parseRuleFrontmatter(raw: string): {
   return { meta, body };
 }
 
-// YAML-ish parser for .soly/STATE.md. Handles 2-level nested objects (for `progress:`).
+// YAML-ish parser for .agents/STATE.md. Handles 2-level nested objects (for `progress:`).
 export function parseStateFrontmatter(yaml: string): {
   meta: Record<string, unknown>;
   progress: ProgressInfo;

package/visual/welcome.ts

@@ -10,7 +10,7 @@
 //   soly adds   plans · state · rules · workflows · ask_pro picker
 //   project     v1.12 · plan 2/5 — auth refactor · ≡ 4 rules · 2 docs
 //   next        → /execute
-//   start here  /soly-init · /plan · /soly · /why · /rules stats
+//   start here  /soly init · /plan · /soly · /why · /rules stats
 //   recent      1.11.2  …  ·  1.10.0  …
 //
 // pi is explicitly credited (engine) with soly as the framework on top. The
@@ -54,7 +54,7 @@ export const SOLY_ART: readonly string[] = [
 const TAGLINE = "the project framework · running on pi, the coding engine";
 const SOLY_ADDS = "plans · state · rules · workflows · ask_pro picker";
 const START_HERE: ReadonlyArray<[string, string]> = [
-	["/soly-init", "scaffold .agents/ in a new project"],
+	["/soly init", "scaffold .agents/ in a new project"],
 	["/plan", "plan the current phase"],
 	["/soly", "state picker  ·  /why  ·  /rules stats"],
 ];
@@ -144,7 +144,7 @@ function bannerLines(opts: WelcomeOpts): string[] {
 
 /** The "project" row value, depending on whether a soly project exists. */
 function projectValue(input: WelcomeInput, styler: ChromeStyler): string {
-	if (!input.hasProject) return styler.dim("no soly project here  →  /soly-init to scaffold");
+	if (!input.hasProject) return styler.dim("no soly project here  →  /soly init to scaffold");
 	const bits = [styler.fg("accent", `v${input.version}`)];
 	if (input.phaseLabel) bits.push(input.phaseLabel);
 	if (input.rulesActive > 0) bits.push(`≡ ${input.rulesActive}`);

package/workflows/done.ts

@@ -0,0 +1,203 @@
+// =============================================================================
+// workflows/done.ts — `soly done <type>/<name>` handler
+// =============================================================================
+//
+// Direct workflow (no LLM transform): wraps up a plan on its branch.
+//  1. Validates we're on the plan's branch (or any soly plan branch if
+//     `<type>/<name>` is omitted — see "implicit mode" below).
+//  2. Commits any uncommitted changes (with a sensible Conventional
+//     Commits message if the user hasn't staged anything).
+//  3. `git push -u origin <branch>` (or warn if no remote).
+//  4. Tries `gh pr create --draft --fill` (or warns if `gh` not on PATH).
+//
+// STATE.md global sync (in main) is deferred to W4 — that's a separate
+// concern about merge coordination.
+// =============================================================================
+
+import * as fs from "node:fs";
+import { execFileSync } from "node:child_process";
+import { parsePlanName, type SolyCommand } from "./parser.ts";
+import type { SolyState } from "../core.js";
+
+export interface DoneResult {
+	handled: boolean;
+	transformedText?: string;
+	completed?: {
+		branch: string;
+		commit: string;
+		pushed: boolean;
+		prUrl: string | null;
+	};
+}
+
+type Notifier = {
+	notify: (text: string, level?: "info" | "warning" | "error") => void;
+};
+
+function git(args: string[], opts: { cwd: string }): string {
+	try {
+		return execFileSync("git", args, {
+			cwd: opts.cwd,
+			encoding: "utf-8",
+			stdio: ["ignore", "pipe", "pipe"],
+		}).trim();
+	} catch (err) {
+		const e = err as { stderr?: Buffer | string; stdout?: Buffer | string; message?: string };
+		const stderr = e.stderr ? e.stderr.toString().trim() : "";
+		throw new Error(`git ${args.join(" ")} failed: ${stderr || e.message || "unknown error"}`);
+	}
+}
+
+/** Try `gh` and return stdout. Throws on failure. */
+function gh(args: string[], opts: { cwd: string; ghPath?: string }): string {
+	const cmd = opts.ghPath ?? "gh";
+	try {
+		return execFileSync(cmd, args, {
+			cwd: opts.cwd,
+			encoding: "utf-8",
+			stdio: ["ignore", "pipe", "pipe"],
+		}).trim();
+	} catch (err) {
+		const e = err as { stderr?: Buffer | string; message?: string };
+		const stderr = e.stderr ? e.stderr.toString().trim() : "";
+		throw new Error(`gh ${args[0]} failed: ${stderr || e.message || "unknown error"}`);
+	}
+}
+
+/** ENOENT-style "command not found" -> throws a specific error. */
+function ghAvailable(ghPath?: string): boolean {
+	const cmd = ghPath ?? "gh";
+	try {
+		execFileSync(cmd, ["--version"], { stdio: "ignore" });
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function reply(text: string): DoneResult {
+	return { handled: true, transformedText: text };
+}
+
+export function buildDoneTransform(
+	cmd: SolyCommand,
+	state: SolyState,
+	ui: Notifier,
+	projectRoot: string,
+	opts: { ghPath?: string } = {},
+): DoneResult {
+	if (!state.exists) {
+		return reply(`soly done: no .agents/ directory in cwd — run /soly init first.`);
+	}
+
+	const raw = cmd.args.join(" ").trim();
+	const parsed = parsePlanName(raw);
+	if ("error" in parsed) {
+		return reply(`soly done: ${parsed.error}\n\nUsage: soly done <type>/<name>`);
+	}
+	const { type, name } = parsed;
+	const branchName = `${type}/${name}`;
+
+	// 1. Preconditions
+	const currentBranch = git(["branch", "--show-current"], { cwd: projectRoot });
+	if (currentBranch !== branchName) {
+		return reply(
+			`soly done: currently on "${currentBranch}", not the plan branch "${branchName}".\n` +
+				`Switch first with \`git checkout ${branchName}\`.`,
+		);
+	}
+
+	// Check there's a remote
+	let hasRemote = false;
+	try {
+		git(["remote", "get-url", "origin"], { cwd: projectRoot });
+		hasRemote = true;
+	} catch {
+		// No remote — we'll skip push but still commit
+	}
+
+	// 2. Commit any pending changes (if anything to commit)
+	const statusBefore = git(["status", "--short"], { cwd: projectRoot });
+	let commitHash = git(["rev-parse", "HEAD"], { cwd: projectRoot });
+	if (statusBefore) {
+		// Auto-stage everything not under .agents/ (project files only)
+		try {
+			git(["add", "-A", "--", ":!.agents/"], { cwd: projectRoot });
+			// Re-check after add
+			const statusAfter = git(["status", "--short"], { cwd: projectRoot });
+			if (statusAfter) {
+				git(["commit", "-m", `${type}(${name}): wip`], { cwd: projectRoot });
+			}
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			return reply(`soly done: commit failed — ${msg}`);
+		}
+		commitHash = git(["rev-parse", "HEAD"], { cwd: projectRoot });
+	}
+
+	// 3. Push
+	let pushed = false;
+	if (hasRemote) {
+		try {
+			git(["push", "-u", "origin", branchName], { cwd: projectRoot });
+			pushed = true;
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			ui.notify(`soly done: push failed — ${msg}\nPlan was committed but not pushed. Push manually with \`git push -u origin ${branchName}\`.`, "warning");
+			return {
+				handled: true,
+				transformedText: `Plan ${branchName} committed locally (${commitHash.slice(0, 7)}), but push failed.\n${msg}`,
+				completed: { branch: branchName, commit: commitHash, pushed: false, prUrl: null },
+			};
+		}
+	} else {
+		ui.notify(`soly done: no 'origin' remote — committed locally only. Add a remote and \`git push\` when ready.`, "warning");
+	}
+
+	// 4. Draft PR via gh
+	let prUrl: string | null = null;
+	if (pushed && ghAvailable(opts.ghPath)) {
+		try {
+			prUrl = gh(
+				[
+					"pr",
+					"create",
+					"--draft",
+					"--fill",
+					"--head",
+					branchName,
+				],
+				{ cwd: projectRoot, ghPath: opts.ghPath },
+			);
+		} catch (err) {
+			// gh failed (maybe not authenticated, or PR already exists, etc.)
+			// Don't fail the whole workflow — just report.
+			const msg = err instanceof Error ? err.message : String(err);
+			ui.notify(
+				`soly done: pushed OK, but draft PR creation failed — ${msg}\n` +
+					`Run \`gh pr create --draft --fill\` manually.`,
+				"warning",
+			);
+		}
+	} else if (pushed) {
+		ui.notify(
+			`soly done: pushed OK, but \`gh\` CLI not found — draft PR not created.\n` +
+				`Install \`gh\` (https://cli.github.com) and run \`gh pr create --draft --fill\` manually.`,
+			"info",
+		);
+	}
+
+	// 5. Done — summarize
+	const prLine = prUrl ? `Draft PR: ${prUrl}` : "No draft PR (push or gh step skipped / failed).";
+	const notice =
+		`Plan ${branchName} done.\n` +
+		`  Commit:   ${commitHash.slice(0, 7)}\n` +
+		`  Pushed:   ${pushed ? "yes" : "no (no origin remote)"}\n` +
+		`  ${prLine}`;
+	ui.notify(notice, "info");
+	return {
+		handled: true,
+		transformedText: notice,
+		completed: { branch: branchName, commit: commitHash, pushed, prUrl },
+	};
+}

package/workflows/execute.ts

@@ -73,7 +73,7 @@ export function buildExecuteTransform(
 		return {
 			handled: true,
 			transformedText:
-				`soly: no .soly/ directory found in cwd (${state.solyDir || "<cwd>"}) — cannot execute phase.\n` +
+				`soly: no .agents/ directory found in cwd (${state.solyDir || "<cwd>"}) — cannot execute phase.\n` +
 				`Initialize a soly project first (see soly quickstart) before running "soly execute".`,
 		};
 	}
@@ -101,7 +101,7 @@ export function buildExecuteTransform(
 			return {
 				handled: true,
 				transformedText:
-					`soly execute: task ${target.taskId} not found in .soly/features/*/tasks/.\n` +
+					`soly execute: task ${target.taskId} not found in .agents/features/*/tasks/.\n` +
 					`Known tasks: ${state.tasks.map((t) => t.id).join(", ") || "(none)"}\n` +
 					`Tip: use the \`soly_list_tasks\` tool to see all available tasks.`,
 			};
@@ -155,7 +155,7 @@ export function buildExecuteTransform(
 		const featureDir = path.dirname(path.dirname(task.dir));
 
 		// Write per-iteration context bundle (B2 of the soly design).
-		// Worker reads this file first; no need to chase 6+ .soly/ files.
+		// Worker reads this file first; no need to chase 6+ .agents/ files.
 		const iter = writeIterationContext({
 			solyDir: state.solyDir,
 			projectRoot,
@@ -179,7 +179,7 @@ export function buildExecuteTransform(
 **Iteration context file written:** \`${iter.relPath}\` (${iter.tokens} tokens, ${iter.bytes} bytes)
 The worker reads this file first — it contains intent, STATE, ROADMAP (n/a for tasks), the feature README, prior task SUMMARYs, and the current task PLAN.
 
-**0-POINT CHECK.** Worker must re-read .soly/docs/ (intent) and .soly/features/${task.feature}/README.md before implementing.
+**0-POINT CHECK.** Worker must re-read .agents/docs/ (intent) and .agents/features/${task.feature}/README.md before implementing.
 
 Launch a single subagent for this work. Do NOT do the work inline.
 
@@ -206,12 +206,12 @@ Soly dir:    ${state.solyDir}
 Feature dir: ${featureDir}
 Task dir:    ${task.dir}
 
-**0-POINT CHECK — read .soly/docs/ first.**
+**0-POINT CHECK — read .agents/docs/ first.**
 These are the project's INTENT (business context, design vision). Re-read them before implementing. If you find a conflict between intent and PLAN.md, flag it instead of silently choosing one.
 
-**Follow the worker self-audit gate (see .soly/rules/process/worker-audit.md):**
+**Follow the worker self-audit gate (see .agents/rules/process/worker-audit.md):**
 1. Run \`dotnet build\` (or relevant build) — 0 warnings
-2. Cross-check diff against .soly/rules/coding/*
+2. Cross-check diff against .agents/rules/coding/*
 3. Invoke \`analyzer-coach\` skill for any rule gaps
 4. Loop until clean (max 3 iterations)
 5. Commit (production-code commit(s))
@@ -224,10 +224,10 @@ ${workflow}
 
 Hard rules:
   - Do not skip the close-out order: production commits -> SUMMARY commit -> status: done.
-  - Do not modify any .soly/rules/ files.
+  - Do not modify any .agents/rules/ files.
   - Do not run subagents yourself.
   - Do not start a task whose \`depends-on:\` lists tasks that are not \`done\`.
-  - PATH DISCIPLINE: all files YOU create must live under \`.soly/\` (iteration, handoff, etc.) or under the project's source dirs. Never write to the project root.
+  - PATH DISCIPLINE: all files YOU create must live under \`.agents/\` (iteration, handoff, etc.) or under the project's source dirs. Never write to the project root.
   - Return: changed files, commands run with exit codes, validation evidence, surprises, decisions needing parent approval.
   - Interactive-only rules are NOT in scope for you: ${interactiveRules.length > 0 ? interactiveRules.join(", ") : "(none)"}.
 \`
@@ -248,7 +248,7 @@ When the subagent completes, synthesize the result. Do not re-execute its work.
 				handled: true,
 				transformedText:
 					target.kind === "all"
-						? `soly execute --all: no tasks found in .soly/features/*/tasks/.`
+						? `soly execute --all: no tasks found in .agents/features/*/tasks/.`
 						: `soly execute --feature ${target.feature}: no tasks found for that feature.`,
 			};
 		}
@@ -274,13 +274,102 @@ When the subagent completes, synthesize the result. Do not re-execute its work.
 		};
 	}
 
+	// === PLAN MODE (new dual-mode: `<type>/<name>` plans live under .agents/plans/<name>/) ===
+	if (target.kind === "plan") {
+		const planDirAbs = `${state.solyDir}/plans/${target.name}`;
+		const planFile = `${planDirAbs}/PLAN.md`;
+		let planBody: string;
+		try {
+			planBody = fs.readFileSync(planFile, "utf-8");
+		} catch {
+			return {
+				handled: true,
+				transformedText:
+					`soly execute: plan ${target.raw} has no PLAN.md at ${planFile}.\n` +
+					`Run \`soly plan ${target.raw}\` first to flesh it out.`,
+			};
+		}
+		const workflow = loadWorkflowMarkdown("execute-plan.md");
+		if (!workflow) {
+			return {
+				handled: true,
+				transformedText:
+					`soly execute: workflow markdown not found: workflows-data/execute-plan.md\n` +
+					`This is an extension installation issue — reinstall soly.`,
+			};
+		}
+		// Write per-iteration context bundle so the worker has intent + STATE
+		// + the plan body in one file.
+		const iter = writeIterationContext({
+			solyDir: state.solyDir,
+			projectRoot,
+			kind: "exec",
+			planName: target.name,
+		});
+		const instruction = `soly execute ${target.raw} — executing plan.
+
+**Plan:** ${target.name}
+**Branch:** ${target.raw}
+**PLAN.md:** ${planFile}
+
+**Iteration context file written:** \`${iter.relPath}\` (${iter.tokens} tokens)
+The worker reads this file first — it contains intent, STATE, ROADMAP, the
+plan body inline, and any prior SUMMARYs for this plan (none on first run).
+
+**Inline plan body (so you have must-haves before reading the file):**
+\`\`\`markdown
+${planBody.slice(0, 4000)}${planBody.length > 4000 ? "\n…(truncated)" : ""}
+\`\`\`
+
+**0-POINT CHECK.** Worker must re-read .agents/docs/ (intent) before implementing.
+
+Launch a single subagent to execute the plan. Do NOT do the work inline.
+
+subagent({
+  agent: ${JSON.stringify(opts.agent ?? "worker")},
+  context: "fresh",
+  async: true,
+  maxSubagentDepth: 1,
+  task: \`You are soly-executor. Execute the plan at \`${planFile}\` end-to-end.
+
+**FIRST ACTION — read the iteration context file:**
+\`\`\`
+${iter.relPath}
+\`\`\`
+It contains intent, STATE, ROADMAP, and the full plan body. Do NOT skip it.
+
+Project root: ${projectRoot}
+Soly dir:    ${state.solyDir}
+Plan dir:    ${planDirAbs}
+
+**0-POINT CHECK — read .agents/docs/ first.**
+
+Follow the workflow below VERBATIM.
+
+=== WORKFLOW: execute-plan.md ===
+${workflow}
+=== END WORKFLOW ===
+
+Hard rules:
+  - All work happens on branch \`${target.raw}\`. Do not switch branches.
+  - When the plan is fully executed and verified, write a SUMMARY.md next to
+    PLAN.md summarizing what was done, what was deferred, and any deviations.
+  - Do not commit unless the workflow tells you to; the user reviews and merges.
+\`)
+}`;
+		return { handled: true, transformedText: instruction };
+	}
+
 	// === PHASE MODE ===
+	if (target.kind !== "phase") {
+		return { handled: false };
+	}
 	const phase = state.phases.find((p) => p.number === target.phase);
 	if (!phase) {
 		return {
 			handled: true,
 			transformedText:
-				`soly execute: phase ${target.phase} not found in .soly/phases/.\n` +
+				`soly execute: phase ${target.phase} not found in .agents/phases/.\n` +
 				`Known phases: ${state.phases.map((p) => p.number).join(", ") || "(none)"}`,
 		};
 	}
@@ -358,8 +447,8 @@ The iteration context file lists all plans (their frontmatter) in section 6, gro
 **Iteration context file written:** \`${iter.relPath}\` (${iter.tokens} tokens, ${iter.bytes} bytes)
 The worker reads this file first — it contains intent, STATE, ROADMAP row for this phase, phase CONTEXT, phase RESEARCH, prior SUMMARYs, ${isPlanLevel ? "and the current PLAN" : "and all PLAN frontmatter summaries"}, and (for exec) the Critical Anti-Patterns from .continue-here.md.
 
-**0-POINT CHECK — worker must read .soly/docs/ first.**
-These are the project's INTENT docs. The worker is about to implement tasks; if the implementation diverges from intent, it will be wrong even if the tests pass. Have the worker re-read .soly/docs/ (and any intent docs linked from PLAN.md) before each plan.
+**0-POINT CHECK — worker must read .agents/docs/ first.**
+These are the project's INTENT docs. The worker is about to implement tasks; if the implementation diverges from intent, it will be wrong even if the tests pass. Have the worker re-read .agents/docs/ (and any intent docs linked from PLAN.md) before each plan.
 
 ${scopeBlock}
 
@@ -389,7 +478,7 @@ Project root: ${projectRoot}
 Soly dir:    ${state.solyDir}
 Phase dir:   ${phase.dir}
 
-**0-POINT CHECK — read .soly/docs/ first.**
+**0-POINT CHECK — read .agents/docs/ first.**
 These are the project's INTENT (business context, design vision). Re-read them before implementing each plan. If you find a conflict between intent and PLAN.md, flag it instead of silently choosing one.
 
 Follow the workflow below VERBATIM — these are the user-approved soly instructions, not suggestions.
@@ -400,9 +489,9 @@ ${workflow}
 
 Hard rules:
   - Do not skip the close-out order: production commits -> SUMMARY commit -> STATE/ROADMAP update.
-  - Do not modify any .soly/rules/ files.
+  - Do not modify any .agents/rules/ files.
   - Do not run subagents yourself.
-  - PATH DISCIPLINE: all files YOU create must live under \`.soly/\` (e.g. .soly/iterations/, .soly/phases/<slug>/, .soly/HANDOFF.json) or under the project's source dirs. Never write PLAN/SUMMARY/CONTEXT/RESEARCH/iteration files to the project root.
+  - PATH DISCIPLINE: all files YOU create must live under \`.agents/\` (e.g. .agents/iterations/, .agents/phases/<slug>/, .agents/HANDOFF.json) or under the project's source dirs. Never write PLAN/SUMMARY/CONTEXT/RESEARCH/iteration files to the project root.
   - Return: changed files, commands run with exit codes, validation evidence, surprises, and any decisions needing parent approval.
   - Interactive-only rules are NOT in scope for you: ${interactiveRules.length > 0 ? interactiveRules.join(", ") : "(none)"}. They describe how the user-facing conversation should go, not how to execute work.
 \`

package/workflows/index.ts

@@ -23,8 +23,10 @@ import { buildResumeTransform } from "./resume.ts";
 import { showStatus, showLog, showDiff } from "./quick.ts";
 import { showDoctor, showIterations, showDiffIterations, showPhaseDelete, showTodos } from "./inspect.ts";
 import { buildPlanTransform, buildDiscussTransform } from "./planning.ts";
-import { createVerifyLoop, type VerifyState } from "./verify.ts";
+import { buildNewTransform } from "./new.ts";
+import { buildDoneTransform } from "./done.ts";
 import { buildMigrateTransform } from "./migrate.ts";
+import { createVerifyLoop, type VerifyState } from "./verify.ts";
 import type { ContextManager } from "../context-manager.ts";
 import type { SolyState } from "../core.js";
 import type { SolyConfig } from "../config.js";
@@ -145,8 +147,25 @@ export function registerWorkflows(pi: ExtensionAPI, deps: WorkflowsDeps): void {
 			return { action: "transform", text: result.transformedText };
 		}
 
+		if (cmd.verb === "new") {
+			const result = buildNewTransform(cmd, state, ctx.ui, ctx.cwd);
+			if (!result.handled || !result.transformedText) return;
+			// Direct execution (the workflow already called ui.notify). The
+			// transformed text goes to the model so it can also tell the user
+			// in chat, but the action is "handled" (no LLM round-trip needed).
+			return { action: "transform", text: result.transformedText };
+		}
+
+		if (cmd.verb === "done") {
+			const result = buildDoneTransform(cmd, state, ctx.ui, ctx.cwd);
+			if (!result.handled || !result.transformedText) return;
+			// Direct execution — workflow already called ui.notify. The
+			// transformed text tells the LLM (and the user in chat) what happened.
+			return { action: "transform", text: result.transformedText };
+		}
+
 		if (cmd.verb === "migrate") {
-			const result = buildMigrateTransform(state);
+			const result = buildMigrateTransform(state, ctx.ui, ctx.cwd);
 			if (!result.handled || !result.transformedText) return;
 			return { action: "transform", text: result.transformedText };
 		}
@@ -179,15 +198,12 @@ Lifecycle:
 Quick info (no LLM round-trip):
   status              — position + progress + phases
   log [N]             — last N decisions from STATE.md
-  diff                — git status + uncommitted .soly/ changes
+  diff                — git status + uncommitted .agents/ changes
   doctor              — health check (missing files, broken refs, stale iterations)
   iterations [N]      — recent iteration bundles
   todos               — pi-todo live list
   phase delete <N>    — soft-delete a phase
 
-Maintenance:
-  migrate             — convert a legacy layout (NN-PLAN files / features/) to phases/<N>/tasks/
-
 State inspection lives on the slash form — \`/soly <sub>\`:
   position · state · plan · roadmap · progress · phases · tasks · task <id> ·
   features · milestone · context · research · config · reload
@@ -249,7 +265,7 @@ State inspection lives on the slash form — \`/soly <sub>\`:
 				return {
 					action: "transform",
 					text: `soly phase — usage:
-  soly phase delete <N>   — soft-delete phase N (move to .soly/phases/.trash/)
+  soly phase delete <N>   — soft-delete phase N (move to .agents/phases/.trash/)
   soly phase list        — list all phases (same as /soly phases)
   soly phase <N>         — alias for "soly plan <N>" (route through planner)`,
 				};
@@ -265,8 +281,8 @@ State inspection lives on the slash form — \`/soly <sub>\`:
 		pendingCompact = false;
 		ctx.compact({
 			customInstructions:
-				"Session was paused via `soly compact`. Handoff files are in .soly/HANDOFF.json " +
-				"and .soly/.continue-here.md. Preserve milestone/phase/plan position and key " +
+				"Session was paused via `soly compact`. Handoff files are in .agents/HANDOFF.json " +
+				"and .agents/.continue-here.md. Preserve milestone/phase/plan position and key " +
 				"decisions in the summary. Drop implementation-detail noise.",
 			onComplete: () => {
 				ctx.ui.notify("soly: session compacted. Use `soly resume` to pick up.", "info");