squads-cli 0.4.13 → 0.6.0

package/dist/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/dist/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/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/seed/BUSINESS_BRIEF.md.template

@@ -0,0 +1,27 @@
+# Business Brief — {{BUSINESS_NAME}}
+
+## About
+
+{{BUSINESS_DESCRIPTION}}
+
+## Research Focus
+
+{{BUSINESS_FOCUS}}
+
+## Priority
+
+**#1**: Deliver value in the research focus above.
+
+## Pressure
+
+LOW — Learning phase. Explore, experiment, report findings.
+
+## Decision Framework
+
+1. Does this advance our focus area?
+2. Is there a simpler approach for 80% of the value?
+3. What's the opportunity cost?
+
+---
+
+*Read by `squads context` for business alignment. Updated by the manager agent as understanding deepens.*

package/dist/templates/seed/CLAUDE.md.template

@@ -0,0 +1,69 @@
+# AI Workforce Operating Manual
+
+This project uses [Agents Squads](https://agents-squads.com) to run an AI workforce.
+
+## Structure
+
+```
+.agents/
+├── BUSINESS_BRIEF.md           # What this workforce focuses on
+├── squads/                     # Squad definitions
+│   ├── company/                # Operations squad
+│   │   ├── SQUAD.md            # Squad config
+│   │   ├── manager.md          # AI manager (orchestrates everything)
+│   │   ├── event-dispatcher.md # Routes events to squads
+│   │   ├── goal-tracker.md     # Tracks business objectives
+│   │   ├── company-eval.md     # Evaluates outputs
+│   │   └── company-critic.md   # Identifies improvements
+│   └── research/               # Research squad
+│       ├── SQUAD.md            # Squad config
+│       ├── researcher.md       # Market/competitor research
+│       ├── analyst.md          # Synthesizes insights
+│       ├── research-eval.md    # Evaluates quality
+│       └── research-critic.md  # Critiques methodology
+├── memory/                     # Persistent state
+│   ├── company/manager/state.md
+│   └── research/researcher/state.md
+├── skills/
+│   └── squads-cli/SKILL.md     # CLI operations manual
+└── config/
+    └── provider.yaml           # LLM provider config
+```
+
+## How It Works
+
+A **manager agent** coordinates your AI workforce using the `squads` CLI:
+1. Reads business context from `BUSINESS_BRIEF.md`
+2. Checks status: `squads dash --json`
+3. Dispatches work to squad agents
+4. Tracks results: `squads goal progress`, `squads kpi record`
+5. Persists learnings: `squads memory write`
+
+## For Humans
+
+Talk to Claude naturally. It knows about the squads system via this file.
+
+Common commands:
+- `squads status` — What's happening now
+- `squads dash` — Full dashboard
+- `squads run company/manager` — Run the AI manager
+- `squads memory read <squad>` — What has the squad learned
+- `squads goal list` — Business objectives
+
+## For Agents
+
+All agents should use the `squads-cli` skill for CLI operations.
+Memory persists across sessions via `.agents/memory/`.
+Git is the coordination layer — commit everything.
+
+## Decision Framework
+
+- **Execute**: Clear task, low risk → do it
+- **Escalate**: Ambiguous scope, high cost → ask the human
+- **Learn**: Record what worked/didn't → `squads memory write`
+
+## Commit Signature
+
+```
+Co-Authored-By: Claude <noreply@anthropic.com>
+```

package/dist/templates/seed/config/provider.yaml

@@ -0,0 +1,4 @@
+# Squads Provider Configuration
+# Selected during: squads init
+
+provider: {{PROVIDER}}

package/dist/templates/seed/hooks/settings.json.template

@@ -0,0 +1,31 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "squads status",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "squads memory sync --no-push",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "squads memory sync --push",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}

package/dist/templates/seed/memory/company/manager/state.md

@@ -0,0 +1,16 @@
+# Manager State
+
+## Last Run
+Never — awaiting first execution.
+
+## Business Understanding
+Pending — will be populated after reading BUSINESS_BRIEF.md.
+
+## Active Squads
+- company (5 agents)
+- research (4 agents)
+
+## Priorities
+1. Read and understand business context
+2. Run initial research
+3. Establish operational rhythm

package/dist/templates/seed/memory/engineering/issue-solver/state.md

@@ -0,0 +1,12 @@
+# Issue Solver State
+
+## Last Run
+Never — awaiting first execution.
+
+## Issues Solved
+None yet.
+
+## Priorities
+1. Check for open GitHub issues
+2. Pick highest-priority solvable issue
+3. Create a PR with the fix

package/dist/templates/seed/memory/intelligence/intel-lead/state.md

@@ -0,0 +1,9 @@
+# Intel Lead - State
+
+> Updated: never
+
+## Last Brief
+No briefs produced yet. First run pending.
+
+## Coverage
+No topics covered yet.

package/dist/templates/seed/memory/marketing/content-drafter/state.md

@@ -0,0 +1,12 @@
+# Content Drafter State
+
+## Last Run
+Never — awaiting first execution.
+
+## Drafts Created
+None yet.
+
+## Priorities
+1. Read business brief for context
+2. Draft first piece of content
+3. Establish content rhythm

package/dist/templates/seed/memory/operations/ops-lead/state.md

@@ -0,0 +1,12 @@
+# Ops Lead State
+
+## Last Run
+Never — awaiting first execution.
+
+## Squads Observed
+None yet.
+
+## Priorities
+1. Read all squad states
+2. Identify what needs founder attention
+3. Establish daily briefing rhythm

package/dist/templates/seed/memory/research/researcher/state.md

@@ -0,0 +1,10 @@
+# Researcher State
+
+## Last Run
+Never — awaiting first execution.
+
+## Research Focus
+Pending — will be set by manager after reading BUSINESS_BRIEF.md.
+
+## Findings
+None yet.

package/dist/templates/seed/skills/gh/SKILL.md

@@ -0,0 +1,57 @@
+# gh — GitHub CLI Operations
+
+You have access to `gh` (GitHub CLI) for repository and project management.
+
+## Issues
+
+```bash
+gh issue list                              # List open issues
+gh issue list --label "bug"                # Filter by label
+gh issue view <number>                     # View issue details
+gh issue create --title "..." --body "..." # Create issue
+gh issue close <number>                    # Close issue
+gh issue comment <number> --body "..."     # Add comment
+```
+
+## Pull Requests
+
+```bash
+gh pr list                                 # List open PRs
+gh pr view <number>                        # View PR details
+gh pr create --title "..." --body "..."    # Create PR
+gh pr merge <number>                       # Merge PR
+gh pr review <number> --approve            # Approve PR
+gh pr checks <number>                      # View CI status
+gh pr diff <number>                        # View PR diff
+```
+
+## Repository
+
+```bash
+gh repo view                               # View repo info
+gh repo clone <owner/repo>                 # Clone repo
+gh api repos/<owner>/<repo>                # Raw API access
+```
+
+## Workflow Runs
+
+```bash
+gh run list                                # List recent runs
+gh run view <id>                           # View run details
+gh run watch <id>                          # Watch run in progress
+```
+
+## Search
+
+```bash
+gh search repos "<query>"                  # Search repos
+gh search issues "<query>"                 # Search issues
+gh search prs "<query>"                    # Search PRs
+```
+
+## Best Practices
+
+- **Check before creating**: Search existing issues/PRs before creating duplicates
+- **Use labels**: Filter and organize with labels
+- **Link issues**: Reference issues in PR descriptions with `Fixes #N`
+- **Review CI**: Always check `gh pr checks` before merging

package/dist/templates/seed/skills/squads-cli/SKILL.md

@@ -0,0 +1,88 @@
+# squads-cli — Operations Manual
+
+You have access to the `squads` CLI for managing your AI workforce.
+
+## Execute (Daily Operations)
+
+```bash
+squads run <squad>/<agent>        # Execute a specific agent
+squads run <squad> --lead         # Orchestrate full squad
+squads run <squad> --parallel     # Run all agents in parallel
+squads list                       # Discover squads and agents
+squads exec list                  # Recent execution history
+squads exec stats                 # Execution statistics
+squads orchestrate <squad>        # Multi-agent coordination
+squads env prompt <squad> -a <agent>  # Get agent prompt
+```
+
+## Understand (Situational Awareness)
+
+```bash
+squads dash --json                # Full dashboard (use --json for parsing)
+squads status [squad]             # Quick status snapshot
+squads context --json             # Business context feed
+squads cost                       # Cost tracking
+squads budget <squad>             # Budget check
+squads health                     # Infrastructure health
+squads history                    # Execution patterns
+squads results [squad]            # Squad output + KPIs
+```
+
+## Track (Objectives + Metrics)
+
+```bash
+squads goal set <squad> "<goal>"  # Set a business objective
+squads goal list [squad]          # List goals
+squads goal progress <squad> <n> "<update>"  # Update progress
+squads goal complete <squad> <n>  # Mark goal done
+squads kpi list                   # List all KPIs
+squads kpi show <squad>           # Squad KPIs
+squads kpi record <squad> <kpi> <value>  # Record metric
+squads kpi trend <squad> <kpi>    # Show trend
+squads feedback add <squad> <1-5> "<feedback>"  # Rate output
+squads autonomy                   # Self-assessment
+```
+
+## Learn (Memory + Knowledge)
+
+```bash
+squads memory read <squad>        # Load squad memory
+squads memory write <squad> "<insight>"  # Persist learning
+squads memory search "<query>"    # Search all memory
+squads memory list                # List all entries
+squads learn "<insight>"          # Capture learning
+squads learnings show <squad>     # View learnings
+squads sync --push                # Sync memory to git
+```
+
+## Schedule (Automation)
+
+```bash
+squads trigger list               # View triggers
+squads trigger fire <squad>       # Manual trigger
+squads autonomous start           # Start scheduler
+squads approval list              # Check pending approvals
+```
+
+## Decision Framework
+
+- **Read before act**: Always `squads context --json` or `squads memory read` first
+- **Track everything**: Use `goal progress`, `kpi record`, `feedback add`
+- **Persist learnings**: `squads memory write` after discoveries
+- **Use JSON**: Add `--json` when parsing output programmatically
+- **Escalate wisely**: High cost or unclear scope → ask the human
+
+## JSON Output
+
+All key commands support `--json` for structured output:
+```json
+{
+  "ok": true,
+  "command": "status",
+  "data": { ... },
+  "error": null,
+  "meta": { "duration_ms": 1230, "connected": true }
+}
+```
+
+When piped (non-TTY), commands auto-output JSON.

package/dist/templates/seed/squads/company/SQUAD.md

@@ -0,0 +1,49 @@
+---
+name: Company Operations
+lead: manager
+channel: "#company"
+model: sonnet
+effort: high
+schedule: "0 9 * * 1-5"
+approvals:
+  policy:
+    auto:
+      - memory.update
+      - goal.set
+      - agent.run.readonly
+    approve:
+      - trigger.fire
+      - agent.run.write
+      - pr.merge
+    confirm:
+      - deploy.production
+      - budget.override
+  thresholds:
+    spend: 50
+    bulk_actions: 5
+    files_changed: 20
+---
+
+# Company Operations
+
+Manages the AI workforce. The manager agent orchestrates all squads, coordinates leads, and runs daily operations.
+
+## Goals
+
+- [ ] Understand business context and set up initial squads
+- [ ] Establish daily operational rhythm
+- [ ] Track and report on business objectives
+
+## Agents
+
+| Agent | Role | Purpose |
+|-------|------|---------|
+| manager | lead | Orchestrates squads, coordinates work, daily operations |
+| event-dispatcher | doer | Monitors events, dispatches to relevant squads |
+| goal-tracker | doer | Tracks business objectives, updates progress |
+| company-eval | evaluator | Evaluates squad outputs and business impact |
+| company-critic | critic | Critiques process, identifies improvements |
+
+## Pipeline
+
+`manager` → dispatches to squads → `company-eval` scores → `company-critic` improves

package/dist/templates/seed/squads/company/company-critic.md

@@ -0,0 +1,21 @@
+---
+name: Company Critic
+role: critic
+model: sonnet
+effort: medium
+---
+
+# Company Critic
+
+Identify systemic issues and improvements across the workforce.
+
+## Instructions
+
+1. Review recent evaluations and feedback trends
+2. Identify recurring issues (missed goals, low quality, wasted effort)
+3. Propose process improvements with specific, actionable suggestions
+4. Record improvement proposals: `squads learn "<improvement>"`
+
+## Output
+
+Improvement proposals recorded via `squads learn` and written to memory

package/dist/templates/seed/squads/company/company-eval.md

@@ -0,0 +1,21 @@
+---
+name: Company Evaluator
+role: evaluator
+model: sonnet
+effort: medium
+---
+
+# Company Evaluator
+
+Evaluate squad outputs and measure business impact.
+
+## Instructions
+
+1. Review recent squad outputs (git commits, reports, memory updates)
+2. Score each output on: relevance (1-5), quality (1-5), impact (1-5)
+3. Record feedback: `squads feedback add <squad> <rating> "<feedback>"`
+4. Identify high-performing and underperforming squads
+
+## Output
+
+Evaluation scores and feedback recorded via `squads feedback add`

package/dist/templates/seed/squads/company/event-dispatcher.md

@@ -0,0 +1,21 @@
+---
+name: Event Dispatcher
+role: doer
+model: haiku
+effort: medium
+---
+
+# Event Dispatcher
+
+Monitor events and dispatch work to relevant squads.
+
+## Instructions
+
+1. Check for new events (GitHub activity, scheduled triggers, manual requests)
+2. Determine which squad should handle each event
+3. Create issues or trigger agent runs as appropriate
+4. Log dispatched events to memory
+
+## Output
+
+Event dispatch log written to `.agents/memory/company/event-dispatcher/state.md`

package/dist/templates/seed/squads/company/goal-tracker.md

@@ -0,0 +1,21 @@
+---
+name: Goal Tracker
+role: doer
+model: haiku
+effort: medium
+---
+
+# Goal Tracker
+
+Track business objectives and update progress across all squads.
+
+## Instructions
+
+1. Read all squad goals: `squads goal list --json`
+2. Check recent activity and execution results
+3. Update goal progress where measurable changes occurred
+4. Identify stalled goals and flag for manager attention
+
+## Output
+
+Goal status report and progress updates via `squads goal progress`