# Configuration

`@teelicht/pi-superagents` loads configuration in two layers: **bundled defaults** and **user overrides**.

Bundled defaults ship inside the package and provide sensible baseline values. User overrides live in:

```text
~/.pi/agent/extensions/subagent/config.json
```

This file is user-owned. A fresh install creates it by copying the bundled defaults, including behavior flags for the built-in Superpowers entrypoint commands.

At runtime, user config merges on top of the bundled defaults. You only need to edit the settings you want to change. Full parseable examples are available in:

```text
~/.pi/agent/extensions/subagent/config.example.json
```

> [!NOTE]
> `config.example.json` is illustrative only. Copy only the settings you want to change into `config.json`; unspecified fields are filled in from the bundled defaults.

## Validation

`pi-superagents` fails closed when `config.json` cannot be trusted. If the file has invalid JSON, unknown keys, or wrong value types, subagent execution is disabled until the file is fixed.

If `config.json` matches the bundled default, the extension may show a non-blocking notice. This is valid for fresh installs; edit only the behavior flags you want to change.

When Pi starts, the extension shows a notification with the config path and exact diagnostics. You can also inspect diagnostics with:

```text
/sp-settings
```

## No Async Configuration

Execution is strictly synchronous and blocking. There is no `async`, `wait`, `collect`, or `cancel` frontmatter key or config key. Lifecycle tools (`subagent_done`, `caller_ping`) are internal child-only tools registered through policy; they are not user-configurable delegation controls.

## Built-in Commands

Slash commands are registered from interactive entrypoint agent frontmatter, not generated from `config.json`. The bundled defaults include behavior flags for three built-in commands:

| Command | Policy Settings |
|---|---|
| `sp-implement` | `useSubagents: true`, `useTestDrivenDevelopment: true`, `useBranches: false`, `worktrees: { enabled: false }` |
| `sp-brainstorm` | `usePlannotator: true` |
| `sp-plan` | `usePlannotator: true` |

Each built-in command has a corresponding bundled interactive entrypoint agent file (`agents/sp-implement.md`, `agents/sp-brainstorm.md`, `agents/sp-plan.md`). The entrypoint agent file provides command metadata (name, description, command name, entry skill) and root lifecycle skills. The command preset in `config.json` only controls runtime behavior flags.

Built-in command behavior can be augmented or overridden by user config. Settings in your `config.json` are deep-merged on top of the bundled defaults: any fields you specify replace the corresponding built-in values, while unspecified fields remain at their built-in defaults. To create a variant of a built-in command, reference the built-in command name in your `commands` map and override only the fields you need. Use a different command name only when you also create a matching interactive entrypoint agent.

## Configuration Keys

### `superagents`

Configures the Superpowers workflow.

| Key | Description |
|---|---|
| `commands` | Map of command behavior presets. Each preset has per-command policy booleans. Slash commands are registered from interactive entrypoint agents; `config.json` only controls behavior flags for existing entrypoint commands. |
| `extensions` | Array of local extension paths or Pi extension source specs that every subagent receives. Implicit Pi extension discovery is disabled by default; add extensions here for child Pi processes. |
| `tools` | Array of tool names or tool extension paths appended to every subagent after role-specific tool policy. Use this for shared tools you do not want to repeat in every agent frontmatter file. |
| `modelTiers` | Maps abstract tier names (`cheap`, `balanced`, `max`, plus any custom tiers) to concrete model configs. |
| `interceptSkillCommands` | List of skill names intercepted for Superpowers entry (`brainstorming`, `writing-plans`). |
| `superpowersSkills` | List of Superpowers process skill names (bundled default, not user-configurable). |

### Extension Allowlist

Subagents run with implicit Pi extension discovery disabled by default. Configure `superagents.extensions` as a global list of extensions that every subagent should receive:

```json
{
  "superagents": {
    "extensions": [
      "./src/extension/custom-subagent-tools.ts",
      "npm:@sting8k/pi-vcc"
    ]
  }
}
```

Local extension entries must point to existing files or directories when the subagent starts. Relative paths resolve from the subagent runtime working directory; use absolute paths for local extensions outside the project. Missing local paths cause subagent launch to fail before Pi starts and include the config source in the error.

Package and remote entries should use normal Pi `-e` source prefixes such as `npm:`, `git:`, `https:`, or `ssh:`. These sources pass through to child Pi unchanged, and child Pi resolves, installs, and loads them through its normal extension resolver. Bare package names such as `@scope/package` are treated as local paths; use `npm:@scope/package` for npm packages.

Agent frontmatter can append additional extensions per-agent using the `extensions` field, which is additive to the global list. Extensions declared in agent frontmatter are appended to the global `extensions` array at session launch.

### Global Tools

Configure `superagents.tools` as a global list of tool names or tool extension paths that every subagent should receive:

```json
{
  "superagents": {
    "tools": ["read", "grep", "find", "ls", "./tools/shared-tool.ts"]
  }
}
```

These tools are appended after each role's normal tool policy and de-duplicated while preserving order. The bundled default config provides the common read-only baseline (`read`, `grep`, `find`, `ls`) globally, so built-in role agents only list extra tools such as `bash` or `write` in frontmatter. Existing agent `tools:` frontmatter still defines that agent's baseline extras; `superagents.tools` saves you from repeating common additions. Path-like entries such as `./tools/shared-tool.ts` are passed to child Pi as tool extensions using Pi's normal `--extension` handling.

Bounded Superpowers roles still cannot receive delegation tools such as `subagent` through this setting; those entries are filtered by policy for bounded roles. Child lifecycle tools (`subagent_done`, `caller_ping`) remain managed by the runtime.

### Entrypoint Agent Frontmatter

Interactive entrypoint agent files own the slash command metadata (name, description, command name, entry skill) and define root lifecycle skills. `config.json` only controls behavior flags.

Create a custom command by adding an entrypoint agent file. Example:

`~/.pi/agent/agents/sp-review.md`

```yaml
---
name: sp-review
description: Review code through the Superpowers workflow
kind: entrypoint
execution: interactive
command: sp-review
entrySkill: using-superpowers
skills: verification-before-completion, receiving-code-review
---

Review code and produce actionable findings.
```

Matching behavior flags in `config.json`:

```json
{
  "superagents": {
    "commands": {
      "sp-review": {
        "useSubagents": false,
        "useTestDrivenDevelopment": false
      }
    }
  }
}
```

### Command Behavior Presets

Each command preset in `config.json` supports these behavior keys:

| Key | Description |
|---|---|
| `useBranches` | Require dedicated git branch for plans/specs. |
| `useSubagents` | Allow delegation through `subagent` tool. |
| `useTestDrivenDevelopment` | Enable TDD guidance. |
| `usePlannotator` | Enable Plannotator browser review at approval points. |
| `worktrees.enabled` | Use git worktree isolation for parallel tasks. |
| `worktrees.root` | Directory for worktrees (default: system temp). |

Command metadata (`description`, `entrySkill`) was moved to entrypoint agent frontmatter. Adding or editing command metadata requires adding or editing an `agents/*.md` entrypoint file.

## Inline Role Output

Superpowers role agents return their findings through Pi tool results. The runtime no longer configures packet output files, so `sp-implementer`, `sp-spec-review`, `sp-code-review`, and `sp-debug` do not create repo-root handoff files during normal subagent-driven development.

Execution artifacts are still available when `artifacts` is enabled. Those files are written to the session artifact directory for debugging and truncation recovery, not to the repository root.

## Compact Inline Subagent Results

Subagent tool results are rendered inline in the Pi conversation as compact, width-bounded lines. A collapsed view shows the subagent name, runtime-confirmed model label, task, status, and live activity (e.g., current tool). Clicking or expanding the result reveals concise details: model, thinking level when available, skills, recent tools, output preview, errors, and artifact paths. This keeps long-running Superpowers workflows readable without scrolling through verbose JSON or full Markdown output.

The compact renderer is active for all `subagent` tool results produced by `pi-superagents`. `/subagents-status` remains available for inspecting active or recently completed runs in a dedicated overlay, including the runtime-confirmed model and separate thinking level when available.

## Run History

Completed subagent runs are stored as JSONL at `~/.pi/agent/run-history.jsonl` so `/subagents-status` can show recent runs across sessions. Inline rows use live progress/result metadata, and run history stores the child Pi-reported model separately from the effective thinking level so the overlay can confirm actual model routing instead of only showing configured defaults. Set `PI_SUPERAGENTS_RUN_HISTORY_PATH` to an absolute file path when you need to isolate run history, for example in tests or sandboxed PI sessions.

## Common Override Examples

Augment the built-in `sp-implement` with custom worktree settings:

```json
{
  "superagents": {
    "commands": {
      "sp-implement": {
        "worktrees": {
          "enabled": true,
          "root": ".worktrees"
        }
      }
    }
  }
}
```

Enable Plannotator for the built-in brainstorm command:

```json
{
  "superagents": {
    "commands": {
      "sp-brainstorm": {
        "usePlannotator": true
      }
    }
  }
}
```

If `root` is inside your repository, it must be ignored by git.

## Custom Commands

Create a custom slash command by adding an interactive entrypoint agent markdown file:

```yaml
---
name: sp-lean
description: Lean Superpowers without subagents
kind: entrypoint
execution: interactive
command: sp-lean
entrySkill: using-superpowers
---

Lean entrypoint for Superpowers workflows.
```

Optional behavior flags in `config.json`:

```json
{
  "superagents": {
    "commands": {
      "sp-lean": {
        "useSubagents": false,
        "useTestDrivenDevelopment": false,
        "worktrees": {
          "enabled": false
        }
      }
    }
  }
}
```

Command names must match `superpowers-<name>` or `sp-<name>` (lowercase alphanumeric and hyphens), and each behavior block must have a matching interactive entrypoint agent to register a slash command.

Agent frontmatter may declare `session-mode: standalone | lineage-only | fork`. Built-in bounded roles ship with `lineage-only`.

## Model Tiers

Superpowers agents use abstract model tiers. Define tiers in your configuration:

```json
{
  "superagents": {
    "modelTiers": {
      "cheap": { "model": "openai/gpt-4o-mini", "thinking": "off" },
      "balanced": { "model": "anthropic/claude-3-5-sonnet", "thinking": "low" },
      "max": { "model": "anthropic/claude-3-5-sonnet", "thinking": "medium" }
    }
  }
}
```

**Supported thinking levels:** `off`, `minimal`, `low`, `medium`, `high`, `xhigh`. The `thinking` key is optional.

> [!NOTE]
> In `config.example.json`, `creative` and `legacy` are illustrative custom tiers added to demonstrate the surface; they are not built-in tiers. `thinking` is optional in any tier definition.

You can edit model tier mappings during an active PI session with `/sp-settings`. The model picker reads PI's authenticated model registry, supports type-to-search filtering by provider, ID, or display name, keeps keyboard selection within the visible result window, then asks for the tier thinking level (`default`, `off`, `minimal`, `low`, `medium`, `high`, or `xhigh`). Successful tier edits write the selected `provider/model` and optional `thinking` value to `config.json` and apply to future Superpowers subagents immediately; already-running subagents keep the model they were launched with.

`/sp-settings` also edits command-scoped workflow toggles. Use `c` to select a command, then toggle `p` for Plannotator, `s` for subagents, `t` for TDD, or `w` for worktrees on that selected command preset. This avoids writing Plannotator or TDD settings into unrelated command presets.

## Direct Skill Interception

Route skill commands through Superpowers:

```json
{
  "superagents": {
    "interceptSkillCommands": ["brainstorming", "writing-plans"]
  }
}
```

When enabled:
- `/skill:brainstorming <task>` → Superpowers with `brainstorming` entry skill
- `/skill:writing-plans <task>` → Superpowers with `writing-plans` entry skill

## Plannotator Browser Review

Plannotator review is enabled per-command via `usePlannotator`. For built-in commands:

- `sp-brainstorm`: `usePlannotator: true` — reviews saved specs
- `sp-plan`: `usePlannotator: true` — reviews saved plans

Install [Plannotator](https://plannotator.ai/) separately:

```text
pi install npm:@plannotator/pi-extension
```

If Plannotator is unavailable, Superpowers falls back to in-chat approval.

## Release Configuration

Maintainer release automation lives in `.github/workflows/release.yml` and uses npm Trusted Publishing. It does not require local configuration keys or npm tokens in `config.json`.

Before changing package metadata, install behavior, or default configuration files, check the [Release Process](releases.md). Release candidates must keep `package.json`, `package-lock.json`, `CHANGELOG.md`, and the npm package contents aligned.

## Superpowers Skills

The bundled `superpowersSkills` list defines process skills. Current list:

```json
"superpowersSkills": [
  "using-superpowers",
  "brainstorming",
  "writing-plans",
  "executing-plans",
  "test-driven-development",
  "requesting-code-review",
  "receiving-code-review",
  "verification-before-completion",
  "subagent-driven-development",
  "dispatching-parallel-agents",
  "using-git-worktrees",
  "finishing-a-development-branch"
]
```

Skill selection is trigger-driven via `using-superpowers`. Do not preload domain skills through command config. Entrypoint `skills` are reserved for lifecycle/root skills with explicit trigger points.

## Status and Settings

Use `/subagents-status` to inspect active and recent subagent runs (`Ctrl+Alt+S`), including runtime-confirmed model labels, thinking levels, resolved skills, and warnings.

Use `/sp-settings` to inspect workflow settings and config diagnostics. In the settings overlay, `c` cycles the selected command; boolean toggles apply to that command only.

## Superpowers Workflow Commands

### `/sp-implement`

Run implementation through the Superpowers workflow:

```text
/sp-implement fix the auth regression
/sp-implement tdd implement the cache invalidation
/sp-implement direct update the config
```

**Inline tokens:** `lean`, `full`, `tdd`, `direct`, `subagents`, `no-subagents`, `--fork`

Root prompts now instruct delegated Superpowers calls to pass the resolved `useTestDrivenDevelopment` value explicitly. This prevents custom commands such as `sp-lean` from accidentally inheriting another command's TDD setting when they delegate to `sp-implementer`. If a direct `subagent` tool call omits the parameter entirely, the runtime does not inject TDD by default.

### `/sp-brainstorm`

Run brainstorming with Plannotator spec review:

```text
/sp-brainstorm design the new onboarding flow
/sp-brainstorm explore mobile push options
```

### `/sp-plan`

Run planning with Plannotator plan review:

```text
/sp-plan redesign the auth flow
/sp-plan plan the mobile push integration
```

## Role Agents

| Role | Agent | Purpose |
|---|---|---|
| Recon | `sp-recon` | Context gathering for task discovery |
| Research | `sp-research` | Evidence gathering for complex logic |
| Implementer | `sp-implementer` | Planned code changes with verification |
| Code Review | `sp-code-review` | Quality reviewer for implementation |
| Spec Review | `sp-spec-review` | Verification against design specs |
| Debug | `sp-debug` | Failure investigation and root-cause analysis; injects `systematic-debugging` |