squads-cli 0.2.0 → 0.2.2

package/dist/templates/seed/idp/catalog/service.yaml.template

@@ -0,0 +1,25 @@
+apiVersion: squads/v1
+kind: Service
+metadata:
+  name: "{{SERVICE_NAME}}"
+  description: "{{BUSINESS_DESCRIPTION}}"
+  owner: "{{OWNER_SQUAD}}"
+  repo: "{{REPO_NAME}}"
+  tags: []
+spec:
+  type: "{{SERVICE_TYPE}}"
+  stack: "{{SERVICE_STACK}}"
+  branches:
+    default: main
+    development: {{BRANCHES_DEVELOPMENT}}
+    workflow: "{{BRANCHES_WORKFLOW}}"
+  ci:
+    template: {{CI_TEMPLATE}}
+    required_checks: []
+    build_command: {{BUILD_COMMAND}}
+    test_command: {{TEST_COMMAND}}
+  deploy: null
+  health: []
+  dependencies:
+    runtime: []
+  scorecard: "{{SERVICE_SCORECARD}}"

package/dist/templates/seed/memory/_squad/goals.md

@@ -0,0 +1,23 @@
+---
+squad: "{{SQUAD_NAME}}"
+updated: "{{CURRENT_DATE}}"
+review_by: "{{REVIEW_DATE}}"
+owner: "{{SQUAD_LEAD}}"
+---
+
+# {{SQUAD_LABEL}} Goals
+
+## Active
+
+(No goals set yet — add your first goal here)
+
+Example format:
+1. **Goal name** — metric: what_to_measure | baseline: unknown | target: X | deadline: YYYY-MM-DD | status: not-started
+
+## Achieved
+
+(none yet)
+
+## Abandoned
+
+(none yet)

package/dist/templates/seed/memory/_squad/priorities.md

@@ -0,0 +1,25 @@
+---
+squad: "{{SQUAD_NAME}}"
+updated: "{{CURRENT_DATE}}"
+review_by: "{{REVIEW_DATE}}"
+owner: "{{SQUAD_LEAD}}"
+---
+
+# {{SQUAD_LABEL}} Priorities
+
+## Focus
+
+1. **Deliver first results** — produce at least one concrete output per cycle
+2. **Learn the context** — read BUSINESS_BRIEF.md and recent squad state before acting
+3. **Collaborate** — coordinate with other squads through memory, not direct calls
+
+## Not Now
+
+- Deep refactoring without a clear need
+- Experimental features not tied to business goals
+
+## Standing Rules
+
+- Always read state.md before starting — don't repeat work
+- Always write state.md after completing — enable the next run
+- Escalate blockers immediately — don't spin in place

package/dist/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/dist/templates/seed/memory/company/directives.md

@@ -0,0 +1,37 @@
+# Strategic Directives
+
+> Updated by: Human operator (you)
+> Read by: All squad leads and agents before every run
+> This file overrides any conflicting guidance in SQUAD.md goals
+
+## Mission
+
+{{BUSINESS_DESCRIPTION}}
+
+## P0: First Value
+
+**All squads work toward delivering visible, useful output from the very first run.**
+
+Research focus: {{BUSINESS_FOCUS}}
+
+### What "useful" means
+- Intelligence produces a brief with sourced facts, not generic summaries
+- Research identifies specific competitors and opportunities, not "the market is growing"
+- Product translates findings into concrete next steps, not vague roadmaps
+- Company evaluates whether outputs actually advanced the business goals
+
+## Decision Framework
+
+1. Does this advance the research focus above?
+2. Is there a simpler approach for 80% of the value?
+3. What's the opportunity cost — what are we NOT doing?
+
+## Constraints
+
+- Learning phase. Explore, experiment, report findings.
+- Don't over-invest in process. Produce output first, optimize later.
+- Every agent output should be something the human operator can act on today.
+
+---
+
+*Update this file as your business goals evolve. Run `squads goal set` for squad-level goals.*

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/product/lead/state.md

@@ -0,0 +1,14 @@
+# Product Lead State
+
+Last update: {{CURRENT_DATE}}
+
+## Active Roadmap
+- [ ] Initialize product strategy from BUSINESS_BRIEF.md
+- [ ] Define initial feature set and priorities
+- [ ] Establish feedback synthesis loop
+
+## Current Focus
+Initial project setup and alignment with business objectives.
+
+## Insights & Learnings
+- No insights yet. Run the product squad to start capturing memory.

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

@@ -0,0 +1,14 @@
+# Research Lead State
+
+Last update: {{CURRENT_DATE}}
+
+## Active Research Topics
+- [ ] Initial market landscape from BUSINESS_BRIEF.md
+- [ ] Key competitor identification
+- [ ] Strategic growth opportunities
+
+## Current Focus
+Initial project setup and market alignment.
+
+## Findings Summary
+- No findings yet. Run the research squad to start capturing memory.

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,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 |