Sakura Agent System Documentation

Overview

Sakura's agent system is a multi-agent pipeline where specialized AI agents collaborate through structured file handoffs. Each agent reads outputs from upstream agents, performs its specialized role, and writes artifacts consumed by downstream agents. The pipeline progresses from discovery through implementation to verification.

Sources: src/agents/, src/orchestrator/pipeline.ts, src/teams/

Agent Communication Flow

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

File Handoff Protocol

Agents communicate exclusively through files in the .sakura/ directory. No agent calls another directly — they read and write structured documents.

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

Agent Reference Table

Agent Profiles

1. Scoping Interviewer

Role: Conducts a structured discovery interview to extract project requirements, constraints, and success criteria from the user. Produces the canonical scope.md that all downstream agents depend on.

Source: src/agents/scoping.ts

Model Tier: Standard (OpenAI GPT or Claude Sonnet)
Thinking: Disabled — conversational, not analytical
Temperature: 0.3 — slightly creative to ask good follow-up questions

System Prompt Purpose: Guides the agent to ask structured questions covering: project type, target users, core features, technical constraints, timeline, and success metrics. Prevents scope creep by keeping questions focused.

Output: .sakura/scope.md — a structured markdown document with sections for overview, goals, users, features, constraints, and non-goals.

Key Behaviors:

• Asks one question at a time to avoid overwhelming the user
• Synthesizes answers into a structured document
• Identifies ambiguities and resolves them before proceeding

2. Feature Scoping Agent

Role: When adding features to an existing project (as opposed to greenfield), this agent analyzes the current codebase and scopes the feature against what already exists. Prevents duplication and ensures architectural consistency.

Source: src/agents/feature-scoping.ts

Model Tier: Standard
Thinking: Disabled
Temperature: 0.2 — deterministic analysis

System Prompt Purpose: Instructs the agent to read existing code structure, identify integration points, and produce a scoped feature plan that respects existing patterns.

Output: feature-scope.md — describes what to build, what to reuse, and what to change.

Key Behaviors:

• Uses read, glob, and grep tools to analyze existing code
• Identifies files that will need modification
• Flags potential conflicts with existing architecture

3. UX Designer

Role: Analyzes competitor products (via URL fetching), extracts UX patterns, and produces a design document that guides frontend implementation. Part of the /build guided workflow.

Source: src/scaffold/build.ts (integrated into build pipeline)

Model Tier: Standard
Thinking: Disabled
Temperature: 0.3

System Prompt Purpose: Instructs the agent to analyze competitor UIs, identify common patterns, and produce actionable design decisions (layout, navigation, color, typography) without requiring a designer.

Output: Design decisions embedded in build-state.json, informing template selection and customization.

Key Behaviors:

• Fetches competitor URLs using the fetch tool
• Extracts meaningful UX patterns from HTML content
• Recommends templates from the Sakura registry

Sources: src/scaffold/build.ts, src/scaffold/registry.ts

4. Software Architect

Role: The most critical planning agent. Reads scope.md and design.md, then produces a comprehensive architecture.md that defines system components, data models, API contracts, and technology choices. All engineer agents must follow this document exactly.

Source: src/agents/planner.ts

Model Tier: Extended (Claude Sonnet with extended thinking, or GPT-5.2)
Thinking: Enabled — complex system design benefits from extended reasoning
Temperature: 0.1 — highly deterministic, architectural decisions must be consistent

System Prompt Purpose: Instructs the agent to produce a complete, unambiguous architecture document. Emphasizes: no placeholders, concrete technology choices, explicit file structure, API schemas, and data models.

Output: architecture.md — the authoritative system design document.

Key Behaviors:

• Reads scope document before producing architecture
• Specifies exact file paths, not just module names
• Defines API contracts with request/response schemas
• Identifies shared utilities to prevent duplication

5. Feature Planner

Role: Breaks down a feature or architecture document into discrete, assignable tasks. Each task has a title, description, assignee (engineer type), acceptance criteria, and dependencies.

Source: src/agents/feature-planner.ts

Model Tier: Standard
Thinking: Disabled
Temperature: 0.1 — task decomposition must be deterministic

System Prompt Purpose: Instructs the agent to produce a task list where each task is independently implementable, has clear acceptance criteria, and maps to a specific engineer type.

Output: tasks/task-N.json files consumed by the pipeline orchestrator.

Task Schema:

type Task = {
  id: string;
  title: string;
  description: string;
  assignee: "backend" | "frontend" | "devops";
  acceptance_criteria: string[];
  dependencies: string[];
  status: "pending" | "in_progress" | "complete" | "failed";
}

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

6. Project Manager (Pipeline Orchestrator)

Role: Not a conversational agent — the Project Manager is the pipeline orchestrator itself. It reads tasks, assigns them to engineer agents in dependency order, tracks state, and manages retries and QA cycles.

Source: src/orchestrator/pipeline.ts

Model Tier: N/A — orchestration logic, not LLM-driven
Thinking: N/A
Temperature: N/A

Key Responsibilities:

• Loads task list and resolves dependency order
• Creates git branches per task via createTaskBranch()
• Invokes engineer agents with task context
• Routes failed tasks to QA for feedback
• Merges completed branches via mergeTaskBranch()
• Creates pull requests via GitHub CLI

Sources: src/orchestrator/pipeline.ts, src/orchestrator/ralph.ts, src/orchestrator/github.ts

7. Engineer Agents (Backend / Frontend / DevOps)

All three engineer types share the same underlying loop (ralphLoop) but receive different system prompts based on their assignee type.

Source: src/orchestrator/pipeline.ts, src/orchestrator/ralph.ts

Model Tier: Extended (Claude Sonnet preferred for code generation)
Thinking: Enabled for complex tasks — helps reason through implementation before writing code
Temperature: 0.2 — low for deterministic code output

System Prompt Structure (from buildEngineerPrompt()):

You are a {assignee} engineer. Complete the following task.

## Task: {title}
{description}

## Acceptance Criteria
- {criterion_1}
- {criterion_2}

## Architecture (follow exactly)
{architecture.md content}

## Project Scope (for context)
{scope.md content}

## QA Feedback (fix these issues)  [only on retry]
{qa_feedback}

Rules:
- Read existing files before modifying them
- Run the build and tests after making changes
- If build/tests fail, fix the issues
- Follow the architecture document exactly
- Output <promise>TASK_COMPLETE</promise> when ALL acceptance criteria are met

Tool Access: Full tool suite — read, write/edit, shell, glob, grep, code, aws, fetch, batch_create

Completion Signal: The engineer outputs <promise>TASK_COMPLETE</promise> when done. The loop detects this tag and exits.

Max Iterations: 30 per task (configurable). After 30 iterations without completion, the task is marked failed.

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

8. QA Reviewer

Role: Reviews completed code changes against the task's acceptance criteria and architecture document. Produces structured feedback that is fed back to the engineer on failure, or approves the task for merging.

Source: src/orchestrator/pipeline.ts (buildQaPrompt())

Model Tier: Standard
Thinking: Disabled
Temperature: 0.1 — deterministic pass/fail decisions

System Prompt Structure (from buildQaPrompt()):

You are a QA reviewer. Review the code changes for this task.

## Task: {title}
{description}

## Acceptance Criteria
- {criterion_1}

## Architecture (check compliance)
{architecture.md content}

Review the current code for:
1. All acceptance criteria met
2. Architecture compliance
3. Error handling
4. Edge cases
5. Security issues

Output APPROVED if all criteria are met, or CHANGES_NEEDED: