pi-soly 0.8.0 → 1.0.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

@@ -34,12 +34,15 @@ const SHIPPED_SKILLS = [
 ] as const;
 
 /** Where pi looks for user agents. Respects HOME/USERPROFILE for
- *  testability (otherwise we'd always write to the real user home). */
+ *  testability (otherwise we'd always write to the real user home).
+ *  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"),                          // vendor-neutral (preferred)
-		path.join(home, ".pi", "agent", "agents"),           // pi's native
+		path.join(home, ".pi", "agent", "agents"),           // pi native (legacy)
 	];
 }
 
@@ -92,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

@@ -371,8 +371,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/index.ts

@@ -80,12 +80,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 +328,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.
@@ -353,10 +353,14 @@ export default function solyExtension(pi: ExtensionAPI) {
 		// 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.
+		// .agents/rules/ is the vendor-neutral project-level convention
+		// (same role as the old .claude/rules/).
 		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"), 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();
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-soly",
-  "version": "0.8.0",
+  "version": "1.0.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).
 
@@ -45,16 +45,13 @@ The **soly** extension adds project-management workflow to [pi-coding-agent](htt
 <project-root>/
 ├── AGENTS.md                      # vendor-neutral agent context (loaded by pi)
 ├── agents.md                      # same as AGENTS.md, lowercase accepted
-├── .agents/                       # project-level agent definitions
-│   ├── project-reviewer.md
-│   └── data-scientist.md
-├── .soly/
+├── .soly/                         # soly state (phases, plans, summaries)
 │   ├── ROADMAP.md                 # phase table
 │   ├── STATE.md                   # current position + decisions log
 │   ├── docs/                      # 0-point intent docs (human-written, locked)
 │   │   ├── vision.md
 │   │   └── architecture.md
-│   ├── rules/                     # project rules (version-controlled)
+│   ├── rules/                     # soly project rules (version-controlled)
 │   │   ├── code-style.md
 │   │   └── testing.md
 │   ├── phases/
@@ -70,8 +67,26 @@ The **soly** extension adds project-management workflow to [pi-coding-agent](htt
 │   ├── 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/)
+│   │   ├── code-style.md
+│   │   └── testing.md
+│   ├── skills/                    # project-scoped skills (pi auto-discovers)
+│   │   └── my-skill/
+│   │       └── SKILL.md
+│   ├── docs/                      # agent-specific docs (intent-style)
+│   │   └── architecture.md
+│   └── agents/                    # project-specific agent definitions
+│       ├── project-reviewer.md
+│       └── 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:
+
+- 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
+
 ## Frontmatter conventions
 
 ### PLAN.md frontmatter (required)
@@ -183,16 +198,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)
 
@@ -298,7 +315,13 @@ tools: read, bash
 You are a data scientist. ...
 ```
 
-Both `~/.agents/` and `~/.pi/agent/agents/` are read (vendor-neutral preferred). `Ctrl+Tab` to see them in the cycle.
+**Discovered from 4 locations** (priority order):
+1. `<project>/.agents/` — project vendor-neutral (preferred)
+2. `<project>/.pi/agent/agents/` — project pi native (legacy)
+3. `~/.agents/` — user vendor-neutral (preferred)
+4. `~/.pi/agent/agents/` — user pi native (legacy)
+
+`Ctrl+Tab` to see them in the cycle.
 
 ### Add a feature to an existing phase
 
@@ -334,9 +357,9 @@ If `/execute` complains about illegal partial state:
 - ❌ Edit `.soly/rules/` files you didn't write — those are project invariants
 - ❌ Skip the SUMMARY — illegal partial state
 - ❌ Spawn `soly-worker` or `soly-debugger` — use `soly-manager` (mode-switches)
-- ❌ Write rules in code comments — use `.soly/rules/*.md` files
+- ❌ Write rules in code comments — use `.soly/rules/*.md` or `.agents/rules/*.md` files
 - ❌ Edit `.soly/phases/*/PLAN.md` after `status: in_progress` — create a new plan
-- ❌ Put intent docs anywhere other than `.soly/docs/`
+- ❌ Put intent docs anywhere other than `.soly/docs/` (or `.agents/docs/` for vendor-neutral)
 
 ## When in doubt
 

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,28 +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. */
-/** User agent home directories, in priority order. First existing one
- *  wins for new agent creation; all are read and merged in the cycle.
- *  Honors $HOME / $USERPROFILE so tests can redirect to a tmp dir. */
-export function userAgentDirs(): string[] {
+/** All known agent home directories, in priority order (project wins
+ *  over user-home; user-home `.agents/` wins over pi-native).
+ *  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 rotorHomeDirs(cwd?: string): string[] {
 	const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
-	return [
-		path.join(home, ".agents"),                          // vendor-neutral (preferred)
-		path.join(home, ".pi", "agent", "agents"),           // pi's native
-	];
+	const dirs: string[] = [];
+	if (cwd) {
+		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"));                       // user (vendor-neutral)
+	dirs.push(path.join(home, ".pi", "agent", "agents"));       // user (pi native, legacy)
+	return dirs;
 }
 
-/** Read all user agent names from every registered home dir. Dedupes,
- *  first-occurrence wins. */
-export function discoverUserAgents(): string[] {
+/** Read all agent names from every home dir. Dedupes, first-occurrence
+ *  wins. If cwd is provided, project dirs are scanned first. */
+export function discoverUserRotors(cwd?: string): string[] {
 	const seen = new Set<string>();
 	const out: string[] = [];
-	for (const dir of userAgentDirs()) {
+	for (const dir of rotorHomeDirs(cwd)) {
 		if (!fs.existsSync(dir)) continue;
 		let entries: string[];
 		try {
@@ -99,7 +107,7 @@ export function discoverUserAgents(): 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);
 					}
@@ -111,9 +119,9 @@ export function discoverUserAgents(): string[] {
 }
 
 /** Build the full cycle of available agents. Built-ins first, then
- *  user-discovered (from all user agent home dirs). Dedupes while
- *  preserving first-occurrence order. */
-export function availableAgents(): string[] {
+ *  project-level agents (if cwd given), then user-home agents.
+ *  Dedupes while preserving first-occurrence order. */
+export function availableAgents(cwd?: string): string[] {
 	const out: string[] = [];
 	const seen = new Set<string>();
 	const push = (n: string) => {
@@ -122,37 +130,37 @@ export function availableAgents(): string[] {
 			out.push(n);
 		}
 	};
-	for (const a of BUILTIN_AGENTS) push(a);
-	for (const a of discoverUserAgents()) 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",
 		"",
@@ -165,19 +173,19 @@ export function formatAgentSwitchNotify(prev: string, next: string): string {
 }
 
 /** Group agents: built-ins + user-defined. */
-export function groupedAvailableAgents(): Array<{ header: string; agents: string[] }> {
-	const all = availableAgents();
+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]`;
 }
@@ -204,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();
-		if (!cycle.includes(currentAgent)) currentAgent = DEFAULT_AGENT;
+		cycle = availableAgents(cwd);
+		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().includes(target)) {
-		return ui.notify(`pi-switch: unknown "${target}". available: ${availableAgents().join(", ")}`, "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}
@@ -314,11 +315,11 @@ you have a specific reason to change it.
 }
 
 function doctorReport(): string {
-	const cycle = availableAgents();
+	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,9 +117,9 @@ 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", () => {
@@ -133,7 +133,7 @@ describe("groupedAvailableAgents", () => {
 		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
@@ -141,6 +141,17 @@ describe("groupedAvailableAgents", () => {
 		process.env.USERPROFILE = prevUserProfile ?? home;
 		fs.rmSync(tmp, { recursive: true, force: true });
 	});
+
+	test("includes project agent when present (cwd scope)", () => {
+		const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), "pis-proj-"));
+		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 = groupedAvailableRotors(projectDir);
+		const userGroup = groups.find((g) => g.header === "user-defined");
+		expect(userGroup?.agents).toContain("project-helper");
+		fs.rmSync(projectDir, { recursive: true, force: true });
+	});
 });
 
 // ---------------------------------------------------------------------------