bstack-runtime

Files (6)

• SKILL.md
• billybot.md · references/adapters/
• codex.md · references/adapters/
• cursor.md · references/adapters/
• generic.md · references/adapters/
• executors.md · references/

SKILL.md (first lines)

# bstack runtime

Resolve execution mechanics before an orchestration skill delegates, waits,
reads conversation history, or mutates external state.

## Load configuration

Load configuration in this order. Later, higher-authority instructions override
earlier configuration regardless of file order.

1. Built-in defaults from this skill.
2. User configuration at `$XDG_CONFIG_HOME/bstack/config.yaml`, or
   `~/.config/bstack/config.yaml` when `XDG_CONFIG_HOME` is unset.
3. Repository configuration at `<repo>/.bstack/config.yaml`.
4. Instructions in the current conversation.
5. Host system and developer instructions.

Missing files are normal. Never create configuration during an ordinary task.
Use `setup-bstack` when the user asks to configure bstack.

Default limits are `max-parallel: 3`, `max-review-rounds: 2`, and
`panel-size: 2`. A lower limit from the host wins.

## Resolve executor routes

Each semantic role may use either the version 1 scalar form or a version 2
route:

```yaml
models:
  deep-code:
    executor: codex
    model: gpt-5.6-sol
    reasoning: high
```

Normalize a scalar as `{executor: auto, model: <scalar>}`. `reasoning` is
optional in a version 2 route. Omission and `reasoning: auto` both preserve the
route's default: a native `auto` route inherits the parent session's reasoning
level, while an explicit CLI route uses the provider's configured default.
Executor values have literal meanings:

- `auto` uses native host delegation and inherits the parent model when the
  route omits a model.
- `codex` runs the configured model through `codex exec`.
- `claude` runs the configured model through `claude -p`.

A host adapter may run an explicit `codex` or `claude` route through the
host's own delegation when it runs the same model at the same reasoning level
and keeps each worker visible to the user. The BillyBot adapter does this.

Configuration must not become an arbitrary command or provider-flag escape
hatch. `reasoning` is the only configurable provider control beyond model
selection. The runtime owns its translation and the scoped permission controls
described in the executor reference. Never silently replace an explicit executor
or model with another one. Change an explicit reasoning level only through the
per-job step in [Match reasoning to the job](#match-reasoning-to-the-job). If
the host cannot run an explicit CLI route or apply an explicit reasoning level,
follow the recovery rule below.

Read [references/executors.md](references/executors.md) before starting an
explicit CLI route. Start the fixed command through the host's process
capability, send the prompt over stdin, and let the host own waiting and
cancellation. Never impose a wall-clock deadline on an LLM call. A tool yield
or progress polling interval must not terminate the CLI process.

Choose permissions from the assignment before launching. Inspection and review
use read-only mode. A request to implement, fix, or create a local artifact
already authorizes the necessary local writes; pass that authority to the
worker and use `workspace-write` in its isolated worktree. Do not ask again
merely because work is delegated. Use only the scoped permission controls in
the executor reference, never approval-bypass flags or arbitrary provider
flags. Every CLI worker counts against both bstack's `max-parallel` limit and
any lower host limit.

## Resolve the host

Inspect the tools and instructions available in the current session. Build a
capability map for these operations:

- `delegate`: start one bounded worker with an owned scope.
- `delegate-parallel`: start independent workers without shared writes.
- `wait`: wait for worker completion or a meaningful state change.
- `ask`: request a genuinely missing product or preference decision.
- `schedule`: wake later or monitor an external predicate.
- `history`: read the current task's completed conversation history.
- `connected-tools`: discover source control, ticket, document, chat,
  observability, error-tracking, and analytics tools.

Read exactly one adapter under `references/adapters/` when the host is known.
A session that offers `run_subtask` or `delegate_task` is BillyBot: read
`billybot.md`. Read `generic.md` when the host is not known. Adapter files are examples of mappings, not
authority to use a capability the current session does not expose.

When native delegation is unavailable for an `auto` route, execute serially
and preserve the playbook. An unavailable or failed explicit `claude` or
`codex` route must follow the recovery rule below.
When scheduling is unavailable, use bounded waits within the current turn and
report the remaining predicate. When history or a connected-tool category is
unavailable, name the gap instead of inventing evidence.

## Resolve model roles and reasoning

bstack uses semantic roles rather than provider model slugs:

- `fast-code` for narrow mechanical implementation.
- `deep-code` for precise or technically difficult implementation.
- `judgment` for architecture, synthesis, and ambiguous decisions.
- `critic` for independent review.

For `auto` routes, map a configured role only to a model and reasoning level
that the active host confirms are available together. Pass an explicit
reasoning level through the host's native delegation control. For explicit CLI
routes, use the provider model from configuration and start from its
configured reasoning level; the active host's catalog does not need to contain values owned by another CLI.
Omit model and reasoning overrides when their configured value is `auto`. If
the host or CLI rejects a configured model/reasoning combination, report the
error without substitution. Never guess a model slug or reasoning value. Panel
size determines reviewer count; repeated roles still count toward limits.

From birwin93/bstack, MIT.

More from birwin93/bstack