squads-cli 0.2.0 → 0.2.2

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

@@ -0,0 +1,329 @@
+---
+name: squads-cli
+description: Squads CLI reference for autonomous agents — run squads, manage memory, check status, set goals, and operate the AI workforce. TRIGGER when using squads commands, dispatching agents, reading/writing memory, checking squad status, or operating the autonomous loop.
+context: fork
+---
+
+# Squads CLI
+
+The `squads` CLI is the operating system for your AI workforce. Agents are the primary users — they call these commands during execution to understand context, persist learnings, and coordinate with other squads.
+
+## Core Concepts
+
+| Concept | Description |
+|---------|-------------|
+| **Squad** | A team of agents in `.agents/squads/{name}/` — defined by `SQUAD.md` |
+| **Agent** | A markdown file (`{agent}.md`) inside a squad directory |
+| **Memory** | Persistent state in `.agents/memory/{squad}/{agent}/` — survives across runs |
+| **Target** | `squad/agent` notation (e.g., `engineering/issue-solver`) |
+| **Context cascade** | Layered context injection: SYSTEM → SQUAD → priorities → directives → state |
+
+## File Structure
+
+```
+.agents/
+├── config/SYSTEM.md              # Immutable rules (all agents)
+├── squads/{squad}/
+│   ├── SQUAD.md                  # Squad identity, goals, KPIs
+│   └── {agent}.md                # Agent definition
+└── memory/
+    ├── {squad}/
+    │   ├── priorities.md          # Current operational focus
+    │   ├── feedback.md            # Last cycle evaluation
+    │   ├── active-work.md         # Open PRs/issues
+    │   └── {agent}/
+    │       ├── state.md           # Agent's persistent state
+    │       └── learnings.md       # Accumulated insights
+    ├── company/directives.md      # Strategic overlay
+    └── daily-briefing.md          # Cross-squad context
+```
+
+---
+
+## Running Agents
+
+### Single Agent
+
+```bash
+# Run specific agent (two equivalent notations)
+squads run engineering/issue-solver
+squads run engineering -a issue-solver
+
+# With founder directive (replaces lead briefing)
+squads run engineering/issue-solver --task "Fix CI pipeline for PR #593"
+
+# Dry run — preview without executing
+squads run engineering --dry-run
+
+# Background execution
+squads run engineering/scanner -b          # Detached
+squads run engineering/scanner -w          # Detached but tail logs
+
+# Use different LLM provider
+squads run research/analyst --provider=google
+squads run research/analyst --provider=google --model=gemini-2.5-flash
+```
+
+### Squad Conversation
+
+Run an entire squad as a coordinated team. Lead briefs → workers execute → lead reviews → iterate until convergence.
+
+```bash
+squads run research                        # Sequential conversation
+squads run research --parallel             # All agents in parallel (tmux)
+squads run research --lead                 # Single orchestrator with Task tool
+squads run research --max-turns 10         # Limit conversation turns
+squads run research --cost-ceiling 15      # Budget cap in USD
+```
+
+### Autopilot (Autonomous Dispatch)
+
+No target = autopilot mode. CLI scores squads by priority, dispatches automatically.
+
+```bash
+squads run                                 # Start autopilot
+squads run --once                          # Single cycle then exit
+squads run --once --dry-run                # Preview what would dispatch
+squads run -i 15 --budget 50              # 15-min cycles, $50/day cap
+squads run --phased                        # Respect depends_on ordering
+squads run --max-parallel 3               # Up to 3 squads simultaneously
+```
+
+### Execution Options
+
+| Flag | Purpose |
+|------|---------|
+| `--verbose` | Detailed output with context sections logged |
+| `--timeout <min>` | Execution timeout (default: 30 min) |
+| `--effort <level>` | `high`, `medium`, `low` (default: from SQUAD.md or high) |
+| `--skills <ids>` | Load additional skills |
+| `--cloud` | Dispatch to cloud worker (requires `squads login`) |
+| `--no-verify` | Skip post-execution verification |
+| `--no-eval` | Skip post-run COO evaluation |
+| `--json` | Machine-readable output |
+
+---
+
+## Memory Operations
+
+Memory is how agents persist knowledge across runs. Files-first — everything is markdown on disk.
+
+### Read Memory
+
+```bash
+# View all memory for a squad
+squads memory read engineering
+
+# Search across ALL squad memory
+squads memory query "CI pipeline failures"
+squads memory query "agent performance"
+```
+
+### Write Memory
+
+```bash
+# Write insight to squad memory
+squads memory write research "MCP adoption rate at 15% — up from 8% last month"
+
+# Write to specific agent
+squads memory write engineering --agent issue-solver "PR #593 blocked by flaky test"
+```
+
+### Capture Learnings
+
+```bash
+# Quick learning capture
+squads learn "Google blocks headless Chrome OAuth — use cookie injection" \
+  --squad engineering --category pattern --tags "auth,chrome,e2e"
+
+# View learnings
+squads learnings
+squads learnings --squad engineering
+```
+
+### Sync Memory
+
+```bash
+squads sync                    # Pull remote changes
+squads sync --push             # Pull + push local changes
+squads sync --postgres         # Also sync to Postgres
+```
+
+---
+
+## Status & Monitoring
+
+### Squad Status
+
+```bash
+squads status                  # All squads overview
+squads status engineering      # Specific squad details
+squads status -v               # Verbose with agent details
+squads status --json           # Machine-readable
+```
+
+### Dashboards
+
+```bash
+squads dash                    # Overview dashboard
+squads dash engineering        # Squad-specific dashboard
+squads dash --ceo              # Executive summary
+squads dash --full             # Include GitHub PR/issue stats (~30s)
+squads dash --list             # List available dashboards
+```
+
+### Execution History
+
+```bash
+squads exec list               # Recent executions
+squads exec list --squad eng   # Filter by squad
+squads exec show <id>          # Execution details
+squads exec stats              # Aggregate statistics
+```
+
+### Cost Tracking
+
+```bash
+squads cost                    # Today + this week
+squads cost --squad research   # Squad-specific costs
+squads cost --json             # Machine-readable
+```
+
+### Health & Readiness
+
+```bash
+squads doctor                  # Check tools, auth, project readiness
+squads doctor -v               # Verbose with install hints
+squads eval engineering/scanner  # Agent readiness score
+```
+
+---
+
+## Goals & Priorities
+
+Goals are aspirational (in SQUAD.md). Priorities are operational (in priorities.md).
+
+### Set Goals
+
+```bash
+squads goal set engineering "Zero CI failures on main branch"
+squads goal list                    # All squads
+squads goal list engineering        # Specific squad
+squads goal complete engineering 1  # Mark done
+squads goal progress engineering 1 "75%"
+```
+
+### Business Context
+
+```bash
+squads context                           # Full business context
+squads context --squad engineering       # Squad-focused context
+squads context --topic "pricing"         # Topic-focused search
+squads context --json                    # Agent-consumable format
+```
+
+---
+
+## Environment & Configuration
+
+### Execution Environment
+
+```bash
+squads env show engineering              # View MCP servers, skills, model, budget
+squads env show engineering --json       # Machine-readable
+squads env prompt engineering            # Ready-to-use prompt for Claude Code
+```
+
+### Provider Management
+
+```bash
+squads providers                         # List available LLM CLI providers
+```
+
+### Sessions
+
+```bash
+squads sessions                          # Active Claude Code sessions
+squads session start                     # Start new session
+squads session end                       # End current session
+```
+
+---
+
+## Autonomous Scheduling
+
+The daemon runs agents on configured schedules without human intervention.
+
+```bash
+squads auto start                  # Start scheduling daemon
+squads auto stop                   # Stop daemon
+squads auto status                 # Show daemon status + next runs
+squads auto pause "quota exhausted"  # Pause with reason
+squads auto resume                 # Resume after pause
+```
+
+---
+
+## Common Patterns
+
+### Agent Self-Context (during execution)
+
+Agents call these to understand their environment:
+
+```bash
+# What am I working with?
+squads env show ${SQUAD_NAME} --json
+
+# What do I know?
+squads memory read ${SQUAD_NAME}
+
+# What's happening across the org?
+squads status --json
+
+# What's the business context?
+squads context --squad ${SQUAD_NAME} --json
+```
+
+### Post-Execution Memory Update
+
+```bash
+# Persist what you learned
+squads memory write ${SQUAD_NAME} "Key finding from this run"
+squads learn "Pattern discovered: X causes Y" --squad ${SQUAD_NAME} --category pattern
+
+# Sync to remote
+squads sync --push
+```
+
+### Dispatch Another Agent
+
+```bash
+# From within an agent, trigger another
+squads run engineering/issue-solver --task "Fix the bug I found in #461" -b
+```
+
+### Check Before Creating
+
+Before creating issues/PRs, check what exists:
+
+```bash
+squads status engineering -v    # See active work
+squads memory read engineering  # See known issues
+squads context --squad engineering --json  # Full context
+```
+
+## Full Command Reference
+
+See `references/commands.md` for complete command listing with all flags.
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| `squads: command not found` | `npm install -g squads-cli` |
+| No squads found | Run `squads init` to create `.agents/` |
+| Agent not found | Check path: `.agents/squads/{squad}/{agent}.md` |
+| Memory not persisting | Check `.agents/memory/` exists, run `squads sync` |
+| Wrong provider | Set `--provider` flag or `provider:` in SQUAD.md frontmatter |
+| API quota exhausted | `squads auto pause "quota"`, switch provider, or wait |
+| Context too large | Use `--effort low` or reduce context layers |

package/templates/seed/skills/squads-cli/references/commands.md

@@ -0,0 +1,181 @@
+# Squads CLI — Full Command Reference
+
+## All Commands
+
+| Command | Description |
+|---------|-------------|
+| `squads init` | Create `.agents/` directory with starter squads |
+| `squads add <name>` | Add a new squad with directory structure |
+| `squads run [target]` | Run squad, agent, or autopilot (no target = autopilot) |
+| `squads orchestrate <squad>` | Run squad with lead agent orchestration |
+| `squads status [squad]` | Show squad status and state |
+| `squads env show <squad>` | View execution environment (MCP, skills, model) |
+| `squads env prompt <squad>` | Output ready-to-use prompt for execution |
+| `squads context` | Get business context for alignment |
+| `squads dashboard [name]` | Show dashboards (`squads dash` alias) |
+| `squads exec list` | List recent executions |
+| `squads exec show <id>` | Show execution details |
+| `squads exec stats` | Show execution statistics |
+| `squads cost` | Show cost summary (today, week, by squad) |
+| `squads budget <squad>` | Check budget status for a squad |
+| `squads health` | Quick health check for infrastructure |
+| `squads doctor` | Check local tools, auth, project readiness |
+| `squads history` | Show recent agent execution history |
+| `squads results [squad]` | Show git activity + KPI goals vs actuals |
+| `squads goal set <squad> <desc>` | Set a goal for a squad |
+| `squads goal list [squad]` | List goals |
+| `squads goal complete <squad> <i>` | Mark goal completed |
+| `squads goal progress <squad> <i> <p>` | Update goal progress |
+| `squads kpi` | Track and analyze squad KPIs |
+| `squads progress` | Track active and completed agent tasks |
+| `squads feedback` | Record and view execution feedback |
+| `squads autonomy` | Show autonomy score and confidence metrics |
+| `squads stats [squad]` | Agent outcome scorecards: merge rate, waste |
+| `squads memory query <q>` | Search across all squad memory |
+| `squads memory read <squad>` | Show memory for a squad |
+| `squads memory write <squad> <content>` | Add to squad memory |
+| `squads memory list` | List all memory entries |
+| `squads memory sync` | Sync memory from git |
+| `squads memory search <q>` | Search stored conversations (requires login) |
+| `squads memory extract` | Extract memories from recent conversations |
+| `squads learn <insight>` | Capture a learning for future sessions |
+| `squads learnings` | View and search learnings |
+| `squads sync` | Git memory synchronization |
+| `squads trigger` | Manage smart triggers |
+| `squads approval` | Manage approval requests |
+| `squads auto start` | Start autonomous scheduling daemon |
+| `squads auto stop` | Stop scheduling daemon |
+| `squads auto status` | Show daemon status and next runs |
+| `squads auto pause [reason]` | Pause daemon |
+| `squads auto resume` | Resume paused daemon |
+| `squads sessions` | Show active Claude Code sessions |
+| `squads session` | Manage current session lifecycle |
+| `squads detect-squad` | Detect squad from cwd (for hooks) |
+| `squads login` | Log in to Squads platform |
+| `squads logout` | Log out |
+| `squads whoami` | Show current user |
+| `squads eval <target>` | Evaluate agent readiness |
+| `squads deploy` | Deploy agents to Squads platform |
+| `squads cognition` | Business cognition engine |
+| `squads providers` | Show available LLM CLI providers |
+| `squads update` | Check for and install updates |
+| `squads version` | Show version information |
+
+## `squads run` — Full Options
+
+```
+squads run [target] [options]
+
+Target formats:
+  (none)                    Autopilot mode
+  <squad>                   Squad conversation
+  <squad>/<agent>           Single agent
+  <squad> -a <agent>        Single agent (flag notation)
+
+Agent execution:
+  -v, --verbose             Detailed output
+  -d, --dry-run             Preview without executing
+  -t, --timeout <min>       Timeout in minutes (default: 30)
+  -b, --background          Run detached
+  -w, --watch               Run detached but tail logs
+  --task <directive>        Founder directive
+  --effort <level>          high | medium | low
+  --skills <ids...>         Additional skills to load
+  --provider <provider>     anthropic | google | openai | mistral | xai | aider | ollama
+  --model <model>           opus | sonnet | haiku | gemini-2.5-flash | gpt-4o | etc.
+  --cloud                   Dispatch to cloud worker
+  --no-verify               Skip post-execution verification
+  --no-eval                 Skip COO evaluation
+  --use-api                 Use API credits instead of subscription
+
+Squad conversation:
+  -p, --parallel            All agents in parallel (tmux)
+  -l, --lead                Single orchestrator with Task tool
+  --max-turns <n>           Max conversation turns (default: 20)
+  --cost-ceiling <usd>      Cost ceiling in USD (default: 25)
+
+Autopilot:
+  -i, --interval <min>      Minutes between cycles (default: 30)
+  --max-parallel <count>    Max parallel squad loops (default: 2)
+  --budget <usd>            Daily budget cap (default: 0 = unlimited)
+  --once                    Single cycle then exit
+  --phased                  Use depends_on phase ordering
+
+Output:
+  -j, --json                Machine-readable output
+```
+
+## `squads init` — Full Options
+
+```
+squads init [options]
+
+  -p, --provider <provider>  LLM provider (claude, gemini, openai, ollama, none)
+  --pack <packs...>          Additional squads: engineering, marketing, operations, all
+  --skip-infra               Skip infrastructure setup
+  --force                    Skip requirement checks
+  -y, --yes                  Accept defaults (non-interactive)
+  -q, --quick                Files only, skip prompts
+```
+
+## `squads memory` — Full Options
+
+```
+squads memory query <query>           Search all memory
+squads memory read <squad>            Show squad memory
+squads memory write <squad> <content> Write to memory
+  --agent <agent>                     Target specific agent
+squads memory list                    List all entries
+squads memory sync [options]          Sync from git
+  --push                              Also push changes
+squads memory search <query>          Search conversations (requires login)
+squads memory extract                 Extract from recent conversations
+```
+
+## `squads context` — Full Options
+
+```
+squads context [options]
+
+  -s, --squad <squad>     Focus on specific squad
+  -t, --topic <topic>     Search memory for topic
+  -a, --agent             JSON for agent consumption
+  -j, --json              JSON output
+  -v, --verbose           Additional details
+```
+
+## Global Patterns
+
+Every command supports:
+- `--json` or `-j` for machine-readable output
+- `--verbose` or `-v` for detailed output
+- `--help` or `-h` for usage information
+
+## SQUAD.md Frontmatter
+
+Squads are configured via YAML frontmatter in SQUAD.md:
+
+```yaml
+---
+name: engineering
+repo: my-org/engineering
+provider: anthropic
+model: opus
+effort: high
+depends_on: [data]
+kpis:
+  merge_rate:
+    target: ">80%"
+    unit: percentage
+---
+```
+
+| Field | Purpose |
+|-------|---------|
+| `name` | Squad identifier |
+| `repo` | GitHub repo (org/repo format) |
+| `provider` | Default LLM provider |
+| `model` | Default model |
+| `effort` | Default effort level |
+| `depends_on` | Phase ordering dependencies |
+| `kpis` | KPI definitions for tracking |

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

@@ -0,0 +1,51 @@
+---
+name: Company
+lead: manager
+channel: "#company"
+model: sonnet
+effort: high
+schedule: "0 9 * * 1-5"
+depends_on: ["*"]
+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 Squad
+
+Orchestrates all squads, evaluates outputs, and closes the feedback loop. Reads `BUSINESS_BRIEF.md` and `directives.md` to ensure all work advances business goals.
+
+## Goals
+
+- [ ] Evaluate squad outputs against the business focus in `BUSINESS_BRIEF.md`
+- [ ] Write feedback per squad: what was valuable, what was noise, what to prioritize next
+- [ ] Ensure no duplicate work across squads (check active-work.md)
+- [ ] Track progress toward directives and flag when goals need updating
+
+## 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/templates/seed/squads/company/company-critic.md

@@ -0,0 +1,57 @@
+---
+name: Company Critic
+role: evaluator
+squad: "company"
+provider: "{{PROVIDER}}"
+model: sonnet
+effort: medium
+trigger: "event"
+cooldown: "1h"
+timeout: 1800
+max_retries: 1
+tools:
+  - Read
+  - Write
+---
+
+# Company Critic
+
+## Role
+
+Find what's broken in how the workforce operates. Challenge assumptions, identify waste, propose fixes.
+
+## How You Work
+
+1. Read the evaluator's scores from `.agents/memory/company/company-eval/state.md`
+2. Read squad states from `.agents/memory/{squad}/*/state.md`
+3. Look for patterns: repeated failures, duplicate work, misaligned effort
+4. Write critique to `.agents/memory/company/company-critic/state.md`
+
+## Output
+
+```markdown
+# Workforce Critique — {date}
+
+## Systemic Issues
+| # | Issue | Affected Squads | Evidence | Severity |
+|---|-------|----------------|----------|----------|
+| 1 | {pattern} | {squads} | {what you observed} | High/Med/Low |
+
+## Waste
+Work that produced no business value. Be specific.
+
+## Process Improvements
+| # | Proposal | Expected Impact | Effort |
+|---|----------|----------------|--------|
+| 1 | {change} | {what improves} | Low/Med/High |
+
+## Questions for Human Operator
+Decisions only a human can make.
+```
+
+## Constraints
+
+- Critique the process, not the agents — agents follow instructions
+- Every issue needs evidence from memory files, not speculation
+- "Things could be better" is not a critique. Name the problem, show the evidence, propose the fix
+- If everything is working well, say so in one line and stop

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

@@ -0,0 +1,57 @@
+---
+name: Company Evaluator
+role: evaluator
+squad: "company"
+provider: "{{PROVIDER}}"
+model: sonnet
+effort: medium
+trigger: "event"
+cooldown: "1h"
+timeout: 1800
+max_retries: 1
+tools:
+  - Read
+  - Write
+---
+
+# Company Evaluator
+
+## Role
+
+Evaluate squad outputs against business goals. Answer: "Did the squads produce value, or noise?"
+
+## How You Work
+
+1. Read business goals from `.agents/BUSINESS_BRIEF.md`
+2. Read directives from `.agents/memory/company/directives.md`
+3. Read each squad's recent state from `.agents/memory/{squad}/*/state.md`
+4. Score each squad's output using the rubric below
+5. Write evaluation to `.agents/memory/company/company-eval/state.md`
+
+## Output
+
+```markdown
+# Squad Evaluation — {date}
+
+## Scores
+| Squad | Relevance (1-5) | Quality (1-5) | Impact (1-5) | Summary |
+|-------|-----------------|---------------|---------------|---------|
+| {squad} | {score} | {score} | {score} | {one-line assessment} |
+
+## Valuable (continue)
+- {squad}: {specific output that advanced business goals}
+
+## Noise (stop)
+- {squad}: {specific output that wasted effort or missed the point}
+
+## Recommendations
+What each squad should focus on next cycle, ranked by business impact.
+```
+
+## Constraints
+
+- Score against BUSINESS_BRIEF.md goals, not general quality
+- "Relevance" = does this advance the business focus?
+- "Quality" = is it sourced, specific, and actionable?
+- "Impact" = would a human act on this?
+- Be specific — "good work" is not feedback. Name the output, explain why.