CCB Config

This is the private agentroles.ccb_self built-in CCB configuration skill. It owns .ccb/ccb.config design, editing, validation, reload readiness, and affected-agent reporting. It is not a global inherited skill for non-self agents.

Read references/config-contracts.md before complex edits or reload-impact analysis.

The canonical skill name remains ccb-config; role projection must keep this private role skill from being merged with or exposed as a global inherited same-name skill.

Scope

Allowed:

• Edit project .ccb/ccb.config.
• Design windows topology, agent names, providers, role bindings, managed tool

windows, sidebar layout, workspaces, provider profiles, model/base URL/env-var references, provider command templates, startup args, permission, restore, queue policy, and watch paths.

• Prefer version = 2 [windows] topology for new configs and structural

edits unless the user explicitly asks for compact syntax.

• Update config to reference already configured or user-supplied fallback

provider/model/base URL/profile/env-var references after provider/API failure.

• Run ccb config validate after every edit.
• Run ccb reload --dry-run before reload materialization.
• Execute ccb reload when validation passed, dry-run was reviewed, the plan

is supported, and the user explicitly wants the change materialized.

• Identify affected agents that may need post-reload guarded runtime refresh.

Forbidden:

• Do not edit .ccb/ccb_memory.md, .ccb/agents/<agent>/memory.md, provider

homes, installed role stores, generated memory, lifecycle, lease, runtime, mailbox, provider session, or tmux state.

• Do not execute ccb restart, ccb kill, ccb clear, or ccb repair from

this skill.

• Do not run raw tmux commands.
• Do not infer pane health from config.
• Do not read, print, store, search for, scrape, borrow, or use API keys.

Required Workflow

1. Resolve config source and target. Project config .ccb/ccb.config is the

normal target; user config ~/.ccb/ccb.config is out of scope unless the user explicitly asks.

1. Read current config and classify active shape: compact, hybrid, or

version = 2 [windows] topology.

1. Preserve existing agent names, provider choices, role bindings, worktree

settings, labels, comments, and advanced overrides unless the user asks to change them.

1. Before editing an existing project config, create one dated pre-edit backup

next to it, for example cp .ccb/ccb.config .ccb/ccb.config.bak.$(date +%s). Restore only from the backup created for this edit.

1. Make the smallest disk edit that satisfies the user request.
2. Run:

bash
ccb config validate

1. If validation fails, report the full validation error, do not run reload,

and do not claim recovery is complete. Restore the previous config when a reliable pre-edit copy exists; otherwise stop and ask for the user's preferred correction or rollback.

1. If the user wants the change materialized and validation passed, run:

bash
ccb reload --dry-run

1. Classify dry-run output:

• no change
• reloadable presentation/config change
• role projection/tool change
• topology/provider/startup change with affected agents
• blocked or unsupported reload

1. Execute ccb reload only when gates pass and materialization intent is

explicit.

1. Re-check the mounted daemon graph after reload.
2. Report affected agents and hand post-reload runtime refresh decisions to

ccb-self-recover.

Affected-Agent Rules

Mark an agent as affected when the change may alter:

• provider command or command template
• provider profile or inherited provider configuration
• model, base URL, API route, or env-var reference
• role id, role version, memory, skill, prompt, or tool projection
• workspace path or worktree mode
• startup args, permission, restore, queue policy, or watch paths

Do not restart affected agents from this skill. Return a handoff:

text
Affected agents: ...
Reload status: ...
Needs recover check: yes|no
Reason: ...
Suggested next skill: ccb-self-recover

Role Binding

Use canonical Role Pack ids such as agentroles.archi and agentroles.ccb_self. The project-local agent name remains the ask target.

Recommended binding:

toml
[windows]
ops = "agentroles.ccb_self:codex"

When a local agent name is required, keep provider authority in [windows] and write only the role overlay:

toml
[windows]
ops = "selfops:codex"

[agents.selfops]
role = "agentroles.ccb_self"

Do not repeat [windows]-owned provider, workspace_mode = "inplace", or workspace_mode = "git-worktree" in [agents.<name>] overlays. Treat ccb config validate style warnings as cleanup work before reload.

If validation reports a missing installed role, tell the user to install it:

bash
ccb roles install agentroles.ccb_self

Do not copy role memory or skills into .ccb manually.

Reporting

Summarize:

• config source and disk path
• exact files changed
• validation result
• dry-run result
• whether reload was run
• affected agents
• blocked runtime actions for ccb-self-recover