pi-soly 1.2.0 → 1.4.0

package/skills/soly-framework/SKILL.md

@@ -1,11 +1,6 @@
----
-name: soly-framework
-description: Use when the user asks how to do anything with the soly framework for pi — start a new project, plan or execute a phase, pause and resume sessions, add rules, add intent docs, write PLAN.md or SUMMARY.md, troubleshoot issues. Triggers on "how do I", "what's the command for", "soly help", "soly framework", and any practical question about using the soly extension. NOT loaded for generic code questions — only when the user is working with the soly workflow.
----
-
 # soly framework
 
-The **soly** extension adds project-management workflow to [pi-coding-agent](https://github.com/nicobailon/pi-coding-agent): intent docs, ROADMAP/STATE/PHASE state machine, and subagent-driven plan execution. This skill is your complete reference for using it.
+The **soly** extension adds project-management workflow to [pi-coding-agent](https://github.com/nicobailon/pi-coding-agent): intent docs, ROADMAP/STATE/PHASE state machine, and LLM-driven plan execution. This skill is your complete reference for using it.
 
 ## Quick start (read first if new)
 
@@ -22,12 +17,12 @@ The **soly** extension adds project-management workflow to [pi-coding-agent](htt
 - A **task** is the smallest unit. Has type, description, verify, accept.
 - **Close-out**: production code commits → `SUMMARY.md` → `STATE.md` updated → ROADMAP check.
 
-## Slash commands (interactive mode)
+## Quick reference — slash commands
 
 | Command | What it does |
 |---|---|
 | `/plan [N]` | Generate or update `PLAN.md` for phase N (or current phase) |
-| `/execute [N[.MM]]` | Dispatch plan(s) to `soly-manager` subagent. `N` = all plans in phase. `N.MM` = specific plan. |
+| `/execute [N[.MM]]` | Execute plan(s) in phase N. `N` = all plans. `N.MM` = specific plan. The LLM (you) executes directly. |
 | `/discuss N` | Discussion-driven scoping for phase N — capture decisions before planning |
 | `/inspect` | One-screen summary: position, phases, recent decisions |
 | `/pause` | Save handoff (`HANDOFF.json` + `.continue-here.md`) for later resume |
@@ -35,10 +30,21 @@ 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 |
-| `/rotor [name]` | Switch the current rotor (or open picker) |
+| `/soly-init` | Scaffold a new soly project (interactive template picker) |
+| `/soly-migrate` | Move legacy `.soly/` to `.agents/` (atomic) |
+| `/soly-status` | Comprehensive one-screen report |
+| `/soly-log [N]` | Show last N notifications from the log |
 
 `/soly <verb>` plain-text aliases also work for some verbs (legacy compat).
 
+## No rotors (removed in 1.4.0)
+
+As of 1.4.0, soly no longer ships rotors. No `/rotor` command, no `Ctrl+Tab` cycle, no footer pill. The LLM picks the right subagent based on the task brief — use `subagent(...)` with `agent: "worker"` for implementation, `"oracle"` for decisions, `"scout"` for recon, `"reviewer"` for adversarial review.
+
+**Why drop them?** Rotors were a UX shortcut (Ctrl+Tab) that pi itself doesn't support well. pi has its own subagent system (`worker`, `oracle`, `scout`, `reviewer`); wrapping it in a "cycle" was over-engineering. The LLM in the main session is the executor; pi's subagents are helpers, not cycle modes.
+
+**For soly work**, the LLM does the work itself — it reads PLAN.md, runs commands, commits, writes SUMMARY.md. It does NOT spawn a soly subagent. Use `subagent(...)` only for read-only research (e.g. `agent: "scout"` for "find all files using X").
+
 ## File structure
 
 ```
@@ -69,26 +75,19 @@ The **soly** extension adds project-management workflow to [pi-coding-agent](htt
 │   └── .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 (migration in progress):** `.soly/` is the legacy soly state. `.agents/` is the new vendor-neutral home. The two work side-by-side:
+**Two parallel conventions:** `.soly/` is soly-specific state. `.agents/` is vendor-neutral agent config. The two coexist:
 
-- **Use `.agents/`** for new projects (recommended)
-- **Use `.soly/`** for legacy projects (still works, will show a deprecation warning)
+- **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
 
-To migrate: `mv .soly .agents` — soly picks up the new location automatically. No data loss.
-
 ## Frontmatter conventions
 
 ### PLAN.md frontmatter (required)
@@ -200,36 +199,6 @@ 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 rotors (4 built-in)
-
-| 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 `/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)
-
-Spawn via `subagent({ agent: "soly-manager", task: ... })`. The task brief tells it which mode to be in:
-
-| Task brief mentions | Mode |
-|---|---|
-| implement, build, write code, add feature, create | **worker** |
-| debug, bug, fix, crash, error, repro, broken | **debugger** |
-| test, coverage, spec, assert, only modify tests | **tester** |
-| review, audit, adversarial, find bugs, qa | **reviewer** |
-| refactor, simplify, extract, rename, no behavior change | **refactor** |
-| document, readme, jsdoc, comment, intent doc | **documenter** |
-| validate, scope, drift, decision, before committing | **oracle** |
-| plan, design, outline, structure, decompose | **planner** |
-
-**soly-manager is ONE agent that switches modes. Don't spawn soly-worker / soly-debugger / etc. — those don't exist anymore.**
-
 ## Tools the LLM can call
 
 | Tool | Purpose |
@@ -247,51 +216,6 @@ Spawn via `subagent({ agent: "soly-manager", task: ... })`. The task brief tells
 | `ask_pro(questions)` | Multi-question picker (tabbed, single/multi-select, ⭐, Other…) |
 | `todo_update(todos)` | Update task list rendered in footer |
 
-## Add a new rule (most common task)
-
-Three places, in priority order:
-
-1. **Project rule** — `~/.pi/agent/agents/soly/rules/<name>.md` (version-controlled, shared with team)
-2. **User rule** — `~/.soly/rules/<name>.md` (per-user, not committed)
-3. **Phase rule** — `<phase-dir>/<plan>.md.rules/<name>.md` (active only for that plan)
-
-Use `/rulewizard` slash command to scaffold a new rule with the right frontmatter.
-
-A rule file looks like:
-
-```markdown
----
-applyTo: "src/**/*.ts"
-priority: 50
----
-
-# TypeScript style
-
-- Strict mode required
-- Never use `any`
-- Prefer `type` over `interface`
-```
-
-## Add a new intent doc
-
-Create a file in `.soly/docs/`:
-
-```markdown
-# Architecture
-
-## Goal
-
-Build a CLI tool that...
-
-## Non-obvious constraints
-
-- Must work offline (no network calls)
-- Must be a single static binary
-- Must integrate with the existing `~/.config/x` schema
-```
-
-Intent docs are 0-point — written BEFORE any plan, by humans. They define the "why", not the "how".
-
 ## Common workflows
 
 ### Start a new project
@@ -300,11 +224,11 @@ Intent docs are 0-point — written BEFORE any plan, by humans. They define the
 2. Write 1-3 intent docs in `.soly/docs/`
 3. Optionally write `AGENTS.md` (or `agents.md`) at project root with project conventions
 4. Create `ROADMAP.md` with phase table
-5. `/plan 1` to start phase 1
+5. `/plan 1` to start the first phase
 
 ### Add project-specific agents
 
-Drop a markdown file in `.agents/<name>.md` (project) or `~/.agents/<name>.md` (user):
+Drop a markdown file in `.agents/agents/<name>.md` (project) or `~/.agents/agents/<name>.md` (user):
 
 ```markdown
 ---
@@ -323,7 +247,7 @@ You are a data scientist. ...
 3. `~/.agents/` — user vendor-neutral (preferred)
 4. `~/.pi/agent/agents/` — user pi native (legacy)
 
-`Ctrl+Tab` to see them in the cycle.
+`Ctrl+Tab` to see them in the cycle. (Removed in 1.4.0 — use `subagent(...)` directly.)
 
 ### Add a feature to an existing phase
 
@@ -345,24 +269,14 @@ If `/execute` complains about illegal partial state:
 3. If yes, finish close-out: update `STATE.md` + `ROADMAP.md`
 4. If no, either commit the SUMMARY or revert the production commits
 
-## Where to look for answers
+## When in doubt
 
-- **"What command does X"** → this skill, Slash commands section
-- **"What does PLAN.md look like"** → this skill, Frontmatter section
-- **"How to add a rule"** → this skill, Add a new rule section
-- **"Why did the LLM do Y"** → `/why`
-- **"What context is loaded"** → `soly_read(artifact: "state")` + `soly_doc_search(...)`
-- **"What was the recent conversation"** → `soly_scratchpad()`
+Call `soly_read(artifact: "state")` and `soly_read(artifact: "roadmap")` first. The system prompt has the layers, but `soly_read` gives you full content. Then check `soly_doc_search` for any other relevant docs.
 
 ## Don'ts
 
 - ❌ 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` or `.agents/rules/*.md` files
+- ❌ Spawn `soly-manager` / `soly-worker` / etc. — there are no soly subagents (removed in 1.3.0). Use pi's built-in subagents via the parent LLM's `subagent(...)` call.
 - ❌ Edit `.soly/phases/*/PLAN.md` after `status: in_progress` — create a new plan
-- ❌ Put intent docs anywhere other than `.soly/docs/` (or `.agents/docs/` for vendor-neutral)
-
-## When in doubt
-
-Call `soly_read(artifact: "state")` and `soly_read(artifact: "roadmap")` first. The system prompt has the layers, but `soly_read` gives you full content. Then check `soly_doc_search` for any other relevant docs.
+- ❌ Put intent docs anywhere other than `.soly/docs/`

package/agents/soly-manager.md

@@ -1,124 +0,0 @@
----
-name: soly-manager
-description: Soly workflow executor. Handles any soly task end-to-end — plan, execute, debug, test, review, refactor, document. Reads the workflow brief passed by the parent and picks the right role for the task. The single writer/reviewer for soly projects.
-thinking: high
-systemPromptMode: replace
-inheritProjectContext: true
-inheritSkills: false
-tools: read, grep, find, ls, bash, edit, write
-defaultContext: fork
-defaultReads: context.md, plan.md
-defaultProgress: true
----
-
-You are `soly-manager`: the workflow executor for the **soly** project-management extension.
-
-The parent agent passes you a task with one of these roles. **Pick the right one based on the task brief, not on your name:**
-
-| Task brief mentions | You are in mode | Your job |
-|---|---|---|
-| implement, build, write code, add feature, create | **worker** | Write the code, run verification, commit |
-| debug, bug, fix, crash, error, repro, broken | **debugger** | Repro → isolate → fix → regression test |
-| test, coverage, spec, assert, only modify tests | **tester** | Write tests, run full suite, never touch prod |
-| review, audit, adversarial, find bugs, qa | **reviewer** | Read-only review with file:line evidence |
-| refactor, simplify, extract, rename, no behavior change | **refactor** | Behavior-preserving structural change |
-| document, readme, jsdoc, comment, intent doc | **documenter** | Update docs, never change product behavior |
-| validate, scope, drift, decision, before committing | **oracle** | Read-only consistency check, no edits |
-| plan, design, outline, structure, decompose | **planner** | Ordered steps with risks; not code |
-
-**You are one agent that switches modes. You are not seven agents.** The system prompt above is your only persona — the task brief tells you which hat to wear.
-
-## Soly-aware defaults (apply in every mode)
-
-**Path discipline — NON-NEGOTIABLE.** All soly-managed files live under `.soly/`:
-- `PLAN.md`, `CONTEXT.md`, `RESEARCH.md`, `SUMMARY.md` → `.soly/phases/<NN>-<slug>/`
-- iteration files → `.soly/iterations/`
-- handoffs → `.soly/HANDOFF.json`, `.soly/.continue-here.md`
-- rules → `.soly/rules/` (NEVER edit — version-controlled)
-- All other files (source code, tests) → normal project dirs
-
-**Close-out order** (when working a plan): production-code commit(s) → SUMMARY commit → `STATUS: done` update.
-Once production commits exist, returning without a committed SUMMARY is an **illegal partial-plan state**.
-
-**Frontmatter contract** for `PLAN.md`: `id`, `title`, `status: pending|in_progress|done`, `phase`, `depends-on`, `parallelizable`. Read frontmatter first.
-
-**pi-todo integration** (auto-tracks plan sub-tasks if `todo_update` tool is available):
-1. At task start: call `todo_update` with all `status: "pending"`
-2. Set first to `in_progress` before starting
-3. Update as you go: `pending` → `in_progress` → `completed`
-4. Clear list (`todo_update({todos: []})`) after SUMMARY committed
-Skip silently if `todo_update` is not available.
-
-## Read first (soly-aware order)
-
-1. `.soly/STATE.md` — milestone, current position, recent decisions
-2. `.soly/ROADMAP.md` — overall phase plan
-3. The target `PLAN.md` (the contract) if a plan is in scope
-4. `<phase>-CONTEXT.md` if it exists (honor user decisions)
-5. `<phase>-RESEARCH.md` if it exists (use chosen libs/patterns)
-
-**Iteration context file** (if the parent references one) is a pre-aggregated bundle. If given, read that INSTEAD of the individual files.
-
-## Mode-specific discipline
-
-These are the few hard rules per mode. Follow them or fail loudly.
-
-### As worker (implement)
-- Atomic edits only — no speculative scaffolding, no TODO comments
-- Per task: read `<read_first>` → minimal correct change → verify `<acceptance_criteria>` (HARD GATE; log deviation after 2 failed fix attempts) → run `<verification>` → commit with `<type>(${PHASE}-${PLAN}): <summary>`
-- Do NOT edit `.soly/rules/`
-
-### As debugger (fix)
-- **Reproduce first.** No fix without a repro. If the user gave a stack trace, build a minimal test that triggers it. If they said "X is broken", find one test case that demonstrates it.
-- **Isolate.** Git blame, grep, bisect. State the root cause in one sentence before fixing.
-- **Fix the cause, not the symptom.** Extra null checks, swallowed errors, type casts mask the bug.
-- **Regression test.** If a test would have caught this, write it. Run the full suite.
-
-### As tester
-- **Hard rule:** you can edit `*.test.*`, `*.spec.*`, `tests/`, `__tests__/`, `test/`. You CANNOT edit anything else. If a test fails because of a prod bug, STOP and report — don't "fix" the prod code.
-- Match the project's existing test style. Don't introduce a new style.
-- Test behavior, not implementation. Black-box > white-box.
-
-### As reviewer (adversarial)
-- **Read-only.** Do NOT edit files. Do NOT fix bugs. Do NOT commit. You produce a review with file:line evidence; the parent decides what to do.
-- Read spec → read test → read impl → diff them. Where do they disagree?
-- Pick 3-4 relevant review angles (correctness, security, performance, maintainability, soly-style).
-- Specific over vague: "Line 47: SQL injection. Use parameterized query." not "the code is buggy".
-
-### As refactor
-- **Behavior preservation is the entire point.** If a test starts failing, you've changed behavior — that's a bug, not a refactor.
-- Smallest possible diff. Run tests after EVERY change.
-- Don't refactor AND fix a bug. Two concerns = unreviewable.
-- If you find a bug, stop, log it, finish the refactor without touching it.
-
-### As documenter
-- **You do NOT change product code.** You write READMEs, JSDoc, `.soly/docs/`, ADRs.
-- Update, don't append. If the README has an "Architecture" section, edit in place.
-- Link, don't repeat. 5 lines + a link > 50 lines of pasted explanation.
-- Don't add marketing fluff ("this powerful, elegant framework...").
-
-### As oracle (validate)
-- **Read-only.** No edits, no code, no new workflow trees.
-- Check: drift, hidden assumptions, scope creep, missing prerequisites, repeated mistakes, unresolved `depends-on`.
-- Sometimes the answer is "this shouldn't be a soly plan at all" — say so.
-- Output: inherited decisions → drift check → hidden assumptions → missing prereqs → scope check → recommendation → confidence.
-
-### As planner
-- Output ordered steps with explicit risks. No code. No "let me also...".
-- Each step: description, depends-on, verification (test or command), acceptance criteria.
-- If the parent asks for a plan, give a plan. Don't drift into implementation.
-
-## Returning
-
-Your final response should follow this shape:
-
-```
-Mode: <worker | debugger | tester | reviewer | refactor | documenter | oracle | planner>
-Did: <one-sentence summary of what you did or found>
-Changed files: <list, or "none" for read-only modes>
-Validation: <test/typecheck/build output, or "n/a" for read-only modes>
-Open risks / decisions needing approval: <list, or "none">
-Recommended next step: <one line>
-```
-
-Be concise. The parent synthesizes, not you.

package/switch/README.md

@@ -1,104 +0,0 @@
-# pi-switch — generic subagent switcher for pi
-
-A tiny pi extension that gives you a **persistent indicator of the current subagent** (footer pill) and lets you **cycle / set / create** agents. Generic — works with any agent in `~/.pi/agent/agents/`.
-
-## Features
-
-- **Footer pill** — always shows current agent with emoji + description
-- **Ctrl+Tab** to cycle to next agent (Shift+Tab is taken by pi's thinking-level cycler)
-- **F2** as fallback for terminals that don't pass Ctrl+Tab through
-- **`/agent`** slash command to show current + available
-- **`/agent <name>`** to set explicitly
-- **`/agent create <name>`** to scaffold a new user agent
-- **`/agent doctor`** to diagnose
-- **`/agent recommend <task>`** to suggest the right agent for a task
-- **Task → agent heuristics** baked into the system prompt so the LLM picks the right agent for the task
-- Persists to `.soly/agent` (if soly project) or `~/.pi-switch/agent` (standalone)
-- Reads user agents from `~/.pi/agent/agents/*.md` on every cycle — drop a file and Ctrl+Tab to see it
-- Silent switch — only the pill updates, chat stays clean
-
-## How agents work
-
-Agents are markdown files with YAML frontmatter. pi-subagents (and pi-switch) discover them from these locations:
-
-| Path | Type | Editable |
-|---|---|---|
-| `~/.pi/agent/npm/node_modules/pi-subagents/agents/*.md` | built-in (worker, oracle, scout, reviewer) | ❌ |
-| `~/.pi/agent/agents/*.md` | user-defined | ✅ |
-| `~/.pi/agent/extensions/pi-soly/agents/*.md` (auto-installed if `useSolyWorkerSubagents: true` in `.soly/config.json`) | soly-manager (mode-switching subagent) | ✅ source |
-
-### Frontmatter schema
-
-```markdown
----
-name: my-reviewer              # required, unique, [a-zA-Z0-9_-]{1,64}
-description: One-liner shown in picker
-thinking: medium               # off | minimal | low | medium | high | xhigh
-systemPromptMode: replace      # replace | append
-inheritProjectContext: true
-inheritSkills: false
-tools: read, grep, find, ls, bash, edit, write
-defaultContext: fork           # fresh | fork
----
-
-You are `my-reviewer`. The system prompt goes here.
-```
-
-## Create a new agent
-
-### Option A: manually
-Drop a markdown file in `~/.pi/agent/agents/<name>.md` (see schema above). Press `Ctrl+Tab` in pi — it joins the cycle.
-
-### Option B: via slash command
-```
-/agent create my-debugger
-```
-You'll be prompted for a one-liner description. Then edit the file to specialize the system prompt.
-
-## Test agents
-
-| Action | How |
-|---|---|
-| See current + available | `/agent` |
-| Cycle | `Ctrl+Tab` (or `F2`) |
-| Set explicitly | `/agent soly-manager` |
-| Diagnose | `/agent doctor` |
-| Recommend for a task | `/agent recommend investigate React Server Components` |
-
-The LLM can also auto-pick — see "Task → agent" below.
-
-## Task → agent heuristics
-
-The LLM's system prompt includes a table mapping task keywords to agents. When the user request matches, the LLM should call `/agent <name>` first, then `subagent({ agent: <name>, ... })`.
-
-| Keywords | Agent | Why |
-|---|---|---|
-| scout, scan, map, where is, locate, skim | 🔍 scout | codebase recon |
-| review, audit, check, adversarial, critique, qa | 👀 reviewer | adversarial review |
-| oracle, decision, tradeoff, which approach, drift | 🔮 oracle | decision consistency |
-| implement, build, write code, add feature, debug, fix, test, refactor, document, plan, validate | ⚡ soly-manager | workflow executor, mode-switches from task brief |
-| (anything else) | ⚡ worker | generic implementation |
-
-Same keywords in Russian work (изучи, баг, тест, etc.).
-
-## Integration with other extensions
-
-- **pi-soly** reads `globalThis.__PI_SWITCH_AGENT__` to know which cycle agent is active. Falls back to `"worker"` if pi-switch isn't loaded.
-- **pi-soly** also auto-installs `soly-manager.md` (single mode-switching subagent) to `~/.pi/agent/agents/` when `useSolyWorkerSubagents: true` in `.soly/config.json`.
-
-## Files
-
-- `core.ts` — agent metadata, discovery, cycling, persistence
-- `prompt.ts` — system-prompt section + task→agent heuristics + `recommendAgent`
-- `index.ts` — footer pill, Ctrl+Tab / F2, `/agent` slash command, `/agent create`/`/agent doctor`/`/agent recommend`
-- `tests/core.test.ts` — tests for core logic
-- `tests/prompt.test.ts` — tests for prompt + recommendAgent
-- `tests/index.test.ts` — tests for slash command parsing
-
-## Development
-
-```bash
-cd packages/pi-soly/switch
-bun test          # switch tests
-bun run typecheck # tsc --noEmit
-```

package/switch/core.ts

@@ -1,229 +0,0 @@
-// =============================================================================
-// core.ts — Generic subrotor switcher for pi
-// =============================================================================
-//
-// Lets the user pick which subagent the LLM uses (for `subagent(...)` calls
-// in the pi-subagents system, and for any extension that reads the current
-// agent). Generic — works with pi-subagents' built-ins (worker, oracle,
-// scout, ...) AND any user-defined agent in `~/.pi/agent/agents/`.
-//
-// Cycle order (Shift+Tab in pi is taken by thinking-level; we use Ctrl+Tab
-// as the primary shortcut, with F2 as fallback for terminals that don't
-// pass Ctrl+Tab through).
-//
-// Communication with other extensions:
-// - 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.
-// =============================================================================
-
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-
-/** Default agent used when no override is set. */
-export const DEFAULT_ROTOR = "worker";
-
-/** Built-in pi-subagents that we always offer in the cycle. */
-export const BUILTIN_ROTORS: readonly string[] = [
-	"worker",
-	"oracle",
-	"scout",
-	"reviewer",
-] as const;
-
-/** Visual metadata for every known agent. Used by the rich status badge,
- *  the header bar, and the multi-line switch notify. */
-export interface RotorMeta {
-	emoji: string;
-	shortLabel: string;
-	description: string;
-	writesFiles: boolean;
-}
-
-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 },
-	reviewer: { emoji: "\ud83d\udc40", shortLabel: "reviewer", description: "adversarial code review", writesFiles: false },
-};
-
-/** Get metadata for an agent. Falls back to a neutral entry for unknown. */
-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",
-		writesFiles: true,
-	};
-}
-
-/** Validate an agent name. */
-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/` 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();
-	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 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 rotorHomeDirs(cwd)) {
-		if (!fs.existsSync(dir)) continue;
-		let entries: string[];
-		try {
-			entries = fs.readdirSync(dir);
-		} catch {
-			continue;
-		}
-		for (const file of entries) {
-			if (!file.endsWith(".md")) continue;
-			try {
-				const raw = fs.readFileSync(path.join(dir, file), "utf-8");
-				const m = raw.match(/^---\n([\s\S]*?)\n---/);
-				if (!m) continue;
-				const fm = m[1] ?? "";
-				const nameMatch = fm.match(/^name:\s*(.+)$/m);
-				if (nameMatch) {
-					const n = (nameMatch[1] ?? "").trim();
-					if (isValidRotorName(n) && !seen.has(n)) {
-						seen.add(n);
-						out.push(n);
-					}
-				}
-			} catch { /* skip unreadable */ }
-		}
-	}
-	return out;
-}
-
-/** Build the full cycle of available agents. Built-ins first, then
- *  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) => {
-		if (!seen.has(n)) {
-			seen.add(n);
-			out.push(n);
-		}
-	};
-	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_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 parseRotorName(raw: string): string | null {
-	const n = raw.trim();
-	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_ROTOR) return null;
-	const meta = getRotorMeta(agent);
-	return `${meta.emoji} ${agent}`;
-}
-
-/** Multi-line switch notify. */
-export function formatRotorSwitchNotify(prev: string, next: string): string {
-	const prevMeta = getRotorMeta(prev);
-	const nextMeta = getRotorMeta(next);
-	const lines: string[] = [
-		"pi-switch agent changed",
-		"",
-		`  ${prevMeta.emoji} ${prev.padEnd(16)} →  ${nextMeta.emoji} ${next}`,
-		`  ${"".padEnd(16)}     ${nextMeta.description}`,
-		"",
-		`  writes files: ${nextMeta.writesFiles ? "yes" : "no (read-only)"}  ·  next subagent call uses: ${next}`,
-	];
-	return lines.join("\n");
-}
-
-/** Group agents: built-ins + user-defined. */
-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_ROTORS.includes(a));
-	if (builtin.length > 0) groups.push({ header: "built-in", agents: builtin });
-	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 = getRotorMeta(agent);
-	const writeTag = meta.writesFiles ? "" : " \u00b7 read-only";
-	return `${meta.emoji} ${agent}  \u00b7  ${meta.description}${writeTag}    [Ctrl+Tab to cycle]`;
-}
-
-// ---------------------------------------------------------------------------
-// Persistence
-// ---------------------------------------------------------------------------
-
-/** Where to persist the current agent. Prefers `.soly/agent` if a soly
- *  project exists (shared with soly extension). Otherwise `~/.pi-switch/agent`. */
-export function agentFilePath(cwd: string): string {
-	const solyAgent = path.join(cwd, ".soly", "agent");
-	if (fs.existsSync(path.join(cwd, ".soly"))) return solyAgent;
-	// Respect HOME/USERPROFILE for testability (otherwise os.homedir() ignores them on Windows)
-	const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
-	const fallbackDir = path.join(home, ".pi-switch");
-	fs.mkdirSync(fallbackDir, { recursive: true });
-	return path.join(fallbackDir, "agent");
-}
-
-/** Read persisted agent from disk. Returns null if missing/invalid. */
-export function loadAgent(cwd: string): string | null {
-	try {
-		const file = agentFilePath(cwd);
-		if (!fs.existsSync(file)) return null;
-		const raw = fs.readFileSync(file, "utf-8").trim();
-		if (!isValidRotorName(raw)) return null;
-		return raw;
-	} catch {
-		return null;
-	}
-}
-
-/** Write current agent to disk. */
-export function saveAgent(cwd: string, agent: string): void {
-	try {
-		const file = agentFilePath(cwd);
-		fs.mkdirSync(path.dirname(file), { recursive: true });
-		fs.writeFileSync(file, agent + "\n", "utf-8");
-	} catch { /* best-effort */ }
-}