squads-cli 0.2.1 → 0.2.2

package/templates/seed/memory/company/company.md

@@ -0,0 +1,31 @@
+---
+type: "company-context"
+updated: "{{CURRENT_DATE}}"
+owner: "manager"
+---
+
+# Company Context
+
+## Mission
+
+{{BUSINESS_DESCRIPTION}}
+
+## What We Build
+
+(Add product or service details here)
+
+## Who Uses It
+
+(Add target customer details here)
+
+## Product
+
+| Offering | Role |
+|----------|------|
+| (Add your products/services) | |
+
+## Alignment
+
+- Results over promises — ship working things
+- Simple over clever — prefer straightforward solutions
+- Customer zero — use your own product

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

@@ -1,84 +1,329 @@
-# squads-cli — Operations Manual
+---
+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
+---
 
-You have access to the `squads` CLI for managing your AI workforce.
+# Squads CLI
 
-## Execute (Daily Operations)
+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 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
+squads status                  # All squads overview
+squads status engineering      # Specific squad details
+squads status -v               # Verbose with agent details
+squads status --json           # Machine-readable
 ```
 
-## Understand (Situational Awareness)
+### Dashboards
 
 ```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 history                    # Execution history
+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
 ```
 
-## Track (Objectives + Metrics)
+### Execution History
 
 ```bash
-squads goal set <squad> "<goal>"  # Set a business objective
-squads goal list [squad]          # List goals
-squads goal complete <squad> <n>  # Mark goal done
-squads kpi list                   # List all KPIs
-squads kpi show <squad>           # Squad KPIs
-squads kpi trend <squad> <kpi>    # Show trend
-squads feedback add <squad> <1-5> "<feedback>"  # Rate output
-squads autonomy                   # Self-assessment
+squads exec list               # Recent executions
+squads exec list --squad eng   # Filter by squad
+squads exec show <id>          # Execution details
+squads exec stats              # Aggregate statistics
 ```
 
-## Learn (Memory + Knowledge)
+### Cost Tracking
 
 ```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
+squads cost                    # Today + this week
+squads cost --squad research   # Squad-specific costs
+squads cost --json             # Machine-readable
 ```
 
-## Schedule (Automation)
+### Health & Readiness
 
 ```bash
-squads trigger list               # View triggers
-squads trigger fire <squad>       # Manual trigger
-squads autonomous start           # Start scheduler
-squads approval list              # Check pending approvals
+squads doctor                  # Check tools, auth, project readiness
+squads doctor -v               # Verbose with install hints
+squads eval engineering/scanner  # Agent readiness score
 ```
 
-## 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
+## Goals & Priorities
 
-## JSON Output
+Goals are aspirational (in SQUAD.md). Priorities are operational (in priorities.md).
 
-All key commands support `--json` for structured output:
-```json
-{
-  "ok": true,
-  "command": "status",
-  "data": { ... },
-  "error": null,
-  "meta": { "duration_ms": 1230, "connected": true }
-}
+### 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
 ```
 
-When piped (non-TTY), commands auto-output JSON.
+### 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/company-critic.md

@@ -1,8 +1,14 @@
 ---
 name: Company Critic
-role: critic
+role: evaluator
+squad: "company"
+provider: "{{PROVIDER}}"
 model: sonnet
 effort: medium
+trigger: "event"
+cooldown: "1h"
+timeout: 1800
+max_retries: 1
 tools:
   - Read
   - Write
@@ -10,16 +16,18 @@ tools:
 
 # Company Critic
 
+## Role
+
 Find what's broken in how the workforce operates. Challenge assumptions, identify waste, propose fixes.
 
-## Instructions
+## 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 Format (REQUIRED)
+## Output
 
 ```markdown
 # Workforce Critique — {date}
@@ -41,7 +49,7 @@ Work that produced no business value. Be specific.
 Decisions only a human can make.
 ```
 
-## Rules
+## Constraints
 
 - Critique the process, not the agents — agents follow instructions
 - Every issue needs evidence from memory files, not speculation

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

@@ -1,8 +1,14 @@
 ---
 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
@@ -10,9 +16,11 @@ tools:
 
 # Company Evaluator
 
-Evaluate squad outputs against business goals. Your job is to answer: "Did the squads produce value, or noise?"
+## Role
 
-## Instructions
+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`
@@ -20,7 +28,7 @@ Evaluate squad outputs against business goals. Your job is to answer: "Did the s
 4. Score each squad's output using the rubric below
 5. Write evaluation to `.agents/memory/company/company-eval/state.md`
 
-## Output Format (REQUIRED)
+## Output
 
 ```markdown
 # Squad Evaluation — {date}
@@ -40,7 +48,7 @@ Evaluate squad outputs against business goals. Your job is to answer: "Did the s
 What each squad should focus on next cycle, ranked by business impact.
 ```
 
-## Rules
+## Constraints
 
 - Score against BUSINESS_BRIEF.md goals, not general quality
 - "Relevance" = does this advance the business focus?