pi-soly 1.13.4 → 1.14.0

package/skills/soly-framework/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: soly-framework
-description: Use when the user invokes soly workflow commands (`/plan`, `/execute`, `/discuss`, `/inspect`, `/pause`, `/resume`, `/quick`, `/soly-init`, `/soly-migrate`, `/soly-status`, `/soly-log`) or asks how to use soly in pi-coding-agent — phases, plans, tasks, intent docs, ROADMAP/STATE state machine, rules, close-out order, and the available soly_* tools. Loaded as the complete reference for managing a soly project end-to-end (init → plan → execute → summary → state update).
+description: Use when the user invokes soly workflow commands (`/plan`, `/execute`, `/discuss`, `/inspect`, `/pause`, `/resume`, `/quick`, `/soly init`, `/soly-status`, `/soly-log`) or asks how to use soly in pi-coding-agent — phases, plans, tasks, intent docs, ROADMAP/STATE state machine, rules, close-out order, and the available soly_* tools. Loaded as the complete reference for managing a soly project end-to-end (init → plan → execute → summary → state update).
 priority: high
 ---
 
@@ -12,9 +12,9 @@ The **soly** extension adds project-management workflow to [pi-coding-agent](htt
 
 **Mental model — three layers, always in system prompt, in this order:**
 
-1. **Project intent** (`.soly/docs/`) — the 0-point. What the user wants the app to be. Written BEFORE plans, by humans.
-2. **Project state** (`.soly/STATE.md`, `ROADMAP.md`) — where we are, current phase, recent decisions.
-3. **Project rules** (`.soly/rules/`, `~/.soly/rules/`) — how to behave in this project.
+1. **Project intent** (`.agents/docs/`) — the 0-point. What the user wants the app to be. Written BEFORE plans, by humans.
+2. **Project state** (`.agents/STATE.md`, `ROADMAP.md`) — where we are, current phase, recent decisions.
+3. **Project rules** (`.agents/rules/`, `~/.agents/rules/`) — how to behave in this project.
 
 **Workflow model — phases and tasks (unified):**
 
@@ -22,7 +22,7 @@ The **soly** extension adds project-management workflow to [pi-coding-agent](htt
 - A **task** is the unit of execution: its own dir with `PLAN.md` (frontmatter: `id`, `kind`, `status`, `depends-on`, optional `feature`) and, when done, `SUMMARY.md`. Tasks run in dependency order.
 - `soly plan <N>` writes a phase's tasks · `soly execute <N>` runs its ready tasks (deps met) in order · `soly verify` reviews.
 - **Close-out** (per task): production commits → task `SUMMARY.md` → flip `status: done` → `STATE.md` / ROADMAP check.
-- Legacy projects (standalone `NN-MM-PLAN.md` files, or a `features/` dir) still load and run; `soly migrate` converts them to this layout.
+- Legacy projects (standalone `NN-MM-PLAN.md` files, or a `features/` dir) still load and run alongside the unified `phases/<N>/tasks/` layout.
 
 ## Commands
 
@@ -43,8 +43,7 @@ Workflow verbs are **plain text** — type `soly <verb>` (NOT a slash command):
 | Command | What it does |
 |---|---|
 | `/rules` · `/docs` | Open the rules / intent-docs **modal** (fuzzy list + preview; `e/d/r` enable·disable·reload on rules). A subcommand (`/rules stats`, `/docs stats`, …) prints to chat instead of opening the modal. |
-| `/soly [<sub>]` | Project-state inspection (position, state, plan, roadmap, phases, tasks, …); bare `/soly` opens the picker |
-| `/soly-init` · `/soly-migrate` | Scaffold a project · migrate `.soly/` → `.agents/` |
+| `/soly [<sub>]` | Project-state inspection (position, state, plan, roadmap, phases, tasks, …); bare `/soly` opens the picker. `/soly init` scaffolds a new project (template: minimal/web-app/library/cli) |
 | `/why` | What rules + state grounded the last turn |
 | `/rulewizard` | Rule vs .editorconfig vs linter guide |
 
@@ -66,44 +65,37 @@ were removed in 1.4.0.
 <project-root>/
 ├── AGENTS.md                      # vendor-neutral agent context (loaded by pi)
 ├── agents.md                      # same as AGENTS.md, lowercase accepted
-├── .soly/                         # soly state (phases, plans, summaries)
+├── .agents/                       # the one home: soly state + vendor-neutral agent config
+│   ├── soly.json                  # soly config (per-project; ~/.agents/soly.json = global)
 │   ├── ROADMAP.md                 # phase table
 │   ├── STATE.md                   # current position + decisions log
 │   ├── docs/                      # 0-point intent docs (human-written, locked)
 │   │   ├── vision.md
 │   │   └── architecture.md
-│   ├── rules/                     # soly project rules (version-controlled)
+│   ├── rules/                     # project rules (version-controlled)
 │   │   ├── code-style.md
 │   │   └── testing.md
 │   ├── phases/
 │   │   ├── 01-foundation/
-│   │   │   ├── 01-CONTEXT.md     # domain + decisions for phase 1
-│   │   │   ├── 01-RESEARCH.md    # what we looked up
-│   │   │   └── tasks/            # unified model: one dir per task
+│   │   │   ├── 01-CONTEXT.md       # domain + decisions for phase 1
+│   │   │   ├── 01-RESEARCH.md      # what we looked up
+│   │   │   └── tasks/              # unified model: one dir per task
 │   │   │       ├── auth-login-a3f9/
-│   │   │       │   ├── PLAN.md   # frontmatter: id, kind, status, depends-on
+│   │   │       │   ├── PLAN.md     # frontmatter: id, kind, status, depends-on
 │   │   │       │   └── SUMMARY.md
 │   │   │       └── auth-token-b1c2/
 │   │   │           └── PLAN.md
 │   │   └── 02-feature-x/
 │   │       └── ...
+│   ├── skills/                    # project-scoped skills (pi auto-discovers)
+│   │   └── my-skill/SKILL.md
+│   ├── agents/                    # project-specific agent definitions
 │   ├── iterations/                # per-execution context bundles (auto)
 │   ├── HANDOFF.json               # pause snapshot
 │   └── .continue-here.md          # pause resume marker
-├── .agents/                       # vendor-neutral agent config (per project)
-│   ├── rules/                     # agent rules (loaded with priority 3, after .soly/rules/)
-│   ├── skills/                    # project-scoped skills (pi auto-discovers)
-│   │   └── my-skill/
-│   │       └── SKILL.md
-│   ├── docs/                      # agent-specific docs (intent-style)
-│   └── agents/                    # project-specific agent definitions
 ```
 
-**Two parallel conventions:** `.soly/` is soly-specific state. `.agents/` is vendor-neutral agent config. The two coexist:
-
-- **Use `.soly/`** for soly workflow artifacts (PLAN.md, SUMMARY.md, etc.)
-- **Use `.agents/`** for things other AI tools should also see (rules, skills, agents)
-- **Use `AGENTS.md`** for top-level project-wide agent conventions
+**One home:** everything lives under `.agents/` — soly's workflow artifacts (PLAN.md, SUMMARY.md, phases, STATE), project rules/docs, and the vendor-neutral config (skills, agents) other AI tools also read. Global rules/config live under `~/.agents/`. `AGENTS.md` at the project root carries top-level agent conventions. (Projects from before the rename used `.soly/`; soly no longer reads it — run `mv .soly .agents`.)
 
 ## Frontmatter conventions
 
@@ -122,9 +114,9 @@ parallelizable: true         # can run alongside siblings
 # Add OAuth flow
 
 ## read_first
-- .soly/STATE.md
-- .soly/ROADMAP.md
-- .soly/rules/code-style.md
+- .agents/STATE.md
+- .agents/ROADMAP.md
+- .agents/rules/code-style.md
 
 ## tasks
 - [ ] **type: implement**, description: Add token refresh logic
@@ -143,7 +135,7 @@ parallelizable: true         # can run alongside siblings
 - bun run lint
 
 ## risks
-- Token storage depends on the encryption scheme (see .soly/docs/architecture.md)
+- Token storage depends on the encryption scheme (see .agents/docs/architecture.md)
 ```
 
 ### SUMMARY.md frontmatter
@@ -191,15 +183,15 @@ priority: 50                   # higher wins on conflict (default: 0)
 
 ## Path discipline (NON-NEGOTIABLE)
 
-**All soly-managed files live under `.soly/`.** Source code lives in the project's normal source tree.
+**All soly-managed files live under `.agents/`.** Source code lives in the project's normal source tree.
 
 | File kind | Goes to |
 |---|---|
-| `PLAN.md`, `SUMMARY.md`, `CONTEXT.md`, `RESEARCH.md` | `.soly/phases/<NN>-<slug>/` |
-| Intent docs (0-point) | `.soly/docs/` |
-| Rules | `.soly/rules/` (project) or `~/.soly/rules/` (user) |
-| Handoff | `.soly/HANDOFF.json`, `.soly/.continue-here.md` |
-| Iteration context | `.soly/iterations/` (auto-generated) |
+| `PLAN.md`, `SUMMARY.md`, `CONTEXT.md`, `RESEARCH.md` | `.agents/phases/<NN>-<slug>/` |
+| Intent docs (0-point) | `.agents/docs/` |
+| Rules | `.agents/rules/` (project) or `~/.agents/rules/` (user) |
+| Handoff | `.agents/HANDOFF.json`, `.agents/.continue-here.md` |
+| Iteration context | `.agents/iterations/` (auto-generated) |
 | Production code, tests | project's normal `src/`, `tests/`, `app/`, etc. |
 
 Use absolute paths (or paths starting with `$SOLY_DIR`) when calling tools. Never bare relative names that could land in cwd.
@@ -243,14 +235,14 @@ The main system prompt only points at these; the detail is here.
 
 **`decision_deck`** — full-screen cards (one per option) with a highlighted code snippet + pros/cons. Reach for it when the choice hinges on the concrete code/structure of each option, not a label, and there are 2–6 alternatives worth comparing side-by-side. Prefer `ask_pro` for short-label choices; don't use it for trivial/yes-no.
 
-**`html_artifact`** — render HTML served from a per-session browser gallery SPA (sidebar + iframe + filter + live SSE updates, one stable localhost URL). Use when a visual rendered result beats terminal text: example galleries, before/after or side-by-side comparisons, tables, diagrams, a small HTML/CSS/SVG demo. Pass `title` + `html` (a body fragment is fine — it's wrapped in a themed skeleton; put code in `<pre><code>`). Pass `id` to re-render/update an artifact in place (instead of piling up copies); pass `assets: [{path, content, encoding?}]` to write sibling files the HTML references by relative path (e.g. an image or `data.json`). The theme is overridable per project via `.soly/artifact-theme.css`. Keep it self-contained unless you use `assets` — no external/CDN requests. Don't use it for a single snippet (markdown code block) or prose. Mention the returned URL to the user.
+**`html_artifact`** — render HTML served from a per-session browser gallery SPA (sidebar + iframe + filter + live SSE updates, one stable localhost URL). Use when a visual rendered result beats terminal text: example galleries, before/after or side-by-side comparisons, tables, diagrams, a small HTML/CSS/SVG demo. Pass `title` + `html` (a body fragment is fine — it's wrapped in a themed skeleton; put code in `<pre><code>`). Pass `id` to re-render/update an artifact in place (instead of piling up copies); pass `assets: [{path, content, encoding?}]` to write sibling files the HTML references by relative path (e.g. an image or `data.json`). The theme is overridable per project via `.agents/artifact-theme.css`. Keep it self-contained unless you use `assets` — no external/CDN requests. Don't use it for a single snippet (markdown code block) or prose. Mention the returned URL to the user.
 
 ## Common workflows
 
 ### Start a new project
 
-1. `soly init` (or manually create `.soly/`, `docs/`, `rules/`)
-2. Write 1-3 intent docs in `.soly/docs/`
+1. `soly init` (or manually create `.agents/`, `docs/`, `rules/`)
+2. Write 1-3 intent docs in `.agents/docs/`
 3. Optionally write `AGENTS.md` (or `agents.md`) at project root with project conventions
 4. Create `ROADMAP.md` with phase table
 5. `/plan 1` to start the first phase
@@ -291,7 +283,7 @@ You are a data scientist. ...
 
 If `/execute` complains about illegal partial state:
 
-1. `cat .soly/iterations/<latest>.md` — see what the last run did
+1. `cat .agents/iterations/<latest>.md` — see what the last run did
 2. Check if `SUMMARY.md` exists for the last plan
 3. If yes, finish close-out: update `STATE.md` + `ROADMAP.md`
 4. If no, either commit the SUMMARY or revert the production commits
@@ -302,8 +294,8 @@ Call `soly_read(artifact: "state")` and `soly_read(artifact: "roadmap")` first.
 
 ## Don'ts
 
-- ❌ Edit `.soly/rules/` files you didn't write — those are project invariants
+- ❌ Edit `.agents/rules/` files you didn't write — those are project invariants
 - ❌ Skip the SUMMARY — illegal partial state
 - ❌ Spawn `soly-manager` / `soly-worker` / etc. — there are no soly subagents (removed in 1.3.0). Use pi's built-in subagents via the parent LLM's `subagent(...)` call.
-- ❌ Edit `.soly/phases/*/PLAN.md` after `status: in_progress` — create a new plan
-- ❌ Put intent docs anywhere other than `.soly/docs/`
+- ❌ Edit `.agents/phases/*/PLAN.md` after `status: in_progress` — create a new plan
+- ❌ Put intent docs anywhere other than `.agents/docs/`

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