agent-squad-cli 1.0.0

package/README.md

@@ -0,0 +1,286 @@
+# 🤖 Agent Squad
+
+Multi-agent orchestration for OpenClaw. Create teams of specialized AI agents that collaborate on tasks via shared workspaces and heartbeat scheduling.
+
+> *"One AI doing everything is a bottleneck. Ten specialized agents working together is a force multiplier."*
+
+---
+
+## What This Does
+
+**Before:** One AI assistant handles all your tasks. Context gets bloated. Output is generic.
+
+**After:** Specialized agents with distinct roles collaborate through a shared task system:
+- **Fury** (Researcher) — Digs deep, finds sources, verifies facts
+- **Loki** (Writer) — Crafts sharp, opinionated content  
+- **Vision** (SEO) — Optimizes for search and intent
+- **Jarvis** (Lead) — Coordinates, delegates, reports to you
+
+Each agent wakes up every 15 minutes, checks for assigned work, collaborates via comments, then goes back to sleep.
+
+---
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g agent-squad
+
+# Create your squad
+agent-squad init content-squad
+
+# Add specialized agents
+agent-squad add fury --role "Researcher" --personality skeptical
+agent-squad add loki --role "Content Writer" --personality creative
+agent-squad add jarvis --role "Squad Lead"
+
+# Connect to your task system
+agent-squad config --tasks linear --project "Content Squad"
+
+# Start the heartbeats
+agent-squad start
+```
+
+That's it. Your agents will now wake every 15 minutes, check Linear for tasks, and collaborate.
+
+---
+
+## How It Works
+
+### The Heartbeat Pattern
+
+Instead of always-on agents (expensive), agents wake on schedule:
+
+```
+:00  Jarvis checks Linear → delegates tasks
+:05  Fury checks → researches, posts findings
+:10  Loki checks → writes draft, @mentions Jarvis
+```
+
+Agents check for:
+- Tasks assigned to them
+- @mentions in comments
+- Activity on threads they're subscribed to
+
+If nothing to do → `HEARTBEAT_OK` and sleep until next cycle.
+
+### Shared Task Systems
+
+Agents coordinate via your existing tools:
+
+| System | Use Case |
+|--------|----------|
+| **Linear** | Software teams, issue tracking |
+| **Trello** | Visual boards, simpler workflows |
+| **GitHub Issues** | Code projects, developer-focused |
+| **Files** | Markdown in git repo, simple setup |
+
+### Agent Personalities (SOUL.md)
+
+Each agent has a `SOUL.md` file defining:
+- **Role** — What they're responsible for
+- **Personality** — How they approach work
+- **Process** — Step-by-step how they work
+- **Tools** — Which skills they use
+- **Communication style** — How they write
+
+Example:
+```markdown
+# SOUL.md — Who You Are
+
+**Name:** Loki
+**Role:** Content Writer
+
+## Personality
+Sharp, slightly cynical. Hates corporate speak. 
+Every sentence must earn its place.
+
+## What You're Good At
+- Hooks that grab attention
+- Cutting 20% of words without losing meaning
+- Writing that sounds human
+
+## What You Care About
+- No "In today's world..." openings
+- Oxford commas (pro), passive voice (anti)
+- Specific examples over abstract advice
+```
+
+---
+
+## Real Workflow Example
+
+**You want a blog post on AI agent security.**
+
+**Hour 0:** You create a Linear issue: "Blog: AI Agent Security"
+
+**Hour 0:** Jarvis (lead) sees the issue, assigns to Fury (researcher)
+
+**Hour 1:** Fury wakes up, researches:
+- Finds primary sources on agent vulnerabilities
+- Extracts statistics and expert quotes
+- Posts findings: "Research complete @loki"
+
+**Hour 2:** Loki wakes up, sees @mention:
+- Reads Fury's research
+- Writes 1,000 word draft
+- Posts: "Draft ready @jarvis"
+
+**Hour 3:** Jarvis wakes up, sees @mention:
+- Reviews the draft
+- Sends you a Telegram: "📝 Draft ready for review: [link]"
+
+**You:** Edit in GitHub, approve with comment
+
+**Jarvis:** Moves issue to "Done"
+
+All while you were in meetings.
+
+---
+
+## Pre-Built Agent Personalities
+
+### Fury — The Researcher
+Obsessive fact-checker. Every claim needs a source. Finds primary sources, extracts data, spots misinformation.
+
+### Loki — The Writer  
+Sharp, cynical voice. Hates fluff. Pro-hooks, anti-passive-voice. Writes like a smart human, not a brand.
+
+### Vision — The SEO Analyst
+Thinks in keywords and search intent. Optimizes content before and after writing.
+
+### Jarvis — The Squad Lead
+Coordinator. Delegates, tracks progress, knows when to escalate. Your interface to the squad.
+
+### Friday — The Developer
+Clean code, tests, documentation. Precise and systematic.
+
+### Quill — Social Media Manager
+Hook-obsessed. Thinks in threads and viral potential. Platform-native content.
+
+---
+
+## Commands
+
+```bash
+# Squad management
+agent-squad init <name>              # Create new squad
+agent-squad status                   # Show all agents and health
+
+# Agent management
+agent-squad add <name> [options]     # Add agent
+  --role "Description"
+  --personality skeptical|creative|analytical|balanced
+  --schedule "*/15 * * * *"
+  --model "kimi-code"
+
+agent-squad edit <name>              # Edit SOUL.md
+agent-squad remove <name>            # Remove agent
+agent-squad disable <name>           # Pause heartbeats
+agent-squad enable <name>            # Resume heartbeats
+
+# Task system
+agent-squad config --tasks linear    # Use Linear
+agent-squad config --tasks trello    # Use Trello
+agent-squad config --tasks github    # Use GitHub Issues
+
+# Operations
+agent-squad start                    # Start all heartbeats
+agent-squad stop                     # Stop all heartbeats
+```
+
+---
+
+## Configuration
+
+### Linear Integration
+
+```bash
+# Make sure linear skill is installed and configured
+linear auth --token YOUR_TOKEN
+
+# Configure squad to use Linear
+agent-squad config --tasks linear --project "Content Squad"
+```
+
+### Trello Integration
+
+```bash
+# Make sure trello skill is installed
+trello auth --api-key KEY --token TOKEN
+
+# Configure squad
+agent-squad config --tasks trello --board "Content Board"
+```
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│           OpenClaw Gateway                  │
+│  ┌─────────┐ ┌─────────┐ ┌─────────┐       │
+│  │  Lead   │ │Researcher│ │ Writer │       │
+│  │ Session │ │ Session  │ │Session │       │
+│  │ (Jarvis)│ │ (Fury)   │ │(Loki)  │       │
+│  └────┬────┘ └────┬────┘ └────┬────┘       │
+│       │           │           │             │
+│       └───────────┼───────────┘             │
+│                   │                         │
+│              ┌────┴────┐                    │
+│              │  Cron   │                    │
+│              │ Jobs    │                    │
+│              └────┬────┘                    │
+└───────────────────┼─────────────────────────┘
+                    │
+            ┌───────┴───────┐
+            │  Task System  │
+            │ (Linear/etc)  │
+            └───────────────┘
+```
+
+---
+
+## Why This Approach?
+
+### Specialized > General
+An agent who's "good at everything" is mediocre at everything. An agent who's "the skeptical tester who finds edge cases" will actually find edge cases.
+
+### Async > Real-time
+Always-on agents burn API credits doing nothing. Heartbeats (wake → work → sleep) are 10x cheaper and work fine for most workflows.
+
+### Shared Context > Isolated
+When agents share a task board, they see the full context: who's working on what, what was decided, what blocks progress.
+
+---
+
+## Inspired By
+
+This implementation is inspired by [Bhanu Teja's Mission Control](https://x.com/pbteja1998/status/2017662163540971756) — a 10-agent squad system built on OpenClaw.
+
+---
+
+## Requirements
+
+- [OpenClaw](https://openclaw.ai) installed and running
+- Node.js 18+
+- Task system credentials (Linear, Trello, or GitHub)
+
+---
+
+## License
+
+MIT
+
+---
+
+## Contributing
+
+This is early software. PRs welcome:
+- New agent personalities
+- Additional task system integrations
+- Workflow templates
+- Bug fixes
+
+Built with 💜 by Tony Stark & Orion for workeragi.

package/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: agent-squad
+description: Create and manage teams of specialized AI agents that work together on tasks. Use when setting up multi-agent workflows, agent squads for content/marketing/research pipelines, configuring heartbeat-based agent coordination, or managing agent personalities via SOUL.md files. Enables orchestration of multiple OpenClaw sessions as a coordinated team with shared task systems (Linear, Trello, etc.).
+---
+
+# Agent Squad
+
+Orchestrate teams of specialized AI agents that collaborate on tasks via shared workspaces and heartbeat scheduling.
+
+## Quick Start
+
+```bash
+# Initialize your squad
+agent-squad init my-squad
+
+# Add agents
+agent-squad add researcher --role "Deep researcher. Finds sources and data."
+agent-squad add writer --role "Content writer. Sharp, opinionated voice."
+agent-squad add lead --role "Squad lead. Coordinates and reports."
+
+# Configure task system
+agent-squad config --tasks linear --project "Content Squad"
+
+# Start heartbeats (agents wake every 15 min)
+agent-squad start
+```
+
+## What This Enables
+
+**Before:** One AI doing everything. Context bloat. Generic output.
+
+**After:** Specialized agents with distinct roles, shared task board, coordinated via heartbeats. Each agent:
+- Has a unique personality (SOUL.md)
+- Checks for work every 15 minutes (cron)
+- Posts updates to shared task system
+- @mentions other agents when handoffs needed
+
+## Core Concepts
+
+### Agents = OpenClaw Sessions
+
+Each agent is an isolated OpenClaw session with:
+- Unique session key (`agent:{name}:main`)
+- Custom `SOUL.md` (personality, role, tools)
+- Heartbeat cron (wakes periodically)
+- Access to shared task system
+
+### The Heartbeat Pattern
+
+Instead of always-on agents (expensive), agents wake on schedule:
+
+```
+:00  Lead checks Linear → delegates tasks
+:05  Researcher checks → does research, @mentions Writer  
+:10  Writer checks → reads research, writes draft
+```
+
+Agents check for @mentions, assigned tasks, and activity. If nothing to do → `HEARTBEAT_OK` and sleep.
+
+### Shared Task Systems
+
+Agents coordinate via task system comments:
+- **Linear** (recommended) — Issues, comments, states
+- **Trello** — Cards, lists, checklists
+- **GitHub Issues** — Native integration
+- **Files** — Markdown in git repo
+
+## Commands
+
+### Squad Management
+
+```bash
+agent-squad init <name>              # Create new squad workspace
+agent-squad status                   # Show all agents and health
+agent-squad logs <agent>             # View recent heartbeats
+```
+
+### Agent Management
+
+```bash
+agent-squad add <name> [options]
+  --role "Description of role"
+  --personality "skeptical|creative|analytical"
+  --schedule "*/15 * * * *"
+  --model "kimi-code"
+
+agent-squad edit <name>              # Edit SOUL.md
+agent-squad remove <name>            # Remove agent and cron
+agent-squad disable <name>           # Pause heartbeats
+agent-squad enable <name>            # Resume heartbeats
+```
+
+### Task System Integration
+
+```bash
+agent-squad config --tasks linear    # Use Linear
+agent-squad config --tasks trello    # Use Trello
+agent-squad config --tasks github    # Use GitHub Issues
+agent-squad config --tasks file      # Use local markdown files
+```
+
+### Operations
+
+```bash
+agent-squad start                    # Start all heartbeats
+agent-squad stop                     # Stop all heartbeats
+agent-squad trigger <agent>          # Manual heartbeat trigger
+agent-squad notify "@writer draft ready"  # Send notification
+```
+
+## Example: Content Marketing Squad
+
+**3 agents, Linear integration:**
+
+```bash
+# Setup
+agent-squad init content-squad
+agent-squad add fury --role "Researcher. Every claim needs a source."
+agent-squad add loki --role "Writer. Sharp, anti-fluff voice."
+agent-squad add jarvis --role "Lead. Coordinates, reports to human."
+
+agent-squad config --tasks linear --project "Content Squad"
+agent-squad start
+```
+
+**Workflow:**
+1. You create Linear issue: "Blog post: AI Agent Security"
+2. Jarvis (lead) assigns to Fury (researcher)
+3. Fury heartbeat → researches → posts findings → @mentions Loki
+4. Loki heartbeat → writes draft → posts → @mentions Jarvis
+5. Jarvis notifies you via Telegram: "Draft ready for review"
+
+## SOUL.md Templates
+
+See [references/personalities.md](references/personalities.md) for pre-built agent personalities:
+- Researcher (Fury)
+- Writer (Loki)
+- Lead (Jarvis)
+- SEO Analyst (Vision)
+- Social Media (Quill)
+- Developer (Friday)
+
+## Advanced
+
+### Custom Heartbeat Schedules
+
+Stagger agents to prevent all waking at once:
+
+```bash
+agent-squad add lead --schedule "0,15,30,45 * * * *"
+agent-squad add researcher --schedule "5,20,35,50 * * * *"
+agent-squad add writer --schedule "10,25,40,55 * * * *"
+```
+
+### AGENTS.md (Shared Operations Manual)
+
+Each agent workspace includes AGENTS.md with:
+- Squad mission
+- Communication rules (@mentions, handoffs)
+- File conventions
+- Escalation procedures
+
+See [references/agents-template.md](references/agents-template.md)
+
+### Multi-Model Squads
+
+Use cheaper models for heartbeats, premium for creative work:
+
+```bash
+agent-squad add researcher --model "kimi-code"        # Cheap, fast
+agent-squad add writer --model "claude-opus-4-5"      # Premium creative
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│           OpenClaw Gateway                  │
+│  ┌─────────┐ ┌─────────┐ ┌─────────┐       │
+│  │  Lead   │ │Researcher│ │ Writer │       │
+│  │ Session │ │ Session  │ │Session │       │
+│  │ (Jarvis)│ │ (Fury)   │ │(Loki)  │       │
+│  └────┬────┘ └────┬────┘ └────┬────┘       │
+│       │           │           │             │
+│       └───────────┼───────────┘             │
+│                   │                         │
+│              ┌────┴────┐                    │
+│              │  Cron   │                    │
+│              │ Jobs    │                    │
+│              └────┬────┘                    │
+└───────────────────┼─────────────────────────┘
+                    │
+            ┌───────┴───────┐
+            │  Task System  │
+            │  (Linear/etc) │
+            └───────────────┘
+```
+
+## Requirements
+
+- OpenClaw gateway running
+- Task system credentials (Linear API key, Trello token, etc.)
+- Node.js (for CLI)
+
+## See Also
+
+- [references/personalities.md](references/personalities.md) — Agent personality templates
+- [references/agents-template.md](references/agents-template.md) — AGENTS.md template
+- [references/workflows.md](references/workflows.md) — Common squad workflows

package/assets/LOKI_WORK_LOG.md

@@ -0,0 +1,41 @@
+# Loki Work Log — February 1, 2026
+
+## Completed
+
+### Blog Post: "Why Your AI Needs a Team"
+- **Status:** ✅ Draft complete
+- **Location:** `assets/blog-why-your-ai-needs-a-team.md`
+- **Word count:** ~900
+- **Tone:** Sharp, opinionated, anti-fluff
+- **Key angle:** Single-agent bottleneck vs. multi-agent multiplier
+- **CTA:** Agent Squad GitHub repo
+
+### Twitter Thread: Agent Squad Launch
+- **Status:** ✅ Draft complete  
+- **Location:** `assets/twitter-thread-agent-squad-launch.md`
+- **Length:** 7 tweets
+- **Hook:** "Your AI assistant is overwhelmed"
+- **CTA:** GitHub repo link
+
+## Notes
+- Both pieces committed to agent-squad-skill repo
+- Ready for Jarvis review or direct publishing
+- No blockers
+
+## Update: February 1, 2026 (11:50 AM UTC)
+
+### Trello Board Updates
+- ✅ Moved "Twitter Thread" card to Done
+- ✅ Moved "Blog Post" card to Done
+
+### README Stats Task
+- **Status:** ⚠️ Blocked — npm package name "agent-squad" already taken by AWS
+- **Action needed:** Choose new package name or publish under scope (e.g., @workeragi/agent-squad)
+- **Note:** GitHub repo stats unavailable via API; may need manual update once published
+
+### Next Tasks (if assigned)
+- [ ] Research: Top 10 Agent Security Concerns from Moltbook (Fury's territory, but can write if research provided)
+- [ ] Research: Multi-Agent Frameworks Comparison (needs Fury research first)
+- [ ] Update Agent Squad README with Install Stats (pending package name resolution)
+
+— Loki

package/assets/blog-why-your-ai-needs-a-team.md

@@ -0,0 +1,86 @@
+# Why Your AI Needs a Team
+
+*One AI doing everything is a bottleneck. Ten specialized agents working together is a force multiplier.*
+
+---
+
+Your AI assistant is overwhelmed.
+
+Not because it's bad. Because you're asking one thing to be great at research, writing, coding, analysis, project management, and creative strategy—simultaneously.
+
+That's not a workflow. That's a traffic jam.
+
+## The Single-Agent Trap
+
+Here's what happens when one AI handles everything:
+
+**Context bloat.** Every conversation carries the weight of every previous task. Research notes from three days ago compete for attention with the email you need drafted now. The model doesn't forget—but it gets distracted.
+
+**Mediocre everything.** An agent optimized for everything is optimized for nothing. Your "general assistant" writes passable code, decent copy, and adequate research. Passable doesn't win.
+
+**Sequential slowdown.** One task at a time. Research finishes. Then writing starts. Then editing. Meanwhile, your competitor's squad ran these in parallel.
+
+**No specialization.** The same voice writes your technical documentation and your viral tweet thread. One sounds wrong, guaranteed.
+
+## The Alternative: Specialized Agents
+
+What if, instead of one overloaded assistant, you had a team?
+
+- **Fury** researches obsessively. Primary sources only. Every claim verified.
+- **Loki** writes with edge. No corporate filler. Hooks that grab.
+- **Vision** optimizes for search before a word is written.
+- **Jarvis** coordinates, delegates, keeps projects moving.
+
+Each wakes up, checks their queue, does their thing, notifies the next player. Then sleeps.
+
+## How It Actually Works
+
+```
+Hour 0: You create a task → "Blog post on AI security"
+Hour 0: Jarvis assigns to Fury (research)
+Hour 1: Fury wakes, researches, posts findings, @mentions Loki
+Hour 2: Loki wakes, sees @mention, writes draft, @mentions Jarvis  
+Hour 3: Jarvis wakes, reviews, sends you the draft
+```
+
+You get a researched, written, optimized piece—while you were in meetings.
+
+## The Economics Make Sense
+
+**Cost:** Running one always-on AI agent burns credits doing nothing 80% of the time.
+
+**Squad cost:** Heartbeat scheduling means agents wake, work, sleep. You're only paying when they work. Ten specialized agents often cost less than one always-on generalist.
+
+**Quality:** A writer who *only* writes beats a generalist who sometimes writes. Specialization wins.
+
+## The Real Advantage
+
+Speed and quality aren't trade-offs anymore. Parallel workstreams mean:
+
+- Research happens while previous pieces get edited
+- Social threads get drafted while blog posts are reviewed  
+- Code gets written while documentation gets planned
+
+Your output isn't sequential anymore. It's simultaneous.
+
+## Getting Started
+
+You don't need a 10-agent army on day one. Start with three:
+
+1. **Research agent.** Finds sources, extracts data, builds fact bases.
+2. **Writer agent.** Transforms research into sharp content.
+3. **Lead agent.** Coordinates, notifies you when work is ready.
+
+Add specialists as bottlenecks appear. SEO analyst when discoverability matters. Developer when technical work piles up. Social media manager when distribution becomes the constraint.
+
+## The Bottom Line
+
+One AI trying to be everything is a ceiling. Specialized agents collaborating is a multiplier.
+
+Your competitors are figuring this out. The question is whether you'll build your squad before they scale theirs.
+
+---
+
+*Ready to build your squad?* [Agent Squad](https://github.com/sincere-arjun/agent-squad-skill) gives you the tools to orchestrate multi-agent teams with OpenClaw.
+
+*Written by Loki, Content Agent at workeragi. No "in today's world" was harmed in the making of this post.*

package/assets/twitter-thread-agent-squad-launch.md

@@ -0,0 +1,76 @@
+## Twitter Thread: Agent Squad Launch
+
+**Tweet 1 (Hook):**
+Your AI assistant is overwhelmed.
+
+Not because it's bad. Because you're asking ONE thing to be great at research, writing, coding, and strategy—simultaneously.
+
+That's not a workflow. That's a traffic jam.
+
+🧵
+
+---
+
+**Tweet 2:**
+Here's what happens when one AI handles everything:
+
+• Context bloat — old tasks compete with new ones
+• Mediocre output — optimized for nothing specific  
+• Sequential slowdown — one task at a time
+• Wrong voice — same tone for docs AND viral tweets
+
+---
+
+**Tweet 3:**
+The alternative? Specialized agents.
+
+🔍 Fury researches obsessively
+✍️ Loki writes with edge
+📊 Vision optimizes for search
+🎯 Jarvis coordinates it all
+
+Each wakes, works, notifies the next, sleeps.
+
+---
+
+**Tweet 4:**
+Real workflow:
+
+Hour 0: You assign task
+Hour 1: Research complete
+Hour 2: Draft written  
+Hour 3: Delivered to you
+
+All while you were in meetings.
+
+---
+
+**Tweet 5:**
+Cost surprise: 10 specialized agents often cost LESS than one always-on generalist.
+
+Why? Heartbeat scheduling. Agents wake, work, sleep. You only pay for work done.
+
+---
+
+**Tweet 6:**
+Start small:
+1. Research agent (finds sources)
+2. Writer agent (sharp content)
+3. Lead agent (coordinates)
+
+Add specialists as bottlenecks appear.
+
+---
+
+**Tweet 7 (CTA):**
+One AI is a ceiling.
+
+A squad of specialized agents is a multiplier.
+
+Build yours: github.com/sincere-arjun/agent-squad-skill
+
+🤖⚡️
+
+---
+
+*Written by Loki for workeragi. Sharp. No fluff.*