diff --git a/.agents/skills/start-agent-team/SKILL.md b/.agents/skills/start-agent-team/SKILL.md new file mode 100644 index 0000000..66d2149 --- /dev/null +++ b/.agents/skills/start-agent-team/SKILL.md @@ -0,0 +1,79 @@ +--- +name: start-agent-team +description: Start and coordinate project-focused multiagent swarm teams using this repository's tmux orchestrator, and show read-only live orchestrator output in the Codex desktop UI. Use only when the user explicitly asks for an agent team, swarm team, worker team, orchestrator, or multiagent session for a coding project or repository. +--- + +# Start Agent Team + +## Launch + +Use this repository's `launch.sh` to start a tmux session with one orchestrator +window. The orchestrator creates workers and long-running subagents for the +target project. + +This skill is only for tmux-backed multiagent teams. Standalone agent or +subagent requests should use native Codex UI agents instead. + +Default to a clean, non-attached launch: + +```bash +REPO_ROOT/launch.sh --session SESSION --root PROJECT_ROOT --no-attach +``` + +- Use `multiagent-` unless the user supplies a session name. +- Use the user's named project root, or the current git root for "this project." +- Add `--resume` only for explicit recovery. +- Keep `ORCHESTRATOR_CLI=codex` unless the user requests another backend. +- Do not overwrite an existing tmux session. + +If the user supplied a task, inspect the orchestrator pane before sending it: + +```bash +tmux capture-pane -t "SESSION:orchestrator" -p -S -200 +tmux send-keys -t "SESSION:orchestrator" "TOP_LEVEL_TASK" Enter +``` + +Do not send input while the orchestrator is starting, blocked on authentication, +or busy. Keep the task high level and let the orchestrator decompose it. + +## Live Codex UI view + +After launch and task delivery, prefer a live read-only terminal view when the +Codex desktop terminal-opening tool is available: + +1. Start the follower in PTY mode (`tty: true`) with a short yield. Keep the + returned running terminal `session_id`. + + ```bash + REPO_ROOT/.agents/skills/start-agent-team/scripts/follow_orchestrator.sh \ + --session SESSION --root PROJECT_ROOT + ``` + +2. Open that terminal in Codex with `codex_app__open_in_codex`, using target + `{ type: "terminal", sessionId: "SESSION_ID" }`. Prefer bottom placement + unless the user requested another layout. +3. Tell the user the panel is a live, read-only orchestrator view. Do not mirror + its entire transcript into commentary. + +The follower validates the project root and attaches a tmux client with both +`read-only` and `ignore-size` flags. It cannot send input to or resize the +orchestrator or worker panes. Do not start it without a PTY or wait +synchronously for it to exit. + +If the terminal-opening tool is unavailable, show a bounded snapshot instead: + +```bash +tmux list-windows -t SESSION -F '#I:#W' +tmux capture-pane -t "SESSION:orchestrator" -p -S -220 +``` + +Treat the orchestrator pane as the delegation boundary. Ask the orchestrator to +spawn, poll, inspect, or finalize its agents; do not drive those agents directly +unless the user explicitly requests bypassing the orchestrator. + +## Safety + +- Do not translate a standalone subagent request into a tmux team. +- Do not delete `PROJECT_ROOT/.multiagent`; it stores durable state. +- Do not kill or replace an existing session with the same name. +- Keep outside-root writes subject to the multiagent write policy. diff --git a/.agents/skills/start-agent-team/agents/openai.yaml b/.agents/skills/start-agent-team/agents/openai.yaml new file mode 100644 index 0000000..cb807c4 --- /dev/null +++ b/.agents/skills/start-agent-team/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Start Agent Team" + short_description: "Launch teams with live orchestrator output" + default_prompt: "Use $start-agent-team to start an agent team and show its live orchestrator output in Codex." diff --git a/.agents/skills/start-agent-team/scripts/follow_orchestrator.sh b/.agents/skills/start-agent-team/scripts/follow_orchestrator.sh new file mode 100755 index 0000000..ed05f62 --- /dev/null +++ b/.agents/skills/start-agent-team/scripts/follow_orchestrator.sh @@ -0,0 +1,65 @@ +#!/usr/bin/env bash +set -euo pipefail + +SESSION="" +ROOT="" + +usage() { + cat <<'USAGE' +Usage: follow_orchestrator.sh --session NAME --root DIR + +Attach a read-only tmux client to the orchestrator window. Run this helper in +a PTY-backed Codex terminal session so the live pane can be opened in the +Codex desktop UI. Keystrokes cannot control or resize the tmux session. +USAGE +} + +die() { + echo "follow-orchestrator: $*" >&2 + exit 1 +} + +while [[ $# -gt 0 ]]; do + case "$1" in + --session) + SESSION="${2:-}" + shift 2 + ;; + --root) + ROOT="${2:-}" + shift 2 + ;; + -h|--help) + usage + exit 0 + ;; + *) + die "unknown argument: $1" + ;; + esac +done + +[[ -n "$SESSION" ]] || die "--session NAME is required" +[[ -n "$ROOT" ]] || die "--root DIR is required" +[[ -d "$ROOT" ]] || die "root does not exist or is not a directory: $ROOT" +command -v tmux >/dev/null 2>&1 || die "missing required command: tmux" +tmux has-session -t "$SESSION" 2>/dev/null || die "missing tmux session: $SESSION" +tmux list-windows -t "$SESSION" -F '#W' | grep -Fxq orchestrator || \ + die "session has no orchestrator window: $SESSION" + +if [[ -z "${TERM:-}" || "${TERM:-}" == "dumb" ]]; then + if infocmp xterm-256color >/dev/null 2>&1; then + export TERM=xterm-256color + else + die "terminal does not support a live tmux view" + fi +fi + +ROOT="$(cd "$ROOT" && pwd -P)" +pane_root="$(tmux display-message -p -t "$SESSION:orchestrator" '#{pane_current_path}')" +[[ -d "$pane_root" ]] || die "orchestrator pane path is not a directory: $pane_root" +pane_root="$(cd "$pane_root" && pwd -P)" +[[ "$pane_root" == "$ROOT" ]] || \ + die "orchestrator root mismatch: expected $ROOT, found $pane_root" + +exec tmux attach-session -r -f ignore-size -t "$SESSION:orchestrator"