pi-soly 1.14.0 → 1.15.0

package/README.md

@@ -78,14 +78,29 @@ Tracked upstream — fix is expected on the pi side, not here.
 ### Workflow — plain-text verbs (type `soly <verb>`, not slash)
 
 ```bash
-soly discuss 3     # talk through decisions before planning phase 3
-soly plan 3        # generate PLAN.md for phase 3
-soly execute 3     # execute phase 3 (or `soly execute 3.02` for one plan)
-soly verify        # self-review loop until "No issues found." (`soly verify stop` to exit)
-soly pause         # save a handoff; `soly resume` to pick it back up
-soly status        # current position + progress (no LLM round-trip)
+# === Plan mode (recommended for new work — each plan is a git branch) ===
+soly new feat/auth-jwt       # create branch + .agents/plans/<name>/ + stub PLAN.md
+soly discuss feat/auth-jwt   # interactive discussion of the plan
+soly plan feat/auth-jwt      # flesh out PLAN.md via ask_pro
+soly execute feat/auth-jwt   # execute the plan in a subagent
+soly done feat/auth-jwt      # commit, push, open draft PR via gh
+soly verify                  # self-review loop until "No issues found." (soly verify stop to exit)
+soly pause                   # save a handoff; soly resume to pick it back up
+soly status                  # current position + progress (no LLM round-trip)
+
+# === Phase mode (legacy — still works for existing projects) ===
+soly plan 3                  # generate PLAN.md for phase 3 (numeric form)
+soly execute 3               # execute phase 3 (or `soly execute 3.02` for one plan)
+soly migrate phases-to-plans # one-shot: import each .agents/phases/<NN>-slug/plans/PLAN.md
+                             #   as a `migrate/legacy-<NN>-slug` branch with .agents/plans/legacy-<NN>-slug/PLAN.md
 ```
 
+> **Why plans instead of phases?** A global phase counter (1, 2, 3, ...) means two
+> developers each starting a "phase 11" write to the same path. With plans, each
+> is a git branch (`feat/auth-jwt`, `fix/login-redirect`, …) with its own
+> `.agents/plans/<name>/PLAN.md` — no collisions, clean isolation, and the branch
+> list itself is the registry of what's in flight.
+
 ### State inspection (`/soly`)
 
 ```bash

package/iteration.ts

@@ -39,6 +39,8 @@ export interface IterationInput {
 	planNumber?: number;
 	/** Task id (only for task-mode execution / planning). */
 	taskId?: string;
+	/** Plan name (only for plan-mode execution / planning — `.agents/plans/<name>/`). */
+	planName?: string;
 	/** Feature name (only for task-mode). Backfilled from disk if omitted. */
 	feature?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-soly",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "Project management + workflow framework for pi-coding-agent. Plans, state, MANDATORY rules, self-review, multi-question picker, native footer + welcome chrome — one npm install, zero config. The LLM drives execution and delegates to a worker subagent when available.",
   "type": "module",
   "main": "index.ts",

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

@@ -274,7 +274,96 @@ 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 {

package/workflows/index.ts

@@ -23,6 +23,9 @@ 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 { 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";
@@ -144,6 +147,29 @@ 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, ctx.ui, ctx.cwd);
+			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") {

package/workflows/migrate.ts

@@ -0,0 +1,172 @@
+// =============================================================================
+// workflows/migrate.ts — `soly migrate phases-to-plans`
+// =============================================================================
+//
+// 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.
+//
+// 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 * 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 }[];
+}
+
+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; message?: string };
+		const stderr = e.stderr ? e.stderr.toString().trim() : "";
+		throw new Error(`git ${args.join(" ")} failed: ${stderr || e.message || "unknown error"}`);
+	}
+}
+
+/** 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 .agents/ directory in cwd — run /soly init first.",
+			migrated: [],
+			skipped: [],
+		};
+	}
+
+	const phaseDirs = listPhaseDirs(state.solyDir);
+	if (phaseDirs.length === 0) {
+		return {
+			handled: true,
+			transformedText: "soly migrate: no phases found in .agents/phases/. Nothing to migrate.",
+			migrated: [],
+			skipped: [],
+		};
+	}
+
+	// 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";
+	| "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;
@@ -67,7 +100,10 @@ export function parseSolyCommand(text: string): SolyCommand | null {
 		verb !== "iterations" &&
 		verb !== "phase" &&
 		verb !== "todos" &&
-		verb !== "verify"
+		verb !== "verify" &&
+		verb !== "new" &&
+		verb !== "done" &&
+		verb !== "migrate"
 	) {
 		return null;
 	}
@@ -157,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 };
@@ -191,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 };
@@ -212,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 };
@@ -253,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/planning.ts

@@ -15,7 +15,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import { describePlanTarget, type SolyCommand } from "./parser.ts";
+import { describePlanTarget, parsePlanName, type SolyCommand } from "./parser.ts";
 import type { SolyState } from "../core.js";
 import {
 	extractPlanSummary,
@@ -91,8 +91,45 @@ export function buildPlanTransform(cmd: SolyCommand, state: SolyState): Planning
 		};
 	}
 
-	// === PHASE MODE ===
+	// === 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 {
+			planBody = "_No PLAN.md yet — the LLM should ask the user for goal / steps / acceptance and write it from scratch._";
+		}
+		const instruction = `soly plan ${target.raw} — fleshing out PLAN.md for plan.
+
+**Plan:** ${target.name}
+**Branch:** ${target.raw}
+**PLAN.md:** ${planFile}
+
+**Inline current PLAN.md body (so you have the existing TBD sections before reading the file):**
+\`\`\`markdown
+${planBody.slice(0, 4000)}${planBody.length > 4000 ? "\n…(truncated)" : ""}
+\`\`\`
+
+**0-POINT CHECK.** Re-read .agents/docs/ (intent) before fleshing out the plan.
+
+If ask_pro is available, use it ONCE to gather goal / steps / acceptance criteria (freeText questions, batched). Then write PLAN.md with the answers. If ask_pro is NOT available, write a sensible stub plan and tell the user to refine it via \`soly plan ${target.raw}\` again.
+
+Hard rules:
+  - Update ONLY ${planFile}. Don't touch other plans or the project root.
+  - Use Conventional Commits format: # Plan: ${target.raw} (h1), ## Goal, ## Steps, ## Acceptance.
+  - Don't commit — the user reviews and commits.`;
+		return { handled: true, transformedText: instruction };
+	}
+
+	// === PHASE MODE (legacy — see W6 in the plans-instead-of-phases plan) ===
 	if (target.kind === "phase") {
+		const deprecationNotice =
+			"⚠️  PHASE MODE IS LEGACY. Phases have been replaced by plans (each plan = a git branch `<type>/<name>` with `.agents/plans/<name>/PLAN.md`).\n" +
+			"To migrate an existing phase to a plan, run \`soly migrate phases-to-plans\` once.\n" +
+			"For new work, use \`soly new <type>/<name>\` (e.g. \`soly new feat/auth-jwt\`).\n" +
+			"This phase handler still works for backward compat but won't get new features.\n\n";
 		const phase = state.phases.find((p) => p.number === target.phase);
 		if (!phase) {
 			return {
@@ -118,7 +155,7 @@ export function buildPlanTransform(cmd: SolyCommand, state: SolyState): Planning
 			kind: "plan",
 			phaseNumber: target.phase,
 		});
-		const instruction = `soly plan ${target.raw} — planning phase ${target.phase} (${phase.name}).
+		const instruction = deprecationNotice + `soly plan ${target.raw} — planning phase ${target.phase} (${phase.name}).
 
 **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.
@@ -463,13 +500,61 @@ export function buildDiscussTransform(
 	}
 
 	const projectRoot = path.dirname(state.solyDir);
+	const arg = (cmd.args[0] ?? "").trim();
+	if (!arg) {
+		const known = state.phases.map((p) => p.number).join(", ") || "(none)";
+		return {
+			handled: true,
+			transformedText:
+				`soly discuss: argument required.\n` +
+				`Usage:\n` +
+				`  soly discuss <N>             — discuss phase N (legacy)\n` +
+				`  soly discuss <type>/<name>  — discuss plan <type>/<name> (e.g. feat/auth-jwt)\n` +
+				`Known phases: ${known}`,
+		};
+	}
+
+	// Plan mode: `<type>/<name>`
+	const planParsed = parsePlanName(arg);
+	if (!("error" in planParsed)) {
+		const planDirAbs = `${state.solyDir}/plans/${planParsed.name}`;
+		const planFile = `${planDirAbs}/PLAN.md`;
+		let planBody: string;
+		try {
+			planBody = fs.readFileSync(planFile, "utf-8");
+		} catch {
+			planBody = "_No PLAN.md yet._";
+		}
+		const instruction = `soly discuss ${arg} — interactive discussion mode for plan.
+
+**Plan:** ${planParsed.name}
+**Branch:** ${arg}
+**PLAN.md:** ${planFile}
+
+**Inline current PLAN.md body:**
+\`\`\`markdown
+${planBody.slice(0, 4000)}${planBody.length > 4000 ? "\n…(truncated)" : ""}
+\`\`\`
+
+**0-POINT CHECK.** Re-read .agents/docs/ (intent) before discussing.
+
+Use \`soly_finish_discuss\` to capture the discussion outcome. The flow:
+1. Read the plan above.
+2. Identify ambiguities / open questions / scope clarifications.
+3.${hasAskPro ? " Use \`ask_pro\` (batched freeText questions) to resolve them with the user." : " Ask the user ONE clear question at a time via the chat."}
+4. Call \`soly_finish_discuss\` with the captured decision.
+5. Tell the user the next step: \`soly plan ${arg}\` to update PLAN.md with the discussion outcome.`;
+		return { handled: true, transformedText: instruction };
+	}
+
+	// Phase mode (legacy)
 	const target = getPhaseForDiscuss(state, cmd.args);
 	if (!target) {
 		const known = state.phases.map((p) => p.number).join(", ") || "(none)";
 		return {
 			handled: true,
 			transformedText:
-				`soly discuss: phase argument required and must exist.\n` +
+				`soly discuss: bad argument "${arg}".\n` +
 				`Usage: soly discuss <N>    (e.g. "soly discuss 11")\n` +
 				`Known phases: ${known}`,
 		};