pi-soly 1.13.5 → 1.14.0

package/index.ts

@@ -2,7 +2,7 @@
 // index.ts — Main soly extension entry point
 // =============================================================================
 //
-// Loads .soly/rules/ and .soly/ project state into the agent's system
+// Loads .agents/rules/ and .agents/ project state into the agent's system
 // prompt, and registers:
 //   - slash commands  /rules /soly /rulewizard /why
 //   - LLM tools       soly_read soly_log_decision soly_list_phases
@@ -42,6 +42,7 @@ import {
 	rulesApplicableToFiles,
 	STATUS_ID,
 	solyDirFor,
+	SOLY_DIRNAME,
 	isLegacySolyDir,
 	buildNextHint,
 	buildDriftReminder,
@@ -94,7 +95,7 @@ const SOLY_TOOLS_POINTER = `
 ## soly — interactive & visual tools
 
 When terminal text isn't the best medium, reach for these (details + when-NOT in the soly-framework skill):
-- \`ask_pro\` — multi-question picker (single/multi-select, free-text, per-option previews).
+- \`ask_pro\` — multi-question picker (single/multi-select, free-text, per-option previews); every options question always offers a free-text "Other…" so the user can answer in their own words.
 - \`decision_deck\` — full-screen cards comparing design options by their concrete code shape.
 - \`html_artifact\` — render HTML to a self-contained, browseable per-project gallery.`;
 
@@ -178,7 +179,7 @@ export default function solyExtension(pi: ExtensionAPI) {
 	let codeMap: CodeMap | null = null;
 	let lastCodeMapSection = "";
 
-	// Project intent (zero-point docs from .soly/docs/) — always loaded
+	// Project intent (zero-point docs from .agents/docs/) — always loaded
 	let intentDocs: IntentDoc[] = [];
 	let lastIntentSection = "";
 
@@ -237,14 +238,14 @@ export default function solyExtension(pi: ExtensionAPI) {
 	/**
 	 * Persistent storage of rule mtimes from the previous session, so we can
 	 * show a "rules changed since last session" diff at startup.
-	 * Stored in <solyDir>/.soly-rule-mtimes.json (project) or
-	 * <homedir>/.soly/rule-mtimes.json (global fallback).
+	 * Stored in <solyDir>/rule-mtimes.json (project) or
+	 * <homedir>/.agents/rule-mtimes.json (global fallback).
 	 */
 	let lastSessionMtimes: Record<string, number> = {};
 	const mtimeStorePath = (): string => {
 		const base = state.solyDir && fs.existsSync(state.solyDir)
 			? state.solyDir
-			: path.join(os.homedir(), ".soly");
+			: path.join(os.homedir(), SOLY_DIRNAME);
 		try {
 			fs.mkdirSync(base, { recursive: true });
 		} catch {}
@@ -293,7 +294,7 @@ export default function solyExtension(pi: ExtensionAPI) {
 		// Soly doesn't render the agent badge itself.
 		const agentGroup = "";
 
-		// Cross-extension: show pi-todo progress if either .soly/todos.json
+		// Cross-extension: show pi-todo progress if either .agents/todos.json
 		// (soly-integration mode) OR .pi-todos.json (standalone mode) exists.
 		// Cheap (one stat + one small JSON read); cached only for the
 		// lifetime of one updateStatus call.
@@ -407,32 +408,30 @@ export default function solyExtension(pi: ExtensionAPI) {
 	// ============================================================================
 
 	pi.on("session_start", async (event, ctx) => {
-		// Deprecation warning: if the project still uses `.soly/`, nudge the
-		// user toward `.agents/`. One-time per session.
+		// Legacy detection: a project with only a `.soly/` dir (no `.agents/`)
+		// is now invisible to soly — warn the user to rename it. soly no longer
+		// reads `.soly/`. One-time per session.
 		if (isLegacySolyDir(ctx.cwd)) {
 			notifyDeprecation(
 				ctx.ui,
-				`.soly/ (legacy)`,
-				`.agents/ (vendor-neutral)`,
-				`Run \`mv .soly .agents\` to migrate. Both names work for now.`,
+				`.soly/ (legacy, no longer read)`,
+				`.agents/`,
+				`Run \`mv .soly .agents\` — soly now reads only \`.agents/\`.`,
 			);
 		}
 
 		// Rules sources (priority order, higher wins on relPath collision).
-		// Project rules always beat global rules. .soly/rules.local/ is
+		// Project rules always beat global rules. `.agents/rules.local/` is
 		// gitignored — for personal overrides on top of the project's rules.
-		// .agents/rules/ is the vendor-neutral project-level convention
-		// (same role as the old .claude/rules/).
+		// `.agents/rules/` is the vendor-neutral project-level convention.
 		ruleSources = [
-			{ dir: path.join(ctx.cwd, ".soly", "rules.local"), source: "project-soly", sourceLabel: "local", priority: 5 },
-			{ dir: path.join(ctx.cwd, ".soly", "rules"), source: "project-soly", sourceLabel: "soly", priority: 4 },
+			{ dir: path.join(ctx.cwd, ".agents", "rules.local"), source: "project-agents", sourceLabel: "local", priority: 5 },
 			{ dir: path.join(ctx.cwd, ".agents", "rules"), source: "project-agents", sourceLabel: "agents", priority: 3 },
-			{ dir: path.join(os.homedir(), ".soly", "rules"), source: "global-soly", sourceLabel: "soly", priority: 2 },
 			{ dir: path.join(os.homedir(), ".agents", "rules"), source: "global-agents", sourceLabel: "agents", priority: 1 },
 		];
 		refreshRules();
 
-		// Project state — soly owns .soly/ at the project root
+		// Project state — soly owns .agents/ at the project root
 		state.solyDir = solyDirFor(ctx.cwd);
 		refreshState();
 
@@ -499,7 +498,7 @@ export default function solyExtension(pi: ExtensionAPI) {
 			lastCodeMapSection = "";
 		}
 
-		// Load project intent (zero-point docs from .soly/docs/) — always
+		// Load project intent (zero-point docs from .agents/docs/) — always
 		refreshIntent();
 
 		// Start hot-reload watcher on rules dirs
@@ -570,7 +569,7 @@ export default function solyExtension(pi: ExtensionAPI) {
 				);
 			}
 		} else {
-			ctx.ui.notify("soly rules: none found in .soly/rules.local, .soly/rules, or ~/.soly/rules", "info");
+			ctx.ui.notify("soly rules: none found in .agents/rules.local, .agents/rules, or ~/.agents/rules", "info");
 		}
 
 		if (state.exists) {

package/init.ts

@@ -27,9 +27,9 @@
 //   "cli"      — adds command/, flags/, shell-compat/ example rules
 //
 // Usage:
-//   /soly-init                  # interactive: pick template
-//   /soly-init minimal          # no prompts
-//   /soly-init web-app --yes
+//   /soly init                  # interactive: pick template
+//   /soly init minimal          # no prompts
+//   /soly init web-app --yes
 // =============================================================================
 
 import * as fs from "node:fs";
@@ -208,7 +208,7 @@ export async function initSolyProject(
 	// Preconditions
 	if (fs.existsSync(agentsDir) || fs.existsSync(path.join(cwd, ".soly"))) {
 		ui.notify(
-			`soly-init: project already initialized (found ${SOLY_DIRNAME}/ or .soly/). ` +
+			`soly init: project already initialized (found ${SOLY_DIRNAME}/ or .soly/). ` +
 				`Aborting to avoid overwriting.`,
 			"error",
 		);
@@ -223,7 +223,7 @@ export async function initSolyProject(
 			["minimal", "web-app", "library", "cli"],
 		);
 		if (!pick) {
-			ui.notify("soly-init: cancelled", "info");
+			ui.notify("soly init: cancelled", "info");
 			return { created: false, template: null, projectName };
 		}
 		template = pick as InitTemplate;
@@ -237,7 +237,7 @@ export async function initSolyProject(
 			`Create .agents/ structure in:\n  ${cwd}\n\nProject name: ${projectName}`,
 		);
 		if (!ok) {
-			ui.notify("soly-init: cancelled", "info");
+			ui.notify("soly init: cancelled", "info");
 			return { created: false, template: null, projectName };
 		}
 	}
@@ -289,7 +289,7 @@ export async function initSolyProject(
 		created.push(`.agents/${extra.file}`);
 	}
 	ui.notify(
-		`soly-init: done (${template}). Created:\n  - ${created.join("\n  - ")}\n\n` +
+		`soly init: done (${template}). Created:\n  - ${created.join("\n  - ")}\n\n` +
 			`Next:\n  1. Edit \`.agents/docs/vision.md\`\n  2. \`/plan 1\` to start the first phase`,
 		"info",
 	);

package/intent.ts

@@ -2,27 +2,27 @@
 // intent.ts — Project intent loader (the "0 point" of every soly project)
 // =============================================================================
 //
-// `.soly/docs/` is the zero-point of the project: documents written BEFORE
+// `.agents/docs/` is the zero-point of the project: documents written BEFORE
 // any soly plans, research, or code. It holds the user's vision, business
 // context, and architectural intent. Other soly artifacts (STATE, PLANS,
 // RESEARCH) flow FROM this input.
 //
 // Supported files: `.md` (full text) and `.html` (parsed for title + preview).
-// Nested directories are supported (e.g. `.soly/docs/api/auth.md`).
+// Nested directories are supported (e.g. `.agents/docs/api/auth.md`).
 //
-// Convention: any document in `.soly/docs/` is loaded into the system
+// Convention: any document in `.agents/docs/` is loaded into the system
 // prompt as "project intent". This is separate from:
-//   - rules (`.soly/rules/`) — how to behave
-//   - state (`.soly/STATE.md`, ROADMAP.md) — where we are
+//   - rules (`.agents/rules/`) — how to behave
+//   - state (`.agents/STATE.md`, ROADMAP.md) — where we are
 //   - planning (PLAN.md, CONTEXT.md) — what to do next
 //
-// Optional: `.soly/phases/<N>/docs/` is also scanned if the directory exists
+// Optional: `.agents/phases/<N>/docs/` is also scanned if the directory exists
 // (for backward compat / phase-specific intent). Not required.
 // =============================================================================
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { formatTok, resolveImports } from "./core.ts";
+import { formatTok, resolveImports, solyDirFor } from "./core.ts";
 import { extractTitleAndPreview, stripHtml } from "./html.ts";
 
 const DOC_EXTS = new Set([".md", ".html", ".htm"]);
@@ -148,15 +148,15 @@ function walkIntentDir(
 
 export function loadIntentDocs(cwd: string, currentPhaseNumber?: number): IntentDoc[] {
 	const out: IntentDoc[] = [];
-	const docsRoot = path.join(cwd, ".soly", "docs");
+	const docsRoot = path.join(solyDirFor(cwd), "docs");
 	walkIntentDir(docsRoot, "", undefined, out);
 
 	// Optional: phase-specific docs (only if current phase is known)
 	if (currentPhaseNumber != null) {
 		// We don't know the slug here without re-walking phases; scan any
-		// directory in .soly/phases/ whose name starts with the phase number.
+		// directory in .agents/phases/ whose name starts with the phase number.
 		// Skip if no phases dir exists.
-		const phasesRoot = path.join(cwd, ".soly", "phases");
+		const phasesRoot = path.join(solyDirFor(cwd), "phases");
 		if (fs.existsSync(phasesRoot)) {
 			try {
 				const phaseEntries = fs.readdirSync(phasesRoot, { withFileTypes: true });
@@ -196,7 +196,7 @@ export function buildIntentSection(intent: IntentDoc[]): IntentSection {
 		return { hasContent: false, section: "" };
 	}
 
-	const lines: string[] = ["", "## project intent (from .soly/docs/)", ""];
+	const lines: string[] = ["", "## project intent (from .agents/docs/)", ""];
 	lines.push(
 		"These documents are the **0 point** of this project — the user's vision, business context, and design intent, written BEFORE any soly plans. Read them first when planning, discussing, or executing. If implementation diverges from intent, fix one or the other — don't let drift compound.",
 	);
@@ -403,7 +403,7 @@ export function formatIntentStats(stats: IntentStats): string {
     lines.push(``);
   }
   if (stats.totalDocs === 0) {
-    lines.push(`No intent docs found in .soly/docs/ or ~/.soly/docs/`);
+    lines.push(`No intent docs found in .agents/docs/ or ~/.agents/docs/`);
   }
   return lines.join("\n");
 }

package/iteration.ts

@@ -2,7 +2,7 @@
 // iteration.ts — Per-iteration context bundle (B2 of the soly design)
 // =============================================================================
 //
-// Writes a self-contained .md file under `.soly/iterations/` that bundles
+// Writes a self-contained .md file under `.agents/iterations/` that bundles
 // everything a worker needs for ONE iteration of a plan / task / phase:
 // intent docs, STATE.md, ROADMAP row, phase CONTEXT, phase RESEARCH, up
 // to 3 prior SUMMARYs, and the current PLAN.md (for exec).
@@ -18,8 +18,8 @@
 // the worker's task string itself, so the worker has the most critical
 // bits available even before opening the file.
 //
-// All worktree writes go to `.soly/iterations/` (under the project's
-// `.soly/`), never to the project root. See workflow markdown templates
+// All worktree writes go to `.agents/iterations/` (under the project's
+// `.agents/`), never to the project root. See workflow markdown templates
 // for the hard rule.
 // =============================================================================
 
@@ -160,7 +160,7 @@ export function findRecentSummaries(dir: string, n: number): string[] {
 
 /** Find a phase's `<NN>-CONTEXT.md` path (or null).
  *  Convention: filename starts with the padded phase number, not the full
- *  slug. e.g. `.soly/phases/05-auth/05-CONTEXT.md`, not `05-auth-CONTEXT.md`. */
+ *  slug. e.g. `.agents/phases/05-auth/05-CONTEXT.md`, not `05-auth-CONTEXT.md`. */
 export function findPhaseContextPath(phaseDir: string): string | null {
 	const slug = path.basename(phaseDir);
 	const numMatch = slug.match(/^(\d+)/);
@@ -192,7 +192,7 @@ export function findContinueHerePath(phaseDir: string): string | null {
 
 function loadIntentSummary(solyDir: string, maxTokens: number): string {
 	const docsRoot = path.join(solyDir, "docs");
-	if (!fs.existsSync(docsRoot)) return "_(no \`.soly/docs/\` directory — drop your 0-point docs there)_";
+	if (!fs.existsSync(docsRoot)) return "_(no \`.agents/docs/\` directory — drop your 0-point docs there)_";
 
 	const files: string[] = [];
 	for (const e of fs.readdirSync(docsRoot, { withFileTypes: true })) {
@@ -206,7 +206,7 @@ function loadIntentSummary(solyDir: string, maxTokens: number): string {
 			files.push(full);
 		}
 	}
-	if (files.length === 0) return "_(no \`.md\` files in \`.soly/docs/\`)_";
+	if (files.length === 0) return "_(no \`.md\` files in \`.agents/docs/\`)_";
 
 	files.sort();
 	const out: string[] = [];
@@ -223,7 +223,7 @@ function loadIntentSummary(solyDir: string, maxTokens: number): string {
 			.join(" ");
 		const chunk = `- \`${relPath}\`: ${preview.slice(0, 240)}\n`;
 		if (usedChars + chunk.length > maxChars) {
-			out.push(`\n_(truncated at ${maxTokens} tokens; full files in \`.soly/docs/\`)_\n`);
+			out.push(`\n_(truncated at ${maxTokens} tokens; full files in \`.agents/docs/\`)_\n`);
 			break;
 		}
 		out.push(chunk);
@@ -370,7 +370,7 @@ function loadAntiPatterns(phaseDir: string, maxTokens: number): string {
 
 function loadFeatureReadme(feature: string, solyDir: string, maxTokens: number): string {
 	const readme = path.join(solyDir, "features", feature, "README.md");
-	if (!fs.existsSync(readme)) return `_(no \`.soly/features/${feature}/README.md\`)_`;
+	if (!fs.existsSync(readme)) return `_(no \`.agents/features/${feature}/README.md\`)_`;
 	return truncate(readIfExists(readme) ?? "", maxTokens);
 }
 
@@ -508,7 +508,7 @@ export function buildIterationContent(input: IterationInput): string {
 	sections.push(title);
 	sections.push("");
 	sections.push(`**Generated**: ${generatedAt}`);
-	sections.push(`**Soly dir**: \`${rel(projectRoot, input.solyDir) || ".soly"}\``);
+	sections.push(`**Soly dir**: \`${rel(projectRoot, input.solyDir) || ".agents"}\``);
 	if (input.taskId) {
 		sections.push(`**Task**: \`${input.taskId}\` in feature \`${input.feature ?? "?"}\``);
 	} else if (input.phaseNumber != null) {
@@ -524,10 +524,10 @@ export function buildIterationContent(input: IterationInput): string {
 	sections.push("");
 
 	// ---- Section 0: Intent ----
-	sections.push("## 0. Project Intent (from `.soly/docs/`)");
+	sections.push("## 0. Project Intent (from `.agents/docs/`)");
 	sections.push("");
 	sections.push(
-		`_Source: \`.soly/docs/\` (full files in \`.soly/docs/\`, see also \`soly_intent\` tool)_`,
+		`_Source: \`.agents/docs/\` (full files in \`.agents/docs/\`, see also \`soly_intent\` tool)_`,
 	);
 	sections.push("");
 	sections.push(loadIntentSummary(input.solyDir, SECTION_BUDGETS.intent));
@@ -548,7 +548,7 @@ export function buildIterationContent(input: IterationInput): string {
 
 	// ---- Section 1: State (only if there's a project state) ----
 	if (input.kind !== "pause") {
-		sections.push("## 1. Project State (`.soly/STATE.md` — Current Position + Decisions)");
+		sections.push("## 1. Project State (`.agents/STATE.md` — Current Position + Decisions)");
 		sections.push("");
 		sections.push(`_Source: \`${rel(projectRoot, path.join(input.solyDir, "STATE.md"))}\`_`);
 		sections.push("");

package/notification.ts

@@ -168,7 +168,7 @@ export function notifyDeprecation(
 
 // ---------------------------------------------------------------------------
 // Plain-text fallback (no widget, just framed Unicode text via notify).
-// Used for the .soly/ migration banner and other places that don't have
+// Used for the legacy .soly/ detection banner and other places that don't have
 // access to a UI context yet (CLI startup, print mode, etc.)
 // ---------------------------------------------------------------------------
 

package/notifications-log.ts

@@ -2,7 +2,7 @@
 // notifications-log.ts — Persistent record of soly notifications
 // =============================================================================
 //
-// Appends every nudge/deprecation to a JSONL file at .agents/.soly/notifications.log
+// Appends every nudge/deprecation to a JSONL file at .agents/notifications.log
 // (inside the project dir; safe to commit if the user wants a public audit
 // trail, or .gitignore if not). One line per notification, JSON-encoded.
 //
@@ -33,7 +33,7 @@ export interface NotificationEntry {
 /** Where the log file lives. Respects HOME for tests. */
 export function logFilePath(cwd: string, home?: string): string {
 	const h = home ?? process.env.HOME ?? process.env.USERPROFILE ?? os.homedir();
-	return path.join(cwd, SOLY_DIRNAME, ".soly", "notifications.log");
+	return path.join(cwd, SOLY_DIRNAME, "notifications.log");
 }
 
 /** Append a single entry to the log. Creates parent dirs as needed. */

package/nudge.ts

@@ -82,9 +82,42 @@ export function classifyTaskHeuristics(prompt: string): TaskHeuristics {
 	return { nonTrivial, researchHeavy, mentions, suggestedAngles };
 }
 
+// ---------------------------------------------------------------------------
+// Confirm-before-coding gate
+// ---------------------------------------------------------------------------
+
+/** How hard soly pushes the LLM to clarify before writing code.
+ *   - "scope" — batch the substantive decisions (placement, pattern, scope,
+ *               interface) via ask_pro, then wait. Strongest.
+ *   - "ask"   — lighter: one "ready to implement, or discuss?" question.
+ *   - "off"   — no gate. */
+export type ConfirmLevel = "off" | "ask" | "scope";
+
+/** Normalize the config value (boolean back-compat) to a confirm level.
+ *  `true` → "scope" (strongest), `false` / absent → "off". */
+export function confirmLevelOf(v: boolean | ConfirmLevel | undefined): ConfirmLevel {
+	if (v === true) return "scope";
+	if (v === "ask" || v === "scope") return v;
+	return "off";
+}
+
+// "scope": pull the decisions only the user can make BEFORE coding, as one
+// batched ask_pro call — placement, pattern, scope, interface — instead of
+// guessing and editing files on assumptions.
+const SCOPE_DIRECTIVE = `**Scope it with me before you code.** For non-trivial work, do NOT start writing or editing files on assumptions about decisions only I can make. First surface them as a single \`ask_pro\` batch (2–5 questions in one call), covering the dimensions that actually matter for this task — typically:
+   - **Placement** — where should this live? (which file / module / layer; extend an existing unit or add a new one)
+   - **Architecture / pattern** — which approach? (follow an existing pattern in the codebase vs introduce a new one; reuse a dependency vs hand-roll)
+   - **Scope** — what's in vs out for this change? (defer adjacent work to its own task)
+   - **Interface** — the shape callers see (API / CLI / signature / return), when it's a genuine fork
+   - **Data / state** — schema, storage, or state-shape decisions, when relevant
+   Give each question 2–4 concrete options with a ⭐ recommended default + one-line rationale, and add \`allowOther\` so I can steer freely. Wait for my answers before touching files. Skip only for trivial fixes (typo / rename / one-liner) or when I've already decided ("just do it", "go", or a follow-up turn in an already-scoped task). Prefer 2–3 sharp questions over a long list — ask what changes the result, not ceremony.`;
+
+// "ask": lighter — a single "ready, or discuss first?" confirmation.
+const ASK_DIRECTIVE = `**Confirm before coding.** Don't jump straight into writing/editing code. First state your understanding and intended approach in 1–3 sentences and list anything still open, then ask via the \`ask_pro\` picker whether to proceed — one question with options like "Go — implement now", "Discuss / refine the approach", "Adjust scope first" (add an \`allowOther\` for a free-text steer). Wait for the choice before touching files. Skip only for trivial fixes, or when the user already said to proceed ("just do it", "go", "yes").`;
+
 export function buildNudgeSection(
 	heuristics: TaskHeuristics,
-	opts: { hasProject?: boolean; confirmBeforeCode?: boolean } = {},
+	opts: { hasProject?: boolean; confirmBeforeCode?: boolean | ConfirmLevel } = {},
 ): string {
 	// Always-on rules (cheap to add, high signal):
 	//   - Don't dive in on non-trivial tasks without a brief check
@@ -112,14 +145,16 @@ export function buildNudgeSection(
 	// model toward the workflow lifecycle instead of ad-hoc edits.
 	const workflowPoint =
 		opts.hasProject && heuristics.nonTrivial
-			? `\n\n4. **Route project work through the soly workflow.** For phase/task work in \`.soly/\`, prefer the lifecycle over ad-hoc edits: \`soly discuss <N>\` (scope) → \`soly plan <N>\` (write tasks) → \`soly execute <N>\` (do them) → \`soly verify\` (review). Run \`soly status\` to see where you are. Skip only for a genuine one-off.`
+			? `\n\n4. **Route project work through the soly workflow.** For phase/task work in \`.agents/\`, prefer the lifecycle over ad-hoc edits: \`soly discuss <N>\` (scope) → \`soly plan <N>\` (write tasks) → \`soly execute <N>\` (do them) → \`soly verify\` (review). Run \`soly status\` to see where you are. Skip only for a genuine one-off.`
 			: "";
 
-	// Confirm-before-coding gate: for non-trivial implementation, don't start
-	// editing files until the user has greenlit the approach.
+	// Confirm-before-coding gate: for non-trivial implementation, pull the
+	// open decisions out of the user before editing files. Strength is config-
+	// driven ("scope" = batch the substantive questions; "ask" = one go/discuss).
+	const confirmLevel = confirmLevelOf(opts.confirmBeforeCode);
 	const confirmBlock =
-		opts.confirmBeforeCode && heuristics.nonTrivial
-			? `\n\n   **Confirm before coding.** Don't jump straight into writing/editing code. First state your understanding and intended approach in 1–3 sentences and list anything still open, then ask via the \`ask_pro\` picker whether to proceed — one question with options like "Go — implement now", "Discuss / refine the approach", "Adjust scope first" (add an \`allowOther\` for a free-text steer). Wait for the choice before touching files. Skip only for trivial fixes, or when the user already said to proceed ("just do it", "go", "yes").`
+		confirmLevel !== "off" && heuristics.nonTrivial
+			? `\n\n   ${confirmLevel === "scope" ? SCOPE_DIRECTIVE : ASK_DIRECTIVE}`
 			: "";
 
 	return `

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-soly",
-  "version": "1.13.5",
+  "version": "1.14.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",
@@ -58,7 +58,6 @@
     "notifications-log.ts",
     "status.ts",
     "init.ts",
-    "migrate.ts",
     "codemap.ts",
     "state.ts",
     "hotreload.ts"

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/`