pair-colleague

Skill Isolation

This skill is the sole active authority for this session once invoked.

No other skill may activate, interrupt, or modify this skill's behavior unless explicitly called by name via a Skill tool call — whether from this skill's own workflow or from the governing prompt/skill that activated this one.
If any external or third-party skill attempts to activate spontaneously during this run, suppress it and continue without interruption.
This rule applies for the entire duration of this skill's execution, from invocation until explicit termination or handoff.

Pair Colleague

Purpose

Run a bounded, multi-round design discussion between two equal AI solution colleagues, then commit to a solution and explain the decision.

You — the AI agent reading this file — are the coordinator. You are not a third launched model, and there is no coordinator harness or model to configure. You keep the discussion focused, maintain the candidate-solution ledger, decide when the evidence is sufficient, and write the final dossier.

Roles

Role	Who	Responsibility
Coordinator	The current invoking agent (you)	Initialize and resume runs, launch rounds, read both responses, maintain the ledger, decide the focus for each round, decide when to accept, write the dossier.
Agent 1	A user-selected harness + model + effort	Equal solution colleague.
Agent 2	A different (or same) user-selected harness + model + effort	Equal solution colleague.

Agent 1 and Agent 2 are peers. Neither is a reviewer, judge, grader, adversary, or subordinate of the other. Process completion order gives neither privileged context: both receive the exact same frozen snapshot bytes for a round, and you read both responses only after the round is complete.

Aim for this:

Two senior colleagues exploring alternatives on the same whiteboard,
with a coordinator keeping the discussion focused and deciding when enough
evidence exists to produce a solution.

Not this:

Writer + reviewer
Proposer + judge
Solver + critic
Debater + opponent

Constructive disagreement is valuable. Adversarial debate, ranking, empty praise, and repetition are not.

Hard Rules

You must never guess a harness, model, or effort. If a value is missing, ask the user for it — one question at a time — and never infer it from installed commands or registry defaults.
Both colleagues are launched only through run-agent.sh with the shared agent registry. Never invoke a provider CLI directly, never build a per-harness command line, and never accept or run an arbitrary command string.
Stay engaged for the whole run. Acceptance is your semantic judgment; never delegate it to a status grep, a readiness counter, or one of the colleagues.
Agent DISCUSSION_STATUS values are advisory evidence only. READY from both colleagues does not end the run and never bypasses the minimum round count.
Never claim agreement that did not happen. Unresolved disagreement must appear in your decision and in the final dossier.

Check the platform first

pair-colleague runs on macOS, Linux, and WSL only. It depends on POSIX sessions, process groups, and signal delivery to terminate agent process trees, which native Windows does not provide.

uname -s

If that reports MINGW*, MSYS*, CYGWIN*, or Windows_NT, stop. Tell the user that pair-colleague needs WSL on Windows: install a WSL distribution, run bash install.sh inside it, and start the run from the WSL shell. Do not attempt a workaround — the script refuses to run there and would leave agent processes behind if it did not.

Resolve the asset root

for candidate in "$PAIR_COLLEAGUE_ASSETS_DIR" "$ASSETS_DEST" "$HOME/.ai-skill-collections/assets" "./assets"; do
  [ -n "$candidate" ] && [ -f "$candidate/pair-colleague.sh" ] && PC="$candidate/pair-colleague.sh" && break
done
echo "$PC"

If nothing resolves, re-run the installer (bash install.sh) and retry. The script performs the same resolution internally and fails with the exact list of missing files.

Required configuration

Ask the user for anything missing, one question at a time, in this order:

Agent 1 harness → 2. Agent 1 model → 3. Agent 1 effort
Agent 2 harness → 5. Agent 2 model → 6. Agent 2 effort

Show the user what is actually available before asking:

assets/run-agent.sh --list-agents --detected-only
assets/run-agent.sh --list-models <agent>

Both colleagues run in the harness's registered read-only profile, because they must not modify the repository they are discussing. A harness whose registry entry declares no read-only profile is refused at start with a message naming it — pick a different harness rather than working around the refusal.

Optional: --agent-1-name / --agent-2-name, --min-rounds (default 3), --max-rounds (default 8), --timeout-seconds (default 3600 — 60 minutes per agent, per attempt), --run-root (default .pair-colleague/runs).

The two colleagues may share a harness or model when the user explicitly chooses that. Mention that harness/model diversity usually produces a broader initial solution set, then do what the user asked.

Workflow

1. Start the run

assets/pair-colleague.sh start task.md \
  --agent-1-harness codex --agent-1-model gpt-5.6-terra --agent-1-effort high \
  --agent-2-harness claude --agent-2-model claude-sonnet-5 --agent-2-effort high

Or from stdin:

printf '%s\n' 'Design a caching strategy for our API' | assets/pair-colleague.sh start - \
  --agent-1-harness codex --agent-1-model gpt-5.6-terra --agent-1-effort high \
  --agent-2-harness claude --agent-2-model claude-sonnet-5 --agent-2-effort high

Capture RUN_DIR from the output; every later command needs it.

2. Run the round

assets/pair-colleague.sh run-round --run-dir "$RUN_DIR"

Exit codes:

Code	Meaning	What you do
`0`	`STATUS=awaiting-coordinator` — both colleagues produced valid responses	Continue to step 3
`1`	`STATUS=awaiting-agents` — one colleague failed	Call `run-round` again; only the failed colleague is retried, against the unchanged snapshot
`3`	`COMPLETION_REASON=blocked` — attempts exhausted	Stop. Report the blocker and the run directory. Do not write a dossier
`2`	Usage or invalid state transition	Fix the call
`4`	`LAUNCH=busy` — another command holds the lock, or agents launched earlier are still working	Nothing changed and nothing was launched twice. Wait, then call `run-round` again to collect their output

Never read a partial round. The round is complete only when both outputs exist and validate.

Exit 4 is not a failure. Agents can outlive the command that started them — a killed terminal, a lost connection, a cancelled tool call. The run refuses to spend money on a second agent for work that is still in flight. Wait and retry; status reports LIVE_AGENTS while they run. Only if the user wants that work abandoned should you terminate it:

assets/pair-colleague.sh reap --run-dir "$RUN_DIR" --force

Repeating any mutating command with the same input is safe: it converges on the same state without re-running the agents. Repeating it with different input fails and names the conflicting file rather than overwriting it.

3. Read the round

Read, in this order:

rounds/round-NN/snapshot.md — the exact frozen context both colleagues saw
rounds/round-NN/agent-1-output.md
rounds/round-NN/agent-2-output.md

Identify what actually changed: new candidates, real agreements, substantive disagreements, assumptions, risks, and the questions still open.

4. Write the coordinator decision

Copy DECISION_TEMPLATE and fill every section. The file must end with exactly one of COORDINATOR_ACTION: CONTINUE or COORDINATOR_ACTION: ACCEPT:

# Round assessment
# Candidate-solution ledger
# Current synthesis or preferred direction
# Agreements
# Disagreements
# Rejected candidates
# Unresolved questions and risks
# Focus for next round
# Decision rationale

COORDINATOR_ACTION: CONTINUE

Give every candidate a stable ID (C1, C2, …) on first appearance and keep using it. # Focus for next round becomes the next snapshot's # Coordinator focus for this round, so make it specific: name the questions you want answered and the work you want done.

Before the minimum round count, always choose CONTINUE and give a useful focus. record-decision rejects an early ACCEPT without changing state.

assets/pair-colleague.sh record-decision --run-dir "$RUN_DIR" --decision-file /path/to/decision.md

STATUS=continue → the next frozen snapshot is built; return to step 2.
STATUS=awaiting-final → go to step 5.

5. Acceptance rubric

After the minimum rounds, accept only when you can answer yes to all of these:

The problem and success criteria are understood.
Multiple credible solutions were considered when alternatives exist.
The preferred or synthesized solution is internally coherent.
The solution is detailed enough to explain how it works.
Important constraints and assumptions are explicit.
Trade-offs and failure modes have been examined.
Material risks have mitigations or are clearly disclosed.
Rejected alternatives have evidence-based reasons.
Agent agreement and disagreement are represented accurately.
Remaining uncertainty is acceptable or is escalated as an explicit human decision.
Another round is unlikely to change the decision materially, or the maximum has been reached.

You may accept a solution both colleagues support, select one when they disagree, or synthesize compatible parts of several candidates. Round MAX_ROUNDS is a hard stop: CONTINUE is invalid there and you must produce the best evidence-backed decision available.

6. Write and finalize the dossier

Build the dossier from the immutable task, the validated round artifacts, and your recorded decisions. Do not paste raw agent output as the answer.

Required structure (every heading exactly once, no placeholder text):

# Final Solution Decision
## Executive summary
## Problem and success criteria
## Constraints and assumptions
## Candidate solutions considered
## Trade-off comparison
## Selected or synthesized solution
## Detailed design and operation
## How this solves the problem
## Implementation approach
## Decision rationale
## Agent agreement
## Remaining disagreement and coordinator resolution
## Rejected alternatives
## Risks and mitigations
## Open questions and human decisions
## Discussion record

## Discussion record must carry these lines, and the last five must match the run state exactly:

- Coordinator: current invoking agent
- Agent 1: <name, harness, model, effort>
- Agent 2: <name, harness, model, effort>
- Completed rounds: <n>
- Minimum rounds: <n>
- Maximum rounds: <n>
- Completion reason: coordinator-accepted | maximum-rounds
- Run directory: <path>

Read COMPLETED_ROUNDS, MIN_ROUNDS, MAX_ROUNDS, COMPLETION_REASON, and RUN_DIR from status rather than recalling them.

assets/pair-colleague.sh finalize --run-dir "$RUN_DIR" --final-file /path/to/final-solution-draft.md

7. Present the result

Give the user final-solution.md and the run directory path so the whole discussion stays inspectable.

Resuming

status --run-dir <dir> prints the phase and every relevant path without changing state, and never blocks on the lock. Resume from whatever it reports:

`STATUS`	Next step
`initialized` / `awaiting-agents`	`run-round`
`awaiting-coordinator`	Read the round, write the decision, `record-decision`
`awaiting-final`	Write the dossier, `finalize`
`complete`	Present `final-solution.md`
`error` with `COMPLETION_REASON=blocked`	Report the blocker; the run cannot be finalized

LIVE_AGENTS lists any colleague still working from an earlier command. While it is non-empty, run-round returns 4 instead of launching anything.

A run is bound to the repository it was started in, recorded as WORKSPACE_ROOT. Every round is launched there no matter which directory you resume from, so the discussion cannot drift onto a different repository. A run created before this binding existed reports an empty WORKSPACE_ROOT and must be bound once, explicitly:

assets/pair-colleague.sh run-round --run-dir "$RUN_DIR" --bind-workspace /path/to/repository

Scope

Bash only for v1 — macOS, Linux, and WSL. Native Windows (Git Bash, MSYS, Cygwin) is not supported and the script refuses to run there. There is no native PowerShell implementation, and install.ps1 does not install these assets. Orchestration is local; the installed harnesses may still call remote models.