# Pair Colleague > Use when a problem deserves two independent AI solution colleagues exploring alternatives together — the invoking agent coordinates a bounded multi-round discussion between two user-configured harness/model pairs and writes a final decision dossier. - Skill: `chanakya-net/pair-colleague` (Agent Skill) - Install (CLI): `npx skillmds@latest add chanakya-net/pair-colleague` - Raw SKILL.md: https://api.skillmd.com/api/skills/chanakya-net/pair-colleague/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: chanakya-net (https://skillmd.com/u/chanakya-net) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/chanakya-net/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: ```text 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: ```text 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. ```bash 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 ```bash 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: 1. Agent 1 harness → 2. Agent 1 model → 3. Agent 1 effort 4. Agent 2 harness → 5. Agent 2 model → 6. Agent 2 effort Show the user what is actually available before asking: ```bash assets/run-agent.sh --list-agents --detected-only assets/run-agent.sh --list-models ``` Effort must be one of `low|medium|high|xhigh|max|maximum` (`maximum` is normalized to `max`). 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 ```bash 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: ```bash 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 ```bash 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: ```bash 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: 1. `rounds/round-NN/snapshot.md` — the exact frozen context both colleagues saw 2. `rounds/round-NN/agent-1-output.md` 3. `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`: ```markdown # 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. ```bash 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): ```markdown # 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: ```markdown - Coordinator: current invoking agent - Agent 1: - Agent 2: - Completed rounds: - Minimum rounds: - Maximum rounds: - Completion reason: coordinator-accepted | maximum-rounds - Run directory: ``` Read `COMPLETED_ROUNDS`, `MIN_ROUNDS`, `MAX_ROUNDS`, `COMPLETION_REASON`, and `RUN_DIR` from `status` rather than recalling them. ```bash 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 ` 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: ```bash 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.