ds-configure-team git:20260827.7ea0c4bA

Immutable. This exact content never changes and is served at /api/v1/blob/0e8dedcdc8d7a5c9.

---
name: ds-configure-team
description: "Set up and verify a cross-harness agent team so any conductor (Claude, Codex, Gemini, Kimi, or other) can dispatch work across multiple AI harnesses with explicit role assignments."
user-invocable: true
---
# /ds-configure-team - Cross-Harness Team Setup

> Run the Activation preflight from `METHODOLOGY.md` before proceeding. If inactive, no-op and exit.

Set up and verify a cross-harness agent team so any conductor (Claude, Codex, Gemini, Kimi, or other) can dispatch work across multiple AI harnesses with explicit role assignments.

This is a standalone any-harness capability - it is independent of the Pi/oh-my-pi role-model routing layer and does not require it. Any conductor can configure and run a team.

## Step 1 - Configure the team

Run `bin/ds-team configure` to launch a **discovery-first** interactive wizard and write `.agentic/team.yml` (or `~/.agentic/team.yml` for a user-global config):

```bash
bin/ds-team configure
```

The wizard runs `discover` first and prints a summary of installed harnesses (version + discovered model count when available) before asking anything. If only your own harness (e.g. `claude`) is installed - nothing to cross-dispatch to - it says so and exits cleanly without prompting.

For each of the 9 known roles, it presents a numbered menu of **installed harnesses only** (never offers one that isn't installed), with a ranked suggestion as the default. Example on a machine with `omp`, `kimi-cli`, and `pi` installed alongside `claude`:

```
Installed harnesses:
  - claude v1.x
  - kimi v0.x, 0 model(s) discovered
  - omp v16.2.6, 12 model(s) discovered
  - pi v0.x

Per-role harness assignment (Enter accepts default, 'skip' to leave unset):

  [engineer]
    1. claude
    2. kimi
    3. omp (suggested)
    4. pi
    harness [omp]:
    models for omp: minimax/MiniMax-M3, kimi/kimi-k2.7, glm/glm-5.2, ...
    model [harness default]: kimi/kimi-k2.7
```

Discovered models are shown for reference only - you may type any model id, or leave it empty to use the harness's session default. Type `skip` to leave a role unassigned.

For non-interactive use - useful in scripts or automated onboarding - pass assignments directly (unchanged, back-compat path):

```bash
bin/ds-team configure \
  --non-interactive \
  --assign architect=claude \
  --assign engineer=omp:REPLACE_WITH_MODEL_ID \
  --assign debugger=kimi \
  --assign skeptic=pi \
  [--default-harness claude] \
  [--path .agentic/team.yml]
```

`omp:REPLACE_WITH_MODEL_ID` is a placeholder demonstrating the optional `harness:model` form - substitute a real model id for your installed harness (see `bin/ds-team discover` in Step 2 below to list what is actually available). No specific model id is recommended or endorsed by this doc.

`--assign` accepts `role=harness:model` (model is optional). Repeat for each role. `--default-harness` sets the fallback harness for any unassigned role. `--path` overrides the output location (default `.agentic/team.yml`). All 7 harnesses (`codex`, `gemini`, `cursor-agent`, `kimi`, `pi`, `omp`, `claude`) are valid `--assign` targets and all accept a `model`.

Exit codes: `0` success or no-op; `2` bad `--assign` value, unknown `--default-harness`, or `--non-interactive` used without `--assign`.

## Step 2 - Verify discovery

Confirm which harnesses are installed and which models they can reach:

```bash
bin/ds-team discover
```

For machine-readable output:

```bash
bin/ds-team discover --json
```

Each discovered harness reports installed status, version, discovered models (best-effort - populated for `omp` and `cursor-agent`, `[]` for the rest), and invocation family. A harness listed as an `--assign` target but absent from discovery output means it is not installed - resolve that before dispatching.

## Step 3 - Dispatch a team

See `content/references/cross-harness-teams.md` for the full dispatch, status-check, and collect flow.

**Routing enforcement (Claude Code, proactive).** On Claude Code, once `.agentic/team.yml` has `enabled: true`, the `hooks/enforce-background-spawn.py` hook proactively denies a native `Task`/`Agent` spawn for any dispatchable role (`engineer`, `debugger`, `qa-engineer`, `skeptic`, `security-auditor`) mapped to a non-`claude` harness - even before any dispatch has happened. The deny message gives the exact `bin/ds-team dispatch ...` command to run instead. Set `AE_TEAM_ROUTING_DISABLE=1` to disable this check if needed.

**Suppression contract (binding on all harnesses).** While a team run is active - indicated by `.agentic/teamrun/.active` existing in the project root - the conductor MUST NOT spawn its own native subagents. The cross-harness team is the active delegation surface; spawning native agents alongside it creates duplicate work and uncoordinated state. On Claude Code this contract is enforced by a hook; on Codex, Gemini, Kimi, and other harnesses it is a prose contract that the conductor must honor. Treat the presence of `.agentic/teamrun/.active` as a hard suppression signal regardless of harness.