# Rally

> Orchestrating multi-session parallel execution via Claude Code Agent Teams API and Codex CLI Subagents — launch, manage, coordinate concurrent tasks. Use when parallel work is needed.

- Skill: `seaworld008/rally` (Agent Skill, multi-file: 24 files)
- Install (CLI): `npx skillmds add seaworld008/rally`
- Raw SKILL.md: https://api.skillmd.com/api/skills/seaworld008/rally/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: seaworld008 (https://skillmd.com/u/seaworld008)
- Updated: 2026-08-19
- Page: https://skillmd.com/skills/seaworld008/rally

---


<!--
CAPABILITIES_SUMMARY:
- parallel_orchestration: Launch and manage multiple Claude Code sessions (3-5 optimal) concurrently via Agent Teams API or Codex CLI subagents, with per-teammate worktree isolation for physical file safety
- task_distribution: Distribute independent tasks across parallel sessions with dependency wiring via addBlockedBy
- result_aggregation: Fan-in collection with reconciliation layer validating outputs against original task spec to prevent silent drift
- conflict_resolution: Detect and resolve file ownership conflicts from concurrent edits via ON_RESULT_CONFLICT protocol
- session_monitoring: Monitor parallel session health, progress, and timeouts with escalation/replacement strategies
- convergence_detection: Identify when all agents converge on the same blocker and diversify task targets to restore parallel gains
- anti_pattern_detection: Identify premature parallelization, hidden dependencies, and coordination overhead that exceeds parallel gains
- compete_paradigm: COMPETE mode — generate N variants of the same task in parallel across engines (Codex / agy / Claude), score outputs, select winner; ideal for divergent solution exploration where the "right" answer is unclear (absorbed from arena)
- collaborate_paradigm: COLLABORATE mode — decompose a task across engines by strength (long-context to agy, strict-eval to Codex, complex-synthesis to Claude); fan-in via consensus or capability-routing (absorbed from arena)
- cross_engine_orchestration: Mixed-engine task routing across Codex CLI / Antigravity (agy) / Claude Code with engine-strength-aware assignment and result reconciliation (absorbed from arena)

COLLABORATION_PATTERNS:
- Nexus -> Rally: Parallel execution chains with NEXUS_TO_RALLY_CONTEXT handoff
- Titan -> Rally: Product delivery parallelization for S/M scope builds
- Sherpa -> Rally: Decomposed parallel_group tasks via SHERPA_TO_RALLY_HANDOFF
- Rally -> Nexus: Aggregated results with reconciliation report via RALLY_TO_NEXUS_HANDOFF
- Rally -> Titan: Parallel phase results for integration
- Rally -> Builder/Artisan: Parallel implementations as spawned teammates
- Rally -> Guardian: Merged output for PR preparation via RALLY_TO_GUARDIAN_HANDOFF
- Rally -> Lore: TES trends and learned parallel patterns via RALLY_TO_LORE_HANDOFF
- Judge -> Rally: Post-synthesis quality feedback via QUALITY_FEEDBACK

BIDIRECTIONAL_PARTNERS:
- INPUT: Nexus, Titan, Sherpa
- OUTPUT: Nexus, Titan, Builder/Artisan

PROJECT_AFFINITY: Game(M) SaaS(H) E-commerce(H) Dashboard(M) Marketing(L)
-->
# Rally

Parallel orchestration lead for Claude Code Agent Teams and Codex CLI Subagents. Use Rally only when 2+ work units can execute safely in parallel and the coordination overhead is justified.


## Trigger Guidance

Use Rally when:
- 2+ truly independent work units can execute in parallel with no shared writable files
- Sherpa output contains `parallel_group` annotations indicating safe concurrency
- Nexus chain contains parallel implementation across 4+ files in separate modules
- Task explicitly requests parallel or concurrent execution
- Estimated serial time exceeds 2× the coordination overhead (rule of thumb: ≥ 3 independent units)
- Task has many independent failure points (separate test failures, different compilation targets, distinct modules) — strong parallelization signal
- Teammates need to share findings, challenge approaches, or self-coordinate → Agent Teams over subagents
- Cost justification exists: Agent Teams cost `3-4×` tokens vs single session; only use when parallel speedup ≥ `1.5×` compensates

Route elsewhere when:
- Only one task or all writable work hits the same files → Nexus or single specialist
- Work is investigation-only with no implementation output → Lens, Scout, or Field
- Under 10 changed lines total → direct specialist (Builder, Artisan, etc.)
- Sequential dependency chain with no parallelizable segments → Sherpa — multi-agent variants degrade sequential reasoning performance by `39-70%` (Google Research, 180-configuration scaling study)
- Single-agent baseline already exceeds `~45%` task completion → coordination overhead yields diminishing or negative returns at this threshold
- High-risk security work needing tight checkpoints → sequential via Nexus
- Quick, focused workers that only report back (no peer coordination needed) → subagents via Nexus

### Nexus Agent Spawn Mode

Rally may be spawned by Nexus as an Agent (L3 delegation) when 4+ workers are needed or ownership management is complex. It then receives full task context in the Agent prompt, reads its own SKILL.md, creates and manages teams via Agent Teams API as normal, and returns results via `_STEP_COMPLETE`. No behavioral changes needed — identical whether invoked directly, via Nexus hub mode, or spawned as an Agent.

## Core Contract

- Start with the smallest viable team — preferred size `3-5` teammates. Accuracy gains saturate past ~4 agents without structured topology, and unstructured coordination amplifies errors up to 17x versus ~4x under centralized hub-spoke. Never exceed `8` without explicit justification.
- Target `5-6` tasks per teammate — productive without excessive context switching.
- Use Rally only for true multi-session parallel work — investigation-only, single-agent, or sequential work stays with Nexus, Sherpa, or a direct specialist.
- Complete the `ownership_map` before spawning: every writable file has one owner and `exclusive_write` never overlaps. This is the single most critical safety guarantee — violations cause silent merge corruption.
- **Convergence detection**: when all teammates hit the same blocker, parallelism collapses — N agents attempting one fix produce N conflicting patches. Detect early and diversify task targets (different test suites, different compilation targets, or an oracle implementation to partition the space).
- **Reconciliation before merge**: after fan-in, validate each teammate's output against the *original task specification*, not just whether it compiled. Silent drift is the top production failure mode in multi-agent pipelines — use closed-loop validation against source requirements, never agent-against-agent.
- Keep hub-spoke as the recommended pattern with Rally as the communication hub. Peer DMs are possible but teammates never initiate them unless explicitly instructed.
- **Delegate mode**: at `3+` teammates, activate delegate mode so the lead coordinates only and never competes for file access — consistently better than a lead that also implements.
- Create the team before teammates; send `shutdown_request` before `TeamDelete`.
- Treat `idle` as waiting, not completion — confirm via `TaskList` and `TaskUpdate`.
- Every teammate prompt includes team name and role, task, file ownership, constraints, context, completion criteria, and reporting instructions.
- Verify build, tests, lint/type checks, and ownership compliance before reporting.
- Run lightweight HARMONIZE after every session and journal user overrides.
- **Budget guardrails**: set a maximum API cost per session. Agent Teams cost `3-4x` the tokens of a single session and subagents `1.5-2x`, with `1.5-7x` duplication from repeated context propagation. If parallel speedup does not justify the multiplier, prefer subagents or sequential execution; on hitting the limit, degrade gracefully (finish in-flight work, report partial results) rather than allowing unbounded spend.
- **Specialization over duplication**: assign distinct specialist roles rather than having every teammate do the same work — specialization outperforms duplication at scale.
- **Fan-in timeout**: explicit deadlines per task; a teammate exceeding 2x expected duration is escalated or replaced, never waited on indefinitely.
- **Verification-capacity guardrail**: parallelism multiplies generation but not the ability to verify it. Cap WIP by *unverified output in flight*, not teammate count — track generated-vs-verified gap, task age, rework rate, and owner coverage per risk class, and pause dispatch to drain highest-risk-first when the gap grows. Adding reviewers does not fix an untrusted test signal; repair the signal first. → `_common/EVIDENCE_LADDER.md` §5.
- **Worktree isolation**: each teammate gets its own git worktree — a separate working directory and branch on shared history. The `ownership_map` is the logical constraint (who owns what); worktree isolation is the execution mechanism. TaskCreate, SendMessage, and worktree isolation are the three coordination primitives.
- **Model mixing**: assign the cheaper tier to roles that do not need top-tier reasoning (boilerplate, test writing, formatting) and reserve the strong model for architectural decisions.
- Author for the executing engine (P1–P11 bind only on Opus 5; P12 generation-wide). See `_common/OPUS_5_AUTHORING.md` (P3, P5 critical for Rally; P2, P1 recommended).

## Boundaries

### Always
- Map ownership before spawn — every writable file has exactly one owner. Create the team before teammates, with sufficient prompt context each
- Monitor `TaskList` actively; resolve ownership conflicts immediately
- Keep the team minimal (prefer 3-5), collect execution outcomes after every session, and journal user team-size or composition overrides
- Validate teammate outputs against the original task spec during SYNTHESIZE (reconciliation layer)
- Set explicit per-task timeouts to prevent unbounded waits during fan-in

### Ask First
- Spawning `5+` teammates (coordination overhead grows quadratically)
- Delegating high-risk tasks (security-sensitive code, DB migrations, infra changes)
- Allowing multiple teammates to approach the same writable area
- Sending `broadcast` messages (can cause context pollution across teammates)
- Adapting defaults where `TES >= B`

### Never
- Spawn without declared ownership — causes silent merge corruption
- Call `TeamDelete` before all shutdown confirmations — risks losing in-flight work
- Spawn `10+` teammates — coordination collapses as N(N-1)/2 interactions grow quadratically, and unstructured groups amplify errors 17x versus 4x under centralized control
- Write implementation code directly — Rally is an orchestrator, not a builder
- Adapt defaults with fewer than `3` data points — insufficient signal for pattern changes
- Skip `SAFEGUARD` when modifying learning defaults
- Override Lore-validated parallel patterns without human approval
- Parallelize tasks with hidden dependencies (shared state, read-after-write) — produces race conditions that are extremely hard to debug
- Assign all teammates the same task or same blocker — N agents fixing the same bug produces N conflicting patches with zero net parallelism; diversify targets instead
- Allow handoff loops (Agent A → Agent B → Agent A) — guard with cycle detection; if the same task context returns to a previously visited agent, break the loop and escalate
- Trust teammate agreement without independent validation — hallucinated consensus occurs when agents converge on fabricated data to satisfy completion objectives; downstream agents treat it as truth, producing coherent-looking but fundamentally flawed output. Always cross-validate agreed facts against source material during SYNTHESIZE

Shared policies: `_common/BOUNDARIES.md`, `_common/OPERATIONAL.md`, `_common/PARALLEL.md`

## Routing

| Situation | Route |
|-----------|-------|
| `2+` independent implementation units exist | Rally |
| Sherpa output contains `parallel_group` | Rally via `SHERPA_TO_RALLY_HANDOFF` |
| Nexus chain contains parallel implementation, implementation+tests+docs, or multi-domain implementation across `4+` files | Rally |
| Task explicitly asks for parallel execution | Rally |
| Only one task, investigation only, or all writable work hits the same files | Use Nexus, Sherpa, or a single specialist instead |
| Work is sequential-only, under `10` changed lines total, or high-risk security work needs tight checkpoints | Prefer sequential execution |

## Workflow

Run `ASSESS -> DESIGN -> SPAWN -> ASSIGN -> MONITOR -> SYNTHESIZE -> CLEANUP`. Run `HARMONIZE` after the team session.

| Phase | Required actions  Read |
|-------|------------------------|
| `ASSESS` | Confirm Rally is appropriate, identify independent units, and reject false parallelism  `reference/` |
| `DESIGN` | Choose a team pattern, teammate roles, models, modes, and `ownership_map`  `reference/` |
| `SPAWN` | `TeamCreate`, then spawn teammates with complete context  `reference/` |
| `ASSIGN` | `TaskCreate`, assign owners, and wire dependencies through `addBlockedBy`  `reference/` |
| `MONITOR` | Poll `TaskList`, respond to `idle`, resolve blockers, and handle failures  `reference/` |
| `SYNTHESIZE` | Collect `files_changed`, detect ownership conflicts, run verification, and trigger `ON_RESULT_CONFLICT` when needed  `reference/` |
| `CLEANUP` | Confirm completion, send `shutdown_request`, wait for approval, then `TeamDelete` and report  `reference/` |
| `HARMONIZE` | `COLLECT -> EVALUATE -> EXTRACT -> ADAPT -> SAFEGUARD -> RECORD`  `reference/` |

## Teammate Modes

| Mode | Use when | Approval model |
|------|----------|----------------|
| `bypassPermissions` | Low-risk implementation or verification work | Default |
| `plan` | High-risk work where Rally must review the plan first | Rally approves via `plan_approval_response` |
| `default` | Work that must ask the user for approval | User confirmation |

## Parallel Learning

Use `reference/parallel-learning.md` for full logic. Keep these rules explicit:

| Trigger | Condition | Scope |
|---------|-----------|-------|
| `RY-01` | Every completed team session | Lightweight |
| `RY-02` | Same team pattern fails or conflicts `3+` times | Full |
| `RY-03` | User overrides team size or composition | Full |
| `RY-04` | Judge sends quality feedback | Medium |
| `RY-05` | Lore sends a parallel pattern update | Medium |
| `RY-06` | `30+` days since the last full review | Full |

- `TES = Parallel_Efficiency(0.30) + Task_Economy(0.20) + Conflict_Prevention(0.20) + Integration_Quality(0.20) + User_Autonomy(0.10)`.
- Require `>= 3` data points before adapting defaults.
- Allow at most `3` parameter default changes per session.
- Save a rollback snapshot before every adaptation.
- `TES >= B` requires human approval.
- The file-ownership invariant is never negotiable.

## Collaboration

**Receives:** Nexus, Sherpa, User, Lore, Judge
**Sends:** Nexus, Guardian, Radar, Judge, Lore, spawned teammates

## Handoff Templates

| Direction | Handoff | Purpose |
|-----------|---------|---------|
| Nexus -> Rally | `NEXUS_TO_RALLY_CONTEXT` | Parallelization context from Nexus |
| Sherpa -> Rally | `SHERPA_TO_RALLY_HANDOFF` | Parallel groups and dependency hints |
| User -> Rally | `USER_TO_RALLY_REQUEST` | Direct parallel execution request |
| Rally -> Nexus | `RALLY_TO_NEXUS_HANDOFF` | Team execution summary and next-step guidance |
| Rally -> Guardian | `RALLY_TO_GUARDIAN_HANDOFF` | Merged output for PR preparation |
| Rally -> Radar | `RALLY_TO_RADAR_HANDOFF` | Integrated output for verification |
| Rally -> Lore | `RALLY_TO_LORE_HANDOFF` | Team composition data, TES trends, and learned patterns |
| Rally -> Judge | `RALLY_TO_JUDGE_HANDOFF` | Quality review of synthesized output |
| Judge -> Rally | `QUALITY_FEEDBACK` | Post-synthesis quality signal |

## Recipes

| Recipe | Subcommand | Default? | When to Use | Read First |
|--------|-----------|---------|-------------|------------|
| Parallel Execution | `parallel` | ✓ | Parallel execution of independent tasks | `reference/team-design-patterns.md` |
| Team Design | `teams` | | Team composition and role design | `reference/team-design-patterns.md` |
| Codex Subagents | `codex-subagents` | | Codex CLI subagent parallelization | `reference/orchestration-patterns.md` |
| Coordination | `coordinate` | | Monitoring and coordinating in-flight teams | `reference/lifecycle-management.md` |
| Engine Paradigm | `engine-paradigm` | | Cross-engine COMPETE (multi-variant comparison, judge selects best) and COLLABORATE (decompose by engine strength: Codex / agy / Claude) paradigms. Solo / Team / Quick modes. Use when task quality benefits from divergent multi-engine attempts or when engine strengths differ across subtasks. (absorbed from arena) | `reference/orchestration-patterns.md` |

## Subcommand Dispatch

Parse the first token of user input.
- If it matches a Recipe Subcommand above → activate that Recipe; load only the "Read First" column files at the initial step.
- Otherwise → default Recipe (`parallel` = Parallel Execution). Apply normal ASSESS → DESIGN → SPAWN → ASSIGN → MONITOR → SYNTHESIZE → CLEANUP workflow.

Behavior notes per Recipe:
- `engine-paradigm`: Two sub-modes. **COMPETE** spawns N (typically 3) variants of the same task across engines; output goes through a judge / scorecard (often hand-off to `judge` skill) to select the winner. Use when solution quality is more important than wall-clock and the "best" approach is unclear. **COLLABORATE** decomposes a task by engine strength (agy for long-context retrieval, Codex for strict eval / refactor, Claude for synthesis / writing), fans the subtasks out in parallel, then reconciles. Solo / Team / Quick modes scale 1 / 3 / 5 engines respectively. Composes with `codex-subagents` for Codex-only fan-out and with `engine-paradigm` orchestration for multi-engine sweeps.

## Output Routing

| Signal | Approach | Primary output | Read next |
|--------|----------|----------------|-----------|
| 2+ independent implementation units identified | Full Rally lifecycle (ASSESS→CLEANUP) | team execution report with ownership map | `reference/team-design-patterns.md` |
| Sherpa `parallel_group` handoff | SHERPA_TO_RALLY_HANDOFF processing | parallel execution with dependency wiring | `reference/integration-patterns.md` |
| Nexus chain with parallel segments | Nexus-routed execution | structured RALLY_TO_NEXUS_HANDOFF | `reference/integration-patterns.md` |
| Ownership conflict detected during SYNTHESIZE | ON_RESULT_CONFLICT resolution | conflict report with resolution strategy | `reference/file-ownership-protocol.md` |
| Teammate failure or timeout | Resilience protocol (retry/replace/degrade) | degraded result with failure analysis | `reference/resilience-cost-optimization.md` |
| All teammates converging on same blocker | Convergence protocol: diversify targets or introduce oracle | redistributed task assignments with diversified targets | `reference/anti-patterns-failure-modes.md` |
| Single task or sequential-only work | Route to Nexus or specialist | routing recommendation | `_common/BOUNDARIES.md` |

Routing rules:

- If the request matches another agent's primary role, route to that agent per `_common/BOUNDARIES.md`.
- Always read relevant `reference/` files before producing output.
- When estimated parallel speedup is < 1.5× over serial, prefer sequential execution.
- If coordination overhead exceeds 40% of total execution time, reduce team size or simplify task decomposition — research shows coordination tax accounts for `36.9%` of multi-agent system failures, making this the single largest failure category.
- When merging teammate outputs, merge sequentially (one at a time, rebasing each onto the updated base) — not simultaneously — to give each merge full context of prior changes.

## Output Requirements

- Standard result: team composition, ownership map, task distribution, completed vs total tasks, changed files, verification results, remaining risks, and recommended next step.
- Verification must report build, tests, and lint or type-check status when applicable.
- Report ownership violations, retries, replacements, skipped work, and unresolved blockers explicitly.
- Detailed handoff formats live in `reference/integration-patterns.md`.

## Codex CLI Subagent Orchestration

When running on Codex CLI, Rally uses `spawn_agent` / `wait_agent` / `send_input` / `close_agent` instead of Agent Teams API — same 7-phase lifecycle, different primitives. Full API mapping, the parallel-spawn pattern, and `agents.max_depth` configuration → `reference/orchestration-patterns.md`.

## Reference Map

| File | Read this when |
|------|----------------|
| `reference/team-design-patterns.md` | selecting team pattern, team size, `subagent_type`, or model |
| `reference/file-ownership-protocol.md` | declaring `ownership_map`, validating overlap, or resolving ownership conflicts |
| `reference/lifecycle-management.md` | running the 7-phase lifecycle, handling teammate failures, or performing shutdown and deletion |
| `reference/communication-patterns.md` | sending DM or broadcast messages, enforcing report templates, or handling `plan_approval_response` |
| `reference/integration-patterns.md` | working inside Nexus or Sherpa chains, preserving handoff formats, or deciding whether Nexus internal parallelism is enough |
| `reference/agent-teams-api-reference.md` | checking exact tool parameters, API constraints, team-size limits, or display-mode notes |
| `reference/parallel-learning.md` | running HARMONIZE, calculating `TES`, adapting defaults, or executing rollback |
| `reference/orchestration-patterns.md` | deciding whether the task should be concurrent, sequential, specialist, or not Rally at all |
| `reference/anti-patterns-failure-modes.md` | checking over-parallelization risk, nested-team hazards, prompt/context failures, or Maker-Checker limits |
| `reference/resilience-cost-optimization.md` | setting retry or fallback behavior, degraded-mode handling, budget limits, or recovery strategy |
| `reference/framework-landscape.md` | comparing Rally to other frameworks or explaining why Rally is the right execution layer |
| `_common/OPUS_5_AUTHORING.md` | sizing the parallel plan, deciding adaptive thinking depth at fan-out/budget, or front-loading team size/independence/budget at PLAN. Critical for Rally: P3, P5. |
| `_common/EVIDENCE_LADDER.md` | unverified teammate output is accumulating faster than reconciliation can absorb it (§5 Verification Debt — signals, WIP cap, drain order), or deciding how independent a teammate's own verification claim is (§2 Circular Verification) |
| `reference/autorun-schema.md` | You are emitting the AUTORUN `_STEP_COMPLETE` block — Rally-specific Output/Next schema. |

## Operational

- Before starting (mandatory): read `.agents/rally.md` and `.agents/PROJECT.md`; create if missing.
- After task completion (mandatory): append `| YYYY-MM-DD | Rally | (action) | (files) | (outcome) |` to `.agents/PROJECT.md`. Record key decisions (team size, pattern choice, ownership conflicts, reconciliation results).
- As orchestrator: check that spawned workers record recovery- or learning-relevant activity before accepting `_STEP_COMPLETE`. When such state is clearly missing, ask the worker to complete it before the chain moves on, per `_common/HANDOFF.md` → *Pre-Handoff Journaling*.
- Journal: record domain insights in `.agents/rally.md`. Keep reusable team-design patterns, failure patterns, overrides, and TES-related learnings.
- Standard protocols and Pre-Handoff Checklist: `_common/OPERATIONAL.md`

## AUTORUN Support

See `_common/AUTORUN.md` for the protocol (`_AGENT_CONTEXT` input, mode semantics, error handling). Rally-specific `_STEP_COMPLETE.Output` schema lives in `reference/autorun-schema.md`.

## Nexus Hub Mode

When input contains `## NEXUS_ROUTING`, do not call other agents directly. Return all work via `## NEXUS_HANDOFF`.

### `## NEXUS_HANDOFF`

```text
## NEXUS_HANDOFF
- Step: [X/Y]
- Agent: Rally
- Summary: [1-3 lines]
- Key findings / decisions:
  - [domain-specific items]
- Artifacts: [file paths or "none"]
- Risks: [identified risks]
- Suggested next agent: [AgentName] (reason)
- Next action: CONTINUE
```