pi-soly 1.13.5 → 1.15.0

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/migrate.ts

@@ -1,85 +1,172 @@
 // =============================================================================
-// workflows/migrate.ts — `soly migrate`: legacy layout → unified (LLM-runnable)
+// workflows/migrate.ts — `soly migrate phases-to-plans`
 // =============================================================================
 //
-// The unified model is `phases/<N>/tasks/<id>/PLAN.md`. Two legacy shapes need
-// converting:
-//   - standalone plan files `phases/<N>/<NN-MM>-PLAN.md` (+ *-SUMMARY.md)
-//   - the separate features model `features/<f>/tasks/<id>/`
+// One-shot migration from the legacy phase layout to the new plan layout.
+// Reads each phase under `.agents/phases/<NN>-<slug>/`, creates a branch
+// `migrate/legacy-<NN>-<slug>`, copies `plans/PLAN.md` to
+// `.agents/plans/legacy-<NN>-<slug>/PLAN.md`, and commits.
 //
-// Conversion is semantic (derive a task id/kind/deps from a plan), so we hand
-// the model a careful, verify-before-delete protocol rather than doing blind
-// file moves in the extension. Returns a transform the LLM executes inline.
+// The user is responsible for merging the migration branch into main.
+// We don't auto-push.
+//
+// Phases whose branch already exists are skipped (re-running is a no-op
+// for them). Phases without `plans/PLAN.md` are also skipped.
 // =============================================================================
 
-import type { SolyState } from "../core.ts";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { execFileSync } from "node:child_process";
+import type { SolyState } from "../core.js";
+
+export interface MigrateResult {
+	handled: boolean;
+	transformedText?: string;
+	migrated: { phase: string; branch: string; planPath: string }[];
+	skipped: { phase: string; reason: string }[];
+}
 
-export type MigrateResult = { handled: boolean; transformedText?: string };
+type Notifier = {
+	notify: (text: string, level?: "info" | "warning" | "error") => void;
+};
 
-/** Phases that still use legacy standalone plan files and have no tasks/ yet. */
-function legacyPhases(state: SolyState): string[] {
-	return state.phases
-		.filter((p) => p.plans.length > 0 && (!p.tasks || p.tasks.length === 0))
-		.map((p) => `${p.slug} (${p.plans.length} plan${p.plans.length === 1 ? "" : "s"})`);
+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; message?: string };
+		const stderr = e.stderr ? e.stderr.toString().trim() : "";
+		throw new Error(`git ${args.join(" ")} failed: ${stderr || e.message || "unknown error"}`);
+	}
 }
 
-export function buildMigrateTransform(state: SolyState): MigrateResult {
+/** List phase dirs under `<solyDir>/phases/` (any NN-prefix). */
+function listPhaseDirs(solyDir: string): string[] {
+	const phasesRoot = path.join(solyDir, "phases");
+	if (!fs.existsSync(phasesRoot)) return [];
+	return fs
+		.readdirSync(phasesRoot, { withFileTypes: true })
+		.filter((d) => d.isDirectory())
+		.map((d) => d.name);
+}
+
+/** Derive `<NN>-<slug>` from a phase dir name. Returns number as string to
+ *  preserve the leading zero (`03` → `"03"`, not `3`). */
+function parsePhaseName(dirName: string): { number: string; slug: string } | null {
+	const m = dirName.match(/^(\d+)-(.+)$/);
+	if (!m) return null;
+	return { number: m[1], slug: m[2] };
+}
+
+export function buildMigrateTransform(
+	state: SolyState,
+	ui: Notifier,
+	projectRoot: string,
+): MigrateResult {
 	if (!state.exists) {
 		return {
 			handled: true,
-			transformedText:
-				`soly migrate: no .soly/ project in this directory — nothing to migrate.`,
+			transformedText: "soly migrate: no .agents/ directory in cwd — run /soly init first.",
+			migrated: [],
+			skipped: [],
 		};
 	}
 
-	const phases = legacyPhases(state);
-	const features = state.features.map((f) => `${f.slug} (${f.taskCount} task${f.taskCount === 1 ? "" : "s"})`);
-
-	if (phases.length === 0 && features.length === 0) {
+	const phaseDirs = listPhaseDirs(state.solyDir);
+	if (phaseDirs.length === 0) {
 		return {
 			handled: true,
-			transformedText:
-				`soly migrate: already on the unified model (phase = group of tasks). Nothing to migrate.`,
+			transformedText: "soly migrate: no phases found in .agents/phases/. Nothing to migrate.",
+			migrated: [],
+			skipped: [],
 		};
 	}
 
-	const detected: string[] = [];
-	if (phases.length > 0) detected.push(`- Legacy plan files in: ${phases.join(", ")}`);
-	if (features.length > 0) detected.push(`- Legacy \`features/\` dirs: ${features.join(", ")}`);
-
-	return {
-		handled: true,
-		transformedText: `soly migrate — convert the legacy layout to the unified model (phase = group of tasks).
-
-Target layout:
-  .soly/phases/<N>/tasks/<task-id>/PLAN.md   (frontmatter: id, kind, status, depends-on, feature?)
-  .soly/phases/<N>/tasks/<task-id>/SUMMARY.md
-
-Detected legacy artifacts:
-${detected.join("\n")}
-
-Do the conversion YOURSELF, carefully, one item at a time. NEVER delete an old file until the new one is written and you've confirmed its contents. Use \`soly_read\` / \`soly_snippet\` to read, your file tools to write/move.
-
-**A. For each legacy plan \`phases/<N>/<NN-MM>-PLAN.md\`:**
-1. Read it. Derive a stable task id \`<short-slug>-<4hex>\` from the plan's title/intent (lowercase, hyphenated, e.g. \`auth-login-a3f9\`).
-2. Write \`phases/<N>/tasks/<id>/PLAN.md\` with frontmatter, then the original body unchanged:
-   \`\`\`
-   ---
-   id: <id>
-   kind: <be|fe|infra|docs|test>   # infer from the plan
-   status: <ready|done>            # done if a matching *-SUMMARY.md exists
-   depends-on: []                  # fill if the plan depends on earlier plans/tasks
-   ---
-   <original plan body>
-   \`\`\`
-3. If a matching \`<NN-MM>-SUMMARY.md\` exists, move it to \`phases/<N>/tasks/<id>/SUMMARY.md\`.
-4. Verify the new files exist and read correctly, THEN delete the old \`<NN-MM>-PLAN.md\` and its \`*-SUMMARY.md\`.
-
-**B. For each \`features/<f>/tasks/<id>/\`:**
-1. Decide which phase it belongs to (ask the user with \`ask_pro\` if it's not obvious from the task/feature).
-2. Move the whole task dir to \`phases/<N>/tasks/<id>/\` and add \`feature: <f>\` to its PLAN.md frontmatter.
-3. When a feature's tasks are all moved, remove the now-empty \`features/<f>/\`.
-
-**Close out:** update any path references in STATE.md / ROADMAP.md, run \`soly status\` and \`soly doctor\` to confirm the new layout loads, then commit. Report a short summary of what moved (counts + any tasks you couldn't place).`,
-	};
+	// Make sure we're on master (migration creates new branches, not from here)
+	let currentBranch = git(["branch", "--show-current"], { cwd: projectRoot }) || "master";
+	if (currentBranch === "HEAD") currentBranch = "master"; // detached HEAD
+	if (currentBranch !== "master" && currentBranch !== "main") {
+		// Auto-stash + checkout master. We could just refuse, but that's annoying.
+		try {
+			git(["checkout", "master"], { cwd: projectRoot });
+		} catch {
+			try {
+				git(["checkout", "main"], { cwd: projectRoot });
+			} catch {
+				return {
+					handled: true,
+					transformedText: `soly migrate: current branch is "${currentBranch}". Switch to master/main first.`,
+					migrated: [],
+					skipped: [],
+				};
+			}
+		}
+	}
+
+	const migrated: MigrateResult["migrated"] = [];
+	const skipped: MigrateResult["skipped"] = [];
+
+	for (const dirName of phaseDirs) {
+		const parsed = parsePhaseName(dirName);
+		if (!parsed) {
+			skipped.push({ phase: dirName, reason: "doesn't match NN-name pattern" });
+			continue;
+		}
+		const branchName = `migrate/legacy-${parsed.number}-${parsed.slug}`;
+		const planSource = path.join(state.solyDir, "phases", dirName, "plans", "PLAN.md");
+		const planTarget = path.join(state.solyDir, "plans", `legacy-${parsed.number}-${parsed.slug}`, "PLAN.md");
+
+		// Skip if no PLAN.md
+		if (!fs.existsSync(planSource)) {
+			skipped.push({ phase: dirName, reason: "no PLAN.md under plans/" });
+			continue;
+		}
+
+		// Skip if branch already exists
+		let branchExists = false;
+		try {
+			git(["rev-parse", "--verify", branchName], { cwd: projectRoot });
+			branchExists = true;
+		} catch {
+			// not found — we'll create
+		}
+		if (branchExists) {
+			skipped.push({ phase: dirName, reason: `branch ${branchName} already exists` });
+			continue;
+		}
+
+		// Create branch and copy file
+		try {
+			git(["checkout", "-b", branchName], { cwd: projectRoot });
+			fs.mkdirSync(path.dirname(planTarget), { recursive: true });
+			fs.copyFileSync(planSource, planTarget);
+			const planTargetRel = `.agents/plans/legacy-${parsed.number}-${parsed.slug}/PLAN.md`;
+			git(["add", planTargetRel], { cwd: projectRoot });
+			git(["commit", "-m", `migrate: import phase ${dirName} as plan`], { cwd: projectRoot });
+			migrated.push({ phase: dirName, branch: branchName, planPath: planTarget });
+		} catch (err) {
+			skipped.push({ phase: dirName, reason: `git error: ${err instanceof Error ? err.message : String(err)}` });
+		}
+	}
+
+	// Stay on the last migration branch so the user can inspect the result.
+	// (We used to checkout back to master, but that removes the new PLAN.md
+	// files from the working tree since they only exist on the migration
+	// branch. The user can `git checkout master` when ready.)
+
+	const notice =
+		`soly migrate: ${migrated.length} migrated, ${skipped.length} skipped.\n` +
+		(migrated.length > 0
+			? migrated.map((m) => `  + ${m.phase} → ${m.branch}`).join("\n") + "\n"
+			: "") +
+		(skipped.length > 0
+			? skipped.map((s) => `  ! ${s.phase}: ${s.reason}`).join("\n") + "\n"
+			: "") +
+		`\nPush and PR the migration branches manually: \`git push origin <branch>\`.`;
+	ui.notify(`soly migrate: ${migrated.length} migrated, ${skipped.length} skipped`, "info");
+	return { handled: true, transformedText: notice, migrated, skipped };
 }

package/workflows/new.ts

@@ -0,0 +1,159 @@
+// =============================================================================
+// workflows/new.ts — `soly new <type>/<name>` handler
+// =============================================================================
+//
+// Direct workflow (NOT a transform): creates a git branch of the form
+// `<type>/<name>`, makes `.agents/plans/<name>/` on that branch, and writes
+// a stub PLAN.md with TBD sections that the user fills in later via
+// `soly plan <type>/<name>`. Plain `soly new ...` from chat just works.
+//
+// `<type>` is a Conventional Commits type (`feat`, `fix`, `chore`, ...).
+// `<name>` is kebab-case. Branch name = `<type>/<name>`, plan directory is
+// `.agents/plans/<name>/` (the type prefix is part of branch identity only).
+// Returns `{ handled: false }` if the user typed something other than the
+// prefix (e.g. `soly something-else`) so the regular handler can run.
+// =============================================================================
+
+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 NewResult {
+	handled: boolean;
+	transformedText?: string;
+	/** On success: branch created, plan dir + stub PLAN.md written, committed. */
+	scaffolded?: { branch: string; planPath: string };
+}
+
+/** We only call `notify` on the UI. Structural type so tests can fake it. */
+export type Notifier = {
+	notify: (text: string, level?: "info" | "warning" | "error") => void;
+};
+
+/** Run `git <args>` and capture stdout. Throws with stderr context on error. */
+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"}`);
+	}
+}
+
+/** Stub PLAN.md body with TBD sections; `soly plan` fills these in later. */
+function stubPlanMarkdown(branchName: string): string {
+	return `# Plan: ${branchName}
+
+_Stub — fill in via \`soly plan ${branchName}\` (uses ask_pro to gather goal / steps / acceptance criteria)._
+
+## Goal
+
+<!-- What does this plan deliver? 1-2 sentences. -->
+
+## Steps
+
+<!-- High-level breakdown. ~3-7 bullets. -->
+
+## Acceptance
+
+<!-- How will we know the plan is done? -->
+`;
+}
+
+/**
+ * Build an error/notification text (also returned as `handled: true,
+ * transformedText` so the caller shows it; for direct execution the
+ * workflow also calls `ui.notify` with the same string).
+ */
+function reply(text: string): NewResult {
+	return { handled: true, transformedText: text };
+}
+
+export function buildNewTransform(
+	cmd: SolyCommand,
+	state: SolyState,
+	ui: Notifier,
+	projectRoot: string,
+): NewResult {
+	if (!state.exists) {
+		return reply(`soly new: no .agents/ directory in cwd — run /soly init first.`);
+	}
+
+	const parsed = parsePlanName(cmd.args.join(" "));
+	if ("error" in parsed) return reply(`soly new: ${parsed.error}`);
+
+	const { type, name } = parsed;
+	const branchName = `${type}/${name}`;
+	// Path used by `git add`/`commit` — relative to projectRoot (where `.git/` is).
+	// The plan lives at `<root>/.agents/plans/<name>/`, so the repo-relative path
+	// is `.agents/plans/<name>`.
+	const planDirRel = `.agents/plans/${name}`;
+	const planDirAbs = `${state.solyDir}/plans/${name}`;
+	const planFile = `${planDirAbs}/PLAN.md`;
+
+	// 1. Preconditions
+	try {
+		git(["rev-parse", "--is-inside-work-tree"], { cwd: projectRoot });
+	} catch {
+		return reply(`soly new: not in a git repository (cwd: ${projectRoot}). Run \`git init\` first.`);
+	}
+
+	const statusOut = git(["status", "--short"], { cwd: projectRoot });
+	// Ignore our own planned files if they're present but untracked — that
+	// can happen if a previous `soly new` died mid-flight. Anything else
+	// (untracked or modified tracked files) is the user's responsibility.
+	if (statusOut) {
+		return reply(
+			`soly new: working tree has uncommitted changes:\n\n${statusOut}\n\n` +
+				`Commit or stash them first.`,
+		);
+	}
+
+	const currentBranch = git(["branch", "--show-current"], { cwd: projectRoot }) || "HEAD (detached)";
+	if (currentBranch !== "master" && currentBranch !== "main" && !/^[a-z]+\//.test(currentBranch)) {
+		return reply(
+			`soly new: currently on "${currentBranch}" (not master/main, not a soly plan branch). ` +
+				`Switch back to master first with \`git checkout master\`.`,
+		);
+	}
+
+	let branchExisted = false;
+	try {
+		git(["rev-parse", "--verify", branchName], { cwd: projectRoot });
+		// Branch already exists — switch to it instead of creating
+		branchExisted = true;
+		git(["checkout", branchName], { cwd: projectRoot });
+	} catch {
+		// Branch doesn't exist — create it
+		git(["checkout", "-b", branchName], { cwd: projectRoot });
+	}
+
+	try {
+		// 2. Scaffold plan dir + stub PLAN.md
+		fs.mkdirSync(planDirAbs, { recursive: true });
+		fs.writeFileSync(planFile, stubPlanMarkdown(branchName), "utf-8");
+
+		// 3. Commit (separate from working-tree check so the new files show)
+		git(["add", planDirRel], { cwd: projectRoot });
+		git(["commit", "-m", `plan: scaffold ${branchName}`], { cwd: projectRoot });
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		return reply(`soly new: scaffold failed — ${msg}\nYou may need to manually clean up branch ${branchName}.`);
+	}
+
+	const notice = branchExisted
+		? `Plan '${name}' reused on existing branch ${branchName}.\nPLAN.md was ${planFile}.\nNext: \`soly plan ${branchName}\``
+		: `Plan '${name}' scaffolded on new branch ${branchName}.\nPLAN.md: ${planFile}\nNext: \`soly plan ${branchName}\``;
+	ui.notify(notice, "info");
+	return {
+		handled: true,
+		transformedText: notice,
+		scaffolded: { branch: branchName, planPath: planFile },
+	};
+}

package/workflows/parser.ts

@@ -18,7 +18,40 @@
 /** 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"
+	| "new" | "done" | "migrate";
+
+/** Allowed Conventional Commits types for `soly new` / `soly plan <type>/<name>` / etc. */
+export const PLAN_TYPES = ["feat", "fix", "chore", "refactor", "docs", "test", "perf", "build", "ci"] as const;
+
+/**
+ * Validate `<type>/<name>` (e.g. `feat/auth-jwt`). Returns parsed parts or
+ * an error message. Pure — no I/O. Shared by `soly new` (workflows/new.ts)
+ * and the plan-mode dispatch in `describePlanTarget` / `describeExecuteTarget`.
+ */
+export function parsePlanName(raw: string): { type: string; name: string } | { error: string } {
+	const trimmed = raw.trim();
+	if (!trimmed) return { error: "missing plan name" };
+	const m = trimmed.match(/^([a-z]+)\/([a-z0-9][a-z0-9-]*[a-z0-9])$/);
+	if (!m) {
+		return {
+			error:
+				`bad plan name "${trimmed}".\n` +
+				`\nExpected: <type>/<name>\n` +
+				`  type  = one of ${PLAN_TYPES.join(", ")}\n` +
+				`  name  = kebab-case\n` +
+				`\nExample: soly plan feat/auth-jwt`,
+		};
+	}
+	const [, type, name] = m;
+	if (!(PLAN_TYPES as readonly string[]).includes(type as string)) {
+		return { error: `bad type "${type}". Must be one of: ${PLAN_TYPES.join(", ")}` };
+	}
+	if ((name as string).length > 64) {
+		return { error: `name "${name}" is too long (max 64 chars)` };
+	}
+	return { type: type as string, name: name as string };
+}
 
 export interface SolyCommand {
 	verb: WorkflowVerb;
@@ -68,6 +101,8 @@ export function parseSolyCommand(text: string): SolyCommand | null {
 		verb !== "phase" &&
 		verb !== "todos" &&
 		verb !== "verify" &&
+		verb !== "new" &&
+		verb !== "done" &&
 		verb !== "migrate"
 	) {
 		return null;
@@ -158,6 +193,7 @@ function parseNewTaskFlag(
  */
 export type ExecuteTarget =
 	| { kind: "phase"; phase: number; plan: number | null; raw: string }
+	| { kind: "plan"; type: string; name: string; raw: string }
 	| { kind: "task"; taskId: string; raw: string }
 	| { kind: "all"; raw: string }
 	| { kind: "feature"; feature: string; raw: string };
@@ -192,6 +228,12 @@ export function describeExecuteTarget(args: string[]): ExecuteTarget | null {
 	const target = positional.trim();
 	if (!target) return null;
 
+	// <type>/<name> plan name — same identifier model as `soly new`.
+	const plan = parsePlanName(target);
+	if (!("error" in plan)) {
+		return { kind: "plan", type: plan.type, name: plan.name, raw };
+	}
+
 	const phase = parsePhaseShape(target);
 	if (phase) {
 		return { kind: "phase", phase: phase.phase, plan: phase.plan, raw };
@@ -213,12 +255,14 @@ export function describeExecuteTarget(args: string[]): ExecuteTarget | null {
  * What `soly plan ...` should target. Dual-mode with execute.
  *
  *   phase    — plan a phase
+ *   plan     — plan a `<type>/<name>` plan (`.agents/plans/<name>/PLAN.md`)
  *   task     — plan (write/flesh out PLAN.md for) an existing task
  *   new-task — create a brand-new task dir + PLAN.md (with frontmatter)
  *   feature  — plan all ready tasks in a feature
  */
 export type PlanTarget =
 	| { kind: "phase"; phase: number; raw: string }
+	| { kind: "plan"; type: string; name: string; raw: string }
 	| { kind: "task"; taskId: string; raw: string }
 	| { kind: "new-task"; slug: string; feature: string; raw: string }
 	| { kind: "feature"; feature: string; raw: string };
@@ -254,6 +298,13 @@ export function describePlanTarget(args: string[]): PlanTarget | null {
 	const target = positional.trim();
 	if (!target) return null;
 
+	// <type>/<name> plan name (e.g. feat/auth-jwt) — plans live at
+	// .agents/plans/<name>/PLAN.md, identity is the branch name.
+	const plan = parsePlanName(target);
+	if (!("error" in plan)) {
+		return { kind: "plan", type: plan.type, name: plan.name, raw };
+	}
+
 	// Plan target only matches plain N (no .MM — plan is per-phase, executed
 	// at the phase level by `soly execute <N.MM>`).
 	const phase = parsePhaseOnlyShape(target);

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"}