pi-soly 0.9.0 → 1.1.0

package/README.md

@@ -4,7 +4,7 @@
 
 **The project management framework for [pi-coding-agent](https://github.com/nicobailon/pi-coding-agent).**
 
-Plans · State · Subagents · Multi-question picker · Agent switcher · Live task list.
+Plans · State · Subagents · Multi-question picker · Rotor switcher · Live task list.
 
 One `npm install`. Zero config. Pure magic.
 
@@ -30,7 +30,7 @@ That's it. Restart pi, and you have:
 
 - **A complete project management engine** — plans, state, subagent-driven execution
 - **A multi-question picker** — `ask_pro` tool for the LLM
-- **An agent switcher** — `Ctrl+Tab` to cycle, footer pill always visible
+- **A rotor switcher** — `Ctrl+Tab` to cycle, footer pill always visible
 - **A live task list** — `todo_update` tool renders in the footer
 - **7 soly agents** installed on first run
 
@@ -43,7 +43,7 @@ That's it. Restart pi, and you have:
 | Write your own planning workflow | `/plan`, `/execute`, `/resume`, `/inspect` — ready |
 | Manually dispatch subagents | `useSolyWorkerSubagents: true` — automatic routing |
 | 3 different packages for pickers/tasks/agents | One package, one config, one install |
-| Agent name as free text in slash commands | Footer pill + `Ctrl+Tab` + `/agent` picker |
+| Rotor name as free text in slash commands | Footer pill + `Ctrl+Tab` + `/rotor` picker |
 | Re-invent the state machine | `.soly/STATE.md` + auto-managed phases |
 
 ---
@@ -94,7 +94,7 @@ ask_pro({
 })
 ```
 
-### 🎛 Agent Switcher
+### 🎛 Rotor Switcher
 
 Footer pill that's always there. `Ctrl+Tab` to cycle. No popup, no friction.
 
@@ -171,11 +171,11 @@ todo_update({
                          ▼
                 ┌──────────────────┐
                 │  switch/         │
-                │  agent switcher  │
+                │  rotor switcher  │
                 │                  │
                 │  Ctrl+Tab        │
                 │  footer pill     │
-                │  /agent picker   │
+                │  /rotor picker   │
                 └────────┬─────────┘
                          │
                          ▼
@@ -196,7 +196,7 @@ todo_update({
 
 ## 📚 Documentation
 
-- **Slash commands** — `/plan`, `/execute`, `/resume`, `/inspect`, `/discuss <N>`, `/quick <task>`, `/agent`
+- **Slash commands** — `/plan`, `/execute`, `/resume`, `/inspect`, `/discuss <N>`, `/quick <task>`, `/rotor`
 - **Tools** — `ask_pro(question[])` and `todo_update(todo[])`
 - **Events** — `session_start`, `before_agent_start`, `message_end`, `tool_call`, `tool_result`
 - **State files** — `.soly/STATE.md`, `.soly/ROADMAP.md`, `.soly/phases/<N>-<slug>/<N>-PLAN.md`

package/agents-install.ts

@@ -35,13 +35,14 @@ const SHIPPED_SKILLS = [
 
 /** Where pi looks for user agents. Respects HOME/USERPROFILE for
  *  testability (otherwise we'd always write to the real user home).
- *  Path scheme: `<root>/.agents/agents/` (vendor-neutral) and
- *  `<root>/.pi/agent/agents/` (pi native, legacy). */
+ *  Agent files live directly in the dir (no `agents/` subfolder):
+ *    ~/.agents/reviewer.md   (NOT ~/.agents/agents/reviewer.md)
+ *  This keeps the path clean and matches the project-level convention. */
 function userAgentsDirs(): string[] {
 	const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
 	return [
-		path.join(home, ".agents", "agents"),                // vendor-neutral (preferred)
-		path.join(home, ".pi", "agent", "agents"),           // pi native
+		path.join(home, ".agents"),                          // vendor-neutral (preferred)
+		path.join(home, ".pi", "agent", "agents"),           // pi native (legacy)
 	];
 }
 
@@ -94,7 +95,7 @@ function copyDirIfMissing(from: string, to: string): "installed" | "skipped" | "
 
 /** Install shipped soly agents to `~/.agents/` (vendor-neutral,
  *  preferred). Legacy `~/.pi/agent/agents/` copies are left alone —
- *  `discoverUserAgents` reads both, so old installs still work. */
+ *  `discoverUserRotors` reads both, so old installs still work. */
 export function installSolyAgents(extensionRoot: string): InstallResult {
 	const result: InstallResult = { installed: [], skipped: [], errors: [] };
 	const src = shippedAgentsDir(extensionRoot);

package/commands.ts

@@ -26,6 +26,7 @@ import {
 	formatAnalyticsFull,
 	formatTok,
 	readIfExists,
+	solyDirFor,
 	type RuleFile,
 	type SolyState,
 } from "./core.ts";
@@ -204,7 +205,7 @@ export function registerCommands(pi: ExtensionAPI, deps: CommandsDeps): void {
 			}
 			const cat = categories[choice];
 			if (!cat) return;
-			const dir = path.join(cwd, ".soly", "rules", cat.name);
+			const dir = path.join(solyDirFor(cwd), "rules", cat.name);
 			try {
 				fs.mkdirSync(dir, { recursive: true });
 			} catch {}
@@ -296,7 +297,7 @@ What must the LLM do?
 				const lastSeg = parsed.pathname.split("/").filter(Boolean).pop() ?? "rule.md";
 				const safeName = lastSeg.replace(/[^A-Za-z0-9._-]/g, "_");
 				const fileName = safeName.endsWith(".md") ? safeName : `${safeName}.md`;
-				const rulesRoot = path.join(process.cwd(), ".soly", "rules");
+				const rulesRoot = path.join(solyDirFor(process.cwd()), "rules");
 				fs.mkdirSync(rulesRoot, { recursive: true });
 				const targetFile = path.join(rulesRoot, fileName);
 				// Refuse to overwrite without warning
@@ -371,8 +372,8 @@ What must the LLM do?
 			};
 			const subcommands: Record<string, SolySub> = {
 				// `agent` subcommand REMOVED — moved to the separate `pi-switch`
-				// extension as the `/agent` slash command (footer pill + Ctrl+Tab).
-				// Soly no longer owns the agent switcher UI.
+				// extension as the `/rotor` slash command (footer pill + Ctrl+Tab).
+				// Soly no longer owns the rotor switcher UI.
 				config: {
 					description: "show merged config (per-project + global + defaults); edit .soly/config.json or ~/.soly/config.json",
 					run: () => {

package/core.ts

@@ -1521,12 +1521,27 @@ export function buildStatusLine(
 // Soly dir helper
 // ============================================================================
 
-/** Default soly dir relative to cwd. */
-export const SOLY_DIRNAME = ".soly";
+/** Preferred soly dir name (vendor-neutral). */
+export const SOLY_DIRNAME = ".agents";
 
-/** Build the .soly dir path for a given cwd. */
+/** Legacy soly dir name. Kept for backward compat with existing projects. */
+export const LEGACY_SOLY_DIRNAME = ".soly";
+
+/** Which project subdir name is currently in use. Returns the first
+ *  one that exists, preferring `.agents/`. Falls back to `.soly/` if
+ *  no `.agents/` exists. If neither exists, returns `.agents/` (so
+ *  new writes go to the new location). */
 export function solyDirFor(cwd: string): string {
-  return path.join(cwd, SOLY_DIRNAME);
+	if (fs.existsSync(path.join(cwd, SOLY_DIRNAME))) return path.join(cwd, SOLY_DIRNAME);
+	if (fs.existsSync(path.join(cwd, LEGACY_SOLY_DIRNAME))) return path.join(cwd, LEGACY_SOLY_DIRNAME);
+	return path.join(cwd, SOLY_DIRNAME); // default to new for new projects
+}
+
+/** True if the legacy `.soly/` dir is in active use (and `.agents/` isn't). */
+export function isLegacySolyDir(cwd: string): boolean {
+	const newPath = path.join(cwd, SOLY_DIRNAME);
+	const oldPath = path.join(cwd, LEGACY_SOLY_DIRNAME);
+	return !fs.existsSync(newPath) && fs.existsSync(oldPath);
 }
 
 // ============================================================================

package/index.ts

@@ -38,6 +38,7 @@ import {
 	loadProjectState,
 	STATUS_ID,
 	solyDirFor,
+	isLegacySolyDir,
 	buildNextHint,
 	buildDriftReminder,
 	type RuleFile,
@@ -53,6 +54,7 @@ import {
 	type SolyConfig,
 } from "./config.ts";
 import { classifyTaskHeuristics, buildNudgeSection } from "./nudge.ts";
+import { notifyNudge, notifyDeprecation } from "./notification.ts";
 import { registerCommands, type CommandUI } from "./commands.ts";
 import { registerTools } from "./tools.ts";
 import { registerWorkflows } from "./workflows/index.ts";
@@ -80,12 +82,12 @@ export default function solyExtension(pi: ExtensionAPI) {
 	let sessionCwd = "";
 
 	// ============================================================================
-	// Agent switcher (Shift+Tab cycles through available subagents)
+	// Rotor switcher (Shift+Tab cycles through available rotors)
 	// ============================================================================
 
 	// ============================================================================
-	// Agent switcher: REMOVED. The agent cycler is now owned by the
-	// separate `pi-switch` extension (footer pill + Ctrl+Tab + /agent slash).
+	// Rotor switcher: REMOVED. The rotor cycler is now owned by the
+	// separate `pi-switch` extension (footer pill + Ctrl+Tab + /rotor slash).
 	// Soly owns a single subagent (soly-manager.md) and the auto-install on
 	// opt-in. Workflows read the current agent from
 	// globalThis.__PI_SWITCH_AGENT__ (set by pi-switch).
@@ -328,7 +330,7 @@ export default function solyExtension(pi: ExtensionAPI) {
 	// and mnemonic for "A"gent.)
 	// ============================================================================
 	// Agent switcher REMOVED — moved to the separate `pi-switch` extension.
-	// Soly no longer owns Ctrl+Tab, the footer pill, or /agent slash.
+	// Soly no longer owns Ctrl+Tab, the footer pill, or /rotor slash.
 	// The current agent is read by soly workflows from
 	// globalThis.__PI_SWITCH_AGENT__ (set by pi-switch), with a fallback
 	// to "worker" if pi-switch isn't installed.
@@ -350,6 +352,17 @@ 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.
+		if (isLegacySolyDir(ctx.cwd)) {
+			notifyDeprecation(
+				ctx.ui,
+				`.soly/ (legacy)`,
+				`.agents/ (vendor-neutral)`,
+				`Run \`mv .soly .agents\` to migrate. Both names work for now.`,
+			);
+		}
+
 		// Rules sources (priority order, higher wins on relPath collision).
 		// Project rules always beat global rules. .soly/rules.local/ is
 		// gitignored — for personal overrides on top of the project's rules.
@@ -663,11 +676,7 @@ export default function solyExtension(pi: ExtensionAPI) {
 		const angle =
 			heuristics.suggestedAngles[0] ?? "want me to confirm assumptions before I start?";
 
-		const label = heuristics.researchHeavy
-			? "soly: research-heavy prompt — clarifying question?"
-			: "soly: non-trivial prompt — clarifying question?";
-
-		ctx.ui.notify(`${label} ${angle}`, "info");
+		notifyNudge(ctx.ui, heuristics.researchHeavy ? "research" : "nonTrivial", angle);
 		nudgeActiveForTask = true;
 		lastNudgePromptKey = text.slice(0, 200);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-soly",
-  "version": "0.9.0",
+  "version": "1.1.0",
   "description": "Project management framework for pi-coding-agent. Workflows, planning, multi-question picker, agent switcher, live task list — one npm install, zero config.",
   "type": "module",
   "main": "index.ts",

package/skills/soly-framework/SKILL.md

@@ -35,7 +35,7 @@ The **soly** extension adds project-management workflow to [pi-coding-agent](htt
 | `/quick <task>` | One-shot task that doesn't need a full plan — direct dispatch |
 | `/soly` | Project state inspection (alias for `/inspect`) |
 | `/why` | Show what context the LLM's last turn was based on |
-| `/agent [name]` | Switch the current cycle agent (or open picker) |
+| `/rotor [name]` | Switch the current rotor (or open picker) |
 
 `/soly <verb>` plain-text aliases also work for some verbs (legacy compat).
 
@@ -81,11 +81,13 @@ The **soly** extension adds project-management workflow to [pi-coding-agent](htt
 │       └── data-scientist.md
 ```
 
-**Two parallel conventions:** `.soly/` is soly-specific state (phases, plans). `.agents/` is vendor-neutral agent config (works with any AI tool that follows the AGENTS.md standard). The two coexist:
+**Two parallel conventions (migration in progress):** `.soly/` is the legacy soly state. `.agents/` is the new vendor-neutral home. The two work side-by-side:
 
-- 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
+- **Use `.agents/`** for new projects (recommended)
+- **Use `.soly/`** for legacy projects (still works, will show a deprecation warning)
+- **Use `AGENTS.md`** for top-level project-wide agent conventions
+
+To migrate: `mv .soly .agents` — soly picks up the new location automatically. No data loss.
 
 ## Frontmatter conventions
 
@@ -198,16 +200,18 @@ The only legal sequence for finishing a plan:
 
 Once production commits exist, returning without a committed `SUMMARY.md` is an **illegal partial-plan state** — the next `/execute` will detect it and refuse to start.
 
-## Cycle agents (4 built-in)
+## Cycle rotors (4 built-in)
 
-| Agent | Writes | Use for |
+| Rotor | Writes | Use for |
 |---|---|---|
 | `worker` | ✅ | Generic implementation, full tools |
 | `oracle` | ❌ | Decision-consistency, no file edits |
 | `scout` | ❌ | Codebase recon, read-only |
 | `reviewer` | ❌ | Adversarial code review |
 
-Switch with `/agent <name>` or `Ctrl+Tab` (cycles through). Footer pill shows current: `· ⚡ worker` / `▶ 🐢 oracle`.
+Switch with `/rotor <name>` or `Ctrl+Tab` (cycles through). Footer pill shows current: `· ⚡ worker` / `▶ 🐢 oracle`.
+
+**Why "rotors"?** Because they *rotate* — `Ctrl+Tab` cycles through them. The word emphasizes the cycling behavior. Subagents (like `soly-manager`) are still called agents — they're a different concept (spawned for a task, not cycled through).
 
 ## Subagent: soly-manager (single, mode-switching)
 
@@ -300,7 +304,7 @@ Intent docs are 0-point — written BEFORE any plan, by humans. They define the
 
 ### Add project-specific agents
 
-Drop a markdown file in `.agents/agents/<name>.md` (project) or `~/.agents/agents/<name>.md` (user):
+Drop a markdown file in `.agents/<name>.md` (project) or `~/.agents/<name>.md` (user):
 
 ```markdown
 ---
@@ -314,9 +318,9 @@ You are a data scientist. ...
 ```
 
 **Discovered from 4 locations** (priority order):
-1. `<project>/.agents/agents/` — project vendor-neutral (preferred)
+1. `<project>/.agents/` — project vendor-neutral (preferred)
 2. `<project>/.pi/agent/agents/` — project pi native (legacy)
-3. `~/.agents/agents/` — user vendor-neutral (preferred)
+3. `~/.agents/` — user vendor-neutral (preferred)
 4. `~/.pi/agent/agents/` — user pi native (legacy)
 
 `Ctrl+Tab` to see them in the cycle.

package/switch/core.ts

@@ -1,5 +1,5 @@
 // =============================================================================
-// core.ts — Generic subagent switcher for pi
+// core.ts — Generic subrotor switcher for pi
 // =============================================================================
 //
 // Lets the user pick which subagent the LLM uses (for `subagent(...)` calls
@@ -12,7 +12,7 @@
 // pass Ctrl+Tab through).
 //
 // Communication with other extensions:
-// - Writes `globalThis.__PI_SWITCH_AGENT__` (in-process)
+// - Writes `globalThis.__PI_SWITCH_ROTOR__` (in-process)
 // - Reads/writes `.soly/agent` if it exists (cross-session persistence,
 //   shared with soly extension). If no soly project, persists to
 //   `~/.pi-switch/agent` instead.
@@ -23,10 +23,10 @@ import * as os from "node:os";
 import * as path from "node:path";
 
 /** Default agent used when no override is set. */
-export const DEFAULT_AGENT = "worker";
+export const DEFAULT_ROTOR = "worker";
 
 /** Built-in pi-subagents that we always offer in the cycle. */
-export const BUILTIN_AGENTS: readonly string[] = [
+export const BUILTIN_ROTORS: readonly string[] = [
 	"worker",
 	"oracle",
 	"scout",
@@ -35,14 +35,14 @@ export const BUILTIN_AGENTS: readonly string[] = [
 
 /** Visual metadata for every known agent. Used by the rich status badge,
  *  the header bar, and the multi-line switch notify. */
-export interface AgentMeta {
+export interface RotorMeta {
 	emoji: string;
 	shortLabel: string;
 	description: string;
 	writesFiles: boolean;
 }
 
-export const AGENT_META: Record<string, AgentMeta> = {
+export const ROTOR_META: Record<string, RotorMeta> = {
 	worker: { emoji: "\u26a1", shortLabel: "worker", description: "generic implementation, all tools", writesFiles: true },
 	oracle: { emoji: "\ud83d\udd2e", shortLabel: "oracle", description: "decision-consistency, no file edits", writesFiles: false },
 	scout: { emoji: "\ud83d\udd0d", shortLabel: "scout", description: "codebase recon, read-only", writesFiles: false },
@@ -50,8 +50,8 @@ export const AGENT_META: Record<string, AgentMeta> = {
 };
 
 /** Get metadata for an agent. Falls back to a neutral entry for unknown. */
-export function getAgentMeta(name: string): AgentMeta {
-	return AGENT_META[name] ?? {
+export function getRotorMeta(name: string): RotorMeta {
+	return ROTOR_META[name] ?? {
 		emoji: "\u2753",
 		shortLabel: name.length > 12 ? name.slice(0, 11) + "\u2026" : name,
 		description: "user-defined agent",
@@ -60,34 +60,36 @@ export function getAgentMeta(name: string): AgentMeta {
 }
 
 /** Validate an agent name. */
-export function isValidAgentName(name: string): boolean {
+export function isValidRotorName(name: string): boolean {
 	return /^[a-zA-Z0-9_-]{1,64}$/.test(name);
 }
 
 /** Discover agent `.md` files in user dir. */
 /** All known agent home directories, in priority order (project wins
  *  over user-home; user-home `.agents/` wins over pi-native).
- *  Project-level `.agents/agents/` is a vendor-neutral per-project
+ *  Project-level `.agents/` is a vendor-neutral per-project
  *  convention — same role as `.soly/` or the old `.claude/`.
+ *  Agent .md files live DIRECTLY in the dir (not in a subfolder):
+ *    .agents/reviewer.md   (NOT .agents/agents/reviewer.md)
  *  Honors $HOME / $USERPROFILE for testability. */
-export function agentHomeDirs(cwd?: string): string[] {
+export function rotorHomeDirs(cwd?: string): string[] {
 	const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
 	const dirs: string[] = [];
 	if (cwd) {
-		dirs.push(path.join(cwd, ".agents", "agents"));         // project (vendor-neutral, preferred)
-		dirs.push(path.join(cwd, ".pi", "agent", "agents"));    // project (pi native, legacy)
+		dirs.push(path.join(cwd, ".agents"));                  // project (vendor-neutral, preferred)
+		dirs.push(path.join(cwd, ".pi", "agent", "agents"));   // project (pi native, legacy)
 	}
-	dirs.push(path.join(home, ".agents", "agents"));              // user (vendor-neutral)
-	dirs.push(path.join(home, ".pi", "agent", "agents"));         // user (pi native, legacy)
+	dirs.push(path.join(home, ".agents"));                       // user (vendor-neutral)
+	dirs.push(path.join(home, ".pi", "agent", "agents"));       // user (pi native, legacy)
 	return dirs;
 }
 
 /** Read all agent names from every home dir. Dedupes, first-occurrence
  *  wins. If cwd is provided, project dirs are scanned first. */
-export function discoverUserAgents(cwd?: string): string[] {
+export function discoverUserRotors(cwd?: string): string[] {
 	const seen = new Set<string>();
 	const out: string[] = [];
-	for (const dir of agentHomeDirs(cwd)) {
+	for (const dir of rotorHomeDirs(cwd)) {
 		if (!fs.existsSync(dir)) continue;
 		let entries: string[];
 		try {
@@ -105,7 +107,7 @@ export function discoverUserAgents(cwd?: string): string[] {
 				const nameMatch = fm.match(/^name:\s*(.+)$/m);
 				if (nameMatch) {
 					const n = (nameMatch[1] ?? "").trim();
-					if (isValidAgentName(n) && !seen.has(n)) {
+					if (isValidRotorName(n) && !seen.has(n)) {
 						seen.add(n);
 						out.push(n);
 					}
@@ -128,37 +130,37 @@ export function availableAgents(cwd?: string): string[] {
 			out.push(n);
 		}
 	};
-	for (const a of BUILTIN_AGENTS) push(a);
-	for (const a of discoverUserAgents(cwd)) push(a);
+	for (const a of BUILTIN_ROTORS) push(a);
+	for (const a of discoverUserRotors(cwd)) push(a);
 	return out;
 }
 
 /** Cycle order. */
 export function nextAgent(current: string, cycle: readonly string[]): string {
-	if (cycle.length === 0) return DEFAULT_AGENT;
+	if (cycle.length === 0) return DEFAULT_ROTOR;
 	const idx = cycle.indexOf(current);
 	if (idx < 0) return cycle[0]!;
 	return cycle[(idx + 1) % cycle.length]!;
 }
 
 /** Parse a user-supplied agent name. */
-export function parseAgentName(raw: string): string | null {
+export function parseRotorName(raw: string): string | null {
 	const n = raw.trim();
-	if (!isValidAgentName(n)) return null;
+	if (!isValidRotorName(n)) return null;
 	return n;
 }
 
 /** Short badge: `<emoji> <name>`. Null for default (silent). */
 export function formatAgentBadge(agent: string): string | null {
-	if (agent === DEFAULT_AGENT) return null;
-	const meta = getAgentMeta(agent);
+	if (agent === DEFAULT_ROTOR) return null;
+	const meta = getRotorMeta(agent);
 	return `${meta.emoji} ${agent}`;
 }
 
 /** Multi-line switch notify. */
-export function formatAgentSwitchNotify(prev: string, next: string): string {
-	const prevMeta = getAgentMeta(prev);
-	const nextMeta = getAgentMeta(next);
+export function formatRotorSwitchNotify(prev: string, next: string): string {
+	const prevMeta = getRotorMeta(prev);
+	const nextMeta = getRotorMeta(next);
 	const lines: string[] = [
 		"pi-switch agent changed",
 		"",
@@ -171,19 +173,19 @@ export function formatAgentSwitchNotify(prev: string, next: string): string {
 }
 
 /** Group agents: built-ins + user-defined. */
-export function groupedAvailableAgents(cwd?: string): Array<{ header: string; agents: string[] }> {
+export function groupedAvailableRotors(cwd?: string): Array<{ header: string; agents: string[] }> {
 	const all = availableAgents(cwd);
 	const groups: Array<{ header: string; agents: string[] }> = [];
-	const builtin = all.filter((a) => BUILTIN_AGENTS.includes(a));
+	const builtin = all.filter((a) => BUILTIN_ROTORS.includes(a));
 	if (builtin.length > 0) groups.push({ header: "built-in", agents: builtin });
-	const user = all.filter((a) => !BUILTIN_AGENTS.includes(a));
+	const user = all.filter((a) => !BUILTIN_ROTORS.includes(a));
 	if (user.length > 0) groups.push({ header: "user-defined", agents: user });
 	return groups;
 }
 
 /** Header line shown above chat. Persistent, dim, single line. */
 export function formatHeaderLine(agent: string): string {
-	const meta = getAgentMeta(agent);
+	const meta = getRotorMeta(agent);
 	const writeTag = meta.writesFiles ? "" : " \u00b7 read-only";
 	return `${meta.emoji} ${agent}  \u00b7  ${meta.description}${writeTag}    [Ctrl+Tab to cycle]`;
 }
@@ -210,7 +212,7 @@ export function loadAgent(cwd: string): string | null {
 		const file = agentFilePath(cwd);
 		if (!fs.existsSync(file)) return null;
 		const raw = fs.readFileSync(file, "utf-8").trim();
-		if (!isValidAgentName(raw)) return null;
+		if (!isValidRotorName(raw)) return null;
 		return raw;
 	} catch {
 		return null;

package/switch/index.ts

@@ -2,18 +2,18 @@
 // index.ts — pi-switch extension entry (v2: footer-pill UI)
 // =============================================================================
 //
-// Wires the agent switcher into pi as a compact footer pill:
+// Wires the rotor switcher into pi as a compact footer pill:
 //   - Footer status pill: "▶ ⚡ worker" (or "· ⚡ worker" for the default)
-//   - Click pill or `/agent` → open full picker modal (SelectList)
-//   - Ctrl+Tab → cycle to next agent (no popup, hot switch)
+//   - Click pill or `/rotor` → open full picker modal (SelectList)
+//   - Ctrl+Tab → cycle to next rotor (no popup, hot switch)
 //   - F2 → same, fallback if your terminal doesn't pass Ctrl+Tab through
-//   - Persists current agent to .soly/agent or ~/.pi-switch/agent
-//   - Exposes `globalThis.__PI_SWITCH_AGENT__` for other extensions
+//   - Persists current rotor to .soly/agent or ~/.pi-switch/agent
+//   - Exposes `globalThis.__PI_SWITCH_ROTOR__` for other extensions
 //   - Injects a short system-prompt section so the LLM knows the current
-//     agent and the available alternatives
+//     rotor and the available alternatives
 //
 // UI philosophy:
-//   - Header is for content, not for tool chrome. Move agents to footer.
+//   - Header is for content, not for tool chrome. Move rotors to footer.
 //   - Click to explore, hotkey to power-use, no DOM clutter in between.
 //   - Visual change is the pill text only. Chat stays clean.
 // =============================================================================
@@ -24,57 +24,57 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import {
-	DEFAULT_AGENT,
-	BUILTIN_AGENTS,
+	DEFAULT_ROTOR,
+	BUILTIN_ROTORS,
 	availableAgents,
 	nextAgent,
-	parseAgentName,
-	groupedAvailableAgents,
-	getAgentMeta,
+	parseRotorName,
+	groupedAvailableRotors,
+	getRotorMeta,
 	loadAgent,
 	saveAgent,
 } from "./core.ts";
 import { buildPiSwitchSection, recommendAgent } from "./prompt.ts";
 
-const GLOBAL_KEY = "__PI_SWITCH_AGENT__";
+const GLOBAL_KEY = "__PI_SWITCH_ROTOR__";
 
 export default function piSwitchExtension(pi: ExtensionAPI) {
 	let cwd = "";
-	let currentAgent: string = DEFAULT_AGENT;
-	let cycle: string[] = [DEFAULT_AGENT];
+	let currentRotor: string = DEFAULT_ROTOR;
+	let cycle: string[] = [DEFAULT_ROTOR];
 	let lastUi: ExtensionUIContext | null = null;
 
 	function refreshCycle(): void {
 		cycle = availableAgents(cwd);
-		if (!cycle.includes(currentAgent)) currentAgent = DEFAULT_AGENT;
+		if (!cycle.includes(currentRotor)) currentRotor = DEFAULT_ROTOR;
 	}
 
 	function publish(): void {
-		(globalThis as Record<string, unknown>)[GLOBAL_KEY] = currentAgent;
+		(globalThis as Record<string, unknown>)[GLOBAL_KEY] = currentRotor;
 	}
 
 	function rerender(): void {
 		if (!lastUi) return;
 		try {
-			const meta = getAgentMeta(currentAgent);
+			const meta = getRotorMeta(currentRotor);
 			// Persistent pill — always visible above the input, even for the
-			// default agent. The user wants a constant mode indicator, not a
+			// default rotor. The user wants a constant mode indicator, not a
 			// transient one. Marker "▶" makes it scannable.
-			const marker = currentAgent === DEFAULT_AGENT ? "·" : "▶";
-			const pill = `${marker} ${meta.emoji} ${currentAgent}`;
+			const marker = currentRotor === DEFAULT_ROTOR ? "·" : "▶";
+			const pill = `${marker} ${meta.emoji} ${currentRotor}`;
 			lastUi.setStatus("pi-switch", pill);
 		} catch { /* no ui yet */ }
 	}
 
-	function setAgent(next: string): void {
-		const prev = currentAgent;
+	function setRotor(next: string): void {
+		const prev = currentRotor;
 		if (next === prev) return;
-		currentAgent = next;
+		currentRotor = next;
 		publish();
 		if (cwd) saveAgent(cwd, next);
 		rerender();
 		// Footer pill is the only visible signal of the switch.
-		// Chat stays clean — agent is plumbing, not conversation content.
+		// Chat stays clean — rotor is plumbing, not conversation content.
 	}
 
 	// ----- session_start: load persisted agent + set initial pill -----
@@ -83,7 +83,7 @@ export default function piSwitchExtension(pi: ExtensionAPI) {
 		lastUi = ctx.ui;
 		publish();
 		const restored = loadAgent(cwd);
-		if (restored) currentAgent = restored;
+		if (restored) currentRotor = restored;
 		refreshCycle();
 		publish();
 		rerender();
@@ -113,7 +113,7 @@ export default function piSwitchExtension(pi: ExtensionAPI) {
 		lastCycleTs = now;
 		lastUi = sctx.ui;
 		refreshCycle();
-		setAgent(nextAgent(currentAgent, cycle));
+		setRotor(nextAgent(currentRotor, cycle));
 	};
 	pi.registerShortcut("ctrl+tab", {
 		description: "Cycle to next agent (worker → oracle → scout → …)",
@@ -124,9 +124,10 @@ export default function piSwitchExtension(pi: ExtensionAPI) {
 		handler: (sctx) => cycleShortcut(sctx),
 	});
 
-	// ----- /agent: open picker, or subcommands (create / doctor / recommend / set) -----
-	pi.registerCommand("agent", {
-		description: "open agent picker, or `set <name>`, `create`, `doctor`, `recommend <task>`",
+	// ----- /rotor: open picker, or subcommands (create / doctor / recommend / set) -----
+	// (formerly /agent — renamed to /rotor in 1.0.0 to match the "rotor" naming convention)
+	pi.registerCommand("rotor", {
+		description: "open rotor picker, or `set <name>`, `create`, `doctor`, `recommend <task>`",
 		handler: async (args, ctx) => {
 			lastUi = ctx.ui;
 			refreshCycle();
@@ -140,7 +141,7 @@ export default function piSwitchExtension(pi: ExtensionAPI) {
 			if (subcommand === "set" && arg) return handleSet(arg, ctx.ui);
 
 			// Direct agent name → set
-			if (subcommand && cycle.includes(subcommand)) return setAgent(subcommand);
+			if (subcommand && cycle.includes(subcommand)) return setRotor(subcommand);
 			if (arg && !subcommand) return handleSet(arg, ctx.ui);
 
 			// No arg: open picker modal
@@ -159,28 +160,28 @@ function openPicker(ui: ExtensionUIContext): void {
 		for (const g of groups) {
 			all.push({ value: "__sep__", label: `── ${g.header} `, description: "", isCurrent: false });
 			for (const a of g.agents) {
-				const m = getAgentMeta(a);
+				const m = getRotorMeta(a);
 				all.push({
 					value: a,
 					label: `${m.emoji}  ${a}`,
 					description: `${m.description}${m.writesFiles ? "" : "  ·  read-only"}`,
-					isCurrent: a === currentAgentRef(),
+					isCurrent: a === currentRotorRef(),
 				});
 			}
 		}
 		return all;
 	}, ui, (choice) => {
-		if (choice && choice !== "__sep__") setAgentRef(choice);
+		if (choice && choice !== "__sep__") setRotorRef(choice);
 	});
 }
 
 function handleSet(name: string, ui: ExtensionUIContext): void {
-	const target = parseAgentName(name);
+	const target = parseRotorName(name);
 	if (!target) return ui.notify(`pi-switch: invalid name "${name}".`, "error");
 	if (!availableAgents(cwd).includes(target)) {
 		return ui.notify(`pi-switch: unknown "${target}". available: ${availableAgents(cwd).join(", ")}`, "error");
 	}
-	setAgentRef(target);
+	setRotorRef(target);
 }
 
 function handleRecommend(task: string, ui: ExtensionUIContext): void {
@@ -191,22 +192,22 @@ function handleRecommend(task: string, ui: ExtensionUIContext): void {
 }
 
 // ---------------------------------------------------------------------------
-// setAgent / currentAgent — module-scope so the modal can mutate them
+// setAgent / currentRotor — module-scope so the modal can mutate them
 // ---------------------------------------------------------------------------
 
-let currentAgentRef: () => string = () => DEFAULT_AGENT;
-let setAgentRef: (next: string) => void = () => {};
+let currentRotorRef: () => string = () => DEFAULT_ROTOR;
+let setRotorRef: (next: string) => void = () => {};
 
 // The picker and the main extension share state via these refs.
 // We patch them in `wire()` at the top of the default export.
 function wire(get: () => string, set: (n: string) => void): void {
-	currentAgentRef = get;
-	setAgentRef = set;
+	currentRotorRef = get;
+	setRotorRef = set;
 }
 
 function refreshAndBuild<T>(
 	ui: ExtensionUIContext,
-	build: (groups: ReturnType<typeof groupedAvailableAgents>) => T,
+	build: (groups: ReturnType<typeof groupedAvailableRotors>) => T,
 	_ui: ExtensionUIContext,
 	_onSelect: (value: string) => void,
 ): void {
@@ -227,7 +228,7 @@ function createAgent(
 		ui.notify("pi-switch: usage — `/agent create <name>`", "info");
 		return;
 	}
-	if (!parseAgentName(name)) {
+	if (!parseRotorName(name)) {
 		ui.notify(`pi-switch: invalid name "${name}". Use letters/digits/dashes/underscores, ≤64 chars.`, "error");
 		return;
 	}
@@ -266,7 +267,7 @@ function createAgent(
 			// race where two parallel createAgent calls would clobber each
 			// other's write after both pass the existsSync check.
 			const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
-			fs.writeFileSync(tmp, agentTemplate(name, description), "utf-8");
+			fs.writeFileSync(tmp, rotorTemplate(name, description), "utf-8");
 			fs.renameSync(tmp, file);
 			ui.notify(
 				`pi-switch: created ${file}\n  → next Ctrl+Tab to see it in the cycle\n  → edit the system prompt to specialize`,
@@ -278,7 +279,7 @@ function createAgent(
 	});
 }
 
-function agentTemplate(name: string, description: string): string {
+function rotorTemplate(name: string, description: string): string {
 	return `---
 name: ${name}
 description: ${description}
@@ -317,8 +318,8 @@ function doctorReport(): string {
 	const cycle = availableAgents(cwd);
 	const userDir = path.join(os.homedir(), ".pi", "agent", "agents");
 	const lines: string[] = ["pi-switch doctor:", ""];
-	const builtins = cycle.filter((a) => BUILTIN_AGENTS.includes(a));
-	const users = cycle.filter((a) => !BUILTIN_AGENTS.includes(a));
+	const builtins = cycle.filter((a) => BUILTIN_ROTORS.includes(a));
+	const users = cycle.filter((a) => !BUILTIN_ROTORS.includes(a));
 	lines.push(`cycle: ${cycle.length} agents (${builtins.length} built-in, ${users.length} user)`);
 	lines.push("");
 	if (!fs.existsSync(userDir)) {

package/switch/tests/core.test.ts

@@ -8,58 +8,58 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import {
-	DEFAULT_AGENT,
-	BUILTIN_AGENTS,
-	AGENT_META,
-	getAgentMeta,
-	isValidAgentName,
-	discoverUserAgents,
+	DEFAULT_ROTOR,
+	BUILTIN_ROTORS,
+	ROTOR_META,
+	getRotorMeta,
+	isValidRotorName,
+	discoverUserRotors,
 	availableAgents,
 	nextAgent,
-	parseAgentName,
+	parseRotorName,
 	formatAgentBadge,
-	formatAgentSwitchNotify,
+	formatRotorSwitchNotify,
 	formatHeaderLine,
-	groupedAvailableAgents,
+	groupedAvailableRotors,
 	agentFilePath,
 	loadAgent,
 	saveAgent,
 } from "../core.js";
 
-describe("DEFAULT_AGENT", () => {
+describe("DEFAULT_ROTOR", () => {
 	test("is 'worker'", () => {
-		expect(DEFAULT_AGENT).toBe("worker");
+		expect(DEFAULT_ROTOR).toBe("worker");
 	});
 });
 
-describe("isValidAgentName", () => {
+describe("isValidRotorName", () => {
 	test("accepts simple names", () => {
-		expect(isValidAgentName("worker")).toBe(true);
-		expect(isValidAgentName("my_agent")).toBe(true);
+		expect(isValidRotorName("worker")).toBe(true);
+		expect(isValidRotorName("my_agent")).toBe(true);
 	});
 	test("rejects invalid", () => {
-		expect(isValidAgentName("with space")).toBe(false);
-		expect(isValidAgentName("")).toBe(false);
-		expect(isValidAgentName("a".repeat(65))).toBe(false);
+		expect(isValidRotorName("with space")).toBe(false);
+		expect(isValidRotorName("")).toBe(false);
+		expect(isValidRotorName("a".repeat(65))).toBe(false);
 	});
 });
 
-describe("AGENT_META", () => {
+describe("ROTOR_META", () => {
 	test("every built-in has metadata", () => {
-		for (const a of BUILTIN_AGENTS) {
-			expect(AGENT_META[a]).toBeDefined();
-			expect(AGENT_META[a]!.emoji.length).toBeGreaterThan(0);
+		for (const a of BUILTIN_ROTORS) {
+			expect(ROTOR_META[a]).toBeDefined();
+			expect(ROTOR_META[a]!.emoji.length).toBeGreaterThan(0);
 		}
 	});
 	test("meta has writesFiles flag", () => {
-		expect(AGENT_META.worker!.writesFiles).toBe(true);
-		expect(AGENT_META.oracle!.writesFiles).toBe(false);
+		expect(ROTOR_META.worker!.writesFiles).toBe(true);
+		expect(ROTOR_META.oracle!.writesFiles).toBe(false);
 	});
 });
 
-describe("getAgentMeta", () => {
+describe("getRotorMeta", () => {
 	test("returns fallback for unknown", () => {
-		const m = getAgentMeta("zzz");
+		const m = getRotorMeta("zzz");
 		expect(m.emoji.length).toBeGreaterThan(0);
 	});
 });
@@ -74,16 +74,16 @@ describe("nextAgent", () => {
 	});
 });
 
-describe("parseAgentName", () => {
+describe("parseRotorName", () => {
 	test("trims and validates", () => {
-		expect(parseAgentName("  oracle  ")).toBe("oracle");
-		expect(parseAgentName("with space")).toBeNull();
+		expect(parseRotorName("  oracle  ")).toBe("oracle");
+		expect(parseRotorName("with space")).toBeNull();
 	});
 });
 
 describe("formatAgentBadge", () => {
 	test("null for default", () => {
-		expect(formatAgentBadge(DEFAULT_AGENT)).toBeNull();
+		expect(formatAgentBadge(DEFAULT_ROTOR)).toBeNull();
 	});
 	test("emoji + name for non-default", () => {
 		const b = formatAgentBadge("oracle");
@@ -91,9 +91,9 @@ describe("formatAgentBadge", () => {
 	});
 });
 
-describe("formatAgentSwitchNotify", () => {
+describe("formatRotorSwitchNotify", () => {
 	test("multi-line: old → new + capability", () => {
-		const out = formatAgentSwitchNotify("worker", "oracle");
+		const out = formatRotorSwitchNotify("worker", "oracle");
 		expect(out).toContain("pi-switch agent changed");
 		expect(out).toContain("worker");
 		expect(out).toContain("oracle");
@@ -117,23 +117,23 @@ describe("formatHeaderLine", () => {
 	});
 });
 
-describe("groupedAvailableAgents", () => {
+describe("groupedAvailableRotors", () => {
 	test("includes built-in group", () => {
-		const groups = groupedAvailableAgents("/nonexistent");
+		const groups = groupedAvailableRotors("/nonexistent");
 		expect(groups[0]?.header).toBe("built-in");
 	});
 	test("includes user group when present", () => {
-		// Use HOME override so the new ~.agents/agents/ scan picks up our fixture
+		// Use HOME override so the new ~.agents/ scan picks up our fixture
 		const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
 		const prevHome = process.env.HOME;
 		const prevUserProfile = process.env.USERPROFILE;
 		const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "pis-home-"));
 		process.env.HOME = tmp;
 		process.env.USERPROFILE = tmp;
-		const agentsDir = path.join(tmp, ".agents", "agents");
+		const agentsDir = path.join(tmp, ".agents");
 		fs.mkdirSync(agentsDir, { recursive: true });
 		fs.writeFileSync(path.join(agentsDir, "my.md"), "---\nname: my-helper\n---\n# body\n");
-		const groups = groupedAvailableAgents();
+		const groups = groupedAvailableRotors();
 		const userGroup = groups.find((g) => g.header === "user-defined");
 		expect(userGroup?.agents).toContain("my-helper");
 		// restore
@@ -144,10 +144,10 @@ describe("groupedAvailableAgents", () => {
 
 	test("includes project agent when present (cwd scope)", () => {
 		const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), "pis-proj-"));
-		const agentsDir = path.join(projectDir, ".agents", "agents");
+		const agentsDir = path.join(projectDir, ".agents");
 		fs.mkdirSync(agentsDir, { recursive: true });
 		fs.writeFileSync(path.join(agentsDir, "proj.md"), "---\nname: project-helper\n---\n# body\n");
-		const groups = groupedAvailableAgents(projectDir);
+		const groups = groupedAvailableRotors(projectDir);
 		const userGroup = groups.find((g) => g.header === "user-defined");
 		expect(userGroup?.agents).toContain("project-helper");
 		fs.rmSync(projectDir, { recursive: true, force: true });