# devil Structured `/devil` command for stress-testing an idea against a devil's advocate and defender. ## Install / load Loaded through the root pi-ext package. See [root README](../../README.md). ## Quick Start ```bash pi /devil we should switch to microservices ``` ## Commands / tools / settings Canonical names: - Slash command: `/devil ` - Settings key: `devil` - Extension dir: `extensions/devil/` - Package: `@bugabinga/pi-ext-devil` Commands: - `/devil ` — start an interactive debate. - `/devil` — reports `Usage: /devil `. Registered flags: - `--devil-rounds ` — override max debate rounds. Clamped to `1..5`. - `--devil-stop ` — override stopping condition. Registered agent-facing tools: none. Shortcuts: none. Hooks: - `session_shutdown` — aborts active debates. Settings under `devil`: | Key | Behavior | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------- | | `model` | Devil + synthesis model. Falls back to current model. | | `defenderModel` | Defense model. Falls back to current model. | | `thinkingLevel` | Fallback thinking level for all roles. | | `devilThinkingLevel` | Devil thinking level. Default `medium`. | | `defenderThinkingLevel` | Defense thinking level. Default `high`. | | `synthesisThinkingLevel` | Synthesis thinking level. Default `off`. | | `roleTimeoutMs` | Timeout per role. Default `90000`, clamped `10000..600000`. | | `maxRounds` | Max debate rounds. Default `2`, clamped `1..5`. | | `extensionMode` | `all` or `off`. Default `all`. | | `stoppingConditions` | `consensus`, `blocking_found`, or `max_rounds`. Default `consensus`. | | `concessionThreshold` | Consensus threshold. Default `0.7`. | | `onBlocking` | `surface`, `escalate`, or `ignore`. Default `surface`; `escalate` adds an unresolved-blocking warning to handoff text. | Valid thinking levels: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`. Invalid values are ignored. Settings and flag defaults are read when the extension loads. ## Behavior | Aspect | Behavior | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Session state | Each debate is independent. Final accepted output is appended as `devil-result`. | | UI | Requires interactive Pi UI. Opens live review, then result editor. | | Context | Uses current cwd, context usage, and an ephemeral fork of the current Pi session branch. | | Models | Devil uses `devil.model` or current model. Defense uses `devil.defenderModel` or current model. Synthesis uses Devil model. | | Auth | Requires API auth for Devil and Defense model providers before starting. | | Context guard | Blocks before starting if current usage + 16k token overhead exceeds 85% of the smaller Devil/Defense context window. | | Sub-agents | Load normal Pi settings/resources/extensions unless `devil.extensionMode` is `off`. | | Sub-agent tools | All available tools except `write` and `edit`. | | Rounds | Devil challenges, Defense responds, transcript accumulates, synthesis produces final verdict. | | Stop: `consensus` | Stops after 2 consecutive resolved Defense responses using `concessionThreshold`, or after `maxRounds`. | | Stop: `blocking_found` | Stops when a Devil round raises zero blocking issues, or after `maxRounds`. | | Stop: `max_rounds` | Runs until `maxRounds`. | | Live review keys | `↑↓/j/k` scroll, `PgUp/Ctrl+u` and `PgDown/Ctrl+d` page, `g/G` top/end. | | Cancel | `q`, `Esc`, or `Ctrl+C` cancels the live review. | | Failure | Failed review stays open until closed. Timeout message suggests `/compact`, then retry. Closing a failed review restores `/devil ` in the editor. | | Results | Edited verdict is appended as `devil-result`; main agent receives advisory handoff and must wait for the next user reply before execution. | | Cleanup | Role-agent forks are removed after use. Leftover temporary debate forks older than 24h are removed on extension load. | ## Configuration Example shape: ```json { "devil": { "maxRounds": 2, "stoppingConditions": "consensus", "concessionThreshold": 0.7, "extensionMode": "all", "roleTimeoutMs": 90000, "onBlocking": "surface" } } ``` Set `devil.extensionMode` to `"off"` to run sub-agents without extensions. Thinking defaults are role-based: Devil `medium`, Defense `high`, Synthesis `off`. Synthesis defaults to `off` because output must be JSON-only. Set `thinkingLevel` as a global fallback, or override per role with `devilThinkingLevel`, `defenderThinkingLevel`, `synthesisThinkingLevel`. ## Output Synthesis includes: - recommendation: `proceed`, `proceed_with_caution`, `revise`, `abandon` - summary - blocking issues - addressable concerns - survived claims - conceded weaknesses - next steps - debate metadata: rounds, blocking challenges raised, unresolved blocking issues in final verdict The result editor title shows the recommendation. Enter sends the edited report to the main agent. Esc discards it. ## Troubleshooting ### "No model selected. Use /model first." Select a model with `/model`, or configure `devil.model`. ### "No defender model selected. Use /model first or set devil.defenderModel." Select a model with `/model`, or configure `devil.defenderModel`. ### "No API key" Configure auth for the selected or configured provider. ### Context limit block Run `/compact`, then retry `/devil`. ### Irrelevant challenges Make `/devil ` more specific. Debate context comes from the current session branch and loaded context.