pi-soly 0.5.10 → 0.7.0

package/skills/soly-framework/SKILL.md

@@ -0,0 +1,320 @@
+---
+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.
+
+## Quick start (read first if new)
+
+**Mental model — three layers, always in system prompt, in this order:**
+
+1. **Project intent** (`.soly/docs/`) — the 0-point. What the user wants the app to be. Written BEFORE plans, by humans.
+2. **Project state** (`.soly/STATE.md`, `ROADMAP.md`) — where we are, current phase, recent decisions.
+3. **Project rules** (`.soly/rules/`, `~/.soly/rules/`) — how to behave in this project.
+
+**Workflow model — phases and plans:**
+
+- A **phase** is a milestone (e.g. "01-foundation"). Has one or more `PLAN.md` files.
+- A **plan** is one ordered execution unit. Has `<task>` blocks.
+- 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)
+
+| 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. |
+| `/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 |
+| `/resume` | Restore from a paused handoff |
+| `/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) |
+
+`/soly <verb>` plain-text aliases also work for some verbs (legacy compat).
+
+## File structure
+
+```
+<project-root>/
+├── .soly/
+│   ├── 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)
+│   │   ├── code-style.md
+│   │   └── testing.md
+│   ├── phases/
+│   │   ├── 01-foundation/
+│   │   │   ├── 01-CONTEXT.md     # domain + decisions for phase 1
+│   │   │   ├── 01-RESEARCH.md    # what we looked up
+│   │   │   ├── 01-PLAN-01.md     # plan 1
+│   │   │   ├── 01-PLAN-01-SUMMARY.md
+│   │   │   ├── 01-PLAN-02.md
+│   │   │   └── 01-PLAN-02-SUMMARY.md
+│   │   └── 02-feature-x/
+│   │       └── ...
+│   ├── iterations/                # per-execution context bundles (auto)
+│   ├── HANDOFF.json               # pause snapshot
+│   └── .continue-here.md          # pause resume marker
+```
+
+## Frontmatter conventions
+
+### PLAN.md frontmatter (required)
+
+```markdown
+---
+id: 01-02                    # phase-plan, zero-padded
+title: Add OAuth flow
+status: pending              # pending | in_progress | done
+phase: 1
+depends-on: []               # other plan ids
+parallelizable: true         # can run alongside siblings
+---
+
+# Add OAuth flow
+
+## read_first
+- .soly/STATE.md
+- .soly/ROADMAP.md
+- .soly/rules/code-style.md
+
+## tasks
+- [ ] **type: implement**, description: Add token refresh logic
+  - files: src/auth/refresh.ts
+  - verify: bun test src/auth/refresh.test.ts
+  - accept: Refresh succeeds when token is expired; fails when refresh_token is also expired
+
+- [ ] **type: tdd**, description: Write integration test for the auth flow
+  - verify: bun test src/auth/
+
+- [ ] **type: checkpoint**, description: Pause for human review of UX
+
+## verification
+- bun test
+- bun run typecheck
+- bun run lint
+
+## risks
+- Token storage depends on the encryption scheme (see .soly/docs/architecture.md)
+```
+
+### SUMMARY.md frontmatter
+
+```markdown
+---
+plan: 01-02
+completed: 2026-06-15
+duration: 47min
+files-touched: 7
+---
+
+# Summary
+
+## Tasks
+- [x] Add token refresh logic
+- [x] Write integration test
+- [x] Pause for human review
+
+## Deviations
+- Refactored `auth/refresh.ts` to use singleton pattern (was factory). Documented in `architecture.md`.
+
+## Verification
+- `bun test`: 142 passing
+- `bun run typecheck`: clean
+- `bun run lint`: 0 warnings
+
+## Next
+- Phase 02 plan 01: User profile page
+```
+
+### Rules file frontmatter (optional)
+
+```markdown
+---
+applyTo: "src/**/*.ts"        # glob (optional, default: all)
+priority: 50                   # higher wins on conflict (default: 0)
+---
+
+# TypeScript style
+
+- Strict mode required
+- Never use `any` — use `unknown` and narrow
+```
+
+## Path discipline (NON-NEGOTIABLE)
+
+**All soly-managed files live under `.soly/`.** Source code lives in the project's normal source tree.
+
+| File kind | Goes to |
+|---|---|
+| `PLAN.md`, `SUMMARY.md`, `CONTEXT.md`, `RESEARCH.md` | `.soly/phases/<NN>-<slug>/` |
+| Intent docs (0-point) | `.soly/docs/` |
+| Rules | `.soly/rules/` (project) or `~/.soly/rules/` (user) |
+| Handoff | `.soly/HANDOFF.json`, `.soly/.continue-here.md` |
+| Iteration context | `.soly/iterations/` (auto-generated) |
+| Production code, tests | project's normal `src/`, `tests/`, `app/`, etc. |
+
+Use absolute paths (or paths starting with `$SOLY_DIR`) when calling tools. Never bare relative names that could land in cwd.
+
+## Close-out order
+
+The only legal sequence for finishing a plan:
+
+1. Production code commits (1+)
+2. `SUMMARY.md` committed
+3. `STATE.md` "Current Position" block updated
+4. `ROADMAP.md` phase checkbox updated
+5. `PLAN.md` frontmatter `status: done`
+
+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)
+
+| Agent | 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`.
+
+## 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 |
+|---|---|
+| `soly_read(artifact, phase, taskId)` | Read soly artifacts: STATE, plan, context, research, ROADMAP, requirements, project, milestone, task |
+| `soly_log_decision(decision, rationale, phase)` | Append to STATE.md Decisions table |
+| `soly_list_phases()` | List all phases with plan counts, C/R markers |
+| `soly_list_tasks()` | List all tasks across features (kind, status, priority, deps) |
+| `soly_todos(paths, limit)` | Scan working tree for TODO/FIXME/HACK/XXX/NOTE |
+| `soly_env()` | Detect runtime (package manager, runtimes, services, scripts) |
+| `soly_snippet(path, offset, limit)` | Read bounded line range with line numbers |
+| `soly_doc_search(query, limit)` | Search .md/.html under cwd (prioritizes intent docs) |
+| `soly_intent()` | List 0-point intent docs from `.soly/docs/` |
+| `soly_scratchpad(limit)` | Recent conversation recap (one line per turn) |
+| `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
+
+1. `soly init` (or manually create `.soly/`, `docs/`, `rules/`)
+2. Write 1-3 intent docs in `.soly/docs/`
+3. Create `ROADMAP.md` with phase table
+4. `/plan 1` to start phase 1
+
+### Add a feature to an existing phase
+
+1. `/plan 1.05` (next plan number)
+2. Edit the generated `PLAN.md`
+3. `/execute 1.05`
+
+### Pause a long session
+
+1. `/pause` → writes `HANDOFF.json` + `.continue-here.md`
+2. Later, in a new session: `/resume`
+
+### Troubleshoot a partial plan
+
+If `/execute` complains about illegal partial state:
+
+1. `cat .soly/iterations/<latest>.md` — see what the last run did
+2. Check if `SUMMARY.md` exists for the last plan
+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
+
+- **"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()`
+
+## 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` files
+- ❌ Edit `.soly/phases/*/PLAN.md` after `status: in_progress` — create a new plan
+- ❌ Put intent docs anywhere other than `.soly/docs/`
+
+## 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.

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();