Sakura Agent Team System

The agent team system is Sakura's multi-agent orchestration layer for autonomous software development. It coordinates specialized AI agents through a fixed pipeline — from discovery to integration — with iterative refinement loops and human-in-the-loop safety gates.

Overview

Agent teams allow Sakura to tackle complex, multi-phase software projects by decomposing work across specialized roles. Each agent operates with a defined scope, model tier, and acceptance criteria. The orchestrator manages task sequencing, branch isolation, QA review cycles, and GitHub integration.

Sources: src/orchestrator/index.ts, src/teams/types.ts

Architecture

The 8 Agent Roles

Each agent is a specialized prompt persona that operates within the tool loop. Roles map to phases of the pipeline.

Sources: src/agents/scoping.ts, src/agents/feature-scoping.ts, src/agents/planner.ts, src/agents/feature-planner.ts, src/agents/analyst.ts, src/agents/docs.ts

The Fixed Pipeline

The pipeline is deterministic and sequential. Each phase must complete before the next begins. The orchestrator manages state across phases.

Sources: src/orchestrator/pipeline.ts, src/orchestrator/preflight.ts

Phase Details

1. Discovery — Scoping, UX, and PM agents analyze the project description and produce structured documents. The PM agent generates the task list that drives all subsequent work.

2. Planning — The Architect agent reads the scope documents and produces an architecture document that all engineers must follow exactly.

3. Implementation — Each task runs in an isolated git branch. Engineers use the full tool loop (read, write, shell, glob, grep, etc.) to implement, build, and test.

4. Verification — The QA agent reviews the code changes for each task against acceptance criteria and architecture compliance.

5. Integration — Completed task branches are merged into an integration branch. A pull request is created on GitHub.

The Ralph Loop — Iterative Refinement

The Ralph loop (ralphLoop) is the core execution engine for individual tasks. It runs the engineer agent in a headless tool loop with automatic retry on build/test failure.

Sources: src/orchestrator/ralph.ts, src/orchestrator/headless-loop.ts

Key behaviors:

• The engineer prompt includes the task description, acceptance criteria, architecture document, project scope, and any QA feedback from a previous attempt
• The agent signals completion by outputting <promise>TASK_COMPLETE</promise>
• Build and test commands run automatically via the shell tool
• If the build fails, the error is injected into context and the agent retries
• Maximum 3 Ralph attempts per task; maximum 20 tool iterations per attempt

Sources: src/orchestrator/pipeline.ts — buildEngineerPrompt() and buildQaPrompt()

Model Tiers

Sakura routes different task types to different model tiers based on complexity and cost requirements.

Sources: src/teams/config.ts, src/config.ts

The resolveModel() function in team config maps tier names to actual model identifiers based on the active provider.

Team Configuration — team.toml

Teams are configured via a TOML file at .sakura/team.toml (or a path specified at runtime).

Sources: src/teams/config.ts

[team]
name = "my-project"
description = "SaaS application with auth, billing, and dashboard"

[models]
reasoning = "claude-sonnet-4-20250514"
coding = "claude-sonnet-4-20250514"
conversational = "claude-haiku-4"
fast = "claude-haiku-4"

[phases]
discovery = ["scoping", "ux", "pm"]
planning = ["architect"]
implementation = ["frontend", "backend", "devops"]
verification = ["qa"]

[settings]
max_ralph_attempts = 3
max_tool_iterations = 20
integration_branch = "sakura/integration"

Config Schema

Task Schema and Lifecycle

Tasks are the atomic unit of work. Each task maps to one engineer agent run, one git branch, and one QA review cycle.

Sources: src/teams/types.ts, src/teams/config.ts

// Task schema (src/teams/types.ts)
type Task = {
  id: string;                    // e.g. "task-001"
  title: string;                 // Short description
  description: string;           // Full implementation details
  assignee: "frontend" | "backend" | "devops";
  acceptance_criteria: string[]; // Checklist the QA agent verifies
  status: TaskStatus;
  branch?: string;               // Git branch name
  qaFeedback?: string;           // Populated after QA review
};

type TaskStatus =
  | "pending"
  | "in_progress"
  | "qa_review"
  | "qa_failed"
  | "complete"
  | "failed";

Task Lifecycle

Tasks are persisted to .sakura/tasks/ as JSON files. The pipeline state (which tasks are complete) is saved to .sakura/pipeline-state.json so runs can be resumed after interruption.

Sources: src/teams/config.ts — saveTask(), savePipelineState(), loadPipelineState()

GitHub Integration

The orchestrator integrates with GitHub via the gh CLI for branch management and PR creation.

Sources: src/orchestrator/github.ts

Functions:

CLI Commands

All team commands are accessed via sakura team <subcommand>.

Sources: src/cli.ts

sakura team create

Initialize a new team project. Creates .sakura/team.toml with defaults and prompts for project description.

sakura team create --name my-app --description "SaaS with auth and billing"

sakura team plan

Run the discovery and planning phases only (scoping + UX + PM + architect). Produces SCOPE.md, ARCHITECTURE.md, and the task list without executing any implementation.

sakura team plan
sakura team plan --config .sakura/team.toml

sakura team run

Execute the full pipeline: discovery → planning → implementation → verification → integration. Resumes from saved state if interrupted.

sakura team run
sakura team run --config .sakura/team.toml --dry-run

sakura team feature

Add a new feature to an existing project. Runs a scoped discovery → planning → implementation cycle for the feature only, without touching existing tasks.

sakura team feature "Add Stripe subscription billing with webhook handling"

Sources: src/agents/feature-scoping.ts, src/agents/feature-planner.ts

sakura team docs

Generate or update project documentation using the docs agent. Reads existing code and produces/updates README.md, API docs, and architecture diagrams.

sakura team docs
sakura team docs --output docs/

Sources: src/agents/docs.ts

sakura team status

Show the current pipeline state: which tasks are complete, in progress, or failed.

sakura team status

Output example:

Pipeline: my-app
  ✓ task-001  Auth routes (backend)          complete
  ✓ task-002  User model (backend)           complete
  ⟳