SAM - Smart Agent Manager

Autonomous TDD agent system for Claude Code, Cursor, Gemini CLI, GitHub Copilot, and Antigravity.

SAM orchestrates a team of specialized AI agents that transform an idea or PRD into working, tested code using strict Test-Driven Development (RED-GREEN-REFACTOR). Don't have a PRD yet? Start with quick-prd (one-pass draft) or scope (full discovery) — SAM will help you draft one.

See it work — sam-agents/example-todo

A working todo app built by SAM in 14 minutes from a single markdown PRD. Every artifact is committed: PRD, contracts, stories, source, tests, and the post-integration screenshots + network log + video that Lens captured. Browse it in 90 seconds to see exactly what SAM produces.

Quick Start

# Interactive mode (choose your platform)
npx sam-agents

# Or specify platform directly
npx sam-agents --platform claude       # Claude Code
npx sam-agents --platform cursor       # Cursor IDE
npx sam-agents --platform antigravity  # Google Antigravity
npx sam-agents --platform gemini       # Gemini CLI
npx sam-agents --platform copilot      # GitHub Copilot
npx sam-agents --platform all          # All platforms

Supported Platforms

Why SAM?

Available Agents

Workflows

SAM ships five composable workflows. Run any of them on its own, or use plan-n-build for the one-shot experience (add --from-idea if you don't have a PRD yet).

Typical flow: quick-prd or scope → plan → build-tdd (manual stepping), or plan-n-build end-to-end. With --from-idea, plan-n-build prepends scope automatically (non-interactive).

quick-prd vs scope

Both produce a valid PRD conforming to prd-schema.md. They differ in how they handle unknowns.

Quick-PRD's ## Assumptions block lets you scan the defaults and reject any that are wrong in seconds. Scope's ## Open Questions block surfaces things the discovery loop couldn't resolve.

Invocation per platform

Inside build-tdd: the TDD loop

For each story, in order:

1. RED — Titan writes failing tests covering every acceptance criterion
2. GREEN — Dyna writes the minimum code to make tests pass, then verifies the build
3. REFACTOR — Argus runs an adversarial review and auto-fixes issues
4. UI — Iris validates UX against design standards (web apps only)
5. CSS — Cosmo checks styling consistency (web apps only)
6. A11y — Aria reviews semantics, keyboard, and contrast (web apps only)
7. Security — Sentinel audits secrets, CVEs, and secure coding (opt-in via --security)
8. Docs — Sage appends a changelog entry for the story

Story status (in YAML frontmatter: ready → in-progress → done / blocked) is the single source of truth. Interrupted runs resume cleanly with plan-n-build --resume.

What Gets Installed

your-project/
├── _sam/                      # Agent and workflow definitions (shared across platforms)
│   ├── agents/                # Atlas, Titan, Dyna, Argus, ...
│   ├── core/agents/           # SAM orchestrator
│   ├── core/resources/        # prd-schema, story-schema, epic-schema, design defaults
│   └── core/workflows/        # quick-prd/, scope/, plan/, build-tdd/, plan-n-build/
├── .claude/commands/sam/      # Claude Code slash commands
├── .cursor/rules/             # Cursor @mention rules
├── .gemini/skills/            # Gemini CLI skills
├── copilot-integration/       # GitHub Copilot instructions
└── .agent/skills/             # Antigravity skills

Workflows write their output to sdocs/ in your project root (prd.md, epics, stories, architecture refs, run reports). This is generated content — not installed by the CLI.

Requirements

• Node.js 16+
• One of:
  • Claude Code CLI
  • Cursor
  • Gemini CLI
  • GitHub Copilot
  • Google Antigravity

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

License

MIT - see LICENSE for details.

Built with AI. Powered by TDD.