SprintFoundry

SprintFoundry is a multi-agent software delivery orchestrator. It takes tickets from GitHub, Linear, or Jira, plans and executes work across a team of specialized AI agents (Product, Architect, Developer, QA, Security, UI/UX, DevOps), and delivers tested, reviewed code as pull requests.

How It Works

Ticket → Orchestrator Agent → Execution Plan → Agent Steps → PR

• A planner (Claude) reads the ticket, classifies the work, and returns a structured execution plan
• A validator enforces platform rules (mandatory QA, human gates, dependency order)
• Each step runs a specialized agent (Claude Code or Codex) in its own workspace
• Agents communicate via the filesystem — each reads prior artifacts and writes its own outputs
• A monitor UI shows live progress, per-step results, streaming agent output, and token usage

Installation

Homebrew (recommended):

brew tap Sagart-cactus/tap
brew install sprintfoundry

npm:

npm install -g sprintfoundry

From source:

git clone https://github.com/Sagart-cactus/SprintFoundry.git
cd SprintFoundry
pnpm install
pnpm build

Quick Start

# Create a project config with guided setup
sprintfoundry init

# Check the profile you plan to run
sprintfoundry doctor --profile local

# Validate config and required env vars
sprintfoundry validate --strict --project my-project

# Run on a GitHub issue
sprintfoundry run --project my-project --source github --ticket 42

# Run on a Linear ticket
sprintfoundry run --project my-project --source linear --ticket LIN-423

# Run with a direct prompt
sprintfoundry run --project my-project --source prompt --prompt "Add CSV export to reports"

# Run a single agent directly (skip SDLC orchestration)
sprintfoundry run --project my-project --source prompt --prompt "Review auth logic" --agent security

# Run a custom agent defined in a YAML file
sprintfoundry run --project my-project --source prompt --prompt "..." --agent my-agent --agent-file agents/my-agent.yaml

# Inspect a finished or failed run
sprintfoundry logs <run-id>

# Resume the latest failed or cancelled run
sprintfoundry resume --latest --project my-project

From source, replace sprintfoundry with pnpm dev --.

If you want a hand-written starting point instead of the wizard, use config/project.minimal.yaml as the baseline template.

Monitor

# From npm/brew install:
sprintfoundry monitor

# From source:
pnpm monitor

Open http://127.0.0.1:4310/

The monitor shows all runs, live step progress, streaming agent output (tool calls, file edits, commands), token usage, and cost.

Local Distributed Testing

Use this mode when you want event ingestion + monitor backed by Postgres/Redis.

1. Create local env values:

cp .env.distributed.example .env.distributed
set -a
source .env.distributed
set +a

docker-compose.distributed.yml uses SPRINTFOUNDRY_COMPOSE_DATABASE_URL and SPRINTFOUNDRY_COMPOSE_REDIS_URL for container-to-container networking (postgres/redis). SPRINTFOUNDRY_DATABASE_URL and SPRINTFOUNDRY_REDIS_URL remain host-oriented defaults.

2. Start distributed services:

docker compose -f docker-compose.distributed.yml up -d --build

This stack runs:

• postgres (postgres:16-alpine) on 5432
• redis (redis:7-alpine) on 6379
• migrate one-shot init job (migrations/001_create_event_tables.sql)
• event-api on 3001 (health: GET /health)
• monitor on 4310

3. Verify services:

docker compose -f docker-compose.distributed.yml ps
curl http://localhost:3001/health
open http://localhost:4310

4. Run SprintFoundry with sink enabled:

pnpm dev -- run --project my-project --source prompt --prompt "test distributed mode"

5. Stop services:

docker compose -f docker-compose.distributed.yml down

Use docker compose -f docker-compose.distributed.yml down -v to also remove the Postgres named volume.

CLI Reference

sprintfoundry <command> [options]

Commands:
  init             Guided project setup
  run              Execute an end-to-end task
  validate         Validate platform and project configuration
  review           Submit a human review decision for a pending gate
  monitor          Start the monitor web UI
  doctor           Check all system dependencies and configuration
  logs             Show the event timeline for a run
  resume           Resume a failed or cancelled run
  project create   Interactively create a new project configuration
  agent create     Interactively create a new custom agent definition

Options (run):
  --project <name>        Project config name (matches config/<name>.yaml)
  --source <source>       Ticket source: github | linear | jira | prompt
  --ticket <id>           Ticket ID (for github/linear/jira sources)
  --prompt <text>         Task description (for prompt source)
  --dry-run               Plan only, do not execute steps
  --agent <agent>         Run a single agent directly, bypassing SDLC orchestration
  --agent-file <path>     Path to a YAML/JSON file defining a custom agent inline

Options (monitor):
  --port <port>           Port to listen on (default: 4310)

Options (review):
  --workspace <path>      Path to the run workspace
  --review-id <id>        Review gate ID (from monitor or workspace)
  --decision <d>          approved | rejected
  --feedback <text>       Optional review comment

Options (doctor):
  --project <name>        Project to load for runtime-aware checks
  --profile <profile>     local | distributed | k8s

Configuration

SprintFoundry uses a two-layer config system:

• config/platform.yaml — system-wide defaults (models, budgets, timeouts, rules, agent definitions)
• config/<project>.yaml — per-project settings (repo, API keys, model overrides, runtime mode, integrations)

Minimal project config:

project_id: my-project
name: My Project
stack: js

repo:
  url: git@github.com:org/repo.git
  default_branch: main

api_keys:
  anthropic: ${ANTHROPIC_API_KEY}

integrations:
  ticket_source:
    type: github
    config:
      token: ${GITHUB_TOKEN}
      owner: org
      repo: repo
  scm:
    type: github
    config:
      token: ${GITHUB_TOKEN}
      owner: org
      repo: repo

ticket_workflow:
  enabled: true
  provider: linear_sdlc
  linear_states:
    todo: [Todo]
    review: [Review]
    done: [Done]
  agents:
    developer: developer
    qa: qa
    merge: merge-bot

See docs/configuration.md for the full reference. For common failures, see docs/troubleshooting.md. For Kubernetes setup, start with docs/k8s-quickstart.md.

Runtime Modes

Each agent runs in one of four modes, configured per-agent in your project config:

Provider	Mode	Description
claude-code	local_sdk	Claude Agent SDK in-process (fastest, no subprocess)
claude-code	local_process	claude CLI as a subprocess
claude-code	container	Claude Code in a Docker container
codex	local_sdk	Codex SDK in-process
codex	local_process	codex CLI as a subprocess

# config/my-project.yaml
runtime_overrides:
  developer:
    provider: claude-code
    mode: local_sdk
  qa:
    provider: codex
    mode: local_process

Agents

Agent	Role
product	Analyzes tickets, writes specs and user stories
architect	Designs systems, writes ADRs and API contracts
developer	Implements features, writes tests
go-developer	Go-specific implementation
qa	Writes and runs tests, validates quality
go-qa	Go-specific QA
merge-bot	Resolves merge blockers, smoke-tests the branch, and merges ready PRs
security	Vulnerability scanning, auth review
ui-ux	Component specs, wireframes, design tokens
devops	CI/CD, Dockerfiles, infrastructure
code-review	Code review, style and correctness

You can also define custom agents via YAML and run them with --agent-file, or create one interactively with sprintfoundry agent create.

See docs/agents.md for full agent details, plugins, and Codex skills.

Stack Detection

SprintFoundry automatically detects the project stack (Node.js, Go, Python, etc.) once at the start of each run and shares the result with all agents via .agent-context/stack.json. This eliminates redundant detection work across agents and keeps context consistent throughout the pipeline.

You can also pin the stack explicitly in your project config:

stack: js   # skip auto-detection

Doctor

sprintfoundry doctor checks all system dependencies before you run:

• Node.js version (>=20 required)
• Git, npm availability
• Monitor assets
• Runs-root writability
• Claude CLI / Codex CLI presence (based on your runtime config)
• Docker daemon (if container mode is configured)
• Anthropic / OpenAI API keys (based on your runtime config)
• GitHub token (if GitHub is the ticket source)

sprintfoundry doctor --project my-project

CI/CD

SprintFoundry ships with GitHub Actions workflows:

• CI (.github/workflows/ci.yml) — runs on every PR and push to main: typecheck, build, unit tests
• Release (.github/workflows/release.yml) — triggers on v* tags: builds, publishes to npm, creates a GitHub release with auto-generated release notes

Repo Structure

src/
  service/           # Orchestration service, agent runner, runtimes
    runtime/         # claude-code and codex runtime adapters
  agents/            # Agent CLAUDE.md instruction files (Claude Code)
  agents-codex/      # Agent CODEX.md instruction files (Codex)
  commands/          # CLI sub-commands (project create, agent create)
  shared/types.ts    # All shared TypeScript types
monitor/             # Monitor server and web UI
config/              # Platform and project YAML configs
containers/          # Agent container Dockerfiles
plugins/             # Optional skill catalogs
tests/               # Unit and integration tests
docs/                # Full documentation

Documentation

• docs/README.md — documentation index and overview
• docs/configuration.md — full configuration reference
• docs/agents.md — agent types, roles, and plugins
• docs/architecture.md — system architecture and flow
• docs/monitor.md — monitor routes and API
• docs/operations.md — runbook and troubleshooting
• docs/decisions.md — architecture decision log

License

SprintFoundry is licensed under the Apache License 2.0. See the LICENSE file for details.

Copyright (c) 2026 Sagar Trivedi.