squadron-agents 0.2.1

The Operating System for Autonomous Software Teams

Squadron

The Operating System for Autonomous Software Teams

Give your AI agents a job. Not just a prompt.

Quick Start • Commands • Architecture • Skills • Roadmap

---

⚡ Install

pip install squadron-agents

That's it. You're ready.

---

🎬 See It In Action

$ squadron report --msg "Refactored the auth module." --ticket "KAN-1"

🚀 Squadron Bridge Activated...
✅ Slack: Message sent to #general
✅ Jira: Comment added to KAN-1

One command. Multiple integrations. Zero context switching.

---

😤 The Problem

You're building with AI agents. They're powerful. They can write code, refactor systems, and solve complex problems.

But here's the frustrating reality:

What You Want	What Actually Happens
Agent finishes a task	You don't know unless you check the terminal
Jira ticket should update	It stays in "To Do" forever
Team needs visibility	They have no idea what the AI is building

Your agents are trapped in a chat window. They can think, but they can't act in your team's workflow.

---

✨ The Solution

Squadron is a bridge that connects your local AI agents to your team's real tools.

┌─────────────────┐         ┌─────────────────┐
│   AI AGENT      │         │   YOUR TEAM     │
│  (Cursor, etc)  │         │                 │
│                 │         │  📋 Jira        │
│  "Task done!"   │────────▶│  💬 Slack       │
│                 │Squadron │  🔔 Discord     │
│                 │ Bridge  │  🐙 GitHub      │
└─────────────────┘         └─────────────────┘

Squadron gives your agents:

• 🗣️ A Voice — Post updates to Slack/Discord
• ✋ Hands — Update Jira tickets, create GitHub PRs
• 👀 Awareness — Overseer watches for new assignments
• 🧠 Context — Knowledge files that define your workflow

---

🚀 Quick Start

1. Install

pip install squadron-agents

2. Configure

Create a .env file in your project root:

# Jira
JIRA_SERVER=https://your-domain.atlassian.net
JIRA_EMAIL=[e-mail]
JIRA_TOKEN=your-api-token

# Slack
SLACK_BOT_TOKEN=xoxb-your-bot-token

# Discord (optional)
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

# GitHub (optional)
GITHUB_TOKEN=ghp_your-token

3. Test

squadron report --msg "Hello from Squadron!" --channel "#general"

If you see ✅ Slack: Message sent — you're live! 🎉

---

📖 Commands

squadron report — Team Updates

Send updates to Slack and optionally update Jira tickets.

# Basic Slack message
squadron report --msg "Starting the database migration"

# With Jira ticket update
squadron report --msg "Fixed the login bug" --ticket "PROJ-101"

# With status transition
squadron report --msg "Feature complete" --ticket "PROJ-101" --status "Done"

squadron broadcast — Discord Announcements

Broadcast updates to your Discord community.

squadron broadcast --msg "🚀 Just shipped v2.0!"

squadron pr — GitHub Pull Requests

Create PRs programmatically.

squadron pr --repo "user/repo" --title "Add auth module" --head "feature-auth"

squadron issue — GitHub Issues

Create issues from the command line.

squadron issue --repo "user/repo" --title "Bug: Login fails on mobile"

squadron overseer — Background Watcher

Start a daemon that watches Jira for new tickets assigned to you.

squadron overseer --interval 30

When a new ticket appears:

🔔 NEW TASK DETECTED!
   Ticket: KAN-42
   Summary: Implement user authentication

---

🏗️ Architecture

Squadron uses a Skill-Based Architecture inspired by the Model Context Protocol (MCP).

squadron/
├── cli.py                 # 🎯 The Router (entry point)
├── overseer.py            # 👀 Background ticket watcher
│
├── skills/                # 🛠️ ACTION LAYER (The Hands)
│   ├── jira_bridge/       # Jira API integration
│   ├── slack_bridge/      # Slack API integration
│   ├── discord_bridge/    # Discord webhooks
│   └── github_bridge/     # GitHub API integration
│
└── knowledge/             # 🧠 CONTEXT LAYER (The Brain)
    ├── TEAM.md            # Who is on the team?
    ├── WORKFLOW.md        # How does work flow?
    └── ROLES.md           # What does each agent do?

Why This Structure?

Layer	Purpose	Example
Skills	Executable actions	JiraTool.update_ticket()
Knowledge	Context for decisions	"Move to Done only after tests pass"

Skills = Hands. Knowledge = Brain.

---

📝 Customizing for Your Team

The knowledge/ folder contains example files that you should customize for your own team:

File	What to Customize
TEAM.md	Replace with your team members (human and AI)
ROLES.md	Define your agent personas and responsibilities
WORKFLOW.md	Set your team's development process and rules

These files provide context that helps your agents understand your workflow. The examples show our agents (Marcus & Caleb) — replace them with your own!

# Example: Edit the roles file
code squadron/knowledge/ROLES.md

---

🔌 Skills

Skill	Status	What It Does
Jira Bridge	✅ Live	Update tickets, add comments, transition status
Slack Bridge	✅ Live	Send formatted messages to channels
Discord Bridge	✅ Live	Broadcast via webhooks
GitHub Bridge	✅ Live	Create PRs and Issues
Overseer	✅ Live	Watch Jira for new assignments

---

🤖 Teaching Your Agents

Add this to your agent's system prompt:

## Tool: Squadron

You have access to the `squadron` CLI for team communication.

### When to use:
- After completing a coding task
- When you hit a blocker and need help
- To update ticket status

### Commands:
- Start task: `squadron report --msg "Starting auth work" --ticket "KAN-1" --status "In Progress"`
- Complete task: `squadron report --msg "Auth complete" --ticket "KAN-1" --status "Done"`
- Announce: `squadron broadcast --msg "Shipped new feature!"`

---

🗺️ Roadmap

• Core CLI — squadron report command
• Jira Integration — Comments + status transitions
• Slack Integration — Rich block messages
• Discord Integration — Webhook broadcasts
• GitHub Integration — PRs and Issues
• Overseer Mode — Background ticket watcher
• PyPI Release — pip install squadron-agents
• Agent Wake-up — Trigger agents when Overseer detects tickets
• Linear/Trello Support — Alternative project management tools
• Email Notifications — SMTP integration

---

🌟 The Origin Story

Squadron was born out of necessity.

We're building BlackCircleTerminal, a quantitative trading platform managed by AI agents. Our virtual developers — Marcus (Strategy) and Caleb (Data) — needed a way to communicate with us when we weren't at the keyboard.

We realized that for agents to be truly useful, they need to be part of the workflow, not just the code editor.

Squadron is the nervous system that connects our AI workforce to our human tools.

---

🤝 Contributing

We're building the future of Agent-First Development. Want to add a new skill?

1. Fork the repo
2. Create a skill in squadron/skills/your_skill/
3. Add tool.py (logic) and SKILL.md (instructions)
4. Open a PR!

Ideas for new skills:

• Linear / Trello / Asana integrations
• Email notifications
• CI/CD triggers
• Calendar scheduling

---

📜 License

MIT © MikeeBuilds

---

Don't just build agents. Give them a job.

⭐ Star this repo • 📦 PyPI • 🐛 Report Bug