pi-soly 1.13.5 → 1.14.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/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.`,
 			};
 		}
@@ -280,7 +280,7 @@ When the subagent completes, synthesize the result. Do not re-execute its work.
 		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 +358,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 +389,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 +400,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

@@ -24,7 +24,6 @@ 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 { buildMigrateTransform } from "./migrate.ts";
 import type { ContextManager } from "../context-manager.ts";
 import type { SolyState } from "../core.js";
 import type { SolyConfig } from "../config.js";
@@ -145,12 +144,6 @@ export function registerWorkflows(pi: ExtensionAPI, deps: WorkflowsDeps): void {
 			return { action: "transform", text: result.transformedText };
 		}
 
-		if (cmd.verb === "migrate") {
-			const result = buildMigrateTransform(state);
-			if (!result.handled || !result.transformedText) return;
-			return { action: "transform", text: result.transformedText };
-		}
-
 		if (cmd.verb === "verify") {
 			const sub = (cmd.args[0] ?? "").toLowerCase();
 			if (sub === "stop" || sub === "off") {
@@ -179,15 +172,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 +239,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 +255,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");

package/workflows/inspect.ts

@@ -6,6 +6,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { solyDirFor } from "../core.js";
 import type { SolyState } from "../core.js";
 import type { SolyConfig } from "../config.js";
 
@@ -28,11 +29,11 @@ interface DoctorCheck {
 export function showDoctor(_cmd: unknown, state: SolyState, ui: InspectUI, config: SolyConfig, activeTools: string[] = []): void {
 	const checks: DoctorCheck[] = [];
 
-	// 1. .soly/ exists
+	// 1. .agents/ exists
 	checks.push({
-		name: ".soly/ directory",
+		name: ".agents/ directory",
 		status: state.exists ? "pass" : "fail",
-		detail: state.exists ? state.solyDir : "no .soly/ found in cwd",
+		detail: state.exists ? state.solyDir : "no .agents/ found in cwd",
 	});
 
 	// 2. STATE.md exists + has frontmatter
@@ -177,13 +178,13 @@ export function showDoctor(_cmd: unknown, state: SolyState, ui: InspectUI, confi
 		}
 	}
 
-	// 9. .soly/rules/ exists if state says rules are loaded
+	// 9. .agents/rules/ exists if state says rules are loaded
 	if (state.exists) {
 		const rulesDir = path.join(state.solyDir, "rules");
 		checks.push({
-			name: ".soly/rules/ directory",
+			name: ".agents/rules/ directory",
 			status: fs.existsSync(rulesDir) ? "pass" : "warn",
-			detail: fs.existsSync(rulesDir) ? "present" : "no rules directory — soly will fall back to ~/.soly/rules/",
+			detail: fs.existsSync(rulesDir) ? "present" : "no rules directory — soly will fall back to ~/.agents/rules/",
 		});
 	}
 
@@ -220,7 +221,7 @@ export function showDoctor(_cmd: unknown, state: SolyState, ui: InspectUI, confi
 			name: "project layout",
 			status: legacy ? "info" : "pass",
 			detail: legacy
-				? "legacy plans/features detected — run `soly migrate` to move to phases/<N>/tasks/"
+				? "legacy plans/features detected — still supported alongside the unified phases/<N>/tasks/ model"
 				: "unified model (phase = group of tasks)",
 		});
 	}
@@ -258,7 +259,7 @@ function pluralDays(n: number): string {
 }
 
 // ---------------------------------------------------------------------------
-// soly todos — read .soly/todos.json or .pi-todos.json and show as a notify.
+// soly todos — read .agents/todos.json or .pi-todos.json and show as a notify.
 // Mirrors what pi-todo would render in the footer, so the user can see
 // todos even when pi-todo extension isn't loaded (e.g. just-installed).
 // ---------------------------------------------------------------------------
@@ -266,7 +267,7 @@ function pluralDays(n: number): string {
 /** Try to find a todo file in cwd. Returns the path or null. */
 function findTodosFile(cwd: string): string | null {
 	const candidates = [
-		path.join(cwd, ".soly", "todos.json"),
+		path.join(solyDirFor(cwd), "todos.json"),
 		path.join(cwd, ".pi-todos.json"),
 	];
 	for (const c of candidates) {
@@ -281,13 +282,13 @@ export function showTodos(
 	ui: InspectUI,
 ): void {
 	if (!state.exists) {
-		ui.notify("soly todos: no .soly/ directory in cwd", "error");
+		ui.notify("soly todos: no .agents/ directory in cwd", "error");
 		return;
 	}
 	const file = findTodosFile(state.solyDir);
 	if (!file) {
 		ui.notify(
-			"soly todos: no todo file found. Install the `pi-todo` extension or write `.soly/todos.json` manually.",
+			"soly todos: no todo file found. Install the `pi-todo` extension or write `.agents/todos.json` manually.",
 			"info",
 		);
 		return;
@@ -329,7 +330,7 @@ export function showIterations(
 	limitDefault: number = 10,
 ): void {
 	if (!state.exists) {
-		ui.notify("soly iterations: no .soly/ directory in cwd", "error");
+		ui.notify("soly iterations: no .agents/ directory in cwd", "error");
 		return;
 	}
 	const iterDir = path.join(state.solyDir, "iterations");
@@ -398,7 +399,7 @@ export function showDiffIterations(
 	ui: InspectUI,
 ): void {
 	if (!state.exists) {
-		ui.notify("soly diff iterations: no .soly/ directory in cwd", "error");
+		ui.notify("soly diff iterations: no .agents/ directory in cwd", "error");
 		return;
 	}
 	const iterDir = path.join(state.solyDir, "iterations");
@@ -456,7 +457,7 @@ export function showPhaseDelete(
 	ui: InspectUI,
 ): void {
 	if (!state.exists) {
-		ui.notify("soly phase delete: no .soly/ directory in cwd", "error");
+		ui.notify("soly phase delete: no .agents/ directory in cwd", "error");
 		return;
 	}
 	if (cmd.args.length < 1) {
@@ -492,7 +493,7 @@ export function showPhaseDelete(
 	out.push(`✓ Phase ${phaseNum} (${phase.name}) moved to .trash/`);
 	out.push(`  ${phase.dir}  →  ${dest}`);
 	out.push("");
-	out.push("To restore: `mv` it back to .soly/phases/");
+	out.push("To restore: `mv` it back to .agents/phases/");
 	out.push("To permanently delete: `rm -rf " + dest + "`");
 	ui.notify(out.join("\n"), "info");
 }

package/workflows/parser.ts

@@ -18,7 +18,7 @@
 /** Verbs currently supported by the workflow handlers. */
 export type WorkflowVerb =
 	| "execute" | "pause" | "compact" | "resume" | "status" | "log" | "diff"
-	| "plan" | "discuss" | "help" | "doctor" | "iterations" | "phase" | "todos" | "verify" | "migrate";
+	| "plan" | "discuss" | "help" | "doctor" | "iterations" | "phase" | "todos" | "verify";
 
 export interface SolyCommand {
 	verb: WorkflowVerb;
@@ -67,8 +67,7 @@ export function parseSolyCommand(text: string): SolyCommand | null {
 		verb !== "iterations" &&
 		verb !== "phase" &&
 		verb !== "todos" &&
-		verb !== "verify" &&
-		verb !== "migrate"
+		verb !== "verify"
 	) {
 		return null;
 	}

package/workflows/pause.ts

@@ -7,8 +7,8 @@
 //
 // Like execute, we transform the input into a detailed LLM instruction that
 // walks the LLM through the soly pause-work workflow. The LLM produces both:
-//   - .soly/HANDOFF.json  (machine-readable state for resume)
-//   - .soly/.continue-here.md  (human-readable context)
+//   - .agents/HANDOFF.json  (machine-readable state for resume)
+//   - .agents/.continue-here.md  (human-readable context)
 //
 // For `compact`, we additionally call ctx.compact() AFTER the handoff files
 // are written — but we still let the LLM drive the handoff generation, since
@@ -94,7 +94,7 @@ export function buildPauseTransform(
 		return {
 			handled: true,
 			transformedText:
-				`soly: no .soly/ directory found in cwd (${state.solyDir || "<cwd>"}) — nothing to pause.\n` +
+				`soly: no .agents/ directory found in cwd (${state.solyDir || "<cwd>"}) — nothing to pause.\n` +
 				`If you wanted to start a soly project, see the soly quickstart.`,
 			triggerCompact: false,
 		};
@@ -122,7 +122,7 @@ export function buildPauseTransform(
 
 ${actionLine}
 
-Current position (from .soly/STATE.md):
+Current position (from .agents/STATE.md):
 ${state.position
 	? `  phase: ${state.position.phase}\n  plan:  ${state.position.plan}\n  status: ${state.position.status}`
 	: "  (no position set — likely pre-planning or paused at a milestone boundary)"}
@@ -139,7 +139,7 @@ Follow the workflow below VERBATIM — these are the user-approved soly instruct
 ${workflow}
 === END WORKFLOW ===
 
-After you write both .soly/HANDOFF.json and .soly/.continue-here.md, tell the user:
+After you write both .agents/HANDOFF.json and .agents/.continue-here.md, tell the user:
   - where the files were written (absolute paths)
   - the resume command: soly resume
   - ${isCompact ? "session will be compacted at end of this turn" : "session state preserved as-is"}

package/workflows/planning.ts

@@ -67,7 +67,7 @@ export function buildPlanTransform(cmd: SolyCommand, state: SolyState): Planning
 		return {
 			handled: true,
 			transformedText:
-				`soly plan: no .soly/ directory in cwd (${state.solyDir || "<cwd>"}) — cannot plan.\n` +
+				`soly plan: no .agents/ directory in cwd (${state.solyDir || "<cwd>"}) — cannot plan.\n` +
 				`Initialize a soly project first.`,
 		};
 	}
@@ -123,8 +123,8 @@ export function buildPlanTransform(cmd: SolyCommand, state: SolyState): Planning
 **Iteration context file written:** \`${iter.relPath}\` (${iter.tokens} tokens, ${iter.bytes} bytes)
 The planner reads this file first — it contains intent, STATE, ROADMAP row for this phase, phase CONTEXT, phase RESEARCH, and prior SUMMARYs.
 
-**0-POINT CHECK — read .soly/docs/ first.**
-These documents hold the project's INTENT — business context, design vision, what the user wants this app to be. Plans that ignore intent produce code that "works" but doesn't fit. If the plan would diverge from anything in .soly/docs/, surface that as a discussion point before committing to it.
+**0-POINT CHECK — read .agents/docs/ first.**
+These documents hold the project's INTENT — business context, design vision, what the user wants this app to be. Plans that ignore intent produce code that "works" but doesn't fit. If the plan would diverge from anything in .agents/docs/, surface that as a discussion point before committing to it.
 
 Phase directory: ${phase.dir}
 Current state:   planCount=${phase.planCount}, context=${phase.contextExists}, research=${phase.researchExists}
@@ -155,11 +155,11 @@ ${workflow}
 
 Hard rules:
   - Do not write production code. Planning only.
-  - One task = one PLAN.md under .soly/phases/<NN>-<slug>/tasks/<task-id>/ (task id = <short-slug>-<4hex>).
+  - One task = one PLAN.md under .agents/phases/<NN>-<slug>/tasks/<task-id>/ (task id = <short-slug>-<4hex>).
   - Each task PLAN.md starts with frontmatter: id, kind, status: ready, depends-on: [task ids], optional feature. The cross-task dependency graph must be acyclic.
   - Each task PLAN needs requirements, must_haves.truths, must_haves.artifacts, must_haves.key_links.
-  - PATH DISCIPLINE: all task PLAN.md / phase CONTEXT.md / RESEARCH.md go under \`.soly/phases/<NN>-<slug>/\`. Never write to the project root.
-  - Update .soly/STATE.md Current Position at the end.
+  - PATH DISCIPLINE: all task PLAN.md / phase CONTEXT.md / RESEARCH.md go under \`.agents/phases/<NN>-<slug>/\`. Never write to the project root.
+  - Update .agents/STATE.md Current Position at the end.
   - Return: created task ids, the dependency order (which tasks are ready first), open questions.
 \`
 })
@@ -231,7 +231,7 @@ The planner reads this file first — it contains intent, STATE, the feature REA
 **Inline plan summary (so you have the must-haves even before reading the file):**
 ${inlineSummary}
 
-**0-POINT CHECK.** Re-read .soly/docs/ (intent) and .soly/features/${task.feature}/README.md (feature context) before refining the plan.
+**0-POINT CHECK.** Re-read .agents/docs/ (intent) and .agents/features/${task.feature}/README.md (feature context) before refining the plan.
 
 This task already has PLAN.md. Your job is to flesh it out / improve it based on intent and feature context — not to start from scratch.
 
@@ -265,7 +265,7 @@ Hard rules:
   - Preserve the existing frontmatter (id, kind, feature, status, etc.) — only update if you find a bug.
   - If you change the plan body materially, commit it as \`chore(tasks): refine plan <task-id>\`.
   - If you only add small clarifications, no commit needed (or include in same commit).
-  - PATH DISCIPLINE: PLAN.md lives at \`.soly/features/<feature>/tasks/<id>/PLAN.md\`. Never write to the project root.
+  - PATH DISCIPLINE: PLAN.md lives at \`.agents/features/<feature>/tasks/<id>/PLAN.md\`. Never write to the project root.
   - Return: what changed, open questions, dependencies discovered.
 \`
 })
@@ -289,8 +289,8 @@ When the subagent returns, summarize what was refined. Do not execute — planni
 				return {
 					handled: true,
 					transformedText:
-						`soly plan: could not create .soly/features/${target.feature}/tasks/ (${(e as Error).message}). ` +
-						`Create it manually: \`mkdir -p .soly/features/${target.feature}/tasks/\``,
+						`soly plan: could not create .agents/features/${target.feature}/tasks/ (${(e as Error).message}). ` +
+						`Create it manually: \`mkdir -p .agents/features/${target.feature}/tasks/\``,
 				};
 			}
 			try {
@@ -305,8 +305,8 @@ When the subagent returns, summarize what was refined. Do not execute — planni
 				return {
 					handled: true,
 					transformedText:
-						`soly plan: created .soly/features/${target.feature}/tasks/ but failed to write README.md (${(e as Error).message}). ` +
-						`Continue manually: \`touch .soly/features/${target.feature}/README.md\``,
+						`soly plan: created .agents/features/${target.feature}/tasks/ but failed to write README.md (${(e as Error).message}). ` +
+						`Continue manually: \`touch .agents/features/${target.feature}/README.md\``,
 				};
 			}
 			// Re-read state so the planner sees the new feature
@@ -331,13 +331,13 @@ When the subagent returns, summarize what was refined. Do not execute — planni
 **Slug:** ${target.slug}
 **Feature README:** ${featureDir}/README.md
 
-**0-POINT CHECK.** Re-read .soly/docs/ (intent) and .soly/features/${target.feature}/README.md (feature context) before planning.
+**0-POINT CHECK.** Re-read .agents/docs/ (intent) and .agents/features/${target.feature}/README.md (feature context) before planning.
 
 **Step 1 — generate task ID.** The task ID is \`<slug>-<4hex>\` (e.g. \`${target.slug}-a3f9\`). Generate 4 lowercase hex chars (use \`crypto.randomBytes(2).toString('hex')\` in node, or any 4-char [0-9a-f]{4} string if you don't have a shell handy).
 
 **Step 2 — create the dir:**
 \`\`\`
-mkdir -p .soly/features/${target.feature}/tasks/<id>
+mkdir -p .agents/features/${target.feature}/tasks/<id>
 \`\`\`
 
 **Step 3 — write PLAN.md** with the frontmatter below + the plan body.
@@ -379,7 +379,7 @@ ${workflow}
 Hard rules:
   - Do not write production code. Planning only.
   - Generate the task id as \`<slug>-<4hex>\` (e.g. \`${target.slug}-a3f9\`) — use 4 lowercase hex chars.
-  - Create the dir \`.soly/features/${target.feature}/tasks/<id>/\` first.
+  - Create the dir \`.agents/features/${target.feature}/tasks/<id>/\` first.
   - Write PLAN.md with the frontmatter (id, kind, feature, status: ready, priority, parallelizable, depends-on).
   - Pick a \`kind:\` value matching the work (be|fe|infra|docs|integration).
   - Pick a reasonable \`priority:\` (default: medium).
@@ -457,7 +457,7 @@ export function buildDiscussTransform(
 		return {
 			handled: true,
 			transformedText:
-				`soly discuss: no .soly/ directory in cwd (${state.solyDir || "<cwd>"}) — cannot discuss.\n` +
+				`soly discuss: no .agents/ directory in cwd (${state.solyDir || "<cwd>"}) — cannot discuss.\n` +
 				`Initialize a soly project first.`,
 		};
 	}
@@ -594,7 +594,7 @@ soly_ask_user({
        { category: "<cat>", choice: "<what was chosen>", rationale: "<why>" },
        ...
      ],
-     canonical_refs: [".soly/docs/<file>", ".soly/ROADMAP.md", ...],
+     canonical_refs: [".agents/docs/<file>", ".agents/ROADMAP.md", ...],
      deferred_ideas: ["<scope creep for future phase>", ...],
      codebase_context: ["src/components/Card.tsx — has rounded/shadow variants, reuse", ...],
    })
@@ -608,7 +608,7 @@ soly_ask_user({
 - ${hasAskPro ? "`ask_pro` — multi-question tabbed picker (PREFERRED)" : "`soly_ask_user` — single-question picker (fallback)"}
 - \`soly_save_discuss_checkpoint\` — save partial progress (use after each answer)
 - \`soly_finish_discuss\` — finalize: writes CONTEXT.md, deletes checkpoint
-- \`soly_read\`, \`soly_snippet\`, \`soly_doc_search\` — read .soly/ artifacts as needed (intent docs are already in your system prompt)
+- \`soly_read\`, \`soly_snippet\`, \`soly_doc_search\` — read .agents/ artifacts as needed (intent docs are already in your system prompt)
 - \`soly_log_decision\` — log to STATE.md Decisions table (use sparingly)
 - Standard pi tools: \`read\`, \`bash\`, \`grep\`, \`find\` for codebase context