Skip to content

AGENTS.md

Latest commit

 

History

History
94 lines (69 loc) · 3.37 KB

AGENTS.md

File metadata and controls

94 lines (69 loc) · 3.37 KB

Agent Instructions

Guidance for AI coding agents working on this repository.

What This Is

squads-cli is a CLI orchestrator for autonomous AI agent teams. It organizes agents into squads (domain-aligned teams), manages their context and memory, and dispatches them via native AI CLIs (claude, gemini, etc.).

The CLI is open source. Agents are the primary consumers — after squads run dispatches an agent, it calls CLI commands to read context, persist memory, and coordinate with other agents.

Repository Structure

src/
├── cli.ts              # All command registrations (Commander.js, lazy imports)
├── commands/            # One file per command — start here for any command change
├── lib/                 # Shared logic (parsing, context, memory, git, providers)
templates/               # Files generated by `squads init`
test/                    # Unit + E2E tests (vitest)

Key files by concern:

Concern File
Squad/agent discovery src/lib/squad-parser.ts
Context injection src/lib/run-context.ts
Agent execution src/commands/run.ts
Multi-agent conversation src/lib/conversation.ts, src/lib/workflow.ts
Provider CLIs src/lib/llm-clis.ts
Memory read/write src/lib/memory.ts
Terminal output src/lib/terminal.ts
Command registration src/cli.ts

Build and Test

npm install
npm run build     # Required before committing — must pass
npm test          # 1700+ tests, all must pass
npm run lint      # ESLint

How to Make Changes

Adding a command

  1. Create src/commands/<name>.ts exporting an async function
  2. Register in src/cli.ts with lazy import
  3. Add --json flag for machine output
  4. Add tests in test/commands/<name>.test.ts

Removing a command

Use the removedCommand() pattern in cli.ts — never silently delete:

program.command('old-name', { hidden: true })
  .description('[removed]')
  .action(removedCommand('old-name', 'Use: squads replacement'));

Modifying squad/agent parsing

All filesystem discovery goes through squad-parser.ts. Never hardcode paths to .agents/ — use findSquadsDir(), findProjectRoot(), loadSquad().

Conventions

  • TypeScript strict mode. No any types.
  • Lazy imports in cli.ts. Commands are loaded only when invoked.
  • Terminal output via terminal.ts. Use writeLine(), colors, bold — not raw console.log.
  • --json on every command. Agents parse CLI output programmatically.
  • No new dependencies without explicit approval.
  • No hardcoded repos, orgs, or file paths. Everything discovered at runtime.
  • Graceful degradation. Missing files, unavailable APIs — handle gracefully, never crash.
  • Conventional Commits. feat:, fix:, docs:, chore:.

Testing

Tests use vitest. Run the full suite before submitting changes:

npm test                    # All tests
npx vitest run test/commands/run.test.ts  # Single file

E2E tests in test/e2e/ run actual CLI commands against temp directories.

What Not to Do

  • Don't add dependencies (especially heavy ones) without discussion
  • Don't use console.log in command implementations
  • Don't hardcode GitHub as the only git provider
  • Don't break --json output formats (agents depend on them)
  • Don't skip the build step — npm run build is the quality gate