SKILL.md (4787B)
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.