cross-squad

Context

When an organization runs multiple Squad instances (e.g., platform-squad, frontend-squad, data-squad), those squads need to discover each other, share context, and hand off work across repository boundaries. This skill teaches agents how to coordinate across squads without creating tight coupling.

Cross-squad orchestration applies when:

• A task requires capabilities owned by another squad
• An architectural decision affects multiple squads
• A feature spans multiple repositories with different squads
• A squad needs to request infrastructure, tooling, or support from another squad

Patterns

Discovery via Manifest

Each squad publishes a .squad/manifest.json declaring its name, capabilities, and contact information. Squads discover each other through:

1. Well-known paths: Check .squad/manifest.json in known org repos
2. Upstream config: Squads already listed in .squad/upstream.json are checked for manifests
3. Explicit registry: A central squad-registry.json can list all squads in an org

{
  "name": "platform-squad",
  "version": "1.0.0",
  "description": "Platform infrastructure team",
  "capabilities": ["kubernetes", "helm", "monitoring", "ci-cd"],
  "contact": {
    "repo": "org/platform",
    "labels": ["squad:platform"]
  },
  "accepts": ["issues", "prs"],
  "skills": ["helm-developer", "operator-developer", "pipeline-engineer"]
}

Context Sharing

When delegating work, share only what the target squad needs:

• Capability list: What this squad can do (from manifest)
• Relevant decisions: Only decisions that affect the target squad
• Handoff context: A concise description of why this work is being delegated

Do NOT share:

• Internal team state (casting history, session logs)
• Full decision archives (send only relevant excerpts)
• Authentication credentials or secrets

Work Handoff Protocol

1. Check manifest: Verify the target squad accepts the work type (issues, PRs)
2. Create issue: Use gh issue create in the target repo with:
   • Title: [cross-squad] <description>
   • Label: squad:cross-squad (or the squad's configured label)
   • Body: Context, acceptance criteria, and link back to originating issue
3. Track: Record the cross-squad issue URL in the originating squad's orchestration log
4. Poll: Periodically check if the delegated issue is closed/completed