setup-benny

Files (1)

• SKILL.md

SKILL.md (first lines)

# Set up Benny

Benny ships as a dormant automation pack inside pstack. The plugin manifest exposes only pstack's normal skill root; this file and the two operational files are not slash skills.

The human enters setup by pointing a bb thread at the pack's `FOR_AGENTS.md`. The bootstrap flow copies the whole pack into the target repository, then reads this file directly at `.bb/automations/benny/skills/setup-benny/SKILL.md`.

Benny needs external configuration and two live bb automations.

bb automations start on a schedule only: a five-field cron expression with a timezone, a one-shot time, or a delay (`bb guide automations`). There is no Slack event trigger. Each Benny automation is therefore an agent automation on a cron schedule that polls the source channel through the provider's Slack MCP tools, selects one eligible report, and records its claim in a ledger file. Each run is its own bb thread, listed by `bb automation runs`.

Do not create or update an automation until the user explicitly asks. Never put a secret value in plugin files, prompts, or committed configuration.

## 1. Copy the pack and enable shared pstack skills

Do this before asking for Benny configuration and before running any `bb automation` write command.

Ask which repository will run the automations, and find its bb project ID with `bb project list --json`. The source pack is the directory containing `FOR_AGENTS.md`. The destination is `<target-repository>/.bb/automations/benny/`.

Merge the entire source pack into the destination:

1. Create the destination when it is absent.
2. Copy every source file to the same relative path.
3. Preserve destination-only files. Never delete unrelated files during install or refresh.
4. Keep user-owned configuration, feature maps, routing maps, rendered prompts, and the ledger outside the destination. Never overwrite them.
5. When an existing source-managed file differs, inspect the diff and merge without discarding local edits. If ownership is ambiguous, stop and ask before replacing it.
6. Verify that the destination contains `FOR_AGENTS.md`, this setup file, both operational files, their references, and the templates.

If this file is already being read from the target destination, treat the copy as complete and run the same verification before continuing.

Make sure pstack is installed and enabled on the bb server that will run the automations. Plugins belong to the bb server, not to the repository, so there is no file to commit for this step.

1. Run `bb plugin list`.
2. If pstack is absent, ask the user for its source and run `bb plugin install git:<repo-url>` or `bb plugin install <local-path>`.
3. If pstack is installed but disabled, run `bb plugin enable pstack`.
4. Change no other plugin.

Run `bb skill list --project <target-project-id> --json` and verify that these shared pstack skills resolve with scope `plugin` from the installed pstack plugin:

- `how`
- `why`
- `tdd`
- `unslop`
- `principle-separate-before-serializing-shared-state`
- `principle-minimize-reader-load`
- `principle-guard-the-context-window`
- `principle-sequence-verifiable-units`
- `principle-fix-root-causes`
- `principle-prove-it-works`

Do not count a skill loaded into the current session, a same-named copy in `~/.bb/skills` or the target's `.bb/skills`, or a provider's own skill directory. The check must show that a fresh thread in the target project receives pstack from the plugin.

If pstack cannot be installed or enabled, or any shared dependency does not resolve, stop and explain the failure.

The Benny files are read directly from `.bb/automations/benny/`. Do not copy that directory into `.bb/skills/`, add it to a plugin manifest, or expect its `SKILL.md` files to appear in the slash-skill list.

Tell the user that `.bb/automations/benny/` and any referenced secret-free configuration must be committed on the default branch before either automation is enabled. Do not commit them unless the user asks.

Once this check passes, live automation prompts may read the committed operational files by their stable repository-relative paths. They must not embed a plugin cache path or copy the file contents.

## 2. Adapt the configuration

Open these copied examples:

- `../../templates/configuration.example.yaml`
- `../reproduce-and-fix-issues/references/feature-map.example.md`

Create user-owned copies outside `.bb/automations/benny/`. These are configuration files, not pack files. Example locations:

- Project config, such as `.bb/benny/configuration.yaml`
- Project feature map, such as `.bb/benny/feature-map.md`
- Project routing map, such as `.bb/benny/routing.md`
- User config, such as `~/.config/benny/configuration.yaml`
- User feature map, such as `~/.config/benny/feature-map.md`

Fill one feature-map section for every user-facing feature the automation may reproduce. Keep it at the user point of view. Do not freeze implementation details or current code paths in the map.

Do not edit the copied examples. Pack refreshes may update source-managed files after conflict review, but they must never touch the user-owned copies.

Prefer committed, secret-free files in the target repository when a fresh automation checkout must read them. Otherwise paraphrase the required values into the live prompt. Reference a repository file only after `git ls-tree` on the default branch confirms that the file is committed there.

The ledger is runtime state, not configuration. Put `state.ledger_path` at an absolute path outside the repository on the machine that runs the automations, because each repro run starts in a fresh worktree. Never commit it.

Use stable repository-relative paths for committed pack and configuration files. Never reference the plugin source directory or a plugin cache path from a live automation.

## 3. Fill the required choices

Ask for or confirm:

- Source Slack channel ID
- Optional operations or status channel ID
- Repository URL and default branch
- Triage identity or Slack user ID
- Issue tracker type, team, project, labels, and intake status
- Tracker adapter skill or MCP actions
- Optional routing map path
- Required control skill name
- Required user-facing feature-map path
- Status emoji strings
- Pull request URL format
- Cron schedule and timezone for each automation, and the lookback window
- Ledger path
- Polling and effort budgets
- Model for triage, repro, code work, and media review, each as a `provider/model/level` tuple

Use only models that `bb provider models <provider-id> --environment <environment-id> --json` lists, with a reasoning level from that model's `supportedReasoningEfforts`. Do not guess a model and do not carry over a private default.

Pick schedules the work can sustain. Triage runs are short, so a few minutes apart is reasonable. Each repro run creates a fresh worktree even when no report qualifies, so space those further apart. Runs may overlap; the ledger claim keeps them off the same report.

The source channel, triage identity, repository, tracker adapter, control skill, and feature map must be explicit. Fail setup if any required value stays ambiguous.

Use pstack's `unslop` skill on the final automation names, descriptions, and prompt shims before saving them.

## 4. Check integration capabilities

The triage automation needs:

- Read access to the configured source Slack channel and its threads
- Thread-reply access in that channel
- Attachment metadata and file download access when reports include media

From rahmanramsi/bb-pstack-plugin, MIT.

More from rahmanramsi/bb-pstack-plugin