pi-soly 1.13.5 → 1.15.0

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

package/workflows/quick.ts

@@ -36,7 +36,7 @@ export function showStatus(
 	config?: SolyConfig,
 ): void {
 	if (!state.exists) {
-		ui.notify("soly: no .soly/ directory in cwd", "error");
+		ui.notify("soly: no .agents/ directory in cwd", "error");
 		return;
 	}
 	const maxPhases = config?.display.maxPhasesInStatus ?? 20;
@@ -122,7 +122,7 @@ const DECISIONS_TABLE_ROW = /^\|\s*([^|]+)\s*\|\s*([^|]+)\s*\|\s*([^|]+)\s*\|\s*
 
 export function showLog(cmd: SolyCommand, state: SolyState, ui: QuickUI): void {
 	if (!state.exists) {
-		ui.notify("soly log: no .soly/ directory in cwd", "error");
+		ui.notify("soly log: no .agents/ directory in cwd", "error");
 		return;
 	}
 
@@ -214,7 +214,7 @@ export async function showDiff(
 	state: SolyState,
 	ui: QuickUI,
 ): Promise<void> {
-	// Graceful without .soly/: use cwd as project root, skip the .soly/ filter
+	// Graceful without .agents/: use cwd as project root, skip the .agents/ filter
 	const projectRoot = state.solyDir ? path.dirname(state.solyDir) : process.cwd();
 	const solyDir = state.solyDir; // may be empty when run outside a soly project
 
@@ -222,7 +222,7 @@ export async function showDiff(
 	const status = await safeExec("git", ["status", "--short", "--branch"], projectRoot);
 	// 2. git diff (tracked changes, no untracked)
 	const diff = await safeExec("git", ["diff", "--stat"], projectRoot);
-	// 3. uncommitted .soly/ file changes (since last commit)
+	// 3. uncommitted .agents/ file changes (since last commit)
 	const solyChanges = await safeExec(
 		"git",
 		["status", "--short", "--", solyDir],
@@ -230,7 +230,7 @@ export async function showDiff(
 	);
 
 	const out: string[] = [];
-	out.push(state.exists ? "=== soly diff ===" : "=== git diff (no .soly/ in cwd) ===");
+	out.push(state.exists ? "=== soly diff ===" : "=== git diff (no .agents/ in cwd) ===");
 	out.push("");
 
 	if (status.code !== 0) {
@@ -246,10 +246,10 @@ export async function showDiff(
 		}
 		if (solyDir) {
 			if (solyChanges.stdout.trim()) {
-				out.push("uncommitted .soly/ changes:");
+				out.push("uncommitted .agents/ changes:");
 				out.push(solyChanges.stdout.trim());
 			} else {
-				out.push("uncommitted .soly/ changes: (none)");
+				out.push("uncommitted .agents/ changes: (none)");
 			}
 		}
 	}

package/workflows/resume.ts

@@ -7,11 +7,11 @@
 // session context from the last handoff.
 //
 // Reads:
-//   - .soly/HANDOFF.json       (machine-readable state, written by pause/compact)
-//   - .soly/.continue-here.md  (human-readable context, written by pause/compact)
+//   - .agents/HANDOFF.json       (machine-readable state, written by pause/compact)
+//   - .agents/.continue-here.md  (human-readable context, written by pause/compact)
 //
 // If neither file exists, falls back to a "no prior handoff" message that
-// tells the LLM to load context from .soly/STATE.md + ROADMAP.md normally.
+// tells the LLM to load context from .agents/STATE.md + ROADMAP.md normally.
 // =============================================================================
 
 import * as fs from "node:fs";
@@ -73,7 +73,7 @@ function formatListSection(label: string, items: string[] | undefined): string {
 function formatHandoffSummary(h: HandoffJson): string {
 	const lines: string[] = [];
 
-	lines.push("=== From .soly/HANDOFF.json ===");
+	lines.push("=== From .agents/HANDOFF.json ===");
 	if (h.generated_at) lines.push(`  generated_at: ${h.generated_at}`);
 	if (h.milestone) lines.push(`  milestone: ${h.milestone}${h.milestone_name ? ` — ${h.milestone_name}` : ""}`);
 	if (h.status) lines.push(`  status: ${h.status}`);
@@ -112,7 +112,7 @@ export function buildResumeTransform(cmd: SolyCommand, state: SolyState): Resume
 		return {
 			handled: true,
 			transformedText:
-				`soly resume: no .soly/ directory in cwd (${state.solyDir || "<cwd>"}) — nothing to resume.\n` +
+				`soly resume: no .agents/ directory in cwd (${state.solyDir || "<cwd>"}) — nothing to resume.\n` +
 				`Initialize a soly project first, or run \`soly pause\` later to create handoff files.`,
 		};
 	}
@@ -149,24 +149,24 @@ export function buildResumeTransform(cmd: SolyCommand, state: SolyState): Resume
 	}
 
 	if (!handoff && !continueMd) {
-		// No prior handoff — fall back to loading from .soly/STATE.md directly.
+		// No prior handoff — fall back to loading from .agents/STATE.md directly.
 		const fallbackScope = phaseFilter != null
 			? `Focus: phase ${phaseFilter}.`
 			: "Scope: full project.";
 		return {
 			handled: true,
 			transformedText:
-				`soly resume: no handoff files found (looked for .soly/HANDOFF.json and .soly/.continue-here.md).\n` +
-				`No prior \`soly pause\` was run — loading context from .soly/STATE.md and .soly/ROADMAP.md directly.\n\n` +
+				`soly resume: no handoff files found (looked for .agents/HANDOFF.json and .agents/.continue-here.md).\n` +
+				`No prior \`soly pause\` was run — loading context from .agents/STATE.md and .agents/ROADMAP.md directly.\n\n` +
 				`${fallbackScope}\n\n` +
-				`Read .soly/STATE.md (Current Position, Decisions, Blockers sections) and .soly/ROADMAP.md.\n` +
+				`Read .agents/STATE.md (Current Position, Decisions, Blockers sections) and .agents/ROADMAP.md.\n` +
 				`Summarize: where the project is, what's next, what's blocking. Then ask the user what to focus on first.`,
 		};
 	}
 
 	const handoffBlock = handoff ? formatHandoffSummary(handoff) : "(no HANDOFF.json found)";
 	const continueBlock = continueMd
-		? `\n=== From .soly/.continue-here.md ===\n${continueMd.trim()}\n`
+		? `\n=== From .agents/.continue-here.md ===\n${continueMd.trim()}\n`
 		: "";
 
 	const focusLine = phaseFilter != null
@@ -182,10 +182,10 @@ ${continueBlock}
 
 === Resume protocol ===
 
-1. **Read .soly/docs/ first** — the project's 0-point intent. Pickup is meaningless without knowing what the user is building toward.
-2. Read .soly/STATE.md to confirm current position (the handoff may be stale).
-3. Read .soly/ROADMAP.md and any CONTEXT.md / RESEARCH.md for the active phase.
-4. Compare handoff's "work remaining" with the actual repo state (git status, recent commits, .soly/ files).
+1. **Read .agents/docs/ first** — the project's 0-point intent. Pickup is meaningless without knowing what the user is building toward.
+2. Read .agents/STATE.md to confirm current position (the handoff may be stale).
+3. Read .agents/ROADMAP.md and any CONTEXT.md / RESEARCH.md for the active phase.
+4. Compare handoff's "work remaining" with the actual repo state (git status, recent commits, .agents/ files).
 5. Produce a one-screen "Where we are" summary:
    - current phase + plan
    - what's actually been done (verified via filesystem / git)

package/workflows-data/discuss-phase.md

@@ -10,7 +10,7 @@ canonical CONTEXT.md. For design/architecture forks you may reach for
 markdown is background context, not a strict protocol.</purpose>
 
 <path_discipline>
-**All soly-managed files live under `.soly/`.** CONTEXT.md, RESEARCH.md, and the discuss checkpoint all go in `.soly/phases/<NN>-<slug>/`. Never write these to the project root. Use absolute paths.
+**All soly-managed files live under `.agents/`.** CONTEXT.md, RESEARCH.md, and the discuss checkpoint all go in `.agents/phases/<NN>-<slug>/`. Never write these to the project root. Use absolute paths.
 
 The iteration context file (path given by the parent in the task prompt) is your single source of truth for intent, STATE, ROADMAP, and any existing phase artifacts. Read it FIRST.
 </path_discipline>
@@ -36,7 +36,7 @@ The iteration context file (path given by the parent in the task prompt) is your
 **Resume:** if a checkpoint file exists, the parent detects it and tells you to resume from where the prior session left off. Acknowledge locked decisions at the top of your output, then continue with the next un-answered gray area.
 </interactive_flow>
 
-<read_first>`.soly/docs/` (INTENT, 0-point) · `.soly/STATE.md` · `.soly/ROADMAP.md` · `${PHASE_DIR}/*-CONTEXT.md` if exists (refine, don't re-derive) · `${PHASE_DIR}/*-DISCUSS-CHECKPOINT.json` if exists (resume from `areas_completed`)</read_first>
+<read_first>`.agents/docs/` (INTENT, 0-point) · `.agents/STATE.md` · `.agents/ROADMAP.md` · `${PHASE_DIR}/*-CONTEXT.md` if exists (refine, don't re-derive) · `${PHASE_DIR}/*-DISCUSS-CHECKPOINT.json` if exists (resume from `areas_completed`)</read_first>
 
 <philosophy>
 **User = visionary. Worker = builder.** The user knows: how it should feel, what's essential vs nice-to-have, specific references. The user doesn't know (don't ask): codebase patterns, technical risks, implementation approach, success metrics.
@@ -90,7 +90,7 @@ PHASE=$1
 # Worker subagent inherits the parent's cwd (the project root), so
 # `pwd` IS the project root. The previous `cd .. && pwd` was a bug.
 PROJECT_ROOT="$(pwd)"
-SOLY_DIR="$PROJECT_ROOT/.soly"
+SOLY_DIR="$PROJECT_ROOT/.agents"
 PHASE_DIR=$(ls -d "$SOLY_DIR/phases/"*"-$PHASE-"* 2>/dev/null | head -1) || { echo "Phase $PHASE not found" >&2; exit 1; }
 PADDED_PHASE=$(printf "%02d" "$(echo "$PHASE" | grep -oE '^[0-9]+' | sed 's/^0*//')")
 PHASE_SLUG=$(basename "$PHASE_DIR")
@@ -137,7 +137,7 @@ If you cannot answer from `.continue-here.md`, return `## Clarifications Needed`
 [ -f "$SOLY_DIR/DECISIONS-INDEX.md" ] && echo "DECISIONS-INDEX.md (prefer over per-phase if present)"
 ```
 
-Most-recent 3 prior `*-CONTEXT.md` files (prefer DECISIONS-INDEX if present). Extract `<decisions>`, `<specifics>`, and patterns (e.g., "user prefers minimal UI"). If `.soly/spikes/MANIFEST.md` or `.soly/sketches/MANIFEST.md` exist with `WRAPPED: true` frontmatter, read as validated findings.
+Most-recent 3 prior `*-CONTEXT.md` files (prefer DECISIONS-INDEX if present). Extract `<decisions>`, `<specifics>`, and patterns (e.g., "user prefers minimal UI"). If `.agents/spikes/MANIFEST.md` or `.agents/sketches/MANIFEST.md` exist with `WRAPPED: true` frontmatter, read as validated findings.
 
 **6. Cross-reference todos.** (Worker doesn't have `soly_todos`; use `bash` + `grep` with phase-domain keywords.)
 
@@ -217,9 +217,9 @@ Requirements locked by SPEC.md. Do not re-litigate.
 </decisions>
 
 <canonical_refs> <!-- MANDATORY -->
-- `.soly/docs/<file>` — <why>
-- `.soly/features/<feat>/README.md` — <why>
-- `.soly/contracts/<file>` — <why>
+- `.agents/docs/<file>` — <why>
+- `.agents/features/<feat>/README.md` — <why>
+- `.agents/contracts/<file>` — <why>
 - (no external docs referenced) <!-- only if literally none -->
 </canonical_refs>
 
@@ -289,8 +289,8 @@ Update after every round. Delete after `write_context` succeeds.
 <hard_rules>
 - No production code. Discussion/planning only.
 - No PLAN.md from this workflow — that's `soly plan`.
-- Don't assume missing intent. If `.soly/docs/` is silent, ask.
+- Don't assume missing intent. If `.agents/docs/` is silent, ask.
 - No scope creep. Deferred ideas → `<deferred_ideas>`, not decisions.
-- No subagents (you ARE one). No `.soly/rules/` edits.
+- No subagents (you ARE one). No `.agents/rules/` edits.
 - Return: structured output per output_protocol + checkpoint updates. Parent relays to user.
 </hard_rules>

package/workflows-data/execute-phase.md

@@ -3,12 +3,12 @@
 <purpose>Execute all plans in a phase, wave by wave. Per plan, follow `execute-plan.md` inline. Update STATE.md between plans. Generate a phase-level VERIFICATION.md at the end. You ARE the executor (`maxSubagentDepth: 1` is enforced — no sub-sub-agents). Checkpoint requests return a structured block; parent relays to user; next `soly execute <N>` resumes from `.execute-checkpoint.json`.</purpose>
 
 <path_discipline>
-**All soly-managed files live under `.soly/`.** Never write PLAN.md, CONTEXT.md, RESEARCH.md, SUMMARY.md, iteration files, or handoffs to the project root. All phase files go in `.soly/phases/<NN>-<slug>/`. Use absolute paths (or paths starting with `$SOLY_DIR`) — never bare relative names that could land in cwd.
+**All soly-managed files live under `.agents/`.** Never write PLAN.md, CONTEXT.md, RESEARCH.md, SUMMARY.md, iteration files, or handoffs to the project root. All phase files go in `.agents/phases/<NN>-<slug>/`. Use absolute paths (or paths starting with `$SOLY_DIR`) — never bare relative names that could land in cwd.
 
 The iteration context file (path given by the parent in the task prompt) is your single source of truth for intent, STATE, ROADMAP, and any existing phase artifacts. Read it FIRST, before any of your own `read` or `ls` calls.
 </path_discipline>
 
-<read_first>`.soly/STATE.md` (single source of truth for "where am I") · `.soly/ROADMAP.md` (phase goal + reqs) · `.soly/docs/` (INTENT, re-read before each plan) · the phase directory: list PLAN.md sorted, plus any SUMMARY.md / CONTEXT.md / RESEARCH.md / `.execute-checkpoint.json`. If `.soly/` missing → stop + error.</read_first>
+<read_first>`.agents/STATE.md` (single source of truth for "where am I") · `.agents/ROADMAP.md` (phase goal + reqs) · `.agents/docs/` (INTENT, re-read before each plan) · the phase directory: list PLAN.md sorted, plus any SUMMARY.md / CONTEXT.md / RESEARCH.md / `.execute-checkpoint.json`. If `.agents/` missing → stop + error.</read_first>
 
 <core_principle>
 **Orchestrate, don't re-specify.** Each PLAN.md is the contract; `execute-plan.md` is the per-plan protocol. This file adds: wave grouping, state transitions between plans, phase-level aggregation (VERIFICATION.md), safe resumption from partial state. The full per-plan steps live in `execute-plan.md` — read it once, then apply per plan.
@@ -28,7 +28,7 @@ PHASE="$1"
 # would fall back to the `write` tool with a relative path, polluting
 # the project root).
 PROJECT_ROOT="$(pwd)"
-SOLY_DIR="$PROJECT_ROOT/.soly"
+SOLY_DIR="$PROJECT_ROOT/.agents"
 PHASE_DIR=$(ls -d "$SOLY_DIR/phases/"*"-$PHASE-"* 2>/dev/null | head -1) || { echo "Phase $PHASE not found" >&2; exit 1; }
 PADDED_PHASE=$(printf "%02d" "$(echo "$PHASE" | grep -oE '^[0-9]+' | sed 's/^0*//')")
 PHASE_SLUG=$(basename "$PHASE_DIR")
@@ -190,7 +190,7 @@ phase: <N>  phase_slug: <slug>  status: pending  generated: <ISO>
 </process>
 
 <hard_rules>
-- No `.soly/rules/` edits. No subagents (`maxSubagentDepth: 1`).
+- No `.agents/rules/` edits. No subagents (`maxSubagentDepth: 1`).
 - No silent skip of partial-state plans — surface and stop.
 - No flipping VERIFICATION.md to `passed` yourself.
 - No silent architectural decisions — use `execute-plan.md`'s Rule 4 + checkpoint.

package/workflows-data/execute-plan.md

@@ -3,12 +3,12 @@
 <purpose>Execute one PLAN.md, produce a matching SUMMARY.md, update STATE.md/ROADMAP.md. Single worker — no sub-subagents.</purpose>
 
 <path_discipline>
-**All soly-managed files live under `.soly/`.** Never write PLAN.md, CONTEXT.md, RESEARCH.md, SUMMARY.md, iteration files, or handoffs to the project root. All phase files go in `.soly/phases/<NN>-<slug>/`. Use absolute paths (or paths starting with `$SOLY_DIR`) — never bare relative names that could land in cwd.
+**All soly-managed files live under `.agents/`.** Never write PLAN.md, CONTEXT.md, RESEARCH.md, SUMMARY.md, iteration files, or handoffs to the project root. All phase files go in `.agents/phases/<NN>-<slug>/`. Use absolute paths (or paths starting with `$SOLY_DIR`) — never bare relative names that could land in cwd.
 
 The iteration context file (path given by the parent in the task prompt) is your single source of truth for intent, STATE, ROADMAP, phase CONTEXT/RESEARCH, prior SUMMARYs, and (section 6) the current PLAN. Read it FIRST.
 </path_discipline>
 
-<read_first>`.soly/STATE.md` · `.soly/ROADMAP.md` · `PLAN.md` (the contract) · `<phase>-CONTEXT.md` if exists (honor user decisions) · `<phase>-RESEARCH.md` if exists (use chosen libs/patterns). If `.soly/` missing → stop + error.</read_first>
+<read_first>`.agents/STATE.md` · `.agents/ROADMAP.md` · `PLAN.md` (the contract) · `<phase>-CONTEXT.md` if exists (honor user decisions) · `<phase>-RESEARCH.md` if exists (use chosen libs/patterns). If `.agents/` missing → stop + error.</read_first>
 
 <atomic_close_out>
 **Only legal close-out order:** `production-code commit(s) → SUMMARY commit → STATE/ROADMAP update`.
@@ -24,7 +24,7 @@ PHASE="$1"; PLAN="$2"  # PLAN optional — defaults to next unfinished
 # Worker subagent inherits the parent's cwd (the project root), so
 # `pwd` IS the project root. The previous `cd .. && pwd` was a bug.
 PROJECT_ROOT="$(pwd)"
-SOLY_DIR="$PROJECT_ROOT/.soly"
+SOLY_DIR="$PROJECT_ROOT/.agents"
 PHASE_DIR=$(ls -d "$SOLY_DIR/phases/"*"-$PHASE-"* 2>/dev/null | head -1) || { echo "Phase $PHASE not found" >&2; exit 1; }
 PADDED_PHASE=$(printf "%02d" "$(echo "$PHASE" | grep -oE '^[0-9]+' | sed 's/^0*//')")
 PHASE_SLUG=$(basename "$PHASE_DIR")
@@ -60,7 +60,7 @@ PARTIAL_PLAN=$([ "$COMMIT_COUNT" -gt 0 ] && [ "$SUMMARY_EXISTS" = false ] && ech
 **5. Execute tasks in order.** Per task:
 
 1. **Read first** — open every `<read_first>` file.
-2. **Implement** — minimal correct change, follow project patterns. No speculative scaffolding. No `.soly/rules/` edits.
+2. **Implement** — minimal correct change, follow project patterns. No speculative scaffolding. No `.agents/rules/` edits.
 3. **Verify acceptance criteria (HARD GATE):**
    - Run the grep/file-check/CLI for each criterion in `<acceptance_criteria>`.
    - Log PASS/FAIL with output. If ANY fails → fix immediately, re-run ALL.
@@ -123,7 +123,7 @@ Can't talk to user directly. Stop, return structured block, parent relays.
 
 **9. Pre-commit hook failure:**
 1. `git commit` fails with hook error. 2. Read error — names hook + what failed. 3. Fix (type/lint/secret). 4. `git add` fixed. 5. Retry. 6. Budget 1–2 cycles per commit. If still failing → `type: "human-action"` checkpoint with hook output.
-**Do NOT use `--no-verify`** unless project's `.soly/docs/` or ROADMAP.md explicitly opts out.
+**Do NOT use `--no-verify`** unless project's `.agents/docs/` or ROADMAP.md explicitly opts out.
 
 **10. Verification failure gate:** 1st retry (hooks flake) → 2nd retry (fix obvious cause) → 3rd retry (apply deviation rules) → 3+ fails → `type: "decision"` checkpoint, STOP.
 
@@ -212,7 +212,7 @@ git commit -m "chore(${PADDED_PHASE}-${PLAN_NUM}): complete plan <N>"
 - Bump `current_plan` in "Current Position".
 - Add `key-decisions` to "Decisions" table (skip if trivial).
 - Update `last_updated`.
-- Keep < 150 lines — archive long-form to `.soly/DECISIONS-INDEX.md` if it grows.
+- Keep < 150 lines — archive long-form to `.agents/DECISIONS-INDEX.md` if it grows.
 
 **Update ROADMAP.md** — phase's progress row: increment completed plan count; status → `In Progress` (more plans) or `Complete` (last) with date.
 
@@ -222,7 +222,7 @@ git commit -m "chore(${PADDED_PHASE}-${PLAN_NUM}): complete plan <N>"
 REQUIREMENTS=$(grep -A1 "^requirements:" "$PLAN_PATH" | tail -1 | sed -E 's/.*\[([^]]+)\].*/\1/' | tr ',' ' ')
 ```
 
-For each ID, find line in `.soly/REQUIREMENTS.md`, flip status to `Complete`.
+For each ID, find line in `.agents/REQUIREMENTS.md`, flip status to `Complete`.
 
 **15. Return:**
 
@@ -241,7 +241,7 @@ For each ID, find line in `.soly/REQUIREMENTS.md`, flip status to `Complete`.
 </process>
 
 <hard_rules>
-- No `.soly/rules/` edits. No `.soly/docs/` edits without explicit user decision in conversation.
+- No `.agents/rules/` edits. No `.agents/docs/` edits without explicit user decision in conversation.
 - No subagents (you ARE one). `maxSubagentDepth: 1` is enforced.
 - **Never skip `<acceptance_criteria>` HARD GATE.** Not optional.
 - **Never emit narrative between SUMMARY `write` and `git commit`** (truncation is a known failure mode).

package/workflows-data/execute-task.md

@@ -1,14 +1,14 @@
 # Execute Task
 
-<purpose>Execute ONE task (atomic unit — a feature slice, one endpoint, one page, one contract wire). Produce SUMMARY.md. Tasks live under `.soly/features/<feature>/tasks/<task-id>/` with PLAN.md as the contract.</purpose>
+<purpose>Execute ONE task (atomic unit — a feature slice, one endpoint, one page, one contract wire). Produce SUMMARY.md. Tasks live under `.agents/features/<feature>/tasks/<task-id>/` with PLAN.md as the contract.</purpose>
 
 <path_discipline>
-**All soly-managed files live under `.soly/`.** Never write PLAN.md, SUMMARY.md, iteration files, or handoffs to the project root. Task files go in `.soly/features/<feature>/tasks/<task-id>/`. Use absolute paths — never bare relative names that could land in cwd.
+**All soly-managed files live under `.agents/`.** Never write PLAN.md, SUMMARY.md, iteration files, or handoffs to the project root. Task files go in `.agents/features/<feature>/tasks/<task-id>/`. Use absolute paths — never bare relative names that could land in cwd.
 
 The iteration context file (path given by the parent in the task prompt) is your single source of truth for intent, STATE, the feature README, prior task SUMMARYs, and the current task PLAN. Read it FIRST.
 </path_discipline>
 
-<read_first>`.soly/STATE.md` · `.soly/docs/` (INTENT, 0-point) · `.soly/features/<feature>/README.md` · `PLAN.md` (the contract) · `.soly/contracts/*` if PLAN.md references it. If `.soly/features/` or task dir missing → error + stop, do not invent paths.</read_first>
+<read_first>`.agents/STATE.md` · `.agents/docs/` (INTENT, 0-point) · `.agents/features/<feature>/README.md` · `PLAN.md` (the contract) · `.agents/contracts/*` if PLAN.md references it. If `.agents/features/` or task dir missing → error + stop, do not invent paths.</read_first>
 
 <task_frontmatter>
 PLAN.md frontmatter (executor must respect all fields; **flag** incomplete ones in your report, don't silently fill):
@@ -46,13 +46,13 @@ STATUS=$(awk '/^---$/{c++; next} c==1{print}' "$TASK_DIR/PLAN.md" | grep -E '^st
 
 If not → return `## Blocker` to parent, stop. Do NOT start a blocked task.
 
-**2. Read intent + feature context.** **0-POINT CHECK** — the iteration context file (path given in the task prompt) already contains the intent docs as a summary, the feature README, prior task SUMMARYs, and the current task PLAN. Use that. If intent and PLAN.md conflict, flag it. Read `.soly/contracts/*` (if it exists) only if the task touches API surfaces.
+**2. Read intent + feature context.** **0-POINT CHECK** — the iteration context file (path given in the task prompt) already contains the intent docs as a summary, the feature README, prior task SUMMARYs, and the current task PLAN. Use that. If intent and PLAN.md conflict, flag it. Read `.agents/contracts/*` (if it exists) only if the task touches API surfaces.
 
 **3. Execute** with standard worker self-audit:
 
 1. Write code.
 2. Run build / typecheck / lint — **0 warnings**.
-3. Cross-check diff against `.soly/rules/coding/*` (or `.editorconfig`).
+3. Cross-check diff against `.agents/rules/coding/*` (or `.editorconfig`).
 4. **Rule gap?** Invoke the project's rule-authoring skill (`analyzer-coach` or equivalent) — it proposes an `.editorconfig` entry, a coding-rule doc addition, or a custom-analyzer rule. Loop until clean, max 3 iterations.
 5. Commit production-code changes (one or more commits).
 
@@ -101,7 +101,7 @@ You may combine into one commit, but the SUMMARY must be on disk before the fron
 </process>
 
 <hard_rules>
-- No `.soly/rules/` edits. No subagents (you ARE one).
+- No `.agents/rules/` edits. No subagents (you ARE one).
 - No starting tasks with un-`done` `depends-on:`.
 - If rule gap → add via the rule-authoring skill. **No silent workarounds** (`#pragma`, `severity = none`).
 - Return: changed files, commands + exit codes, validation evidence, surprises, decisions needing parent approval.
@@ -112,5 +112,5 @@ You may combine into one commit, but the SUMMARY must be on disk before the fron
 </interactive_rules_out_of_scope>
 
 <dual_mode_note>
-Project may also have `.soly/phases/` (phase-based layout, distinct from task-based). You are only responsible for this task. Don't touch phases. Don't modify ROADMAP.md or STATE.md beyond what your close-out requires (typically nothing for tasks — the parent updates those).
+Project may also have `.agents/phases/` (phase-based layout, distinct from task-based). You are only responsible for this task. Don't touch phases. Don't modify ROADMAP.md or STATE.md beyond what your close-out requires (typically nothing for tasks — the parent updates those).
 </dual_mode_note>