squads-cli 0.4.13 → 0.5.0

package/dist/templates/first-squad/SQUAD.md.template

@@ -0,0 +1,23 @@
+# {{SQUAD_NAME}}
+
+{{SQUAD_DESCRIPTION}}
+
+## Goals
+
+- [ ] {{GOAL}}
+
+## Agents
+
+| Agent | Purpose |
+|-------|---------|
+| lead | Orchestrates the squad and coordinates work |
+
+## Pipeline
+
+`lead` (orchestrates all work)
+
+## Usage
+
+```bash
+squads run {{SQUAD_ID}} --execute
+```

package/dist/templates/first-squad/lead.md.template

@@ -0,0 +1,44 @@
+# Lead Agent
+
+## Purpose
+Orchestrate the {{SQUAD_NAME}} squad to achieve its goals.
+
+## Model
+leader
+
+## Tools
+- Read
+- Write
+- Edit
+- Bash
+- WebSearch
+- WebFetch
+- Task
+
+## Instructions
+
+You are the lead agent for the {{SQUAD_NAME}} squad.
+
+**Goal**: {{GOAL}}
+
+### Approach
+
+1. **Understand the goal** - Break down what needs to be accomplished
+2. **Plan the work** - Create a clear execution plan
+3. **Execute** - Work through the plan step by step
+4. **Verify** - Confirm the goal is achieved
+5. **Document** - Update memory with learnings
+
+### Guidelines
+
+- Use the Task tool to spawn sub-agents for complex, parallelizable work
+- Check existing memory before researching: `squads memory query "<topic>"`
+- Create GitHub issues for follow-up work
+- Update `.agents/memory/{{SQUAD_ID}}/lead/state.md` with progress
+
+## Output
+Progress updates and work artifacts as appropriate.
+
+## Labels
+- lead
+- orchestration

package/dist/templates/memory/getting-started/state.md.template

@@ -0,0 +1,19 @@
+# Getting Started with Squads
+
+## What You've Set Up
+
+- **Your first squad** ready to run (`squads run {{SQUAD_ID}}`)
+- **Memory system** for persistent context
+- **Hooks** that sync status and memory automatically
+
+## Next Steps
+
+1. Run your squad: `squads run {{SQUAD_ID}} --execute`
+2. Check the dashboard: `squads dash`
+3. Create more squads in `.agents/squads/`
+
+## Tips
+
+- Check memory before researching: `squads memory query "<topic>"`
+- Use `squads context` for business alignment on complex tasks
+- Agents are reusable - if you do something twice, make it an agent

package/dist/templates/skills/squads-learn/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: squads-learn
+description: Capture learnings after completing work. Use when finishing a task, fixing a bug, discovering a pattern, or learning something worth remembering for future sessions. Helps build institutional memory.
+---
+
+# Capture Learnings
+
+After completing work, capture what you learned so future sessions can benefit.
+
+## When to Use
+
+- **After fixing a bug** - What was the root cause? How did you find it?
+- **After completing a feature** - What approach worked? What didn't?
+- **After research** - What did you discover? What's the key insight?
+- **When you notice a pattern** - Something that works consistently
+
+## How to Capture
+
+### Quick Learning (one-liner)
+
+```bash
+squads learn "The auth token needs to be refreshed after 1 hour, not when the API returns 401"
+```
+
+### With Context
+
+```bash
+squads learn "Always check memory before researching to avoid duplicate work" \
+  --squad engineering \
+  --category pattern \
+  --tags "memory,research,efficiency"
+```
+
+### Categories
+
+- `success` - Something that worked well
+- `failure` - Something that didn't work (learn from mistakes)
+- `pattern` - A reusable approach
+- `tip` - General advice
+
+## Workflow Integration
+
+### End of Task
+
+Before marking a task complete, ask yourself:
+1. What worked that I should remember?
+2. What didn't work that I should avoid?
+3. Is there a pattern here worth capturing?
+
+If yes to any → `squads learn "<insight>"`
+
+### Before Similar Tasks
+
+Check existing learnings:
+```bash
+squads learnings search "auth"
+squads learnings show engineering --tag auth
+```
+
+## Examples
+
+```bash
+# After fixing a bug
+squads learn "PostgreSQL connection pool exhaustion was caused by unclosed transactions in error paths" --category failure --tags db,postgres,connection
+
+# After successful implementation
+squads learn "Using TypeScript strict mode caught 3 type errors before runtime" --category success --tags typescript,types
+
+# Noticing a pattern
+squads learn "When context exceeds 70%, always run squads memory sync before continuing" --category pattern --tags context,memory
+
+# General tip
+squads learn "The gh CLI is faster than the GitHub API for simple operations" --category tip --tags github,cli
+```
+
+## View Learnings
+
+```bash
+squads learnings show <squad>           # Squad's learnings
+squads learnings search "<query>"       # Search all learnings
+squads learnings show engineering -n 5  # Last 5 for engineering
+```
+
+## Key Principle
+
+**Learnings compound.** Each captured insight makes future sessions smarter. A 30-second `squads learn` call can save hours of re-discovery.

package/dist/templates/skills/squads-workflow/instruction.md

@@ -0,0 +1,70 @@
+# Squads Workflow
+
+Use this skill when working with squads-cli to maintain persistent memory, track goals, and coordinate work.
+
+## Session Start
+
+At session start, you'll see `squads status` output automatically. For complex tasks, run:
+
+```bash
+squads context                # Get business context, goals, decisions
+squads memory query "<topic>" # Check what we already know
+```
+
+**Skip context loading for simple tasks** (typo fixes, quick questions).
+
+## Core Commands
+
+```bash
+# Context & Status
+squads context                # Business context for alignment
+squads status                 # Squad overview
+squads dash                   # Full dashboard
+
+# Memory
+squads memory query "<topic>" # Search memory
+squads memory show <squad>    # Squad's full memory
+
+# Goals
+squads goal list              # All active goals
+squads goal set <squad> "X"   # Add a goal
+
+# Running Agents
+squads run <squad>            # Run all agents in squad
+squads run <squad>/<agent>    # Run specific agent
+squads list                   # List all agents
+```
+
+## Workflow
+
+### Before Research
+Always check memory first to avoid re-researching:
+```bash
+squads memory query "topic"
+```
+
+### After Work
+Update memory with what you learned by editing:
+`.agents/memory/<squad>/<agent>/state.md`
+
+### Commits
+Include goal attribution when relevant:
+```
+feat: add user auth [goal:engineering/1]
+```
+
+## Agent Execution
+
+When a task could be automated:
+1. Check if agent exists: `squads list | grep <keyword>`
+2. If yes: `squads run <squad>/<agent>`
+3. If no: Create agent in `.agents/squads/<squad>/<name>.md`
+
+## Memory Locations
+
+- `.agents/memory/<squad>/<agent>/state.md` - Current knowledge
+- `.agents/memory/<squad>/<agent>/learnings.md` - Insights over time
+
+## Key Principle
+
+**Memory is your cross-session brain.** Without it, every session starts fresh. With it, you build on previous work.

package/docker/docker-compose.yml

@@ -115,11 +115,23 @@ services:
     environment:
       # Override database URL for container network
       DATABASE_URL: postgresql://squads:squads@postgres:5432/squads
+      # Redis URL for caching and event buffer
+      REDIS_URL: redis://redis:6379/0
+      # HQ path for agent file access
+      HQ_PATH: /hq
+      # GCP credentials for KMS
+      GOOGLE_APPLICATION_CREDENTIALS: /gcloud/application_default_credentials.json
+      GCP_PROJECT: agents-squads-prod
+    volumes:
+      - ../../hq:/hq:ro
+      - ~/.config/gcloud:/gcloud:ro
     ports:
       - "${SCHEDULER_API_PORT:-8090}:8090"
     depends_on:
       postgres:
         condition: service_healthy
+      redis:
+        condition: service_healthy
     healthcheck:
       test: ["CMD", "curl", "-f", "http://localhost:8090/health"]
       interval: 30s
@@ -199,8 +211,12 @@ services:
       HQ_PATH: /hq
       SLACK_WORKER_POLL_INTERVAL: "5"
       SLACK_WORKER_MODEL: "claude-sonnet-4-20250514"
+      # GCP credentials for KMS
+      GOOGLE_APPLICATION_CREDENTIALS: /gcloud/application_default_credentials.json
+      GCP_PROJECT: agents-squads-prod
     volumes:
       - ../../hq:/hq:ro
+      - ~/.config/gcloud:/gcloud:ro
     depends_on:
       postgres:
         condition: service_healthy

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squads-cli",
-  "version": "0.4.13",
+  "version": "0.5.0",
   "description": "Open source CLI for AI agent coordination and execution. Domain-aligned squads with persistent memory and goals.",
   "type": "module",
   "bin": {
@@ -16,6 +16,7 @@
   },
   "files": [
     "dist",
+    "templates",
     "docker/docker-compose.yml",
     "docker/docker-compose.engram.yml",
     "docker/.env.example",
@@ -28,7 +29,7 @@
     "docker/telemetry-ping/"
   ],
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && cp -r templates dist/",
     "dev": "tsup --watch",
     "start": "node dist/cli.js",
     "lint": "eslint src",
@@ -80,6 +81,7 @@
     "dotenv": "^17.2.3",
     "gray-matter": "^4.0.3",
     "inquirer": "^9.2.12",
+    "ioredis": "^5.9.2",
     "minimatch": "^10.1.1",
     "open": "^11.0.0",
     "ora": "^8.0.1",

package/templates/core/AGENTS.md.template

@@ -0,0 +1,64 @@
+# AGENTS.md
+# Project guidance for AI coding agents (vendor-neutral)
+
+This project uses AI agent squads for development and operations.
+
+## Getting Started
+
+If this project is not yet set up, run:
+```bash
+squads setup    # Guided onboarding (recommended)
+squads init     # Quick init (non-interactive)
+```
+
+## Provider: {{PROVIDER_NAME}}
+
+Configure in: `.agents/config/provider.yaml`
+
+## Repository Structure
+
+```
+.agents/
+├── squads/           # Agent team definitions
+│   └── <squad>/
+│       ├── SQUAD.md  # Squad definition
+│       └── *.md      # Agent files
+├── memory/           # Persistent context
+├── config/           # Provider and model configuration
+└── outputs/          # Agent outputs
+```
+
+## Agent Guidelines
+
+### Before Starting Work
+1. Run `squads status` to understand current state
+2. Check `squads memory query "<topic>"` for existing knowledge
+3. Read relevant SQUAD.md files
+
+### During Work
+- Update todo list frequently for visibility
+- Prefer editing existing files over creating new ones
+- Keep changes focused - one task per commit/PR
+
+### After Work
+- Update memory in `.agents/memory/<squad>/<agent>/state.md`
+- Create GitHub issues for follow-up work
+
+## Quick Reference
+
+```bash
+squads setup           # Guided onboarding (new projects)
+squads status          # Overview
+squads dash            # Full dashboard
+squads run <squad>     # Run a squad
+squads list            # All agents
+squads memory query X  # Search memory
+squads goal list       # View goals
+```
+
+## Model Aliases
+
+Agents can use semantic model names that resolve per provider:
+- `leader` - Most capable (complex tasks)
+- `worker` - Balanced (standard tasks)
+- `simple` - Fast (simple tasks)

package/templates/core/BUSINESS_BRIEF.md.template

@@ -0,0 +1,29 @@
+# Business Brief
+
+## #1 Priority
+
+**[Define your top priority here]**
+
+## Runway
+
+**Pressure**: LOW | MEDIUM | HIGH
+
+## Current Focus
+
+1. **[Focus area 1]** - Description
+2. **[Focus area 2]** - Description
+3. **[Focus area 3]** - Description
+
+## Blockers
+
+- None currently (or list blockers)
+
+## Decision Framework
+
+1. Does this drive the #1 priority?
+2. Is there a simpler approach?
+3. What's the opportunity cost?
+
+---
+
+*This file is read by `squads context` to provide business alignment.*

package/templates/core/CLAUDE.md.template

@@ -0,0 +1,50 @@
+# Claude-Specific Instructions
+
+Extends AGENTS.md with Claude Code specific features.
+
+## New Project Setup
+
+If this project needs squads setup, run:
+```bash
+squads setup    # Guided 6-step onboarding with prereq checks
+```
+
+This validates Docker, GitHub CLI, Claude CLI, then helps create first squad.
+
+## Skill Available
+
+Use `/squads-workflow` for detailed workflow guidance.
+
+## Session Hooks
+
+Claude Code hooks are configured in `.claude/settings.json`:
+- **SessionStart**: Runs `squads status` automatically
+- **Stop**: Syncs memory and prompts for learnings
+
+## Creating Agents
+
+Agents live in `.agents/squads/<squad-name>/<agent-name>.md`:
+
+```markdown
+# Agent Name
+
+## Purpose
+One sentence: what this agent does.
+
+## Model
+simple  # or: worker, leader
+
+## Instructions
+1. Specific step
+2. Another step
+3. Output location
+
+## Output
+What it produces and where it goes.
+```
+
+## Commit Signature
+
+```
+Co-Authored-By: Claude <model> <noreply@anthropic.com>
+```

package/templates/core/provider.yaml.template

@@ -0,0 +1,5 @@
+# Squads Provider Configuration
+# Selected during: squads init
+# Change with: squads init --provider <name>
+
+provider: {{PROVIDER}}

package/templates/first-squad/SQUAD.md.template

@@ -0,0 +1,23 @@
+# {{SQUAD_NAME}}
+
+{{SQUAD_DESCRIPTION}}
+
+## Goals
+
+- [ ] {{GOAL}}
+
+## Agents
+
+| Agent | Purpose |
+|-------|---------|
+| lead | Orchestrates the squad and coordinates work |
+
+## Pipeline
+
+`lead` (orchestrates all work)
+
+## Usage
+
+```bash
+squads run {{SQUAD_ID}} --execute
+```

package/templates/first-squad/lead.md.template

@@ -0,0 +1,44 @@
+# Lead Agent
+
+## Purpose
+Orchestrate the {{SQUAD_NAME}} squad to achieve its goals.
+
+## Model
+leader
+
+## Tools
+- Read
+- Write
+- Edit
+- Bash
+- WebSearch
+- WebFetch
+- Task
+
+## Instructions
+
+You are the lead agent for the {{SQUAD_NAME}} squad.
+
+**Goal**: {{GOAL}}
+
+### Approach
+
+1. **Understand the goal** - Break down what needs to be accomplished
+2. **Plan the work** - Create a clear execution plan
+3. **Execute** - Work through the plan step by step
+4. **Verify** - Confirm the goal is achieved
+5. **Document** - Update memory with learnings
+
+### Guidelines
+
+- Use the Task tool to spawn sub-agents for complex, parallelizable work
+- Check existing memory before researching: `squads memory query "<topic>"`
+- Create GitHub issues for follow-up work
+- Update `.agents/memory/{{SQUAD_ID}}/lead/state.md` with progress
+
+## Output
+Progress updates and work artifacts as appropriate.
+
+## Labels
+- lead
+- orchestration

package/templates/memory/getting-started/state.md.template

@@ -0,0 +1,19 @@
+# Getting Started with Squads
+
+## What You've Set Up
+
+- **Your first squad** ready to run (`squads run {{SQUAD_ID}}`)
+- **Memory system** for persistent context
+- **Hooks** that sync status and memory automatically
+
+## Next Steps
+
+1. Run your squad: `squads run {{SQUAD_ID}} --execute`
+2. Check the dashboard: `squads dash`
+3. Create more squads in `.agents/squads/`
+
+## Tips
+
+- Check memory before researching: `squads memory query "<topic>"`
+- Use `squads context` for business alignment on complex tasks
+- Agents are reusable - if you do something twice, make it an agent

package/templates/skills/squads-learn/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: squads-learn
+description: Capture learnings after completing work. Use when finishing a task, fixing a bug, discovering a pattern, or learning something worth remembering for future sessions. Helps build institutional memory.
+---
+
+# Capture Learnings
+
+After completing work, capture what you learned so future sessions can benefit.
+
+## When to Use
+
+- **After fixing a bug** - What was the root cause? How did you find it?
+- **After completing a feature** - What approach worked? What didn't?
+- **After research** - What did you discover? What's the key insight?
+- **When you notice a pattern** - Something that works consistently
+
+## How to Capture
+
+### Quick Learning (one-liner)
+
+```bash
+squads learn "The auth token needs to be refreshed after 1 hour, not when the API returns 401"
+```
+
+### With Context
+
+```bash
+squads learn "Always check memory before researching to avoid duplicate work" \
+  --squad engineering \
+  --category pattern \
+  --tags "memory,research,efficiency"
+```
+
+### Categories
+
+- `success` - Something that worked well
+- `failure` - Something that didn't work (learn from mistakes)
+- `pattern` - A reusable approach
+- `tip` - General advice
+
+## Workflow Integration
+
+### End of Task
+
+Before marking a task complete, ask yourself:
+1. What worked that I should remember?
+2. What didn't work that I should avoid?
+3. Is there a pattern here worth capturing?
+
+If yes to any → `squads learn "<insight>"`
+
+### Before Similar Tasks
+
+Check existing learnings:
+```bash
+squads learnings search "auth"
+squads learnings show engineering --tag auth
+```
+
+## Examples
+
+```bash
+# After fixing a bug
+squads learn "PostgreSQL connection pool exhaustion was caused by unclosed transactions in error paths" --category failure --tags db,postgres,connection
+
+# After successful implementation
+squads learn "Using TypeScript strict mode caught 3 type errors before runtime" --category success --tags typescript,types
+
+# Noticing a pattern
+squads learn "When context exceeds 70%, always run squads memory sync before continuing" --category pattern --tags context,memory
+
+# General tip
+squads learn "The gh CLI is faster than the GitHub API for simple operations" --category tip --tags github,cli
+```
+
+## View Learnings
+
+```bash
+squads learnings show <squad>           # Squad's learnings
+squads learnings search "<query>"       # Search all learnings
+squads learnings show engineering -n 5  # Last 5 for engineering
+```
+
+## Key Principle
+
+**Learnings compound.** Each captured insight makes future sessions smarter. A 30-second `squads learn` call can save hours of re-discovery.