squads-cli 0.2.1 → 0.2.2

package/dist/run-context-GB6GUCKZ.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import {
+  extractMcpServersFromDefinition,
+  gatherSquadContext,
+  loadApprovalInstructions,
+  loadCompanyContext,
+  loadPostExecution,
+  loadSystemProtocol,
+  parseAgentFrontmatter,
+  resolveContextRoleFromAgent
+} from "./chunk-XTHZT53Y.js";
+import "./chunk-M5FXNY6Y.js";
+import "./chunk-ZTQ7ISUR.js";
+import "./chunk-TYFTF53O.js";
+import "./chunk-7OCVIDC7.js";
+export {
+  extractMcpServersFromDefinition,
+  gatherSquadContext,
+  loadApprovalInstructions,
+  loadCompanyContext,
+  loadPostExecution,
+  loadSystemProtocol,
+  parseAgentFrontmatter,
+  resolveContextRoleFromAgent
+};
+//# sourceMappingURL=run-context-GB6GUCKZ.js.map

package/dist/run-context-GB6GUCKZ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/{status-AQNLDZVN.js → status-PFFB2NV6.js}

@@ -9,6 +9,9 @@ import {
   cleanupStaleSessions,
   getLiveSessionSummaryAsync
 } from "./chunk-BODLDQY7.js";
+import {
+  checkForUpdate
+} from "./chunk-J6QF4ZQX.js";
 import {
   fetchOperationalStatus
 } from "./chunk-TZXD6WFN.js";
@@ -16,21 +19,6 @@ import {
   Events,
   track
 } from "./chunk-QJ7C7CMB.js";
-import {
-  findSimilarSquads,
-  findSquadsDir,
-  listAgents,
-  listSquads,
-  loadSquad,
-  resolveExecutionContext
-} from "./chunk-TYFTF53O.js";
-import {
-  findMemoryDir,
-  getSquadState
-} from "./chunk-ZTQ7ISUR.js";
-import {
-  checkForUpdate
-} from "./chunk-J6QF4ZQX.js";
 import {
   RESET,
   bold,
@@ -42,6 +30,18 @@ import {
   privacyHeader,
   writeLine
 } from "./chunk-M5FXNY6Y.js";
+import {
+  findMemoryDir,
+  getSquadState
+} from "./chunk-ZTQ7ISUR.js";
+import {
+  findSimilarSquads,
+  findSquadsDir,
+  listAgents,
+  listSquads,
+  loadSquad,
+  resolveExecutionContext
+} from "./chunk-TYFTF53O.js";
 import "./chunk-7OCVIDC7.js";
 
 // src/commands/status.ts
@@ -349,4 +349,4 @@ async function showSquadStatus(squadName, squadsDir, options) {
 export {
   statusCommand
 };
-//# sourceMappingURL=status-AQNLDZVN.js.map
+//# sourceMappingURL=status-PFFB2NV6.js.map

package/dist/{sync-ZI3MHA4G.js → sync-FR6LQJ4C.js}

@@ -1,19 +1,8 @@
 #!/usr/bin/env node
-import {
-  getEnv
-} from "./chunk-EHQJHRIW.js";
 import {
   Events,
   track
 } from "./chunk-QJ7C7CMB.js";
-import {
-  findSquadsDir,
-  listSquads,
-  parseSquadFile
-} from "./chunk-TYFTF53O.js";
-import {
-  findMemoryDir
-} from "./chunk-ZTQ7ISUR.js";
 import {
   RESET,
   colors,
@@ -21,6 +10,17 @@ import {
   icons,
   writeLine
 } from "./chunk-M5FXNY6Y.js";
+import {
+  findMemoryDir
+} from "./chunk-ZTQ7ISUR.js";
+import {
+  getEnv
+} from "./chunk-EHQJHRIW.js";
+import {
+  findSquadsDir,
+  listSquads,
+  parseSquadFile
+} from "./chunk-TYFTF53O.js";
 import "./chunk-7OCVIDC7.js";
 
 // src/commands/sync.ts
@@ -833,4 +833,4 @@ async function syncCommand(options = {}) {
 export {
   syncCommand
 };
-//# sourceMappingURL=sync-ZI3MHA4G.js.map
+//# sourceMappingURL=sync-FR6LQJ4C.js.map

package/dist/templates/seed/config/SYSTEM.md

@@ -1,3 +1,9 @@
+---
+version: "1.0"
+scope: "all-agents"
+authority: "squads-cli"
+---
+
 # System Protocol
 
 Immutable rules for all agent executions. Every agent reads this before starting work.

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