Add spec for swarm command and remote spawn features

[khaliqgant]

Summary

• Adds formal specification for two complementary features inspired by Cursor's scaling agents approach
• Local Swarm Command: Spin up N workers + coordinator with a single command (agent-relay swarm --workers 3 "task")
• Remote Spawn (--remote): Spawn agents on cloud workspaces from local CLI

What's in the spec

Existing Infrastructure Audit

• cloud link - exists, creates auth config
• spawn - local only, needs --remote flag
• agents --remote - exists, lists cloud agents
• Cloud API endpoints for spawn/list/delete - exist

Implementation Tasks (~7 days)

Swarm Command:

1. CLI skeleton (0.5d)
2. Multi-spawn orchestration (1d)
3. Task distribution protocol (0.5d)
4. Worker lifecycle management (0.5d)

Remote Spawn:

1. --remote flag for spawn (0.5d)
2. API key auth for CLI→cloud (0.5d)
3. Workspace selection (0.5d)
4. Remote status display (0.5d)
5. Swarm with --remote (0.5d)
6. Detach/attach (1d)

Future:

• Continuity auto-briefing for workers (1d)

Key Design Decisions

• Coordinator decides worker roles (v1), role templates later (v2)
• Workers get task-scoped context (like Cursor), but have continuity access for queries
• Uses existing cloud link infrastructure for auth
• Hybrid mode: local coordinator + cloud workers

Open Questions

1. Worker naming convention in swarm
2. Standardized task-assignment protocol vs free-form messaging
3. Resource limit detection for local swarms
4. Auto-wake stopped workspaces on --remote
5. Billing visibility for cloud spawns

Test plan

• Review spec for completeness
• Validate existing infrastructure audit is accurate
• Discuss open questions
• Approve for implementation

🤖 Generated with Claude Code

[my-senior-dev-pr-review]

🤖 My Senior Dev — Analysis Complete

👤 For @khaliqgant

📁 Expert in src/dashboard/react-components/ (10 edits) • ⚡ 57th PR this month

View your contributor analytics →

---

📊 1 file reviewed • 2 high risk • 4 need attention

🚨 High Risk:

• docs/proposals/swarm-and-remote-spawn.md — Critical impact on security and functionality due to API key reliance and lack of tests.

⚠️ Needs Attention:

• docs/proposals/swarm-and-remote-spawn.md — Significant concerns regarding performance and logic that could affect system reliability.

---

🚀 Open Interactive Review →

The full interface unlocks features not available in GitHub:

• 💬 AI Chat — Ask questions on any file, get context-aware answers
• 🔍 Smart Hovers — See symbol definitions and usage without leaving the diff
• 📚 Code Archeology — Understand how files evolved over time (/archeology)
• 🎯 Learning Insights — See how this PR compares to similar changes

---

💬 Chat here: @my-senior-dev explain this change — or try @chaos-monkey @security-auditor @optimizer @skeptic @junior-dev

📖 View all 12 personas & slash commands

You can interact with me by mentioning @my-senior-dev in any comment:

In PR comments or on any line of code:

• Ask questions about the code or PR
• Request explanations of specific changes
• Get suggestions for improvements

Slash commands:

• /help — Show all available commands
• /archeology — See the history and evolution of changed files
• /profile — Performance analysis and suggestions
• /expertise — Find who knows this code best
• /personas — List all available AI personas

AI Personas (mention to get their perspective):

Persona	Focus
@chaos-monkey 🐵	Edge cases & failure scenarios
@skeptic 🤨	Challenge assumptions
@optimizer ⚡	Performance & efficiency
@security-auditor 🔒	Security vulnerabilities
@accessibility-advocate ♿	Inclusive design
@junior-dev 🌱	Simple explanations
@tech-debt-collector 💳	Code quality & shortcuts
@ux-champion 🎨	User experience
@devops-engineer 🚀	Deployment & scaling
@documentation-nazi 📚	Documentation gaps
@legacy-whisperer 🏛️	Working with existing code
@test-driven-purist ✅	Testing & TDD

For the best experience, view this PR on myseniordev.com — includes AI chat, file annotations, and interactive reviews.