repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

extensions/devil/README.md

Raw

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.

Quick Start

pi
/devil we should switch to microservices

Commands / tools / settings

Canonical names:

Commands:

Registered flags:

Registered agent-facing tools: none.

Shortcuts: none.

Hooks:

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 <idea> 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:

{
  "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:

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 <idea> more specific. Debate context comes from the current session branch and loaded context.

Markdown source
# 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 <idea>`
- Settings key:
  `devil`
- Extension dir:
  `extensions/devil/`
- Package:
  `@bugabinga/pi-ext-devil`

Commands:

- `/devil <idea>` — start an interactive debate.
- `/devil` — reports `Usage:
  /devil <your idea>`.

Registered flags:

- `--devil-rounds <n>` — override max debate rounds.
  Clamped to `1..5`.
- `--devil-stop <consensus|blocking_found|max_rounds>` — 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 <idea>` 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 <idea>` more specific.
Debate context comes from the current session branch and loaded context.