Smux Compozy Pairing

---
name: smux-compozy-pairing
description: Orchestrates an interactive tmux-based pairing workflow where the current agent acts as an autonomous orchestrator, Codex authors the Compozy PRD/TechSpec/tasks, Claude Code challenges assumptions over tmux-bridge, and the orchestrator advances the run through compozy start without a human approval loop. Use when a feature needs collaborative TUI-driven spec and task generation. Don't use for headless automation, single-agent drafting, or flows that call codex exec or claude -p.
---

# Smux Compozy Pairing

## Procedures

**Step 1: Validate inputs and build the launch plan**
1. Require a feature name that resolves to `.compozy/tasks/<feature-name>/`.
2. Execute `eval "$(python3 .agents/skills/smux-compozy-pairing/scripts/render-session-plan.py --feature-name "<feature-name>" --repo-root "$PWD")"` to load the emitted shell assignments into the current shell.
3. Confirm that `tmux`, `tmux-bridge`, `codex`, `claude`, and `compozy` are available in `PATH`.
4. Read `references/runtime-contract.md` before launching the worker TUIs.
5. Treat `"$CODEX_LAUNCH"` and `"$CLAUDE_LAUNCH"` as authoritative. The helper already injects a Codex workflow overlay via `developer_instructions` and a Claude workflow overlay via `--append-system-prompt-file`.
6. Prefer the shell wrappers under `scripts/` when you need a concrete command string:
   - `scripts/print-session-command.sh --feature-name "$FEATURE_NAME" --repo-root "$REPO_ROOT" --kind codex-launch`
   - `scripts/print-session-command.sh --feature-name "$FEATURE_NAME" --repo-root "$REPO_ROOT" --kind claude-launch`
   - `scripts/print-session-command.sh --feature-name "$FEATURE_NAME" --repo-root "$REPO_ROOT" --kind start`
   - `scripts/run-codex-worker.sh --feature-name "$FEATURE_NAME" --repo-root "$REPO_ROOT"`
   - `scripts/run-claude-worker.sh --feature-name "$FEATURE_NAME" --repo-root "$REPO_ROOT"`
   - `scripts/run-compozy-start.sh --feature-name "$FEATURE_NAME" --repo-root "$REPO_ROOT"`

**Step 2: Bootstrap the tmux workspace**
1. If `$TMUX` is empty, execute `tmux new-session -s "$SESSION_NAME" -c "$REPO_ROOT"` and continue inside that attached session before using `tmux-bridge`.
2. Rename the active window with `tmux rename-window "$WINDOW_NAME"`.
3. Run `tmux-bridge doctor` after entering the tmux session and before sending the first message.
4. Label the current pane with `tmux-bridge name "$(tmux-bridge id)" "$ORCHESTRATOR_LABEL"`.
5. Create two worker panes rooted at `"$REPO_ROOT"` and rebalance the layout:
   - `CODEX_PANE="$(tmux split-window -hPF '#{pane_id}' -c "$REPO_ROOT")"`
   - `CLAUDE_PANE="$(tmux split-window -vPF '#{pane_id}' -c "$REPO_ROOT")"`
   - `tmux select-layout tiled`
6. Label the worker panes with `tmux-bridge name "$CODEX_PANE" "$CODEX_LABEL"` and `tmux-bridge name "$CLAUDE_PANE" "$CLAUDE_LABEL"`.
7. Resolve the worker launch commands through the shell wrapper so you cannot accidentally drop a required flag:
   - `CODEX_CMD="$("$SKILL_ROOT/scripts/print-session-command.sh" --feature-name "$FEATURE_NAME" --repo-root "$REPO_ROOT" --kind codex-launch)"`
   - `CLAUDE_CMD="$("$SKILL_ROOT/scripts/print-session-command.sh" --feature-name "$FEATURE_NAME" --repo-root "$REPO_ROOT" --kind claude-launch)"`
8. Launch the interactive workers with raw tmux pane control:
   - `tmux send-keys -t "$CODEX_PANE" -l -- "$CODEX_CMD"`
   - `tmux send-keys -t "$CODEX_PANE" Enter`
   - `tmux send-keys -t "$CLAUDE_PANE" -l -- "$CLAUDE_CMD"`
   - `tmux send-keys -t "$CLAUDE_PANE" Enter`
9. Never launch `codex exec`, `codex review`, `claude -p`, or `claude --print` in this workflow.
10. Use raw `tmux` only for pane lifecycle and TUI bootstrap. Once the workers are running, route every orchestrator-to-worker and worker-to-worker exchange through `tmux-bridge`.

**Step 3: Brief the workers**
1. Read `assets/boot-prompts.md`.
2. Send the Codex boot prompt to `"$CODEX_LABEL"` with `tmux-bridge message`.
3. Send the Claude boot prompt to `"$CLAUDE_LABEL"` with `tmux-bridge message`.
4. Respect the `smux` read guard on every interaction: read, message or type, read again, then press Enter.
5. Ensure the boot prompts include literal `tmux-bridge read`, `tmux-bridge message`, and `tmux-bridge keys` command sequences for Codex-to-Claude, Claude-to-Codex, and worker-to-orchestrator replies.
6. Keep Codex as the sole writer of `_techspec.md`, ADRs, `_tasks.md`, and `task_*.md` unless the user explicitly reassigns ownership.
7. Treat the orchestrator as an autonomous agent, not as a human relay. Routine PRD, TechSpec, and task-breakdown checkpoints must be resolved inside the session unless the source requirements are truly contradictory or missing.
8. Use the launch-time prompt overlays for stable role behavior and use the boot prompts only for run-specific context such as feature slug, pane labels, and exact phase ordering.

**Step 4: Resolve the PRD gate**
1. Inspect `"$PRD_PATH"` before starting the workflow.
2. If `"$PRD_PATH"` already exists, treat it as the active PRD and move to the TechSpec phase.
3. If `"$PRD_PATH"` does not exist, default to instructing Codex to run `"$PRD_COMMAND"` before any TechSpec work unless the original user request explicitly said to skip PRD creation.
4. Require Codex to consult Claude directly over `tmux-bridge` for requirement pressure, scope control, and checkpoint rehearsal during the PRD phase.
5. Only escalate beyond the session if the source requirements are contradictory or a business-critical choice truly cannot be inferred from the prompt, repository context, existing artifacts, or the pair's recommendations.
6. When `cy-create-prd` reaches a required checkpoint, have Codex message `"$ORCHESTRATOR_LABEL"` with the exact question plus its current recommendation.
7. Resolve that checkpoint inside the session. The orchestrator should synthesize the original user goal, repository context, existing PRD/ADR state, and Claude's critique, then send the decision straight back to Codex.
8. If the choice is already strongly constrained by accepted PRD answers, existing ADRs, or explicit non-goals, carry it forward directly or answer with a single-option confirmation instead of reopening it as a fresh menu.
9. Do not advance until either:
   - `"$PRD_PATH"` exists and Codex confirms the PRD was saved, or
   - the original user request explicitly told the run to skip PRD creation.

**Step 5: Run the TechSpec phase**
1. Instruct Codex to run `"$TECHSPEC_COMMAND"` only after the PRD gate is resolved.
2. Require Codex to consult Claude directly over `tmux-bridge` for design challenges, trade-off checks, and question rehearsal.
3. Do not reopen technical choices that are already effectively closed by the approved PRD, accepted ADRs, or explicit non-goals as a fresh multi-option vote.
4. For those already-constrained choices, have Codex either carry the decision forward directly or ask the orchestrator for a single-option confirmation if a checkpoint is still useful.
5. When `cy-create-techspec` reaches a required checkpoint, have Codex message `"$ORCHESTRATOR_LABEL"` with the exact question plus its current recommendation.
6. Resolve that checkpoint inside the session. The orchestrator may briefly pressure-test the recommendation with Claude, but it should not stop for human approval in the normal case.
7. Forward the orchestrator's answer back to Codex and let the TechSpec flow continue.
8. Do not advance until `"$TECHSPEC_PATH"` exists and Codex confirms the TechSpec was saved.

**Step 6: Run the task phase**
1. Instruct Codex to run `"$TASKS_COMMAND"` only after the TechSpec is approved and saved.
2. Apply the same orchestrator-owned checkpoint loop for the task-breakdown review required by `cy-create-tasks`.
3. Re-run `"$VALIDATE_COMMAND"` after Codex reports success, even if `cy-create-tasks` already validated the task set internally.
4. Do not advance until validation exits `0` and `"$TASKS_DIR"` contains `_tasks.md` plus at least one `task_*.md`.

**Step 7: Execute the workflow**
1. Run `"$START_COMMAND"` from the orchestrator pane after task validation passes.
2. Keep the execution runtime aligned with Codex: `--ide codex --model gpt-5.5 --reasoning-effort xhigh`.
3. Treat the generated start wrapper as authoritative because it strips interactive Codex/tmux session variables such as `CODEX_THREAD_ID`, `TMUX`, and `TMUX_PANE` before launching `compozy start`.
4. Let the run finish through the normal Compozy cockpit or the output mode already encoded in the command.
5. Report the resulting `compozy start` state back to the human user.

## Error Handling
* If `tmux-bridge doctor` fails, fix tmux connectivity before creating panes or sending messages.
* If a worker pane exits or never reaches its TUI prompt, relaunch only that pane and resend its boot prompt.
* If Claude cannot run `tmux-bridge` because Bash is blocked by its permission mode, relaunch the Claude pane with `claude --model opus --permission-mode bypassPermissions`, then resend the Claude boot prompt.
* If Codex or Claude receives a `[tmux-bridge from:...]` message, reply to the pane ID from the header instead of answering locally.
* If the current orchestrator pane is only a passive shell and cannot resolve checkpoints autonomously, stop and relaunch the workflow from an actual agent-controlled tmux pane before continuing.
* If Codex attempts to shortcut the workflow with `codex exec`, `claude -p`, or another headless command, stop, relaunch the worker interactively, and restart the current phase.
* If either worker discusses the design locally without using `tmux-bridge` for peer communication, resend the boot prompt with the explicit command snippets from `assets/boot-prompts.md` and restart that exchange.
* If the PRD gate reveals that no PRD exists and the original user request did not explicitly waive PRD creation, never hand-write `_prd.md`. Route the work through `"$PRD_COMMAND"` instead.
* If Codex reopens a choice that is already constrained by accepted PRD answers, existing ADRs, or explicit non-goals as a fresh A/B/C/D menu, stop that checkpoint and restate it as either carry-forward context or a single-option confirmation.
* If a checkpoint genuinely cannot be resolved from the prompt, repository context, existing artifacts, and Claude/Codex recommendations, ask the human user one targeted question, keep the panes alive, and continue the same phase after the answer arrives.