pi-soly 0.5.9 → 0.6.0

package/agents/soly-manager.md

@@ -0,0 +1,124 @@
+---
+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/agents-install.ts

@@ -2,11 +2,13 @@
 // agents-install.ts — Idempotent install of soly-aware subagent configs
 // =============================================================================
 //
-// Soly ships its own variants of pi-subagents' worker and oracle, with
-// soly-specific system prompts (path discipline, plan structure, todo
-// integration). pi-subagents discovers agents from `~/.pi/agent/agents/`
-// (and a few other paths), so on first session_start we copy our agent
-// `.md` files there.
+// Soly ships ONE subagent: `soly-manager`. It's a workflow executor that
+// switches modes (worker / debugger / tester / reviewer / refactor /
+// documenter / oracle / planner) based on the task brief the parent passes.
+// One agent, one system prompt, all roles.
+//
+// pi-subagents discovers agents from `~/.pi/agent/agents/`, so on first
+// session_start we copy our `soly-manager.md` there.
 //
 // IDEMPOTENT: if the target file already exists (user may have customized
 // it), we do NOT overwrite. This is one-way "first install wins".
@@ -18,13 +20,7 @@ import * as path from "node:path";
 
 /** soly agent files bundled with the extension. */
 const SHIPPED_AGENTS = [
-	"soly-worker.md",
-	"soly-debugger.md",
-	"soly-tester.md",
-	"soly-refactor.md",
-	"soly-oracle.md",
-	"soly-reviewer.md",
-	"soly-documenter.md",
+	"soly-manager.md",
 ] as const;
 
 /** Where pi-subagents looks for user agents. Respects HOME/USERPROFILE

package/commands.ts

@@ -371,7 +371,7 @@ 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 (header bar + Ctrl+Shift+S).
+				// extension as the `/agent` slash command (footer pill + Ctrl+Tab).
 				// Soly no longer owns the agent switcher UI.
 				config: {
 					description: "show merged config (per-project + global + defaults); edit .soly/config.json or ~/.soly/config.json",

package/config.ts

@@ -35,10 +35,11 @@ export interface SolyConfig {
 		preferAskPro: boolean;
 		/** When soly pause is invoked, also auto-save HANDOFF.json (currently always true; knob for future). */
 		autoCheckpointOnPause: boolean;
-		/** Opt-in: install soly-worker / soly-oracle agent configs to
-		 *  ~/.pi/agent/agents/ on session_start, and use soly-worker in
-		 *  soly execute workflows. Off by default — most users don't need
-		 *  soly-specialized subagents since the workflow template already
+		/** Opt-in: install soly-manager agent config to
+		 *  ~/.pi/agent/agents/ on session_start. The single soly subagent
+		 *  is mode-switching (worker/debugger/tester/reviewer/etc. based on
+		 *  the task brief). Off by default — most users don't need a soly-
+		 *  specialized subagent since the workflow template already
 		 *  contains soly instructions. */
 		useSolyWorkerSubagents: boolean;
 	};

package/index.ts

@@ -85,9 +85,9 @@ export default function solyExtension(pi: ExtensionAPI) {
 
 	// ============================================================================
 	// Agent switcher: REMOVED. The agent cycler is now owned by the
-	// separate `pi-switch` extension (header bar + Ctrl+Shift+S + /agent slash).
-	// Soly still owns the soly-specific agent files (soly-worker.md etc.) and
-	// the auto-install on opt-in. Workflows read the current agent from
+	// separate `pi-switch` extension (footer pill + Ctrl+Tab + /agent 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+Shift+S, the header bar, or /agent slash.
+	// Soly no longer owns Ctrl+Tab, the footer pill, or /agent 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.
@@ -388,16 +388,16 @@ export default function solyExtension(pi: ExtensionAPI) {
 			}
 		}
 
-		// Auto-install soly-aware subagent configs (soly-worker, soly-oracle)
-		// to ~/.pi/agent/agents/ on first run. Opt-in via
-		// config `agent.useSolyWorkerSubagents` (default false). Idempotent —
-		// respects any existing user-customized copies.
+		// Auto-install soly-manager subagent config to ~/.pi/agent/agents/
+		// on first run. Opt-in via config `agent.useSolyWorkerSubagents`
+		// (default false). Idempotent — respects any existing user-
+		// customized copies.
 		if (activeConfig.agent.useSolyWorkerSubagents) {
 			const extRoot = path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, "$1"));
 			const installResult = installSolyAgents(extRoot);
 			if (installResult.installed.length > 0) {
 				ctx.ui.notify(
-					`soly: installed subagent configs (${installResult.installed.join(", ")}) — run \`/subagents-doctor\` to verify`,
+					`soly: installed subagent config (${installResult.installed.join(", ")}) — run \`/subagents-doctor\` to verify`,
 					"info",
 				);
 			}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-soly",
-  "version": "0.5.9",
+  "version": "0.6.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/switch/README.md

@@ -1,11 +1,12 @@
 # pi-switch — generic subagent switcher for pi
 
-A tiny pi extension that gives you a **persistent indicator of the current subagent** (header bar above chat) and lets you **cycle / set / create** agents. Generic — works with any agent in `~/.pi/agent/agents/`.
+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
 
-- **Header bar above chat** — shows current agent with emoji + description
-- **Ctrl+Shift+S** to cycle to next agent (Shift+Tab is taken by pi's thinking-level cycler)
+- **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
@@ -13,7 +14,8 @@ A tiny pi extension that gives you a **persistent indicator of the current subag
 - **`/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+Shift+S to see it
+- 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
 
@@ -21,9 +23,9 @@ Agents are markdown files with YAML frontmatter. pi-subagents (and pi-switch) di
 
 | Path | Type | Editable |
 |---|---|---|
-| `~/.pi/agent/npm/node_modules/pi-subagents/agents/*.md` | built-in (worker, oracle, scout, ...) | ❌ |
+| `~/.pi/agent/npm/node_modules/pi-subagents/agents/*.md` | built-in (worker, oracle, scout, reviewer) | ❌ |
 | `~/.pi/agent/agents/*.md` | user-defined | ✅ |
-| `~/.pi/agent/extensions/soly/agents/*.md` (auto-installed if `useSolyWorkerSubagents: true` in `.soly/config.json`) | soly-augmented (soly-worker, soly-debugger, ...) | ✅ source |
+| `~/.pi/agent/extensions/pi-soly/agents/*.md` (auto-installed if `useSolyWorkerSubagents: true` in `.soly/config.json`) | soly-manager (mode-switching subagent) | ✅ source |
 
 ### Frontmatter schema
 
@@ -45,7 +47,7 @@ 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+Shift+S` in pi — it joins the cycle.
+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
 ```
@@ -58,8 +60,8 @@ You'll be prompted for a one-liner description. Then edit the file to specialize
 | Action | How |
 |---|---|
 | See current + available | `/agent` |
-| Cycle | `Ctrl+Shift+S` |
-| Set explicitly | `/agent soly-debugger` |
+| Cycle | `Ctrl+Tab` (or `F2`) |
+| Set explicitly | `/agent soly-manager` |
 | Diagnose | `/agent doctor` |
 | Recommend for a task | `/agent recommend investigate React Server Components` |
 
@@ -71,37 +73,32 @@ The LLM's system prompt includes a table mapping task keywords to agents. When t
 
 | Keywords | Agent | Why |
 |---|---|---|
-| research, investigate, look up, find out, explore, compare libraries | 📚 researcher | external docs, ecosystem behavior |
 | scout, scan, map, where is, locate, skim | 🔍 scout | codebase recon |
-| plan, design, architect, outline, structure | 📋 planner | decompose into steps |
 | review, audit, check, adversarial, critique, qa | 👀 reviewer | adversarial review |
 | oracle, decision, tradeoff, which approach, drift | 🔮 oracle | decision consistency |
-| debug, bug, fix, crash, error, repro | 🐞 soly-debugger | bug investigation |
-| test, tests, coverage, spec, assert | 🧪 soly-tester | test-only work |
-| refactor, clean up, simplify, extract, rename | 🔄 soly-refactor | pure refactoring |
-| document, docs, readme, jsdoc | 📝 soly-documenter | doc updates |
-| implement, build, write code, add feature | ⚡ worker | implementation |
-| orchestrate, coordinate, dispatch, chain | 🤝 delegate | multi-agent |
+| 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
 
-- **soly** reads `globalThis.__PI_SWITCH_AGENT__` to know which subagent to launch for `soly execute`. Falls back to `"worker"` if pi-switch isn't loaded.
-- **Soly** also auto-installs soly-augmented agents (soly-worker, soly-debugger, etc.) to `~/.pi/agent/agents/` when `useSolyWorkerSubagents: true` in `.soly/config.json`.
+- **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` — header bar, Ctrl+Shift+S, `/agent` slash command, `/agent create`/`/agent doctor`/`/agent recommend`
-- `tests/core.test.ts` — 21 tests for core logic
-- `tests/prompt.test.ts` — 20 tests for prompt + 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 ~/.pi/agent/extensions/pi-switch
-bun test          # 41 tests
+cd packages/pi-soly/switch
+bun test          # switch tests
 bun run typecheck # tsc --noEmit
 ```

package/switch/core.ts

@@ -7,8 +7,9 @@
 // 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, so we use
-// Ctrl+Shift+S — mnemonic for "S"witch).
+// 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_AGENT__` (in-process)
@@ -29,11 +30,7 @@ export const BUILTIN_AGENTS: readonly string[] = [
 	"worker",
 	"oracle",
 	"scout",
-	"researcher",
-	"planner",
-	"context-builder",
 	"reviewer",
-	"delegate",
 ] as const;
 
 /** Visual metadata for every known agent. Used by the rich status badge,
@@ -49,11 +46,7 @@ export const AGENT_META: Record<string, AgentMeta> = {
 	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 },
-	researcher: { emoji: "\ud83d\udcda", shortLabel: "researcher", description: "external docs / libraries", writesFiles: false },
-	planner: { emoji: "\ud83d\udccb", shortLabel: "planner", description: "planning + ordering, no code", writesFiles: false },
-	"context-builder": { emoji: "\ud83c\udfd7", shortLabel: "ctx-builder", description: "context handoff for other agents", writesFiles: true },
 	reviewer: { emoji: "\ud83d\udc40", shortLabel: "reviewer", description: "adversarial code review", writesFiles: false },
-	delegate: { emoji: "\ud83e\udd1d", shortLabel: "delegate", description: "pure orchestration, dispatches others", writesFiles: false },
 };
 
 /** Get metadata for an agent. Falls back to a neutral entry for unknown. */
@@ -160,7 +153,7 @@ export function groupedAvailableAgents(userDir?: string): Array<{ header: string
 export function formatHeaderLine(agent: string): string {
 	const meta = getAgentMeta(agent);
 	const writeTag = meta.writesFiles ? "" : " \u00b7 read-only";
-	return `${meta.emoji} ${agent}  \u00b7  ${meta.description}${writeTag}    [Ctrl+Shift+S to cycle]`;
+	return `${meta.emoji} ${agent}  \u00b7  ${meta.description}${writeTag}    [Ctrl+Tab to cycle]`;
 }
 
 // ---------------------------------------------------------------------------

package/switch/index.ts

@@ -15,7 +15,7 @@
 // UI philosophy:
 //   - Header is for content, not for tool chrome. Move agents to footer.
 //   - Click to explore, hotkey to power-use, no DOM clutter in between.
-//   - Visual change is the pill text + a one-line toast on switch.
+//   - Visual change is the pill text only. Chat stays clean.
 // =============================================================================
 
 import type { ExtensionAPI, ExtensionUIContext } from "@earendil-works/pi-coding-agent";
@@ -242,7 +242,7 @@ function createAgent(
 		const description = desc?.trim() || `custom agent (${name})`;
 		fs.writeFileSync(file, agentTemplate(name, description), "utf-8");
 		ui.notify(
-			`pi-switch: created ${file}\n  → next Ctrl+Shift+S to see it in the cycle\n  → edit the system prompt to specialize`,
+			`pi-switch: created ${file}\n  → next Ctrl+Tab to see it in the cycle\n  → edit the system prompt to specialize`,
 			"info",
 		);
 	});

package/switch/prompt.ts

@@ -19,7 +19,7 @@ export const TASK_AGENT_HINTS: ReadonlyArray<{
 	  agent: "scout", emoji: "\ud83d\udd0d",
 	  why: "codebase recon, patterns, file locations" },
 	{ pattern: /\b(plan|design|architect|outline|structure|break\s*down|steps|order)\b/i,
-	  agent: "planner", emoji: "\ud83d\udccb",
+	  agent: "soly-manager", emoji: "\ud83d\udccb",
 	  why: "decompose into ordered steps, identify risks" },
 	{ pattern: /\b(review|audit|check|adversarial|critique|find\s+bugs|qa)\b/i,
 	  agent: "reviewer", emoji: "\ud83d\udc40",
@@ -28,22 +28,22 @@ export const TASK_AGENT_HINTS: ReadonlyArray<{
 	  agent: "oracle", emoji: "\ud83d\udd2e",
 	  why: "decision consistency, hidden assumptions, drift detection" },
 	{ pattern: /\b(debug|bug|fix|crash|error|stack\s*trace|repro|why\s+is\s+this\s+broken)\b/i,
-	  agent: "soly-debugger", emoji: "\ud83d\udc1e",
+	  agent: "soly-manager", emoji: "\ud83d\udc1e",
 	  why: "isolated bug investigation with minimal repro" },
 	{ pattern: /\b(test|tests|coverage|spec|assert)\b/i,
-	  agent: "soly-tester", emoji: "\ud83e\uddea",
+	  agent: "soly-manager", emoji: "\ud83e\uddea",
 	  why: "test-only work, never modifies prod code" },
 	{ pattern: /\b(refactor|clean\s*up|simplify|extract|rename|restructure|no\s+behavior\s+change)\b/i,
-	  agent: "soly-refactor", emoji: "\ud83d\udd04",
+	  agent: "soly-manager", emoji: "\ud83d\udd04",
 	  why: "pure refactoring, behavior-preserving" },
 	{ pattern: /\b(document|docs|readme|jsdoc|comment|annotate)\b/i,
-	  agent: "soly-documenter", emoji: "\ud83d\udcdd",
+	  agent: "soly-manager", emoji: "\ud83d\udcdd",
 	  why: "doc updates, READMEs, inline annotations" },
 	{ pattern: /\b(implement|build|write\s+code|add\s+feature|create\s+the)\b/i,
 	  agent: "worker", emoji: "\u26a1",
 	  why: "generic implementation with all tools" },
 	{ pattern: /\b(orchestrate|coordinate|dispatch|chain|run\s+in\s+parallel|first\s+.+\s+then)\b/i,
-	  agent: "delegate", emoji: "\ud83e\udd1d",
+	  agent: "soly-manager", emoji: "\ud83e\udd1d",
 	  why: "multi-agent orchestration" },
 	// Russian keywords (loose match — Russian words inflect heavily; we match
 	// word stems, accepting some false positives as the cost of broader coverage)
@@ -54,7 +54,7 @@ export const TASK_AGENT_HINTS: ReadonlyArray<{
 	  agent: "scout", emoji: "\ud83d\udd0d",
 	  why: "codebase recon, patterns, file locations" },
 	{ pattern: /(спланир|plan|design|architect)/i,
-	  agent: "planner", emoji: "\ud83d\udccb",
+	  agent: "soly-manager", emoji: "\ud83d\udccb",
 	  why: "decompose into ordered steps, identify risks" },
 	{ pattern: /(проверь|ревью|аудит|review|audit)/i,
 	  agent: "reviewer", emoji: "\ud83d\udc40",
@@ -63,22 +63,22 @@ export const TASK_AGENT_HINTS: ReadonlyArray<{
 	  agent: "oracle", emoji: "\ud83d\udd2e",
 	  why: "decision consistency, hidden assumptions, drift detection" },
 	{ pattern: /(баг|ошибк|почему\s+(?:падает|ломает)|debug|bug|crash|stack\s*trace|repro)/i,
-	  agent: "soly-debugger", emoji: "\ud83d\udc1e",
+	  agent: "soly-manager", emoji: "\ud83d\udc1e",
 	  why: "isolated bug investigation with minimal repro" },
 	{ pattern: /(тест|покрыт|test|coverage|spec|assert)/i,
-	  agent: "soly-tester", emoji: "\ud83e\uddea",
+	  agent: "soly-manager", emoji: "\ud83e\uddea",
 	  why: "test-only work, never modifies prod code" },
 	{ pattern: /(рефактор|упрост|refactor|simplify|extract|restructure)/i,
-	  agent: "soly-refactor", emoji: "\ud83d\udd04",
+	  agent: "soly-manager", emoji: "\ud83d\udd04",
 	  why: "pure refactoring, behavior-preserving" },
 	{ pattern: /(документ|описани|document|readme|jsdoc)/i,
-	  agent: "soly-documenter", emoji: "\ud83d\udcdd",
+	  agent: "soly-manager", emoji: "\ud83d\udcdd",
 	  why: "doc updates, READMEs, inline annotations" },
 	{ pattern: /(реализуй|сделай|напиши|создай|implement|build|add\s+feature|create\s+the)/i,
 	  agent: "worker", emoji: "\u26a1",
 	  why: "generic implementation with all tools" },
 	{ pattern: /(оркестрируй|координируй|orchestrate|coordinate|dispatch|chain)/i,
-	  agent: "delegate", emoji: "\ud83e\udd1d",
+	  agent: "soly-manager", emoji: "\ud83e\udd1d",
 	  why: "multi-agent orchestration" },
 ];
 
@@ -98,37 +98,34 @@ export function buildPiSwitchSection(): string {
 
 ## pi-switch — when to use \`/agent\`
 
-The \`/agent\` slash command + \`Ctrl+Shift+S\` shortcut cycle through available subagents. Use the right agent for the job:
+The \`/agent\` slash command + \`Ctrl+Tab\` shortcut cycle through 4 built-in cycle agents. Use the right one for the job:
 
-- **Read-only / no edits** (oracle, scout, researcher, planner, reviewer): for analysis, planning, review. They won't modify files.
-- **Write tools** (worker, context-builder, delegate): for implementation.
+- **Read-only / no edits** (oracle, scout, reviewer): for analysis, planning, review. They won't modify files.
+- **Write tools** (worker): for implementation.
 - **User-defined** in \`~/.pi/agent/agents/\`: any agent the user has added — drop a markdown file with YAML frontmatter (name, description) and it joins the cycle automatically.
 
-The current agent is shown in a header bar above the chat (with emoji + description) and in the footer status line as \`[emoji name]\`. When the agent changes, a multi-line notification appears with the old → new diff and capability summary.
+The current agent is shown in the footer status line as \`[emoji name]\`.
 
-When you need a specialist for a sub-task, use the right agent via the parent LLM's \`subagent(...)\` call — the system will use the currently active agent. You can also use \`/agent <name>\` to switch explicitly, but in most cases the orchestrator picks the right agent for each step.
+When you need a specialist for a sub-task, use the right agent via the parent LLM's \`subagent(...)\` call.
 
-**Task → agent heuristics.** Before launching a generic \`subagent(...)\`, scan the request for these keywords and call \`/agent <name>\` first if it matches:
+**Soly subagent:** there is exactly one — \`soly-manager\`. It's a workflow executor that switches modes (worker/debugger/tester/reviewer/refactor/documenter/oracle/planner) based on the task brief. For any soly plan execution, spawn \`soly-manager\` via \`subagent(...)\` with the task — it picks the right mode itself.
+
+**Task → agent heuristics.** Before launching a generic \`subagent(...)\`, scan the request for these keywords:
 
 | Keywords in request | Suggested agent | Why |
 |---|---|---|
-| research, investigate, look up, find out, explore, compare libraries, what is the best | 📚 researcher | external docs, ecosystem behavior |
 | scout, scan, map, find all, where is, locate, explore codebase, skim | 🔍 scout | codebase recon, patterns, file locations |
-| plan, design, architect, outline, structure, break down, steps, order | 📋 planner | decompose into ordered steps, identify risks |
 | review, audit, check, adversarial, critique, find bugs, qa | 👀 reviewer | adversarial correctness, security, style review |
 | oracle, decision, tradeoff, compare, which approach, is this wise, drift | 🔮 oracle | decision consistency, hidden assumptions |
-| debug, bug, fix, crash, error, stack trace, repro, why is this broken | 🐞 soly-debugger | isolated bug investigation with minimal repro |
-| test, tests, coverage, spec, assert | 🧪 soly-tester | test-only work, never modifies prod code |
-| refactor, clean up, simplify, extract, rename, restructure, no behavior change | 🔄 soly-refactor | pure refactoring, behavior-preserving |
-| document, docs, readme, jsdoc, comment, annotate | 📝 soly-documenter | doc updates, READMEs, inline annotations |
-| implement, build, write code, add feature, create the | ⚡ worker | generic implementation with all tools |
-| orchestrate, coordinate, dispatch, chain, run in parallel | 🤝 delegate | multi-agent orchestration |
+| implement, build, write code, add feature, create the, debug, fix, test, refactor, document, plan, validate | ⚡ soly-manager | workflow executor, picks mode from task brief |
+| (anything else) | ⚡ worker | generic implementation, all tools |
 
 For multi-step tasks, the orchestrator (you) decides which agents run and in what order. You can chain agents via \`subagent({ chain: [...] })\` or run them in parallel via parallel tasks.
 
 DON'T:
-- Launch a worker for analysis (use oracle/scout)
+- Launch a worker for analysis (use oracle/scout/reviewer)
 - Launch an oracle for implementation (it has no write tools)
+- Spawn soly-worker / soly-debugger / soly-tester — there is only \`soly-manager\`
 - Manually edit \`.soly/agent\` or \`~/.pi-switch/agent\` — use the slash command
 `;
 }

package/switch/tests/core.test.ts

@@ -105,7 +105,7 @@ describe("formatHeaderLine", () => {
 	test("always non-empty (even for default)", () => {
 		const h = formatHeaderLine("worker");
 		expect(h).toContain("worker");
-		expect(h).toContain("Ctrl+Shift+S");
+		expect(h).toContain("Ctrl+Tab");
 	});
 	test("includes read-only tag when applicable", () => {
 		const h = formatHeaderLine("oracle");

package/switch/tests/index.test.ts

@@ -13,9 +13,10 @@ import { availableAgents } from "../core.js";
 describe("/agent handler parse logic (regression for `/agent researcher` bug)", () => {
 	// The original bug: `/agent researcher` was interpreted as "show list"
 	// instead of "set agent to researcher" because the parser only checked
-	// the SECOND token, not the first.
+	// the SECOND token, not the first. (After cycle reduction, `researcher`
+	// is no longer a built-in, so we use `oracle` as the example agent.)
 	test("single-arg '/agent <name>' is a set, not a list", () => {
-		const input = "researcher";
+		const input = "oracle";
 		const parts = input.trim().split(/\s+/);
 		const subcommand = parts[0]?.toLowerCase();
 		const cycle = availableAgents();