| 1 | --- |
| 2 | name: "cross-squad" |
| 3 | description: "Coordinating work across multiple Squad instances" |
| 4 | domain: "orchestration" |
| 5 | confidence: "medium" |
| 6 | source: "manual" |
| 7 | tools: |
| 8 | - name: "squad-discover" |
| 9 | description: "List known squads and their capabilities" |
| 10 | when: "When you need to find which squad can handle a task" |
| 11 | - name: "squad-delegate" |
| 12 | description: "Create work in another squad's repository" |
| 13 | when: "When a task belongs to another squad's domain" |
| 14 | --- |
| 15 | |
| 16 | ## Context |
| 17 | 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. |
| 18 | |
| 19 | Cross-squad orchestration applies when: |
| 20 | - A task requires capabilities owned by another squad |
| 21 | - An architectural decision affects multiple squads |
| 22 | - A feature spans multiple repositories with different squads |
| 23 | - A squad needs to request infrastructure, tooling, or support from another squad |
| 24 | |
| 25 | ## Patterns |
| 26 | |
| 27 | ### Discovery via Manifest |
| 28 | Each squad publishes a `.squad/manifest.json` declaring its name, capabilities, and contact information. Squads discover each other through: |
| 29 | 1. **Well-known paths**: Check `.squad/manifest.json` in known org repos |
| 30 | 2. **Upstream config**: Squads already listed in `.squad/upstream.json` are checked for manifests |
| 31 | 3. **Explicit registry**: A central `squad-registry.json` can list all squads in an org |
| 32 | |
| 33 | ```json |
| 34 | { |
| 35 | "name": "platform-squad", |
| 36 | "version": "1.0.0", |
| 37 | "description": "Platform infrastructure team", |
| 38 | "capabilities": ["kubernetes", "helm", "monitoring", "ci-cd"], |
| 39 | "contact": { |
| 40 | "repo": "org/platform", |
| 41 | "labels": ["squad:platform"] |
| 42 | }, |
| 43 | "accepts": ["issues", "prs"], |
| 44 | "skills": ["helm-developer", "operator-developer", "pipeline-engineer"] |
| 45 | } |
| 46 | ``` |
| 47 | |
| 48 | ### Context Sharing |
| 49 | When delegating work, share only what the target squad needs: |
| 50 | - **Capability list**: What this squad can do (from manifest) |
| 51 | - **Relevant decisions**: Only decisions that affect the target squad |
| 52 | - **Handoff context**: A concise description of why this work is being delegated |
| 53 | |
| 54 | Do NOT share: |
| 55 | - Internal team state (casting history, session logs) |
| 56 | - Full decision archives (send only relevant excerpts) |
| 57 | - Authentication credentials or secrets |
| 58 | |
| 59 | ### Work Handoff Protocol |
| 60 | 1. **Check manifest**: Verify the target squad accepts the work type (issues, PRs) |
| 61 | 2. **Create issue**: Use `gh issue create` in the target repo with: |
| 62 | - Title: `[cross-squad] <description>` |
| 63 | - Label: `squad:cross-squad` (or the squad's configured label) |
| 64 | - Body: Context, acceptance criteria, and link back to originating issue |
| 65 | 3. **Track**: Record the cross-squad issue URL in the originating squad's orchestration log |
| 66 | 4. **Poll**: Periodically check if the delegated issue is closed/completed |
| 67 | |
| 68 | ### Feedback Loop |
| 69 | Track delegated work completion: |
| 70 | - Poll target issue status via `gh issue view` |
| 71 | - Update originating issue with status changes |
| 72 | - Close the feedback loop when delegated work merges |
| 73 | |
| 74 | ## Examples |
| 75 | |
| 76 | ### Discovering squads |
| 77 | ```bash |
| 78 | # List all squads discoverable from upstreams and known repos |
| 79 | squad discover |
| 80 | |
| 81 | # Output: |
| 82 | # platform-squad → org/platform (kubernetes, helm, monitoring) |
| 83 | # frontend-squad → org/frontend (react, nextjs, storybook) |
| 84 | # data-squad → org/data (spark, airflow, dbt) |
| 85 | ``` |
| 86 | |
| 87 | ### Delegating work |
| 88 | ```bash |
| 89 | # Delegate a task to the platform squad |
| 90 | squad delegate platform-squad "Add Prometheus metrics endpoint for the auth service" |
| 91 | |
| 92 | # Creates issue in org/platform with cross-squad label and context |
| 93 | ``` |
| 94 | |
| 95 | ### Manifest in squad.config.ts |
| 96 | ```typescript |
| 97 | export default defineSquad({ |
| 98 | manifest: { |
| 99 | name: 'platform-squad', |
| 100 | capabilities: ['kubernetes', 'helm'], |
| 101 | contact: { repo: 'org/platform', labels: ['squad:platform'] }, |
| 102 | accepts: ['issues', 'prs'], |
| 103 | skills: ['helm-developer', 'operator-developer'], |
| 104 | }, |
| 105 | }); |
| 106 | ``` |
| 107 | |
| 108 | ## Anti-Patterns |
| 109 | - **Direct file writes across repos** — Never modify another squad's `.squad/` directory. Use issues and PRs as the communication protocol. |
| 110 | - **Tight coupling** — Don't depend on another squad's internal structure. Use the manifest as the public API contract. |
| 111 | - **Unbounded delegation** — Always include acceptance criteria and a timeout. Don't create open-ended requests. |
| 112 | - **Skipping discovery** — Don't hardcode squad locations. Use manifests and the discovery protocol. |
| 113 | - **Sharing secrets** — Never include credentials, tokens, or internal URLs in cross-squad issues. |
| 114 | - **Circular delegation** — Track delegation chains. If squad A delegates to B which delegates back to A, something is wrong. |