topics

# Role Profiles And Capacity Skill

Date: 2026-06-24

## Purpose

Define the profile and capacity substrate for dynamic execution nodes:

1. `loop.role_profiles` in `.ccb/ccb.config`, where users declare which
   role/provider/model/thinking/workspace combinations are allowed.
2. A `ccb loop capacity` script protocol that can ensure, inspect, and release
   concrete node capacity by profile name and count.

This document originally described an `orchestrator-capacity` skill. The
current preferred design is topology-driven:

```text
orchestrator proposes topology
  -> ccb loop topology commits desired state
  -> topology reconciler uses role profiles, capacity, lifecycle, and layout
```

The goal is no longer to let `orchestrator` directly request dynamic capacity.
The goal is to keep provider/model/thinking/profile policy declarative while
the topology reconciler safely loads and releases execution agents.

For the broader lifecycle policy shared by frontend, planner, orchestrator,
and execution roles, see
[dynamic-agent-lifecycle-and-skills.md](dynamic-agent-lifecycle-and-skills.md).
This document remains focused on orchestrator execution capacity.

## Design Principle

Separate source policy from runtime instances.

```text
.ccb/ccb.config
  declares allowed loop capacity profiles

orchestrator-topology skill
  proposes graph nodes, edges, artifacts, and release gates

ccb loop topology commit/reconcile
  validates graph intent and commits desired topology

ccb loop capacity ensure/release/status
  remains a lower-level substrate for creating or releasing concrete profile
  instances when the reconciler needs it

runtime layout manager / ccbd / guarded reload
  performs window, pane, provider, service-graph, and runtime-authority mutation
```

`orchestrator` may submit topology intent only through the narrow topology
surface. Capacity and lifecycle surfaces are permission boundaries for scripts
and operators, not the normal orchestrator path.

## Config Shape

Proposed rich TOML shape:

```toml
[loop.capacity]
enabled = true
max_nodes = 4
default_lifetime = "current_round"
name_template = "loop-{loop_id}-{profile}-{index}"
reuse = "prefer_idle"

[loop.role_profiles.coder]
role = "agentroles.coder"
provider = "codex"
model = "gpt-5.5"
thinking = "high"
workspace_mode = "git-worktree"
max_instances = 4
reuse = "prefer_idle"

[loop.role_profiles.checker]
role = "agentroles.checker"
provider = "codex"
model = "gpt-5.5"
thinking = "medium"
workspace_mode = "git-worktree"
max_instances = 4
reuse = "prefer_idle"

[loop.role_profiles.round_checker]
role = "agentroles.round_checker"
provider = "claude"
model = "opus"
thinking = "high"
workspace_mode = "inplace"
max_instances = 1
reuse = "prefer_idle"
```

### `loop.capacity`

Fields:

| Field | Meaning |
| :--- | :--- |
| `enabled` | Whether script-driven loop capacity is allowed. |
| `max_nodes` | Project-wide maximum dynamic execution nodes per loop. Default should be `4`. |
| `default_lifetime` | Default lifetime for generated agents, usually `current_round`. |
| `name_template` | Deterministic generated-agent name pattern. |
| `reuse` | Default reuse policy for idle matching agents. |

Allowed lifetime values:

- `current_round`
- `current_loop`
- `manual_release`

Allowed reuse values:

- `prefer_idle`: reuse idle matching agents before creating new ones.
- `always_new`: create fresh agents unless max capacity blocks it.
- `pinned`: use an existing configured long-lived agent matching the profile.

### `loop.role_profiles.<profile>`

Fields:

| Field | Meaning |
| :--- | :--- |
| `role` | RolePack id, for example `agentroles.coder`. |
| `provider` | CCB provider id. |
| `model` | Optional provider model shortcut, following current agent model rules. |
| `thinking` | Provider-neutral reasoning intensity request. |
| `workspace_mode` | Same semantics as agent workspace mode. |
| `workspace_group` | Optional group/template for shared git-worktree behavior. |
| `startup_args` | Optional advanced provider args; must not conflict with `model` or `thinking`. |
| `provider_profile` | Optional provider profile overlay, same boundary as agent overlays. |
| `max_instances` | Per-profile maximum active generated agents. |
| `reuse` | Optional per-profile override. |

`role`, `provider`, and `max_instances` should be required. `model`,
`thinking`, workspace, startup args, and provider profile fields are optional.

`thinking` is a source-level intent field. Runtime implementation must map it
through provider adapters. If a provider does not support a requested thinking
level, validation should fail visibly instead of silently ignoring it.

## Command Surface

The capacity substrate should expose only three command families. These may be
called by topology reconciliation, by operator diagnostics, or by legacy
compatibility flows.

### Ensure

```bash
ccb loop capacity ensure \
  --loop-id loop_123 \
  --profile coder=2 \
  --profile checker=2 \
  --lifetime current_round \
  --json
```

Responsibilities:

- Parse requested profile counts.
- Validate `loop.capacity.enabled`.
- Validate profile names exist in config.
- Enforce project and per-profile max counts.
- Reuse idle matching agents when allowed.
- Create missing agents through CCB-owned runtime mutation.
- Return ready ask targets or structured blockers.
- Return placement evidence such as `node_id`, `window_name`, or `placement`
  when available; these fields are CCB-owned evidence, not orchestrator input.
- Record capacity ownership under runtime loop state.

Example output:

```json
{
  "status": "ok",
  "loop_id": "loop_123",
  "capacity_ref": ".ccb/runtime/loops/loop_123/capacity.json",
  "agents": [
    {
      "name": "loop-loop_123-coder-1",
      "profile": "coder",
      "role": "agentroles.coder",
      "provider": "codex",
      "lifetime": "current_round",
      "node_id": "node1",
      "placement": {"mode": "execution_node", "window_name": "node-loop_123-node1"},
      "source": "cr