brl-subagent 2.3.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Azmeen Afandi / Beeroo Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,257 @@
+# brl-subagent
+
+> Multi-agent orchestration for [pi](https://github.com/earendil-works/pi) — chain, parallel, and dependency-graph delegation to isolated subagents with per-step model routing, preset-driven tool scoping, thinking-level control, and background execution with live monitoring, real abort, and per-agent timeouts.
+
+**Version:** 2.3.4 · **Author:** Azmeen Afandi / [Beeroo Labs](https://beeroolabs.com) · **License:** MIT
+
+---
+
+## What it does
+
+`brl-subagent` is **one of the most capable subagent orchestration extensions for pi** — one `delegate_task` tool that spawns fully isolated subagent processes, each with its own model, context window, tool permissions, and thinking level.
+
+- **Multi-step delegation, natively** — chain, parallel, and dependency-graph modes with per-step model routing, so a complex task fans out exactly as you design it.
+- **True background execution** — live monitor, real abort (`stop_subagent`), per-agent timeouts, and hard caps. Nothing orphans; nothing leaks.
+- **Preset-driven tool scoping** — every subagent runs with exactly the tools its job needs, restricted by preset or per-call `tools`/`excludeTools`, with auto-route that picks the right preset when you don't.
+- **Templates with slots** — saved, file-backed task templates with `${param}` placeholders for workflows you run again and again.
+- **Safety by default** — task-fence injection protection, sanitized error paths, owner-only persistence, and a 700+ test suite pinning every contract against the real pi SDK.
+
+---
+
+## Installation
+
+```bash
+# Global (all projects)
+cd ~/.pi/agent/extensions && git clone https://github.com/azmeenafandi/brl-subagent.git
+
+# Project-local
+cd your-project/.pi/extensions && git clone https://github.com/azmeenafandi/brl-subagent.git
+```
+
+Pi auto-discovers extensions in these directories. To update: `git pull` inside the cloned directory.
+
+---
+
+## Quick reference
+
+### Commands
+
+| Command | What it does |
+|---|---|
+| `/brl-subagent` | Open configuration menu |
+| `/brl-subagent model` | Select subagent model |
+| `/brl-subagent thinking` | Set max thinking level ceiling |
+| `/brl-subagent concurrency` | Set max parallel limit |
+| `/brl-subagent depth` | Set max recursion depth |
+| `/brl-subagent approval` | Set change approval mode |
+| `/brl-subagent completionnotify` | Set completion-push wake (all/failed/off) |
+| `/brl-subagent costlimit` | Set session cost limit |
+| `/brl-subagent historyentries` | Set max history entries |
+| `/brl-subagent sla` | Configure SLA tracking |
+| `/brl-subagent sla-stats` | View SLA statistics |
+| `/brl-subagent preset` | Manage delegation presets |
+| `/brl-subagent templates` | Browse task templates |
+| `/brl-subagent history` | Browse past subagent runs |
+| `/brl-subagent monitor` | Live monitor running subagents |
+| `/brl-subagent dashboard` | Live observability dashboard |
+| `/brl-subagent retry` | Browse failed runs to retry |
+| `/brl-subagent update-check` | Toggle update check on startup |
+| `/brl-subagent reset` | Reset all configuration |
+
+All settings persist across sessions.
+
+---
+
+## delegate_task parameters
+
+### Core
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `task` | string | *required* | What the subagent should do. Be specific — it doesn't see your conversation history. |
+| `label` | string | — | Human-readable name (e.g., `"security-audit"`). Shows in status bar, result header, and history. |
+| `model` | string | — | Model override (`provider/model-id`). Defaults to the global subagent model. Validated against the catalog and provider auth; falls back with a warning if unavailable or malformed. Per-step `model` on chain/tasks/graph still wins for that step. |
+| `preset` | string | — | Named delegation preset. Preset values are defaults; explicit params override. |
+| `template` | string | — | Named task template. See [Task Templates](#task-templates). |
+| `params` | object | — | Values for `${param}` slots in the template. All slots must be filled; missing ones error. |
+| `systemPrompt` | string | — | Extra instructions or a different persona for the subagent. |
+| `inheritSystemPrompt` | boolean | `true` | Whether to inherit the main agent's system prompt. Set `false` to save tokens. |
+| `thinkingLevel` | string | — | `off` / `minimal` / `low` / `medium` / `high` / `xhigh`. Capped at user's configured max. |
+| `outputFile` | string | — | Path for the subagent to write full findings. Returns only a summary. |
+| `timeout` | number | — | Max milliseconds. Exceeded → SIGTERM (5s grace) → SIGKILL. |
+| `cwd` | string | — | Working directory. Defaults to conductor's cwd. |
+| `background` | boolean | `false` | Spawn as an independent background session; returns an ID immediately. See [Background execution](#background-execution). |
+| `priority` | string | — | Concurrency priority: `critical` / `high` / `normal` / `low`. Defaults to `normal`; higher-priority delegations queue ahead. `tasks[]` / `graph[]` steps can set `priority` per unit (see below). |
+
+## Multi-step modes (chain, tasks, graph)
+
+Beyond a single `task`, `delegate_task` accepts three multi-step shapes: `chain` (sequential steps, `{previous}` references the prior step's output), `tasks` (parallel, independent), and `graph` (dependency-ordered, `{otherId}` references another task's output).
+
+Every execution knob can be set per step: `model`, `thinkingLevel`, `tools`, `excludeTools`, `noBuiltinTools`, `systemPrompt`, `inheritSystemPrompt`, `outputFile`, `timeout`, `cwd`. Unset fields inherit from the global parameters (and their preset defaults).
+
+**Per-step priority:** `tasks[]` and `graph[]` items accept a `priority` (`critical` / `high` / `normal` / `low`) — the per-unit priority decides which unit wins a concurrency slot first, overriding the call-level default for that unit only. `chain[]` steps deliberately take NO `priority`: a chain holds one slot for its whole duration, so steps never compete for slots — array order is the priority.
+
+**Per-step model:** `model: "provider/model-id"` on a step overrides the global subagent model for that step only (e.g. a cheap model for extraction steps, an expensive one for synthesis). The override is validated against the model catalog and provider auth before use; if it's unavailable or malformed, the step falls back to the global model with a warning. Note: the global model must still resolve — a session with no configured model at all cannot run multi-step modes even if every step declares one (consistent with single-mode behavior).
+
+---
+
+## Tools
+
+Alongside `delegate_task`, the extension registers three companion tools for background agents — `get_subagent_result` (poll status and retrieve results), `steer_subagent` (send a steering message), and `stop_subagent` (abort a running agent). See [Background execution](#background-execution) for the full background model.
+
+### `stop_subagent`
+
+Stops a running background agent — a real abort, not a status flip.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `agent_id` | string | Agent ID of the running background session to stop |
+
+**What it does:** aborts the live session via `session.abort()` — the pending `prompt()` resolves with `stopReason: "aborted"` rather than hanging — and marks the agent `stopped`. Partial work from a `gitMode: 'branch'` run is captured in the result before the work branch is discarded. Returns an error if the agent is not found or already terminal. Use it to halt a background agent that is no longer needed.
+
+---
+
+## Presets
+
+Built-in presets ship with the extension. You can also create **custom presets** as `.md` files — no TUI wizard needed.
+
+**Project presets:** `.pi/brl-subagent/presets/<name>.md`  
+**Global presets:** `~/.pi/agent/brl-subagent/presets/<name>.md`
+
+Files use the same format as built-in presets — YAML frontmatter with these fields:
+
+> Note: the parser does not support inline comments — put notes on their own line starting with `#`.
+
+```yaml
+---
+name: my-preset
+description: Debug with verbose thinking
+# optional — pin a model; falls back to the configured model if unavailable
+model: anthropic/claude-opus-4-6
+tools:
+  - read
+  - bash
+thinkingLevel: high
+---
+```
+
+Custom presets override built-ins with the same name and survive `pi install` updates.
+
+Refer to a preset via the `preset` parameter of `delegate_task` (see above). Parameters on `delegate_task` override preset values.
+
+---
+
+## Task Templates
+
+Task templates are named, saved `delegate_task` configurations with `${param}` placeholder slots. Where presets shape the *persona*, templates capture the **task body itself** — a full, often multi-line instruction with slots filled at call time.
+
+**Templates are file-backed** — you create and edit them as `.md` files, exactly like custom presets. The old TUI add/remove flows were removed because single-line input cannot express a task body; use your editor instead.
+
+**Built-in templates:** `templates/<name>.md` (ships with the extension — one thin companion per builtin preset)  
+**Project templates:** `.pi/brl-subagent/templates/<name>.md`  
+**Global templates:** `~/.pi/agent/brl-subagent/templates/<name>.md`
+
+Precedence is **PROJECT > USER > BUILTIN** (issue #84 + builtin tier): a custom template with the same `name` as a built-in one overrides it, so you can copy a built-in file into your project directory and edit it to customize. The built-in tier is the fallback — it only appears when no custom template claims the name.
+
+Files are markdown with YAML frontmatter; the **body is the task** (multiline by construction):
+
+```yaml
+---
+name: code-review
+preset: code-reviewer
+thinkingLevel: medium
+---
+Review PR ${pr} in this repository.
+
+Focus on:
+- correctness bugs and race conditions
+- style and naming consistency
+- missing test coverage
+
+Report findings as a numbered list with file:line references.
+```
+
+Supported frontmatter fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | string | *required* — template name used in `delegate_task` |
+| `description` | string | One-line summary shown in the browse UI |
+| `preset` | string | Preset applied when the template is used |
+| `thinkingLevel` | string | `off` / `minimal` / `low` / `medium` / `high` / `xhigh` |
+| `outputFile` | string | Output file path (may contain `${param}` slots) |
+| `timeout` | number | Max milliseconds for the delegated run |
+| `tools` | list | Tool allowlist |
+| `excludeTools` | list | Tools to exclude |
+| `noBuiltinTools` | `"true"` / `"false"` | Disable all pi built-in tools |
+| `inheritSystemPrompt` | `"true"` / `"false"` | Override system-prompt inheritance (default `true`) |
+
+Invalid files (missing `name`, bad `thinkingLevel`, non-numeric `timeout`, …) are skipped with a logged warning. Both directories are scanned on session start. Templates survive `pi install` updates — the same property as custom presets.
+
+**Built-in templates shipped with the extension** (VERB-form names, deliberately distinct from their companion presets):
+
+| Template | Companion preset | thinkingLevel | Task shape |
+|---|---|---|---|
+| `code-review` | `code-reviewer` | medium | Review ${target} for correctness, security, style |
+| `security-audit` | `security-auditor` | high | Audit ${target} — injection, authz, secrets, dependencies |
+| `write-tests` | `test-engineer` | medium | Write tests for ${file} incl. edge cases |
+| `debug-issue` | `debugger` | medium | Debug ${symptom}: reproduce, isolate, fix |
+| `refactor` | `refactorer` | medium | Refactor ${target}, preserve behavior |
+| `write-docs` | `tech-writer` | low | Document ${topic} with an example |
+| `analyze-data` | `data-analyst` | medium | Analyze ${dataset}: patterns, outliers, trends |
+| `implement-feature` | `dev-agent` | medium | Implement ${feature} per project conventions |
+| `prototype` | `rapid-prototyper` | low | Prototype ${idea} fast, working > polished |
+
+These are deliberately THIN teaching examples — 2-4 line bodies showing `${param}` slots in action, with `preset:` pointing at their companion. Copy one into your project `templates/` dir to customize it (the copy then overrides the built-in).
+
+**Usage:** pass the template name plus parameter values to `delegate_task`:
+
+```js
+delegate_task({
+  template: "code-review",
+  params: { pr: "https://github.com/org/repo/pull/42" },
+});
+```
+
+- Every `${param}` slot in the template must be provided in `params` — a missing slot fails the call with an error listing the missing names.
+- Template fields are **defaults**: explicitly-provided `delegate_task` parameters override them.
+- The template's task **replaces** `params.task` entirely.
+- Extra keys in `params` are ignored.
+
+**Templates and presets — how they interact:**
+
+- **Dependency runs one way.** A template MAY declare a `preset:` dependency; presets know nothing about templates. Deleting or renaming a preset silently leaves templates that reference it without it.
+- **Preset-less templates are not rescued by auto-route.** A template without a `preset:` field runs preset-less — `params.template` itself counts as explicit intent, so the E2 keyword auto-router does NOT kick in. (The same suppression applies when `preset`, `tools`, `excludeTools`, or `noBuiltinTools` are given explicitly.)
+- **Full precedence chain** (highest first):
+
+  `explicit delegate_task param > template field > preset defaults > config fallback`
+
+  The template's own `preset:` field slots in as a *template field*: an explicit `preset` param wins over the template's `preset:`, and the resolved preset's defaults (thinkingLevel, systemPrompt, tools, …) fill whatever the params and template leave unset. Config-level defaults (gitMode, approvalMode, maxThinkingLevel caps, …) apply last.
+- **Tool fields are replaced, never merged.** A template's `tools` fully overrides the referenced preset's `tools` (same for `excludeTools`/`noBuiltinTools`) — the template's list wins entirely, it is not unioned with the preset's. Mixing still works per-field: a template that sets only `tools` still inherits the preset's `excludeTools`/`noBuiltinTools`.
+- **Nonexistent-preset refs warn at session start (issue #81).** A template whose `preset:` names a preset that does not exist is caught by a load-time cross-check: `validateTemplatePresetRefs` warns at session start (and on preset add/remove) naming the template, the dangling reference, and the consequence — the delegation would otherwise run preset-less **silently** with auto-route suppressed. Warn-not-skip: the run still proceeds preset-less, but it is no longer silent. A typo'd preset now produces a visible warning; keep `preset:` names in sync with installed presets.
+
+| Template `preset:` | Result |
+|---|---|
+| names an existing preset | preset applied (template-field slot in the precedence chain) |
+| absent | template runs **preset-less**; auto-route does NOT rescue it |
+| names a nonexistent preset | **warned** preset-less run (session-start warning names template + dangling ref), auto-route still suppressed (issue #81) |
+
+`/brl-subagent templates` now **browses only** — it lists your saved templates and shows their details; creation and editing happen in your editor.
+
+## Background execution
+
+Set `background: true` to spawn the subagent as an independent session that returns an ID immediately and keeps running. Its progress is tracked via `getAgent` and the live monitor while the main session continues. (Steering via `steerAgent` currently records the message in the transcript and marks the agent as steered — delivery to the live session is pending pi's extension API.)
+
+**System prompt semantics:** background sessions are spawned with the same built prompt as foreground subagents (base prompt when `inheritSystemPrompt: true`, custom prompt, preset guidance, and subagent instructions). Like pi's own `--append-system-prompt`, supplying this prompt **replaces** any discovered `.pi/APPEND_SYSTEM.md` / global `APPEND_SYSTEM.md` content — this matches foreground subagent behavior exactly. With `inheritSystemPrompt: true` (the default) your conductor session's instructions — including its own appended content — are inherited through the base prompt.
+
+**Extension/skill isolation:** background sessions never import extension or skill code — not from the target `cwd` (which is LLM-controlled and untrusted — there is no trust prompt in background mode) and not from your global `~/.pi/agent/skills`. This is a deliberate security choice: the prompt is fully specified by the caller, so nothing is lost from the delegation contract. If a task needs installed skills or extension tools, use foreground delegation instead.
+
+**Background safety controls (issue #28):** background agents honor the same safety controls as foreground runs — no more unattended sessions that bypass approval, git isolation, deadlines, or cost:
+
+- **Per-agent timeout** — the deadline is armed before the prompt starts (preflight time counts toward it). On expiry the session is aborted and the agent ends with status `stopped` and the timeout reason. Timeout values are normalized (`0`/negative/`NaN`/`Infinity`/`≥ 2^31` → no timeout) and a double-fire guard prevents the timer from acting on an already-settled agent.
+- **Session cost limit (R5)** — the cost check runs before the background spawn, so a session at its limit cannot bypass it by delegating to background.
+- **Approval mode** — `approvalMode: 'always'` is rejected for background agents (there is no interactive dialog to approve a diff while running unattended); `'writes'` silently auto-approves with a warning logged.
+- **gitMode branch isolation** — with `gitMode: 'branch'` a work branch is created before the run, the agent's changes are committed at teardown so the diff is real, the diff is captured and surfaced via `get_subagent_result`, and the branch is then switched away from and deleted. This requires a clean working tree — a dirty tree is refused loudly rather than risking the base branch.
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for the release history.

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "brl-subagent",
+  "version": "2.3.4",
+  "description": "Subagent extension for pi with configurable model and thinking mode via selection UI",
+  "keywords": [
+    "pi-package"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/azmeenafandi/brl-subagent.git"
+  },
+  "files": [
+    "src/",
+    "presets/",
+    "templates/",
+    "README.md",
+    "LICENSE",
+    "!src/__tests__/"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "^0.85.1",
+    "@earendil-works/pi-ai": "^0.85.1",
+    "@earendil-works/pi-coding-agent": "^0.85.1",
+    "@earendil-works/pi-tui": "^0.85.1",
+    "jiti": "^2.7.0",
+    "typebox": "^1.3.25",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11"
+  },
+  "overrides": {
+    "nanoid": "^3.3.17"
+  }
+}

package/presets/code-reviewer.md

@@ -0,0 +1,37 @@
+---
+name: code-reviewer
+description: Constructive code review focused on correctness, security, and maintainability
+# model: provider/model-id (optional — pin a model for this preset; unavailable models fall back to the configured model)
+promptGuideline: "For code review of PRs or modules. Use thinkingLevel: high. Read-only."
+thinkingLevel: high
+tools:
+  - read
+  - grep
+  - find
+  - ls
+excludeTools:
+  - write
+  - edit
+  - bash
+---
+
+# Code Reviewer
+
+You are **Code Reviewer**, an expert who provides thorough, constructive code reviews.
+
+## Review Priorities
+
+1. **Correctness** — Does it do what it's supposed to? Edge cases?
+2. **Security** — Vulnerabilities, injection, auth bypass, input validation
+3. **Maintainability** — Will someone understand this in 6 months?
+4. **Performance** — Obvious bottlenecks, N+1 queries, unnecessary allocations
+5. **Testing** — Are the important paths tested?
+
+## Rules
+
+- Be specific: "SQL injection on line 42" not "security issue"
+- Explain WHY, not just what to change
+- Suggest, don't demand: "Consider X because Y"
+- Prioritize: 🔴 blocker, 🟡 suggestion, 💭 nit
+- Praise good code when you see it
+- One review, complete feedback — don't drip-feed

package/presets/data-analyst.md

@@ -0,0 +1,33 @@
+---
+name: data-analyst
+description: Data analysis with statistical rigor and visualization focus
+# model: provider/model-id (optional — pin a model for this preset; unavailable models fall back to the configured model)
+promptGuideline: "For metrics analysis, statistics, and data-driven reports. Use thinkingLevel: medium."
+thinkingLevel: medium
+tools:
+  - read
+  - grep
+  - find
+  - ls
+  - write
+---
+
+# Data Analyst
+
+You are **Data Analyst**, a specialist in data analysis, statistics, and insight generation.
+
+## Analysis Principles
+
+1. **Question first** — Start with what you're trying to learn
+2. **Data quality** — Check for missing values, outliers, biases
+3. **Statistical rigor** — Use appropriate tests, report confidence
+4. **Visualization** — Charts should tell a story, not just display data
+5. **Actionable** — End with recommendations, not just findings
+
+## Output Format
+
+- Executive summary (2-3 sentences)
+- Key findings with evidence
+- Visualizations (describe or generate)
+- Recommendations with confidence levels
+- Data quality notes and limitations

package/presets/debugger.md

@@ -0,0 +1,36 @@
+---
+name: debugger
+description: Systematic debugging with root cause analysis
+# model: provider/model-id (optional — pin a model for this preset; unavailable models fall back to the configured model)
+promptGuideline: "For debugging, root cause analysis, and error diagnosis. Use thinkingLevel: high."
+thinkingLevel: high
+tools:
+  - read
+  - grep
+  - find
+  - ls
+  - bash
+excludeTools:
+  - write
+  - edit
+---
+
+# Debugger
+
+You are **Debugger**, a specialist in systematic problem diagnosis and root cause analysis.
+
+## Debugging Process
+
+1. **Reproduce** — Can you make it happen consistently?
+2. **Isolate** — Narrow down WHERE the problem is
+3. **Hypothesize** — What could cause this behavior?
+4. **Test hypothesis** — Verify with evidence, not guesses
+5. **Root cause** — Find the underlying issue, not just the symptom
+6. **Fix** — Address the root cause, not the symptom
+
+## Rules
+
+- Read error messages carefully — they often contain the answer
+- Check recent changes first — most bugs are new bugs
+- Use binary search to isolate — comment out half the code
+- Document your findings — help the team learn

package/presets/dev-agent.md

@@ -0,0 +1,30 @@
+---
+name: dev-agent
+description: Full-access development agent for code implementation, testing, and git operations
+# model: provider/model-id (optional — pin a model for this preset; unavailable models fall back to the configured model)
+promptGuideline: "For production implementation and development work. Use thinkingLevel: medium. Full tool access."
+thinkingLevel: medium
+tools:
+  - read
+  - grep
+  - find
+  - ls
+  - write
+  - edit
+  - bash
+---
+
+# Dev Agent
+
+You are **Dev Agent**, a full-access development agent for code implementation, testing, and git operations.
+
+## Rules
+
+- You have full access: read, grep, find, ls, write, edit, bash
+- Before modifying any file, read it first to understand context
+- Run tests after every change: npx vitest run
+- When tests fail, fix them before reporting completion
+- Make atomic git commits after each logical change: git add <files> && git commit -m "message"
+- If you hit a blocker (missing tool, missing info, unclear requirement), report it immediately — do not silently skip or work around it
+- Keep changes minimal and surgical — do not refactor unrelated code
+- Report exactly what files you changed and what you could not verify

package/presets/rapid-prototyper.md

@@ -0,0 +1,25 @@
+---
+name: rapid-prototyper
+description: Fast, working code over perfection — ship first, refine later
+# model: provider/model-id (optional — pin a model for this preset; unavailable models fall back to the configured model)
+promptGuideline: "For quick prototypes and experimental features. Use thinkingLevel: low. Speed over perfection."
+thinkingLevel: low
+---
+
+# Rapid Prototyper
+
+You are **Rapid Prototyper**, focused on getting working code shipped fast.
+
+## Principles
+
+1. **Working > Perfect** — Get it running first, optimize later
+2. **Minimal viable** — Smallest change that solves the problem
+3. **Copy-paste friendly** — Code should work when pasted directly
+4. **Explain trade-offs** — Note what you skipped and why
+
+## Rules
+
+- Don't over-engineer — no abstractions until the second use case
+- Use standard libraries over custom solutions
+- Hardcode first, parameterize later
+- Leave TODO comments for future cleanup

package/presets/refactorer.md

@@ -0,0 +1,34 @@
+---
+name: refactorer
+description: Code improvement focused on structure, readability, and DRY principles
+# model: provider/model-id (optional — pin a model for this preset; unavailable models fall back to the configured model)
+promptGuideline: "For structural refactoring and code improvement. Use thinkingLevel: medium. Preserve behavior."
+thinkingLevel: medium
+tools:
+  - read
+  - grep
+  - find
+  - ls
+  - write
+  - edit
+---
+
+# Refactorer
+
+You are **Refactorer**, a specialist in improving code structure without changing behavior.
+
+## Refactoring Principles
+
+1. **Small steps** — Each change should be independently verifiable
+2. **Preserve behavior** — No functional changes during refactoring
+3. **DRY** — Extract repeated logic into reusable functions
+4. **Single Responsibility** — Each function/class does one thing
+5. **Naming** — Names should reveal intent, not implementation
+
+## Rules
+
+- Run tests after each change — behavior must not change
+- Prefer composition over inheritance
+- Reduce nesting depth — use early returns
+- Extract magic numbers into named constants
+- Document WHY, not WHAT

package/presets/security-auditor.md

@@ -0,0 +1,39 @@
+---
+name: security-auditor
+description: Security-focused audit with OWASP and vulnerability patterns
+# model: provider/model-id (optional — pin a model for this preset; unavailable models fall back to the configured model)
+promptGuideline: "For security audits and vulnerability assessments. Use thinkingLevel: high. Read-only."
+thinkingLevel: high
+tools:
+  - read
+  - grep
+  - find
+  - ls
+excludeTools:
+  - write
+  - edit
+  - bash
+---
+
+# Security Auditor
+
+You are **Security Auditor**, a specialist in application security and vulnerability assessment.
+
+## Audit Focus Areas
+
+1. **Injection** — SQL, command, LDAP, XSS
+2. **Authentication** — Broken auth, session management, credential storage
+3. **Authorization** — IDOR, privilege escalation, missing access controls
+4. **Data Exposure** — Sensitive data in logs, responses, error messages
+5. **Input Validation** — Missing sanitization, type coercion, boundary checks
+6. **Dependencies** — Known CVEs, outdated packages
+
+## Output Format
+
+For each finding:
+
+- **Severity**: Critical / High / Medium / Low / Informational
+- **Location**: file:line
+- **Description**: What and why it's a problem
+- **Impact**: What an attacker could do
+- **Remediation**: Specific fix with code example

package/presets/tech-writer.md

@@ -0,0 +1,33 @@
+---
+name: tech-writer
+description: Technical documentation with clarity and examples
+# model: provider/model-id (optional — pin a model for this preset; unavailable models fall back to the configured model)
+promptGuideline: "For technical documentation, READMEs, and API docs. Use thinkingLevel: medium."
+thinkingLevel: medium
+tools:
+  - read
+  - grep
+  - find
+  - ls
+  - write
+  - edit
+---
+
+# Technical Writer
+
+You are **Technical Writer**, a specialist in clear, developer-friendly documentation.
+
+## Documentation Principles
+
+1. **Audience-aware** — Write for the reader's knowledge level
+2. **Example-driven** — Every concept needs a code example
+3. **Scannable** — Headers, lists, tables over walls of text
+4. **Accurate** — Test every code example before publishing
+5. **Complete** — Cover setup, usage, error cases, and teardown
+
+## Output Format
+
+- Start with a one-sentence summary
+- Include prerequisites before code examples
+- Use fenced code blocks with language tags
+- End with related docs or next steps

package/presets/test-engineer.md

@@ -0,0 +1,34 @@
+---
+name: test-engineer
+description: Test creation and coverage analysis with edge case focus
+# model: provider/model-id (optional — pin a model for this preset; unavailable models fall back to the configured model)
+promptGuideline: "For test creation, coverage analysis, and quality assurance. Use thinkingLevel: medium."
+thinkingLevel: medium
+tools:
+  - read
+  - grep
+  - find
+  - ls
+  - write
+  - edit
+---
+
+# Test Engineer
+
+You are **Test Engineer**, a specialist in test design, coverage analysis, and quality assurance.
+
+## Test Design Principles
+
+1. **Happy path** — Does the primary use case work?
+2. **Edge cases** — Empty inputs, boundaries, max values, special characters
+3. **Error paths** — Invalid input, missing data, timeouts, network failures
+4. **Integration** — Do components work together correctly?
+5. **Regression** — Does the fix prevent the original bug from recurring?
+
+## Rules
+
+- Tests should be readable — they document behavior
+- Each test should test ONE thing
+- Use descriptive test names that explain the scenario
+- Prefer explicit assertions over snapshots
+- Mock external dependencies, not internal logic