# Toban — Complete Documentation

Generated: 2026-04-05T22:00:54.164Z

---

# Getting Started

## What is Toban?

Toban is an AI agent orchestration platform that organizes coding agents as a team. You define sprints with tasks, and Toban assigns them to Builder agents that work in isolated git branches. You review and approve or reject each agent's work from a real-time dashboard, keeping humans in control of every change that lands in your codebase.

All workspaces include the full Pro feature set. No credit card required -- sign in with GitHub and start. AI agent usage (Claude Code API credits) is billed separately by Anthropic. A typical task consumes roughly 50K-200K tokens depending on complexity.

This guide walks you through creating your first Toban Project and running AI agents on your codebase.

## Prerequisites

- Node.js 20+
- A GitHub account
- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated: `npm install -g @anthropic-ai/claude-code` then run `claude` once to sign in with your Anthropic account

## 1. Sign Up

Visit [toban.dev](https://toban.dev) and sign in with your GitHub account. Toban uses GitHub OAuth -- no separate password required.

## 2. Create a Project

After signing in, you will be guided through the setup wizard. The Project is not created until you complete the wizard, so you can go back and change settings at any step.

### Name Your Project

Give your Project a name and optional description. This appears in the dashboard header and agent prompts.

### Connect a GitHub Repository

Enter the GitHub repository URL for your project (e.g., `https://github.com/your-org/your-repo`). Toban will:
- Clone the repository when agents start
- Create isolated branches for each task
- Auto-merge completed work back to the base branch

You can add additional repositories later in Settings > Repositories.

### Choose Your Agent Engine

Select the engine for your worker agents:

| Engine | Description |
|--------|-------------|
| Claude Code CLI | Anthropic's official coding CLI. Primary and recommended engine. |

Currently, Claude Code is the only fully supported engine. Support for additional engines (Codex, Gemini) exists in the provider system but is not yet production-ready.

### Configure Agents

The default setup creates a **Manager** and a **Builder** agent. The Manager coordinates sprint planning and task proposals via chat. The Builder implements code changes in isolated git worktrees.

## 3. Set Your Project Spec

After Project creation, go to the **/spec** page to write your project specification. This is a free-text document that describes:
- What your project does
- Target users
- Tech stack and architecture
- Key constraints or conventions

The spec is injected into every agent prompt, giving agents the context they need to make good decisions. A well-written spec significantly improves agent output quality.

## 4. Configure Repositories

Go to **Settings > Repositories** to register repositories that agents should work with:
- **Main repository**: The primary codebase (set during wizard)
- **Sub repositories**: Additional repos agents may need access to
- **Access control**: Restrict which agent roles can access each repo

## 5. Install the CLI

The CLI (`toban-cli`) runs on your local machine and orchestrates agent execution. No global install is needed -- `npx` downloads the latest version on the fly.

```bash
# Install Claude Code CLI (required as the agent engine)
npm install -g @anthropic-ai/claude-code

# Run the Toban CLI (no global install needed)
npx toban-cli@latest start --api-url <URL> --api-key <KEY>
```

> **Tip:** On the **Sprint page**, click the **"$ run"** / **"CLI"** button in the header to copy the full command with the API URL and key pre-filled for your Project.

### CLI Options

```
--api-url <url>       Toban API base URL (or TOBAN_API_URL env)
--api-key <key>       API key (or TOBAN_API_KEY env)
--working-dir <dir>   Repository root (default: cwd)
--branch <branch>     Base branch (default: main)
--model <model>       AI model for Manager chat
--engine <type>       Agent engine (default: claude-code)
--ws-port <port>      WebSocket port (default: 4000, 0=auto)
--debug               Verbose output (or DEBUG=1 env)
```

## 6. Create a Sprint

Back on the **Sprint page** in the dashboard:

1. Click **+ Sprint** to create a new sprint (starts as **Active** immediately -- no planning phase)
2. Set a **Sprint Goal** and optional **Deadline** (click next to the phase stepper)
3. Open the **Chat Panel** and ask the Manager to propose tasks (e.g., "Propose tasks for this sprint")
4. The Manager analyzes your project spec and backlog, then proposes tasks as interactive cards
5. Click **Sprint** or **Backlog** on each card to add to the current sprint or save for later
6. Adjust priorities and assignments on the Kanban board if needed

You can also create tasks manually by clicking **Add Task** on the sprint board.

**Tips for good task descriptions:**
- Be specific: "Add user login with GitHub OAuth" not "Add auth"
- Include acceptance criteria when possible
- Reference relevant files or documentation

## 7. Run Agents

Once the sprint has tasks and the CLI is connected, agents start automatically:

- Tasks owned by agent roles (builder) are **automatically picked up** by the CLI
- The CLI transitions them from `todo` to `in_progress` and spawns the agent
- Tasks owned by `user` are never auto-started -- those are for you
- Watch agent progress in the **Terminal Panel** (tool use, file edits, bash commands)

The CLI handles the full lifecycle:
1. Creates an isolated git worktree for the agent
2. Injects agent memories, ADRs, and task context into the prompt
3. Spawns the Claude Code CLI process
4. Monitors progress and streams activity to the Dashboard via WebSocket
5. On completion: merges the agent's branch to main, pushes to remote, generates structured review report

> **Important**: The CLI auto-merges completed work to main, but the task moves to **Review** status -- not Done. **You must explicitly Approve or Reject every task** before it is marked as complete. Rejected tasks go back to the agent with your feedback. Nothing is considered "done" without your approval.
>
> This trunk-based workflow is the current default. Support for other branching strategies (e.g. GitHub Flow with pull requests) is planned.

## 8. Review Completed Work

When an agent finishes a task, it moves to **Review** status on the sprint board:

1. Click the task card to expand the **Structured Review Report** (requirement match, code quality, test coverage, risks, verdict)
2. Click **Approve** to mark as done, or **Reject** with feedback (the agent will rework the task)
3. Rejected tasks go back to the agent with your feedback attached

## 9. Track Progress

- **Sprint Board** shows real-time task status via WebSocket (no reload needed)
- **Analytics page** has Velocity charts, Burndown, Daily Activity, and Agent contribution
- **Sprint Goal** and **Deadline countdown** are visible in the sprint header

## Prompt Transparency

Want to see exactly what instructions your agents receive? Go to **Agents > Prompts** in the sidebar to preview the full prompt for any agent role. The preview shows all injected content:

- Role description and security rules
- Project Spec (vision, tech stack, constraints)
- ADR summaries
- Task-specific instructions

This lets you verify and tune the prompt before agents start working. The preview is also available via the API: `GET /api/v1/agents/:name/prompt-preview`.

## Tips: Working with Claude Code Directly

The dashboard chat (Manager) is useful for quick task proposals and sprint management. For deeper work -- architecture discussions, debugging, code reviews, strategic planning -- **use Claude Code CLI directly** in your terminal.

To give Claude Code full context about your Toban project, feed it the documentation:

```
Read https://app.toban.dev/llms-full.txt
```

Combined with your project's `CLAUDE.md`, this gives Claude Code everything it needs to act as your senior engineering partner while Toban handles the sprint management and agent orchestration.

## Next Steps

- [Architecture Guide](./architecture.md) -- How Toban works under the hood
- [Setup Guide](./setup-guide.md) -- Detailed setup and configuration reference
- [ADR Guide](./adr-guide.md) -- Architecture Decision Records for agent governance
- [Error Reference](./error-reference.md) -- Error codes and troubleshooting
- [Security Guide](./security.md) -- Security model and guarantees


---

# Setup Guide

Detailed configuration reference for Toban Projects, agents, repositories, and the CLI.

## Prerequisites

- Node.js 20+
- A GitHub account (for OAuth login)
- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code): `npm install -g @anthropic-ai/claude-code`

## GitHub App and OAuth

Toban uses two GitHub integrations:

### GitHub OAuth App

Used for user authentication. When you sign in at toban.dev, you authorize Toban to read your GitHub identity. This creates a session cookie used by the dashboard.

### GitHub App

Used for repository operations. The GitHub App is installed on your organization or personal account and grants Toban:
- Read access to repository metadata
- Write access for creating branches and pushing commits
- Token generation for git operations (installation tokens, 1hr expiry)

When you connect a repository during Project setup, Toban checks that the GitHub App is installed with access to that repository. If not, it prompts you to install or reconfigure the App.

## Project Creation

The setup wizard collects all configuration before creating anything. The Project is **deferred** -- it is only created in the database after you complete the final step. This prevents orphaned Projects if you abandon the wizard.

### Wizard Steps

1. **Project name and description** -- Display name for the Project
2. **GitHub repository** -- The primary repo agents will work on
3. **Agent engine** -- Currently Claude Code is the only production-ready engine
4. **Confirmation** -- Review and create

After creation, you land on the Sprint page. The next steps are:
- Write your project spec at `/spec`
- Add additional repositories at Settings > Repositories

## Repository Configuration

### Main Repository

Set during Project creation. This is the primary codebase that agents clone and work on. The repository URL is stored as `github_repo` (format: `owner/repo`).

### Sub Repositories

Additional repositories can be registered at **Settings > Repositories**. Each entry has:

| Field | Description |
|-------|-------------|
| `repo_name` | Display name |
| `repo_path` | GitHub path (`owner/repo`) or local path |
| `description` | Optional description |
| `access_agents` | Which agent roles can access this repo (empty = all) |

The CLI clones all registered repositories at startup and creates worktrees in the appropriate repo for each task.

### Access Control

By default, all agents can access all repositories. To restrict access:
1. Go to Settings > Repositories
2. Edit the repository
3. Add specific agent roles to the access list (e.g., only `builder`)

## Agent Configuration

### Engine Selection

Each agent has an engine configuration that determines how it runs:

| Setting | Description |
|---------|-------------|
| `engine` | Engine type: `claude-code` (recommended), `claude-api`, `gemini`, `codex`, `custom` |
| `execution_mode` | Currently `local` only (BYOK mode is not yet functional) |
| `command_template` | Custom command template for the `custom` engine |

Configure agents at the **Agents** page or via `PUT /api/v1/agents/:name/config`.

### Agent Roles

| Role | Capabilities |
|------|-------------|
| **Manager** | Sprint coordination, task proposals, chat interaction (read-only repo access) |
| **Builder** | Full code read/write, test execution, commits |

The Manager is created automatically during Project setup. The Builder is the primary worker agent.

## Sprint Configuration

### Creating a Sprint

Sprints can be created from the dashboard Sprint page or via the API:

```bash
POST /api/v1/sprints
{ "number": 1 }
```

### Sprint Status

Sprints start as **Active** by default -- there is no planning phase in the UI. The `planning` status exists in the API for backward compatibility but is not used in the current UX. The phase flow is: Active -> Review -> Retrospective -> Completed.

### Manager Interaction

The Manager is an LLM-powered agent that coordinates the sprint. It:
- Proposes tasks based on the project spec and backlog
- Responds to user chat messages
- Requests approval before spawning worker agents
- Tracks task progress and suggests status transitions

The Manager uses the enriched context from `GET /api/v1/manager/context`, which includes tasks, agent statuses, the project spec, backlog items, and retrospective data from previous sprints.

## CLI Configuration

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `TOBAN_API_URL` | Yes | Toban API base URL |
| `TOBAN_API_KEY` | Yes | Project API key |
| `LLM_BASE_URL` | No | OpenAI-compatible API URL for Manager (overrides Claude CLI) |
| `LLM_API_KEY` | No | API key for the LLM provider |
| `DEBUG` | No | Set to `1` for verbose output |

### CLI Flags

All environment variables can be overridden with CLI flags:

```bash
npx toban-cli@latest start \
  --api-url https://api.toban.dev \
  --api-key tb_wsXXX_sk_XXX \
  --working-dir /path/to/your/repo \
  --branch main \
  --model claude-sonnet-4-20250514 \
  --ws-port 4000
```

### WebSocket Port

The CLI starts a WebSocket server (default port 4000) that the Dashboard connects to for real-time communication. If port 4000 is unavailable, use `--ws-port 0` for automatic port selection. The CLI registers its port with the API so the Dashboard can discover it.

## Project Settings

| Setting | Description |
|---------|-------------|
| `name` | Project display name |
| `description` | Project description |
| `language` | AI communication language (`en` or `ja`) |
| `workflow` | Workflow type: `scrum`, `kanban`, or `checklist` |
| `github_repo` | Connected GitHub repository (`owner/repo`) |
| `spec` | Project specification (editable at `/spec`) |
| `terminal_emulator` | Preferred terminal for local agent execution |

Update via the Settings page or `PUT /api/v1/workspace` (the API uses `workspace` internally).

## Backend Deployment

### Cloudflare Workers (API)

The API runs on Cloudflare Workers with D1 (SQLite) storage.

```bash
cd toban/api
npm install

# Configure wrangler.jsonc with your Cloudflare account
# Set secrets:
#   GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET
#   GITHUB_APP_ID, GITHUB_PRIVATE_KEY
#   APP_URL (frontend URL for OAuth redirect)

# Run migrations
npx wrangler d1 migrations apply toban-db

# Deploy
npm run deploy
```

### Frontend (Next.js)

The dashboard is a Next.js application deployed to any Node.js hosting platform.

```bash
cd toban
npm install

# Create .env.local:
#   API_URL=https://your-api.example.com
#   API_KEY=internal-proxy-key

npm run build
npm run start
```

### Infrastructure (Terraform)

The `terraform/` directory manages Cloudflare resources:
- D1 database
- Workers deployment
- Custom domain configuration
- Monitoring and alerting


---

# Architecture Overview

Toban has three main components that work together:

```
Browser                         Your Machine
+-----------------+             +------------------+
|   Dashboard     |  WebSocket  |   Toban CLI      |
|   (toban.dev)   | <---------> |   (toban-cli)    |
|                 |             |                  |
|  Sprint Board   |             |  Manager Agent   |
|  Chat Panel     |             |  Builder Agents  |
|  Terminal View  |             |  Git Operations  |
|  Review Flow    |             |                  |
+-----------------+             +------------------+
        |                               |
        |  REST API                     |  Git Push
        v                               v
+-----------------+             +------------------+
|   Toban API     |             |   GitHub         |
|   (Cloudflare)  |             |   Repositories   |
|                 |             +------------------+
|  Quality Scores |
|  Failure DB     |
|  Knowledge      |
+-----------------+
```

## Dashboard

The web interface where you manage sprints, review agent work, and chat with the Manager.

- **Sprint Board** -- Kanban-style task management with drag-and-drop
- **Chat Panel** -- Talk to the Manager agent to plan sprints, propose tasks, and coordinate
- **Terminal Panel** -- See what agents are doing in real-time (file reads, edits, commands)
- **Review Flow** -- Approve or reject completed work with one click

## Toban CLI

Runs on your machine and orchestrates the AI agents.

- **Manager Agent** -- An AI that reads your codebase, proposes tasks, and manages the sprint
- **Builder Agents** -- AI agents that implement tasks in isolated git worktrees
- **Templates** -- Configurable prompt templates that control agent behavior (implementation, reviewer)

The CLI connects to the Dashboard via WebSocket for real-time communication. When the Dashboard is not open, it falls back to API polling.

## Toban API

Hosted on Cloudflare Workers. Stores all data (tasks, sprints, agents, messages) and handles authentication via GitHub OAuth.

- **Quality Scores** -- Review results are aggregated into per-agent quality scores
- **Failure DB** -- Past failures and review rejections are stored to prevent recurring issues
- **Knowledge** -- Shared memory entries for cross-agent context preservation

## How a Task Gets Done

1. You create a task (or the Manager proposes one)
2. Move the task to "In Progress" on the Sprint Board
3. The CLI picks it up and spawns a Builder agent in a git worktree
4. The Builder implements the change and commits
5. The CLI runs a reviewer template to perform structured code review
6. The CLI merges to main, pushes, and writes a review report
7. You review and approve (or reject) on the Sprint Board
8. Results feed back into Quality Scores and Failure DB

## Communication

- **Real-time**: WebSocket between Dashboard and CLI (chat, agent activity, proposals)
- **Persistent**: REST API for task/sprint/agent data storage
- **Git**: Agents commit in worktrees, CLI pushes to GitHub

## Security

- Agents run in isolated git worktrees (not your working directory)
- The Manager has read-only access to repositories
- Worker agents auto-start on tasks assigned to agent roles (manual approval mode planned)
- GitHub App tokens are refreshed automatically (1-hour expiry)

For more details, see the [Setup Guide](./setup-guide.md) and [Getting Started](./getting-started.md).


---

# Toban API Reference

Base URL: `https://api.toban.dev`

## Authentication

All `/api/v1/*` endpoints require a Bearer token:

```
Authorization: Bearer tb_wsXXX_sk_XXX
```

API keys are Project-scoped and automatically generated on login. Copy the CLI connection command from the Sprint page header. User session keys expire after 7 days of inactivity (sliding window). Agent keys do not expire.

---

## Health

### `GET /api/health`

Health check. No auth required.

**Response:** `200 OK`
```json
{ "status": "ok" }
```

---

## Site Status

### `GET /api/site/status`

Public site status (maintenance mode, banner). No auth required.

**Response:**
```json
{
  "maintenance": false,
  "maintenance_message": "The system is currently under maintenance.",
  "banner": false,
  "banner_message": "",
  "banner_scheduled_at": ""
}
```

---

## Auth

### `GET /api/auth/github`

Redirect to GitHub OAuth authorization. No auth required.

### `GET /api/auth/github/callback`

GitHub OAuth callback. Exchanges code for token, creates/finds workspace, sets session cookie.

### `GET /api/auth/github/installed`

GitHub App post-installation callback. Links the GitHub App installation to the workspace.

### `POST /api/auth/logout`

Invalidate the current session and clear the session cookie.

### `GET /api/auth/me`

Check if the current session is valid. Returns minimal session info (no workspace data). For user profile data (GitHub login, avatar), use `GET /api/v1/auth/me` instead (requires workspace-scoped auth).

---

## Config

### `GET /api/v1/config/constants`

Public configuration constants. No workspace-specific data. Returns available roles, engines, templates, and other UI configuration.

**Response:**
```json
{
  "roles": ["manager", "builder"],
  "engines": ["claude-code", "claude-api", "gemini", "codex", "custom"],
  "templates": ["implementation", "reviewer"],
  "priorities": ["p0", "p1", "p2", "p3"],
  "task_statuses": ["todo", "in_progress", "review", "done", "blocked"]
}
```

---

## Workspace

### `GET /api/v1/workspace`

Get current workspace details including name, description, connected repo, language, workflow type, and spec.

**Response:**
```json
{
  "id": "ws-abc123",
  "name": "My Project",
  "description": "A web application",
  "github_org": "my-org",
  "github_repo": "my-org/my-repo",
  "agent_type": "claude-code",
  "language": "en",
  "workflow": "scrum",
  "spec": "Project specification text...",
  "created_at": "2026-01-01T00:00:00",
  "updated_at": "2026-01-02T00:00:00"
}
```

### `PUT /api/v1/workspace`

Update workspace settings.

**Body:**
```json
{
  "name": "string (optional)",
  "description": "string (optional)",
  "language": "en | ja (optional)",
  "workflow": "scrum | kanban | checklist (optional)",
  "github_repo": "owner/repo (optional)",
  "spec": "string (optional)",
  "terminal_emulator": "auto | terminal.app | iterm2 | ghostty | ... (optional)"
}
```

### `DELETE /api/v1/workspace`

Delete workspace and all associated data.

---

## Workspace Repositories

### `GET /api/v1/workspace/repositories`

List registered repositories.

**Response:**
```json
[
  {
    "id": "repo-abc123",
    "workspace_id": "ws-abc123",
    "repo_path": "my-org/my-app",
    "repo_name": "my-app",
    "description": "Main application",
    "access_agents": ["builder"],
    "created_at": "2026-01-01T00:00:00"
  }
]
```

### `POST /api/v1/workspace/repositories`

Add a repository.

**Body:**
```json
{
  "repo_path": "owner/repo",
  "repo_name": "repo-name",
  "description": "optional description",
  "access_agents": ["builder"]
}
```

### `PUT /api/v1/workspace/repositories/:id`

Update a repository configuration.

### `DELETE /api/v1/workspace/repositories/:id`

Remove a repository.

---

## Workspace Export / Import

### `GET /api/v1/workspace/export`

Export workspace configuration as JSON. Includes agents and task templates.

**Response:**
```json
{
  "version": 1,
  "exported_at": "2026-01-01T00:00:00.000Z",
  "workspace": {
    "name": "My Project",
    "description": "...",
    "language": "en",
    "workflow": "scrum"
  },
  "agents": [
    { "name": "builder", "engine": "claude-code", "execution_mode": "local", "system_prompt": null }
  ],
  "task_templates": [
    { "title": "Setup repo", "description": "...", "priority": "p0", "owner": "builder", "labels": "[]" }
  ]
}
```

### `POST /api/v1/workspace/import`

Import workspace configuration from JSON.

**Body:**
```json
{
  "version": 1,
  "mode": "merge | replace (optional, default: merge)",
  "agents": [],
  "task_templates": []
}
```

**Response:**
```json
{ "ok": true, "mode": "merge", "stats": { "agents_imported": 2, "templates_imported": 3 } }
```

---

## Workspace User Tasks

### `GET /api/v1/workspace/user-tasks`

List user tasks (manual/human tasks separate from agent sprint tasks). Supports query param `status` to filter by `todo`, `in_progress`, or `done`.

**Response:**
```json
[
  {
    "id": "utask-abc12345",
    "workspace_id": "ws-abc123",
    "title": "Review deployment guide",
    "description": "",
    "status": "todo",
    "related_tasks": ["task-uuid-1"],
    "created_at": "2026-01-01T00:00:00",
    "completed_at": null
  }
]
```

### `GET /api/v1/workspace/user-tasks/blockers`

List incomplete user tasks that block active sprint tasks (tasks whose `related_tasks` overlap with current sprint task IDs).

**Response:**
```json
[
  {
    "id": "utask-abc12345",
    "title": "Review deployment guide",
    "status": "todo",
    "related_tasks": ["task-uuid-1"],
    "blocked_sprint_tasks": [
      { "id": "task-uuid-1", "title": "Deploy to prod", "status": "todo", "owner": "builder" }
    ]
  }
]
```

### `POST /api/v1/workspace/user-tasks`

Create a user task.

**Body:**
```json
{
  "title": "string (required, max 200)",
  "description": "string (optional, max 2000)",
  "related_tasks": ["task-id-1"]
}
```

### `PUT /api/v1/workspace/user-tasks/:id`

Update a user task.

**Body:**
```json
{
  "title": "string (optional)",
  "description": "string (optional)",
  "status": "todo | in_progress | done (optional)",
  "related_tasks": ["task-id"]
}
```

### `DELETE /api/v1/workspace/user-tasks/:id`

Delete a user task.

---

## Git Token

### `GET /api/v1/workspace/git-token`

Return a short-lived GitHub App installation token for git operations (clone, push, pull). Tokens expire after 1 hour.

**Response:**
```json
{
  "token": "ghs_xxxxxxxxxxxx",
  "expires_at": "2026-01-01T01:00:00Z"
}
```

Used by the CLI's credential helper script to authenticate git operations on demand.

---

## Workspaces (Multi-Project)

### `GET /api/v1/workspaces`

List all workspaces for the current user (by GitHub login).

**Response:**
```json
[
  { "id": "ws-abc123", "name": "My Project", "github_org": "my-org", "github_avatar": "https://..." }
]
```

### `POST /api/v1/workspaces`

Create a new workspace and switch to it (sets session cookie).

**Body:**
```json
{
  "language": "en | ja (optional)"
}
```

### `POST /api/v1/workspaces/:id/switch`

Switch to another workspace owned by the same user. Returns a new API key and sets session cookie.

**Response:**
```json
{
  "key": "tb_xxx_sk_xxx",
  "workspace": { "id": "ws-abc123", "name": "My Project" }
}
```

---

## Projects

### `POST /api/v1/projects/setup`

Complete project setup for the current workspace. Creates the manager agent, Sprint 0, initial tasks, and a welcome message. Optionally creates additional agents with per-role engine configuration.

**Body:**
```json
{
  "name": "string (optional)",
  "github_repo": "owner/repo (optional)",
  "agent_type": "claude-code | codex | custom (optional, default: claude-code)",
  "language": "en | ja (optional, default: ja)",
  "description": "string (optional)",
  "agents": [
    {
      "name": "builder",
      "engine": "claude-code | claude-api | gemini | codex | custom (optional)",
      "execution_mode": "local | byok (optional)",
      "api_key": "string (optional)",
      "command_template": "string (optional)"
    }
  ]
}
```

**Response:** `201 Created`
```json
{
  "workspace": { "id": "ws-abc123", "name": "My Project", "..." : "..." },
  "manager_agent": { "name": "manager", "status": "active", "..." : "..." },
  "sprint": { "number": 0, "status": "active" }
}
```

---

## Manager

### `GET /api/v1/manager/context`

Returns enriched context for the Manager agent. This is the primary endpoint the CLI uses to build the Manager's system prompt. Includes:

- Current sprint info and status
- All tasks with their statuses and assignments
- Agent statuses and activity
- Project spec
- Backlog items
- Previous sprint retrospective data

---

## Tasks

### `GET /api/v1/tasks`

List all tasks. Supports query params:

| Param | Description |
|-------|-------------|
| `status` | Filter by status: `todo`, `in_progress`, `review`, `done`, `blocked` |
| `sprint` | Filter by sprint number |
| `owner` | Filter by agent name |

### `POST /api/v1/tasks`

Create a task.

**Body:**
```json
{
  "title": "Implement login page",
  "description": "Create OAuth login flow with GitHub",
  "owner": "builder (optional, auto-inferred from type)",
  "priority": "p0 (optional, default: p1)",
  "status": "todo (optional)",
  "type": "feature (optional, auto-inferred from title/description)",
  "sprint": 1,
  "branch": "string (optional)",
  "labels": ["feature", "auth"],
  "blocks": [],
  "blocked_by": [],
  "context_notes": "string (optional)",
  "target_repo": "string (optional)",
  "parent_task": "uuid (optional)",
  "story_points": 3
}
```

### `PATCH /api/v1/tasks/:id`

Update a task. Common fields:

```json
{
  "status": "in_progress",
  "owner": "builder",
  "review_comment": "Completed implementation with tests",
  "commits": "abc1234,def5678",
  "story_points": 3
}
```

The `review_comment` field is used by agents to describe what they did. The `commits` field records commit hashes produced during the task.

### `DELETE /api/v1/tasks/:id`

Delete a task (soft delete).

### `POST /api/v1/tasks/:id/approve`

Approve a task in review status (moves to done).

### `POST /api/v1/tasks/:id/reject`

Reject a task in review status (moves back to in_progress with feedback).

**Body:**
```json
{ "reason": "Tests are failing" }
```

### `POST /api/v1/tasks/:id/review-action`

Combined review action endpoint. Supports `approve` (marks task done, unblocks children) or `fix` (creates a fix sub-task).

**Body:**
```json
{
  "action": "approve | fix",
  "comment": "string (optional)",
  "fix_description": "string (optional, used when action is fix)"
}
```

**Response (approve):**
```json
{
  "ok": true,
  "status": "done",
  "unblocked_children": [{ "id": "...", "title": "..." }]
}
```

**Response (fix):**
```json
{
  "ok": true,
  "status": "review",
  "fix_task": { "id": "...", "title": "Fix: original title" }
}
```

### `POST /api/v1/tasks/:id/review-report`

Submit a structured review report for a task. If the task is currently `in_progress`, it is automatically transitioned to `review`.

**Body:**
```json
{
  "summary": "string (required)",
  "changes": "string (optional, description of changes made)",
  "test_results": "string (optional)",
  "commits": "string (optional, comma-separated commit hashes)",
  "notes": "string (optional)"
}
```

**Response:**
```json
{ "ok": true }
```

---

## Stories

### `GET /api/v1/stories`

List all stories in the workspace. Stories group related tasks.

### `POST /api/v1/stories`

Create a story. Auto-creates a Builder task for the story.

**Body:**
```json
{
  "title": "string (required)",
  "description": "string (optional)",
  "sprint": 1,
  "priority": "p1 (optional)"
}
```

### `GET /api/v1/stories/:id`

Get a single story with its tasks.

### `PATCH /api/v1/stories/:id`

Update a story.

### `DELETE /api/v1/stories/:id`

Delete a story.

### `GET /api/v1/stories/:id/tasks`

List tasks belonging to a story.

---

## Agents

### `GET /api/v1/agents`

List all agents in the workspace with their current status. By default, finished child processes are excluded.

| Param | Description |
|-------|-------------|
| `all` | Set to `true` to include all agents (including finished child processes) |

### `POST /api/v1/agents`

Create an agent.

**Body:**
```json
{ "name": "builder" }
```

### `PUT /api/v1/agents`

Upsert agent status. Used by the CLI to report agent state. This is an upsert -- if the agent does not exist, it is created.

**Body:**
```json
{
  "name": "builder",
  "status": "active",
  "activity": "Working on task-123",
  "parent_agent": "string (optional)",
  "ws_port": 4000
}
```

The `ws_port` field registers the CLI's WebSocket server port so the Dashboard can connect.

### `PUT /api/v1/agents/:name/config`

Update agent engine configuration.

**Body:**
```json
{
  "engine": "claude-code",
  "execution_mode": "local",
  "api_key": "sk-... (optional, encrypted at rest)",
  "system_prompt": "Custom instructions..."
}
```

### `DELETE /api/v1/agents/:name`

Remove an agent. Cannot delete `manager` or agents that have been active or have assigned tasks.

### `GET /api/v1/agents/:name/context`

Return the assembled agent context (for debugging). Shows the full context that would be injected into the agent's system prompt.

**Response:**
```json
{
  "agent_name": "builder",
  "context": "Full context string...",
  "parts": { "..." : "..." }
}
```

### `GET /api/v1/agents/:name/api-docs`

Return the API reference prompt for CLI/agent consumption.

### `GET /api/v1/agents/:name/prompt-preview`

Return the full prompt that would be sent to the agent, for transparency.

| Param | Description |
|-------|-------------|
| `mode` | `compact` (default) or `full` |

**Response:**
```json
{
  "agent_name": "builder",
  "role": "builder",
  "mode": "compact",
  "prompt": "...",
  "length": 5000,
  "token_estimate": 1250
}
```

### `POST /api/v1/agents/check-stalls`

Detect stalled agents (no heartbeat within the configured timeout). Updates their status to `stalled`.

**Response:**
```json
{
  "stalled": [{ "name": "builder", "last_seen": "2026-01-01T00:00:00" }],
  "count": 1
}
```

---

## Agent Progress

### `POST /api/v1/agents/progress`

Report agent progress (called by agent-runner during task execution).

**Body:**
```json
{
  "agent_name": "builder",
  "task_name": "string (optional)",
  "step": "string (optional)",
  "file": "string (optional)",
  "detail": "string (optional)"
}
```

### `GET /api/v1/agents/:name/progress`

Get latest progress entries for a specific agent (up to 20).

**Response:**
```json
[
  {
    "id": "...",
    "agent_name": "builder",
    "task_name": "Implement login",
    "step": "writing tests",
    "file": "src/auth.test.ts",
    "detail": "Added 3 test cases",
    "created_at": "2026-01-01T00:05:00"
  }
]
```

### `GET /api/v1/agents/progress/latest`

Get the latest progress entry per agent across the workspace.

### `DELETE /api/v1/agents/progress/purge`

Purge progress data older than 24 hours.

---

## Agent Memories (Knowledge)

### `GET /api/v1/agents/memories`

List all memory entries across all agents in the workspace.

| Param | Description |
|-------|-------------|
| `type` | Filter by type: `identity`, `feedback`, `project`, `reference` |
| `agent` | Filter by agent name |

**Response:**
```json
{
  "memories": [
    {
      "id": "...",
      "workspace_id": "ws-abc123",
      "agent_name": "builder",
      "key": "preferred-framework",
      "type": "project",
      "content": "Use Next.js for all frontend work",
      "version": 1,
      "last_validated_at": "2026-01-01T00:00:00",
      "expires_days": 7,
      "updated_at": "2026-01-01T00:00:00",
      "created_at": "2026-01-01T00:00:00"
    }
  ],
  "count": 1
}
```

### `GET /api/v1/agents/memories/shared`

List shared memory entries visible to all agents in the workspace.

### `GET /api/v1/agents/memories/expired`

List expired memory entries in the workspace (entries past their `expires_days` since `last_validated_at`).

### `GET /api/v1/agents/memories/search`

Search memory entries by keyword across key and content fields.

| Param | Description |
|-------|-------------|
| `q` | Search keyword (required) |
| `type` | Filter by type (optional) |
| `agent` | Filter by agent name (optional) |

### `GET /api/v1/agents/:name/memories`

List all memory entries for a specific agent. Optional query param `type` to filter.

### `PUT /api/v1/agents/:name/memories/:key`

Create or update a memory entry (upsert by agent name + key). Supports optimistic locking via `version`.

**Body:**
```json
{
  "content": "string (required, max 2000)",
  "type": "identity | feedback | project | reference (required)",
  "version": 1,
  "expires_days": 7
}
```

### `POST /api/v1/agents/memories/:id/revalidate`

Refresh `last_validated_at` to now, extending the memory's expiration window.

### `DELETE /api/v1/agents/:name/memories/:key`

Delete a memory entry.

---

## Sprints

### `GET /api/v1/sprints`

List all sprints.

### `POST /api/v1/sprints`

Create a sprint.

**Body:**
```json
{ "number": 1 }
```

The sprint defaults to `active` status. The `planning` status is accepted for backward compatibility but is not used in the current UX. The UI creates sprints as Active immediately.

### `POST /api/v1/sprints/current/start`

Start the current sprint. This is the primary endpoint the CLI calls at startup. It:
1. Activates the sprint (sets status to `active`)
2. Sets assigned agents to `starting` status
3. Returns the full sprint context (tasks, agents, workspace info)

**Response:**
```json
{
  "sprint": { "number": 1, "status": "active" },
  "agents": [{ "name": "builder", "status": "starting", "engine": "claude-code", "execution_mode": "local" }],
  "skippedAgents": [],
  "tasks": [...]
}
```

### `PATCH /api/v1/sprints/:number`

Update sprint status or metadata.

**Body:**
```json
{
  "status": "review (optional)",
  "goal": "string (optional)",
  "deadline": "string (optional)"
}
```

Status values: `planning`, `active`, `review`, `retrospective`, `completed`

Valid transitions: `planning` -> `active` -> `review` -> `retrospective` -> `completed` (and `review` -> `active` for re-opening).

> **Note**: `planning` exists for API backward compatibility. The UI starts sprints as Active by default. The primary phase flow is: Active -> Review -> Retrospective -> Completed.

### `GET /api/v1/sprints/current/tasks`

Get tasks, agents, sprints list, latest agent progress, and repositories for the current active sprint. Supports query param `sprint` to specify a sprint number.

### `GET /api/v1/sprints/:number/review`

Get sprint review data with summary, completion stats, tasks grouped by owner, and retrospective comments.

### `GET /api/v1/sprints/:number/retro`

Get retrospective comments for a sprint.

### `POST /api/v1/sprints/:number/retro`

Submit a retrospective comment.

**Body:**
```json
{
  "agent_name": "builder",
  "went_well": "Fast implementation of auth flow",
  "to_improve": "Need better test coverage",
  "suggested_tasks": [
    { "title": "Add e2e tests for auth", "priority": "p1" }
  ]
}
```

---

## Analytics

### `GET /api/v1/sprints/:number/analytics`

Sprint analytics data for charts. Includes summary stats, breakdowns by agent/type/priority, and burndown data.

**Response:**
```json
{
  "sprint": { "number": 1, "status": "active", "created_at": "...", "completed_at": null },
  "summary": {
    "total": 10,
    "done": 6,
    "review": 2,
    "in_progress": 1,
    "todo": 1,
    "completion_rate": 60,
    "total_points": 30,
    "done_points": 18
  },
  "by_agent": {
    "builder": { "total": 5, "done": 3, "points": 15 }
  },
  "by_type": { "feature": 6, "bug": 2, "chore": 2 },
  "by_priority": { "p0": 3, "p1": 5, "p2": 2 },
  "burndown": [
    { "date": "2026-01-01", "remaining": 10 },
    { "date": "2026-01-02", "remaining": 8 }
  ],
  "tasks": [
    { "id": "...", "title": "...", "status": "done", "owner": "builder", "type": "feature", "story_points": 3 }
  ]
}
```

### `GET /api/v1/analytics/velocity`

Cross-sprint velocity data. Shows task and story point completion across sprints.

| Param | Description |
|-------|-------------|
| `limit` | Number of sprints to include (default: 10) |

**Response:**
```json
{
  "velocity": [
    {
      "sprint": 1,
      "status": "completed",
      "total": 10,
      "done": 8,
      "total_points": 30,
      "done_points": 24
    }
  ]
}
```

### `GET /api/v1/analytics/daily`

Daily activity data including hourly task activity, cumulative completion trend, and scorecard.

| Param | Description |
|-------|-------------|
| `date` | Date in YYYY-MM-DD format (default: today) |

**Response:**
```json
{
  "date": "2026-01-15",
  "scorecard": {
    "tasks_done": 5,
    "points": 12,
    "agents_active": 2,
    "types": { "feature": 3, "bug": 2 }
  },
  "hourly": [
    { "hour": 0, "done": 0, "started": 0, "total": 0 },
    { "hour": 14, "done": 3, "started": 1, "total": 5 }
  ],
  "cumulative": [
    { "date": "2026-01-14", "total": 20, "daily": 4 },
    { "date": "2026-01-15", "total": 25, "daily": 5 }
  ],
  "tasks": [
    { "id": "...", "title": "...", "owner": "builder", "type": "feature", "completed_at": "2026-01-15T14:30:00" }
  ]
}
```

---

## ADR (Architecture Decision Records)

### `GET /api/v1/adr`

List all ADR records for the workspace, ordered by number descending.

**Response:**
```json
[
  {
    "id": "uuid",
    "workspace_id": "ws-abc123",
    "number": 1,
    "title": "Use PostgreSQL for primary database",
    "status": "accepted",
    "context": "We need a relational database...",
    "decision": "Use PostgreSQL via Supabase",
    "rationale": "Strong SQL support, good ecosystem...",
    "consequences": "Need to manage migrations...",
    "author": "builder",
    "superseded_by": null,
    "created_at": "2026-01-01T00:00:00",
    "updated_at": "2026-01-01T00:00:00"
  }
]
```

### `GET /api/v1/adr/prompt`

Get ADR summary formatted as prompt text for agent injection. Returns accepted and proposed ADRs as a concise reference block.

**Response:**
```json
{ "prompt": "\n### Architecture Decisions (ADR)\n..." }
```

### `GET /api/v1/adr/:id`

Get a single ADR by ID.

### `POST /api/v1/adr`

Create a new ADR. The `number` is auto-assigned.

**Body:**
```json
{
  "title": "string (required)",
  "context": "string (required)",
  "decision": "string (required)",
  "rationale": "string (required)",
  "consequences": "string (optional)",
  "author": "string (optional)",
  "status": "proposed | accepted | deprecated | superseded (optional, default: proposed)"
}
```

**Response:** `201 Created`
```json
{ "id": "uuid", "number": 1 }
```

### `PATCH /api/v1/adr/:id`

Update an ADR. All fields are optional.

**Body:**
```json
{
  "title": "string (optional)",
  "status": "proposed | accepted | deprecated | superseded (optional)",
  "context": "string (optional)",
  "decision": "string (optional)",
  "rationale": "string (optional)",
  "consequences": "string (optional)",
  "superseded_by": "uuid | null (optional)"
}
```

### `DELETE /api/v1/adr/:id`

Delete an ADR.

---

## Messages

### `GET /api/v1/messages`

Get messages. Supports query params:

| Param | Description |
|-------|-------------|
| `channel` | Filter by channel (agent name) |
| `mode` | `team` for team-wide messages |

### `POST /api/v1/messages`

Send a message.

**Body:**
```json
{
  "from": "user",
  "to": "manager",
  "content": "Please prioritize the login feature"
}
```

Messages are the API-polling fallback for communication. When the Dashboard is connected via WebSocket, messages flow through the WS server instead.

---

## Failures

### `GET /api/v1/failures`

List failure records for the workspace. Failures are recorded when tasks fail or are rejected during review.

### `POST /api/v1/failures`

Record a failure.

---

## Activity

### `GET /api/v1/activity`

Get activity timeline for the workspace.

---

## Audit Logs

### `GET /api/v1/audit-logs`

Get security audit logs (prompt injection attempts, auth events, agent spawns).

---

## Search

### `GET /api/v1/search?q=query`

Search tasks and messages.

---

## Repos (GitHub)

### `GET /api/v1/repos`

List repositories from the connected GitHub account/organization.

### `POST /api/v1/repos`

Create a new GitHub repository.

### `GET /api/v1/repos/orgs`

List GitHub organizations the user has access to.

### `GET /api/v1/repos/pulls`

List pull requests for the connected repo.

---

## User Info

### `GET /api/v1/auth/me`

Get current user info (GitHub login and avatar) from the workspace. This is the workspace-scoped variant; `GET /api/auth/me` (without `/v1/`) is the session-only check used by the auth flow.

**Response:**
```json
{
  "github_login": "octocat",
  "github_avatar": "https://avatars.githubusercontent.com/u/..."
}
```

---

## Assistant

### `GET /api/v1/assistant/templates`

List available agent and project templates.

**Response:**
```json
{
  "agents": [{ "name": "builder", "..." : "..." }],
  "projects": [{ "..." : "..." }]
}
```

### `POST /api/v1/assistant/suggest-agents`

Suggest agent composition based on project type.

**Body:**
```json
{ "projectType": "web-app" }
```

**Response:**
```json
{
  "agents": ["builder"],
  "details": [{ "name": "builder", "..." : "..." }]
}
```

### `POST /api/v1/assistant/translate-task`

Convert a natural language instruction into a structured task.

**Body:**
```json
{ "instruction": "Add dark mode to the settings page" }
```

**Response:**
```json
{
  "task": { "title": "...", "description": "...", "type": "feature", "owner": "builder", "priority": "p1" }
}
```

### `POST /api/v1/assistant/generate-sprint0`

Generate Sprint 0 tasks and create them in the database.

**Body:**
```json
{
  "projectName": "My App",
  "selectedAgents": ["builder"],
  "templateKey": "web-app (optional)",
  "language": "en | ja (optional)"
}
```

**Response:** `201 Created`
```json
{
  "tasks": [{ "id": "...", "title": "...", "description": "...", "owner": "builder", "priority": "p0" }],
  "agents": ["builder"]
}
```

---

## Admin (Site Owner Only)

These endpoints require site owner access (the user who created the first workspace).

### `GET /api/v1/admin/settings`

Get all site settings.

### `PUT /api/v1/admin/settings`

Update site settings.

**Body:**
```json
{
  "maintenance_enabled": "true | false",
  "maintenance_message": "string",
  "banner_enabled": "true | false",
  "banner_message": "string",
  "banner_scheduled_at": "string"
}
```

### `GET /api/v1/admin/workspaces`

List all workspaces (admin view).

### `GET /api/v1/admin/stats`

Site-wide statistics.

**Response:**
```json
{
  "workspaces": 42,
  "active_workspaces_7d": 15,
  "total_tasks": 1200,
  "total_agents": 85
}
```

---

## API Keys (Internal)

These endpoints are mounted at `/api/keys` (no `/v1/` prefix, no workspace auth).

### `POST /api/keys`

Generate a new API key for an agent.

**Body:**
```json
{
  "workspace_id": "ws-abc123",
  "agent_name": "builder"
}
```

### `GET /api/keys/:workspace_id`

List keys for a workspace (prefix only, no secrets).

### `DELETE /api/keys/:id`

Revoke an API key.

---

## Rate Limits

| Endpoint Type | Limit |
|--------------|-------|
| Auth endpoints | 60 requests/minute |
| API endpoints | 600 requests/minute |
| Per-workspace | 600 requests/minute |
| Write operations (per IP) | 60/minute per workspace |

Rate limit headers are included in responses:
- `X-RateLimit-Limit`
- `X-RateLimit-Remaining`
- `X-RateLimit-Reset`


---

# ADR Guide (Architecture Decision Records)

ADRs record important decisions about your project's architecture, process, and policies. They explain *why* a decision was made and *what* its consequences are — providing context that helps agents make better choices.

## When to Write an ADR

Write an ADR when you make a decision that has lasting consequences:

| Situation | ADR? |
|---|---|
| "We chose D1 over Postgres because of Cloudflare integration" | Yes (architecture decision) |
| "System core tasks are assigned to user, not agents" | Yes (process decision) |
| "Authentication uses GitHub App, not OAuth App" | Yes (design decision) |
| "Use Zod for all API validation" | Yes (coding standard with rationale) |

**Simple test**: Does the decision have a "because" or "rationale"? Write an ADR. For simple conventions without rationale, use your project's CLAUDE.md or Knowledge entries instead.

## How ADRs Work

ADRs are injected into both the Manager and worker agent prompts. When making decisions (e.g., which tasks to propose, who to assign them to), agents consult ADRs as binding guidelines.

The injection flow:
1. API builds an ADR summary from all `accepted` and `proposed` records
2. The summary is included in agent prompts under "## Architecture Decision Records"
3. Agents treat `ACCEPTED` ADRs as mandatory constraints

## ADR Structure

Each ADR has:

| Field | Description |
|---|---|
| **Title** | Short description of the decision |
| **Status** | `proposed`, `accepted`, `deprecated`, `superseded` |
| **Context** | Why this decision was needed (the problem) |
| **Decision** | What was decided (the solution) |
| **Rationale** | Why this approach was chosen over alternatives |
| **Consequences** | What changes as a result (trade-offs) |

## Creating ADRs

### Via the Dashboard

1. Go to **Settings > ADR**
2. Click **New ADR**
3. Fill in the fields
4. Set status to `proposed` or `accepted`

### Via the API

```bash
curl -X POST /api/v1/adr \
  -H "Authorization: Bearer $TOBAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "System core tasks assigned to user",
    "status": "accepted",
    "context": "AI agents modifying their own behavior logic creates safety risks",
    "decision": "Tasks involving prompts, CLI flow, auth, or DB schema changes are assigned to user",
    "rationale": "Core changes require design intent understanding that agents lack",
    "consequences": "Slower implementation of core features, but safer and more consistent"
  }'
```

## Status Lifecycle

```
proposed → accepted → deprecated
                   → superseded (by a newer ADR)
```

- **Proposed**: Under discussion, agents see it but it's not mandatory
- **Accepted**: Binding, agents must follow it
- **Deprecated**: No longer relevant, removed from prompts
- **Superseded**: Replaced by a newer ADR

## Examples

### ADR-001: System Core Tasks Assigned to User

- **Context**: AI agents modifying agent behavior logic, prompts, or security rules could cause unpredictable changes
- **Decision**: Tasks involving (1) agent prompts/templates, (2) CLI execution flow, (3) Manager logic, (4) auth/security, (5) DB schema changes are assigned to `user`
- **Rationale**: These require understanding of design intent that agents cannot reliably infer
- **Consequences**: Core features take longer but remain safe and consistent

### ADR-002: Database Uses Cloudflare D1

- **Context**: Need a database for the API backend
- **Decision**: Use Cloudflare D1 (SQLite-based) for all persistent storage
- **Rationale**: Zero-config with Workers, no separate infrastructure to manage, generous free tier
- **Consequences**: Limited to SQLite syntax, no full-text search, max 10GB per database

## Viewing ADR Prompts

To see exactly what agents receive:

```bash
curl $TOBAN_API_URL/api/v1/adr/prompt \
  -H "Authorization: Bearer $TOBAN_API_KEY"
```


---

# Error Reference

When you encounter an error, note the **error code** and **request ID** shown in the error message. These help us diagnose issues quickly.

## How to Read Errors

API errors return:
```json
{
  "error": "Human-readable message",
  "code": "ERR_TASK_NOT_FOUND",
  "request_id": "abc123def456"
}
```

The `request_id` is also in the response header `X-Request-Id`.

CLI errors are logged to `~/.toban/logs/error.log` in JSON format:
```json
{"timestamp":"2026-03-18T10:00:00Z","code":"CLI_AGENT_SPAWN_FAILED","message":"...","context":{}}
```

---

## API Error Codes

### Authentication (ERR_AUTH_*)

| Code | HTTP | Cause | User Action |
|---|---|---|---|
| ERR_AUTH_MISSING | 401 | No API key or session cookie | Log in again or check API key |
| ERR_AUTH_INVALID | 401 | API key not found in database | Regenerate API key in Settings |
| ERR_AUTH_EXPIRED | 401 | Session older than 7 days | Log in again |
| ERR_AUTH_FORBIDDEN | 403 | Agent trying to access other agent's resources | Check task ownership |

### Tasks (ERR_TASK_*)

| Code | HTTP | Cause | User Action |
|---|---|---|---|
| ERR_TASK_NOT_FOUND | 404 | Task ID does not exist | Check the task ID, it may have been deleted |
| ERR_TASK_VALIDATION | 400 | Invalid field values (bad priority, status, etc.) | Check the request body matches the schema |
| ERR_TASK_DUPLICATE | 201 (warning) | Similar task title exists in same sprint | Consider using update_task instead |
| ERR_TASK_UPDATE_FAILED | 500 | Database error during update | Retry; if persistent, check logs |

### Sprints (ERR_SPRINT_*)

| Code | HTTP | Cause | User Action |
|---|---|---|---|
| ERR_SPRINT_NOT_FOUND | 404 | Sprint number does not exist | Check sprint number |
| ERR_SPRINT_TRANSITION | 400 | Invalid phase transition (e.g., skipping review) | Follow the flow: active -> review -> retrospective -> completed. Cannot skip phases. |
| ERR_SPRINT_VALIDATION | 400 | Invalid sprint data | Check request body |

### Agents (ERR_AGENT_*)

| Code | HTTP | Cause | User Action |
|---|---|---|---|
| ERR_AGENT_NOT_FOUND | 404 | Agent name not in database | Check agent name spelling |
| ERR_AGENT_FORBIDDEN | 403 | Agent trying to modify another agent's task | Assign the task to the correct agent |
| ERR_AGENT_SPAWN_BLOCKED | 409 | Same agent already running | Wait for the current task to finish |

### Review (ERR_REVIEW_*)

| Code | HTTP | Cause | User Action |
|---|---|---|---|
| ERR_REVIEW_VALIDATION | 400 | Missing required review fields | Include all fields: requirement_match, files_changed, code_quality, test_coverage, risks, verdict |
| ERR_REVIEW_TASK_NOT_FOUND | 404 | Task not found for review submission | Check task ID |

### General

| Code | HTTP | Cause | User Action |
|---|---|---|---|
| ERR_VALIDATION | 400 | Request body failed Zod validation | Check the `details` array for specific field errors |
| ERR_NOT_FOUND | 404 | Resource not found | Check the URL and ID |
| ERR_RATE_LIMITED | 429 | Too many requests (600/min API, 60/min auth) | Wait a moment and retry |
| ERR_INTERNAL | 500 | Unexpected server error | Note the request_id and report it |
| ERR_MAINTENANCE | 503 | System is in maintenance mode | Wait for maintenance to complete |

---

## CLI Error Codes

### Agent Lifecycle (CLI_AGENT_*)

| Code | Cause | Action |
|---|---|---|
| CLI_AGENT_SPAWN_FAILED | Claude CLI failed to start | Check `claude --version`, ensure Claude Code is installed |
| CLI_AGENT_TIMEOUT | Agent exceeded time limit | Task may be too large; split into smaller tasks |
| CLI_AGENT_CRASH | Agent process exited unexpectedly | Check agent stdout in terminal panel for details |

### Git Operations (CLI_GIT_*)

| Code | Cause | Action |
|---|---|---|
| CLI_GIT_CLONE_FAILED | Repository clone failed | Check GitHub App permissions and repo URL |
| CLI_GIT_MERGE_FAILED | Merge conflict or worktree issue | Check if files were modified concurrently |
| CLI_GIT_PUSH_FAILED | Push rejected after rebase retry | Remote may have diverged; pull and retry manually |
| CLI_GIT_WORKTREE_FAILED | Worktree creation failed | Check disk space and git status |

### API Communication (CLI_API_*)

| Code | Cause | Action |
|---|---|---|
| CLI_API_REQUEST_FAILED | API request returned error | Check API URL and network connectivity |
| CLI_API_AUTH_FAILED | API key rejected | Regenerate API key in dashboard Settings |
| CLI_API_TIMEOUT | API did not respond in time | Check if Cloudflare Workers is running |

### Review (CLI_REVIEW_*)

| Code | Cause | Action |
|---|---|---|
| CLI_REVIEW_LLM_FAILED | Claude CLI review process failed | Check `claude` is accessible and API quota |
| CLI_REVIEW_LLM_TIMEOUT | Review took longer than 120s | Diff may be too large; this is non-fatal (fallback to text review) |
| CLI_REVIEW_PARSE_FAILED | LLM output was not valid JSON | Non-fatal; falls back to text review |
| CLI_REVIEW_API_FAILED | Review report API returned error | Check API logs with request_id |

### Template Actions (CLI_ACTION_*)

| Code | Cause | Action |
|---|---|---|
| CLI_ACTION_FAILED | Pre/post action threw an error | Check ~/.toban/logs/error.log for details |
| CLI_MEMORY_INJECT_FAILED | Failed to inject memories into CLAUDE.md | Non-fatal; agent runs without memories |
| CLI_MEMORY_COLLECT_FAILED | Failed to collect memories after task | Non-fatal; memories not saved |

---

## Troubleshooting

### "Auto-review failed. Please review manually."

This means the `review_changes` post-action failed. Common causes:
1. Worktree was deleted before review could run
2. Claude CLI timed out (120s limit for large diffs)
3. LLM returned non-JSON response

Check `~/.toban/logs/error.log` for the specific CLI_REVIEW_* code.

### Sprint phase won't change

Valid transitions: active -> review -> retrospective -> completed.
You cannot skip phases (e.g., active -> completed returns ERR_SPRINT_TRANSITION).

### Agent not picking up tasks

1. Check CLI is running (`curl localhost:4000/health`)
2. Task must have `owner` set to an agent role (builder, cloud-engineer, etc.)
3. Task must be in the current active sprint
4. Same agent cannot run two tasks simultaneously

### Error log location

CLI errors: `~/.toban/logs/error.log`
API errors: Cloudflare Workers dashboard > Logs


---

# Security Guide

Toban is designed with security as a core principle. This guide explains the security model, isolation mechanisms, and best practices for running AI agents safely on your codebase.

## Security Model Overview

Toban enforces security at multiple layers:

1. **Authentication** -- GitHub OAuth for users, workspace-scoped API keys for CLI
2. **CSRF protection** -- Token-based CSRF defense on all dashboard API calls
3. **Agent isolation** -- Each agent runs in its own git worktree
4. **Role boundaries** -- Agents can only perform role-appropriate actions
5. **Input validation** -- All data validated and sanitized via Zod schemas
6. **Workspace-scoped access** -- API keys and data are isolated per workspace

## Authentication

### GitHub OAuth Flow

1. User clicks "Sign in with GitHub" on the dashboard
2. Browser redirects to GitHub's authorization page
3. User approves, GitHub redirects back with an authorization code
4. The API exchanges the code for an access token
5. The API creates a session and sets a secure HTTP-only cookie
6. Subsequent dashboard requests include the session cookie

The session cookie is HTTP-only and secure (HTTPS-only in production). The dashboard never has direct access to the GitHub token.

### CSRF Protection

All state-changing requests from the dashboard include a CSRF token:

1. The dashboard fetches a CSRF token from the API on page load
2. The token is included in a custom header on every POST/PUT/PATCH/DELETE request
3. The API validates the token against the session before processing the request

The API proxy route (`/api/proxy/[...path]`) handles CSRF token injection automatically.

### API Key Authentication

CLI and programmatic access uses Bearer tokens in the format `tb_ws{workspace_id}_sk_{secret}`:

- Each key is scoped to a **single Project** (workspace)
- Keys cannot access data from other Projects
- User session keys are auto-generated on login and expire after 7 days of inactivity (sliding window)
- Agent keys (used by the CLI) expire after 24 hours of inactivity (sliding window extends on use)

## Agent Sandboxing

### Git Worktree Isolation

Every agent task runs in an isolated git worktree:

```
your-repo/
├── src/                          <-- Your working directory (untouched)
└── .worktrees/
    └── builder-task-123/         <-- Agent's isolated copy
        ├── src/
        └── ...
```

This means:
- Agents cannot modify your working directory directly
- Each agent has its own branch and working copy
- Failed or rejected work is discarded without affecting your code
- Multiple agents can work simultaneously without conflicts

### Branch Isolation

Each agent creates a dedicated branch:
```
agent/builder-task-123
agent/cloud-eng-task-456
```

Completed work is merged back to the base branch with `--no-ff` (no fast-forward), preserving a clear merge history.

### Automatic Cleanup

When an agent finishes (or fails), its worktree is automatically cleaned up. No stale branches or orphaned directories are left behind.

### Manager Permission Mode

The Manager agent (which coordinates sprints and responds to chat) runs with restricted permissions. When using the Claude Code CLI engine, the Manager is launched with `--permission-mode plan`, which limits its ability to execute arbitrary tools. The Manager can analyze and plan but relies on ACTION blocks to request changes, which require user approval. Other engines may have different permission models.

### Task Auto-Start

When the CLI is connected, tasks assigned to agent roles (builder, cloud-engineer, etc.) are automatically picked up and executed. Tasks assigned to `user` are never auto-started. To prevent agents from working on a task, set its owner to `user` before connecting the CLI.

> **Note**: Auto-start is the recommended workflow for fast iteration. A manual approval mode (approve/reject before each agent starts) will be available as an opt-in setting in a future release.

## Credential Management

### GitHub App Installation Tokens

Toban uses a **git credential helper** that fetches fresh GitHub App installation tokens on demand:

1. At CLI startup, a shell script is written to `~/.toban/git-credential-helper.sh` (mode `0700`, owner-only executable)
2. The script calls `GET /api/v1/workspace/git-token` with the workspace API key
3. The API returns a short-lived GitHub App installation token (1 hour expiry)
4. Git invokes this helper automatically on push/pull operations

This avoids:
- Storing long-lived tokens on disk
- Embedding tokens in git remote URLs (which are visible in `.git/config`)
- Token expiry issues during long-running agent tasks

After initial clone, any embedded tokens in remote URLs are cleaned and replaced with plain `https://github.com/...` URLs.

## Role Boundaries

Each agent role has strictly defined capabilities enforced in the system prompt:

| Role | Can Do | Cannot Do |
|------|--------|-----------|
| **Manager** | Coordinate sprints, propose tasks, review backlog | Write code directly |
| **Builder** | Write code, run tests, commit changes | Modify infrastructure |

If an agent is asked to perform work outside its role, the prompt instructs it to refuse and suggest the appropriate agent.

## Input Validation

All data entering the system is validated with Zod schemas:

| Context | Max Length | Validation |
|---------|-----------|------------|
| Project spec | 10 KB | HTML sanitized |
| Task description | 2 KB | HTML sanitized |
| Message content | 2 KB | HTML sanitized |
| Agent name | 64 chars | Alphanumeric + hyphens only |

### HTML Sanitization

All user input is sanitized to remove:
- `<script>` tags
- `<iframe>` and `<embed>` tags
- Event handlers (`onclick`, `onerror`, etc.)
- `javascript:` URLs
- Other XSS vectors

## API Key Security

### Best Practices

- **Rotate keys regularly** -- Create new keys and revoke old ones
- **Use environment variables** -- Never hardcode keys in source code
- **Limit distribution** -- Only share keys with team members who need CLI access
- Store keys in your shell profile or a secrets manager, not in version control

## Rate Limiting

The API enforces rate limits to prevent abuse:

| Endpoint Type | Limit |
|--------------|-------|
| Auth endpoints | 60 requests/minute |
| API endpoints | 600 requests/minute |
| Write operations (per workspace + IP) | 60/minute |

## Audit Logging

Security-relevant events are logged:

- API key creation and revocation
- Agent spawning and termination
- Task status changes
- Authentication events

Access audit logs from the dashboard or via `GET /api/v1/audit-logs`.

## Reporting Security Issues

If you discover a security vulnerability in Toban, please report it responsibly:

1. **Do not** open a public GitHub issue
2. Use [GitHub Security Advisories](https://github.com/totte-dev/toban-cli/security/advisories/new) to submit a private report
3. Or contact us via [X DM (@recuupfeg)](https://x.com/recuupfeg)
4. Include steps to reproduce and potential impact

We aim to acknowledge reports within 48 hours and provide fixes within 7 days for critical issues.

## Data Storage and Privacy

### What Toban Stores

- **Project metadata**: Project name, description, spec, language, workflow settings
- **Task data**: Titles, descriptions, status, review comments, story points
- **Agent activity**: Status, last seen timestamps, progress logs
- **Messages**: Chat messages between users and the Manager agent
- **Knowledge and ADRs**: Shared knowledge and architecture decisions
- **GitHub metadata**: GitHub username, avatar URL, org name, installation ID

### What Toban Does NOT Store

- **Your source code**: Agents run on your local machine via the CLI. Code is cloned locally, not uploaded to Toban servers.
- **Git diffs or file contents**: Review comments contain summaries, not raw code.
- **Anthropic API keys**: Your Claude Code authentication stays on your machine.

### Where Data Is Stored

All data is stored in Cloudflare D1 (SQLite at the edge) and Cloudflare R2 (for workspace exports). Data is replicated across Cloudflare's global network.

### Data Deletion

When you delete a Project, all associated data (tasks, sprints, agents, messages, knowledge, ADRs, audit logs) is permanently deleted. This is a hard delete with no recovery — use the workspace export feature to back up data before deletion.


---

# Release Notes

## v0.3.0 (2026-03-26)

Simplification release: removed features that added complexity without improving agent performance, streamlined the sprint workflow.

### Removed Features

- **Playbook**: Rule injection into agent prompts did not improve code quality — context noise outweighed benefits. All playbook rules, enforcement levels, rule evaluations, and Defense Report removed.
- **Skills**: Task-level tag injection into prompts had no measurable effect.
- **Secrets**: Encrypted environment variable injection was never used.
- **Goals**: OKR management and goal evaluation were unused.
- **Recurring Tasks**: Periodic task auto-generation was unused.
- **Review Diffs**: Diff recording between reject/approve was never populated.
- **Strategist role**: Strategy, content, research, and story-decompose templates removed. Remaining roles: Manager, Builder. Remaining templates: implementation, reviewer.

### Story Workflow

- **Direct task creation**: Stories no longer trigger AI decomposition. Creating a Story auto-creates a Builder task. Additional tasks can be added manually.
- **Enrich is optional**: Tasks no longer require acceptance criteria or steps before being dispatched. Agents read the codebase and decide what to do.

### Fixes

- **Audit Log**: Fixed authentication check — user sessions (`user:` prefix) now correctly allowed.
- **Story delete**: Fixed FK constraint error by unlinking tasks before deletion.
- **DELETE proxy**: Fixed empty body forwarding that caused 500 errors.
- **All new workspaces default to Pro plan**.

### Documentation

- Public docs updated to reflect current feature set (architecture, getting-started, API reference, glossary, pricing, setup guide).
- CLI README updated (removed Manager LLM references, updated pipeline flow).

### E2E Tests

- Updated for removed features (Goals, Playbook). 13 tests pass, 2 gracefully skipped.

### Known Issues (resolved from v0.2.0)

- ~~Defense Report page~~ → removed
- ~~Playbook rule management~~ → removed
- ~~Strategist proposals fetch~~ → removed

## v0.2.0 (2026-03-21)

Major update: Product Goals, onboarding wizard, multi-agent orchestration, and review intelligence.

### Product Goals

- **Goals & Key Results**: Set product goals, track key results, and link them to sprints. Goal status updates automatically based on sprint outcomes.
- **Strategy Log**: Record strategic decisions from chat or retrospectives. Dedicated Strategy tab on the dashboard.
- **Agents are goal-aware**: Active goals are included in agent context, so tasks align with your current priorities.

### Onboarding

- **`toban init`**: Interactive setup wizard — select repos, configure agents, and connect GitHub in one command.
- **Browser-based auth**: GitHub login opens in your browser — no token copy-paste needed.
- **Auto-review on push**: Setup installs a git hook that runs `toban review` on every push.

### Review Intelligence

- **Diff analysis**: Tracks what code changes turn a rejection into an approval, surfacing improvement patterns over time.
- **Defense report**: Monthly summary of issues caught by Playbook — by category, by rule, with 3-month trends.
- **Public metrics**: Share anonymized quality metrics at `/public/metrics` (no login required).

### Multi-Agent Orchestration (CLI v0.10.0)

- **Parallel builders**: Run multiple builders at the same time. Git conflicts are handled automatically with rebase and escalation.
- **Task auto-split**: Large tasks are automatically broken into subtasks by AI.
- **Dependency-aware assignment**: Tasks are dispatched in the right order based on dependencies.
- **Context sharing**: Each builder's changes are passed to the next, reducing redundant work.
- **Stall detection**: Idle agents are detected and cleaned up automatically.

### Agent Concurrency Settings

- **Dashboard UI**: Settings > Agents — adjust how many builders and cloud engineers run in parallel.

### Bug Fixes

- Sprint phase buttons now display correctly (e.g., "Start Sprint" in planning phase).
- Workspace switching properly resets all state.
- Reviewer falls back to general code quality review when no matching task is found.
- Retrospective data parsing is more resilient to malformed output.
- Various stability improvements for task updates and agent coordination.

### Known Issues (remaining)

- Individual use only — team/multi-user features not available.
- GitHub App org installation may not appear in Setup (workaround: set installation_id manually).

## v0.1.1 (2026-03-20)

### Reviewer Agent

- **Independent Reviewer process**: Reviewer spawns as a separate Claude Code agent (10 turns, 5min timeout) instead of single-turn `--print` call. Can read files, run tests, and analyze diffs in context.
- **Task-type specific review**: Review criteria vary by task type (implementation, content, infra, research, strategy, bug, chore).
- **Customizable review rules**: Reviewer prompt externalized to `prompts/templates.ts`. Project-specific rules injected from Playbook.
- **Test execution in review**: Reviewer runs `npm test` before evaluation. Failed tests = automatic NEEDS_CHANGES.
- **Reviewer Playbook rules**: 5 default locked/overridable rules (scope check, test requirement, metadata-only rejection, etc.)
- **Review scoring**: Each review produces a 0-100 quality score.
- **Verdict badges**: Task cards show Approved (green), Changes (amber), Blocked (red) with hover tooltip.

### Knowledge & Learning

- **Skills → Playbook integration**: Skills moved from hardcoded CLI to Playbook rules (category="skill"). Tag-based matching — only injected when task labels match rule tags.
- **Shared Agent Memory**: Agents can share knowledge across the team via `shared: true` in memory frontmatter. Tag-based pinpoint injection.
- **Knowledge management page**: Settings > Knowledge with Shared Memories (click-to-expand) + Skills tabs.
- **Failure Database**: Auto-populated on task reject. Past failures injected into agent prompts to prevent recurring issues. Japanese text normalize, retry noise dedup.
- **Team Knowledge**: `POST /failures/analyze` groups failure patterns and suggests Playbook rules. One-click apply to Playbook.
- **Previous Review injection**: Retry tasks receive prior review feedback in prompt.

### Sprint Planning (Strategist)

- **`toban plan`**: Strategist agent analyzes backlog, velocity, quality trends, and failure patterns to generate sprint plans via local Claude CLI.
- **`toban propose`**: Strategist analyzes data sources and suggests improvement tasks. Auto-runs when sprint enters retrospective.
- **Proposals UI**: Improvement proposals displayed in retrospective view with approve (→ Sprint / → Backlog) and reject (with reason) buttons.
- **Sprint Plan API**: CRUD endpoints for plans with approve/reject workflow.
- **Proposals API**: CRUD + batch create + approve with sprint target + reject with reason.
- **Analytics in Manager context**: Velocity and quality trends injected into Manager prompt.

### Sprint Flow

- **Sprint transition guards**: Active → Review blocked if in_progress tasks remain. Review → Retro blocked if review/in_progress/todo tasks remain. Retro → Complete blocked while Strategist is generating proposals.
- **Retrospective auto-proposals**: Entering retrospective triggers Strategist to analyze and generate improvement proposals.
- **Review → Retro required**: Removed "Next Sprint" shortcut from Review phase. Must go through Retrospective.
- **Phase error display**: Sprint phase transition failures shown to user (was silently swallowed).
- **CLI active-only task pickup**: Agents only pick up tasks during active phase, not during review/retrospective.

### Quality & Data

- **Quality Score API**: `GET /sprints/:number/quality` and `GET /analytics/quality` with first-pass approve rate, avg review score, and per-agent breakdown.
- **Quality Score UI**: Analytics page trend chart + Sprint header badge.
- **Failure DB management page**: Filter by agent/type, expandable detail rows, pattern analysis UI.
- **Recurring Tasks page**: CRUD with frequency options, enabled/disabled toggle.
- **Tasks Skills field**: Skills array on tasks and recurring tasks, UI editing in task modal.

### Agent Reliability

- **NEEDS_CHANGES → todo**: Tasks with NEEDS_CHANGES verdict automatically reset to todo.
- **Retry limit**: After 3 failed attempts, task moves to review with "Blocked" comment for human review.
- **allow_no_commit_completion**: Template flag — agents that complete without code changes go to review instead of infinite loop.
- **Stream result fallback**: Extracts completion from stream-json result when COMPLETION_JSON is not explicitly output.
- **Per-task execution logger**: `~/.toban/logs/tasks/{taskId}.jsonl` for debugging.
- **Description pre-check**: Tasks with descriptions under 20 characters are auto-blocked.
- **Context budget**: 30K token limit with priority-ordered section trimming.
- **Auto-split**: Tasks with SP >= 5 are automatically split by LLM into subtasks.

### Templates

- **Content template**: For documentation tasks (docs-only file restrictions).
- **Strategy template**: For research/planning tasks (read-only + web search).
- **Reviewer template**: For code review (read-only + test execution).

### Setup & Configuration

- **4 required agents**: Setup automatically creates Manager, Builder, Reviewer, Strategist. Free plan limit raised to 4.
- **Setup overwrite protection**: Re-running setup on a configured project returns 409.
- **Dynamic model selection**: Agent engine setting resolved to model ID per role. Builder defaults to Opus 4.6, Reviewer/Strategist to Sonnet 4.6.
- **Workspace switching**: Cookie and localStorage properly cleared on project switch.

### Infrastructure

- **API proxy removal (production)**: Browser communicates directly with `api.toban.dev`.
- **Agent API key expiry**: 24-hour expiry with sliding window.
- **Git credential caching**: 50-minute token cache.
- **blocked status**: Added to task status enum.
- **Playbook tags**: Tag-based skill rule matching.
- **Sprint plans + Task proposals tables**: Persistent storage for Strategist outputs.
- **Origin header forwarding**: Proxy forwards Origin for correct cookie domain on localhost.

### Known Issues (fixed from v0.1.0)

- ~~Agent API keys do not expire~~ → 24h expiry with sliding window
- ~~Review timeout on large diffs~~ → Reviewer agent with 5min timeout

### Known Issues (remaining)

- Individual use only — team/multi-user features not available
- GitHub App org installation may not appear in Setup (workaround: set installation_id manually)
- Manager chat is unreliable — use `toban plan` / `toban propose` CLI commands instead
- **API 500 on D1 writes**: Task updates and review-report may intermittently return 500. CLI retries automatically (2 attempts with backoff), but root cause needs investigation
- **Reviewer max-turns**: Reviewer may hit 5-turn limit on no-commit verification tasks. Increase planned
- **Strategist proposals fetch**: `toban propose` may fail to save proposals due to execSync blocking Node.js event loop. Proposals display in CLI but may not persist to DB
- **engine/model column**: DB `agents.engine` mixes provider types (claude-code) and model names (claude-opus). CLI has PROVIDER_ENGINE_IDS workaround
- **Setup duplicate tasks**: Initial Sprint #0 may generate duplicate tasks via Manager or RETRO suggested_tasks
- **RETRO_JSON parse**: Agent may append text after RETRO_JSON, causing parse failure
- **localStorage leakage**: Workspace-scoped data (terminal, proposals) not prefixed with workspace ID — cleared on switch but not preserved per project
- **Sprint #0 planning status**: Newly created projects start with planning status. UI now shows "Start Sprint" button correctly

## v0.1.0 (2026-03-19)

Initial public release.

### Features

- **Sprint Management**: Kanban board with drag-and-drop, sprint phases (active/review/retrospective/completed)
- **Manager AI**: LLM-powered task proposals, sprint coordination, interactive proposal cards
- **Builder Agent**: Automated code implementation in git worktrees, trunk-based development
- **Auto Code Review**: LLM-generated structured review (requirement match, code quality, test coverage, risks, verdict)
- **Real-time Dashboard**: WebSocket-powered live updates for tasks, agents, and sprint state
- **Sprint Analytics**: Velocity, burndown, hourly activity, cumulative charts
- **Playbook**: Configurable agent rules (locked/overridable/recommended), per-agent targeting
- **ADR System**: Architecture Decision Records injected into agent prompts
- **Project Spec**: Vision, roadmap, tech stack — feeds into agent context
- **Multi-repo Support**: Agents can work across multiple repositories
- **GitHub App Auth**: OAuth login, installation token for git operations
- **CLI**: `npx toban-cli@latest start` — connects to dashboard, spawns agents locally

### Known Issues

- Individual use only — team/multi-user features are not yet available
- GitHub App installed on an organization may not appear in Setup repo selection (personal account only)
- Project deletion and re-creation may leave stale data in some edge cases
- Claude Code CLI must be installed locally to run agents (no cloud execution yet)
- Review timeout on large diffs (workaround: keep tasks small)
- Agent API keys do not currently expire (fix planned)


---

# Toban vs Claude Code: When Do You Need a Platform?

Claude Code is an excellent AI coding assistant. If you're already using it, you know how powerful it is for writing code, debugging, and exploring codebases. So why would you add Toban on top?

This page gives you an honest comparison to help you decide.

## What Claude Code Does Well (Alone)

Claude Code is the fastest way to get things done when you have a clear, one-off task:

- **Deep debugging** — point it at a bug, get a fix
- **Architecture exploration** — ask questions about your codebase
- **Quick implementations** — "add a reload button to this component"
- **Refactoring** — rename, restructure, modernize code

For these immediate, well-defined tasks, Claude Code alone is quicker and has less overhead. There's no reason to add process around a 5-minute fix.

## What Toban Adds

Toban wraps Claude Code in a development workflow. The difference becomes clear when you're working across multiple tasks over days and weeks:

| Capability | Claude Code Alone | Toban + Claude Code |
|---|---|---|
| Task execution | Manual, one at a time | Sprint-based, queued and tracked |
| Task planning | You decide what to do next | Manager AI proposes tasks from your backlog |
| Code review | You review the diff yourself | Structured LLM review with quality scoring |
| Quality tracking | None — each session starts fresh | Quality Score trends across sprints |
| Learning from mistakes | You remember (or don't) | Failure Database captures and prevents recurring issues |
| Agent behavior control | CLAUDE.md only | Knowledge base + ADRs that accumulate over time |
| Sprint analytics | None | Velocity, burndown, task completion metrics |
| Progress visibility | Terminal output | Real-time dashboard via WebSocket |

### The Key Differences

**Sprint Management** — Toban organizes work into sprints. The Manager AI reviews your backlog, proposes tasks, and sequences them. You approve or reject. No more "what should I work on next?"

**Structured Review** — Every task gets an LLM code review before merge. Reviews follow consistent criteria and produce Quality Scores. Over time, you see whether your agents are improving.

**Knowledge & ADRs** — Shared knowledge and architectural decisions that guide agent behavior. Coding conventions and design rationale are captured and injected into agent prompts automatically. New agents inherit team knowledge from day one.

**Failure Database** — When reviews catch issues, the patterns are recorded. Future agents receive warnings about past failures relevant to their current task. The system gets smarter with every review cycle.

**Quality Score Tracking** — Numeric Quality Scores per task and per sprint. See trends, identify weak areas, and measure improvement over time.

## When to Use Claude Code Directly

Use Claude Code without Toban when:

- You need an immediate answer or quick fix
- You're doing exploratory work (architecture, debugging, research)
- The task is self-contained and doesn't need tracking
- You're prototyping or experimenting

Claude Code is your power tool for deep, focused work. Keep using it directly for these cases.

## When to Use Toban

Use Toban when:

- You have a backlog of tasks and want structured execution
- You care about code quality trends over time
- You want consistent review standards across all changes
- You're building a project where mistakes should accumulate into team knowledge
- You want to spend less time deciding what to do next and more time approving results

Toban is your project management layer. It handles the "what, when, and how well" so Claude Code can focus on the "how."

## Recommended Workflow

Most developers use both:

1. **Toban for sprint work** — queue up tasks, let the Manager AI propose priorities, have agents implement and get reviewed
2. **Claude Code directly for deep work** — architecture decisions, complex debugging, exploratory coding

They complement each other. Toban adds process and data accumulation. Claude Code adds speed and flexibility.

## The Compounding Effect

The real value of Toban shows up over time. Each sprint cycle:

- Review data feeds the Failure Database
- Quality scores accumulate and reveal trends
- Knowledge and ADRs get refined based on real outcomes
- The Manager AI gets better context for task proposals

After a few sprints, your agents are measurably smarter than when they started. This compounding effect is something you can't get from Claude Code alone — no matter how good it is at individual tasks.

## Getting Started

Already using Claude Code? Toban takes about 5 minutes to set up:

```bash
npx toban-cli@latest start --api-url https://api.toban.dev --api-key <KEY>
```

Your existing Claude Code authentication works automatically. See the [Getting Started guide](./getting-started.md) for the full setup walkthrough.


---

# Glossary

Definitions of terms used in Toban.

## Core Concepts

### Project
The top-level unit of management in Toban. A Project contains a connected GitHub repository, agents, sprints, and ADRs. Switch between Projects from the sidebar header.

> **API name**: `workspace`. The API endpoints use `/api/v1/workspace`, but the user-facing term is "Project."

### Sprint
A time-boxed work cycle. Phases progress in order: Active -> Review -> Retrospective -> Completed. A Project can have multiple Sprints. Sprint #0 is the initial sprint auto-created on Project setup.

### Task
A unit of work within a Sprint. Status transitions: todo -> in_progress -> review -> done. When the owner is set to an agent role (e.g. builder), the CLI picks it up automatically. Tasks owned by `user` require manual handling.

### Backlog
Tasks not assigned to any Sprint (sprint number = -1). Use the Backlog to queue work for future Sprints.

### Story
A higher-level work item that groups related Tasks. Creating a Story auto-creates a Builder task for it. Stories provide structure for larger features.

### Handoff Notes
Context notes attached to a task (`context_notes` field). Used to pass information between agents or from a user to an agent when a task is created or reassigned.

## Agents

### Manager
LLM-powered coordination agent. Interacts with users via chat, proposes tasks (propose_tasks), requests agent spawning (spawn_agent), and manages Sprint flow. Included as a platform service.

### Builder
Worker agent that implements code. Works in an isolated git worktree, commits changes, and the CLI merges to main and pushes on completion.

### Reviewer
A template (not a standalone agent role) used to perform structured code review on completed tasks. Produces a review report with quality scoring.

## Configuration

### Template
A prompt template that controls agent behavior. Available templates: `implementation` (for Builder task execution) and `reviewer` (for code review).

### Knowledge
Shared memory entries that persist across agent sessions. Used for cross-agent context (design decisions, known issues, architecture notes). Managed at Settings > Knowledge or via the API.

### ADR (Architecture Decision Record)
A document recording an architectural decision for the Project. ADRs are injected into agent prompts so agents respect past decisions. Each ADR has context, decision, rationale, and consequences.

### Project Spec
Defines the Project's vision, target users, tech stack, roadmap, and constraints. Used as context in agent prompts.

### Prompts
A read-only debug preview of the full prompt that agents receive. Available at Agents > Prompts or via `GET /api/v1/agents/:name/prompt-preview`.

## Infrastructure

### CLI (toban-cli)
The local agent runner. Communicates with the dashboard via WebSocket and REST API. Spawns and manages agent processes. Run with `npx toban-cli@latest start`.

### Engine
The execution backend for agents. Currently only `claude-code` (Claude Code CLI) is supported. Future engines: `claude-api`, `codex`, `gemini`.

### Worktree
An isolated working directory created via git worktree for each task. Each agent gets its own branch and directory, merged to main on completion.

### Audit Log
A record of security-relevant events in the workspace (auth events, agent spawns, prompt injection attempts).

## Workflow

### Story Points
Estimation of task size using the Fibonacci sequence: 1, 2, 3, 5, 8.

### Velocity
Total story points completed per Sprint. Viewable on the Analytics page.

### Quality Score
A numeric score (0-100) calculated from review results. Based on requirement match, code quality, test coverage, and risk assessment. Tracked per task and aggregated per sprint.

### Enrich
An optional step that adds structured details (acceptance criteria, technical notes) to a task before agent execution. Not required.

### Sprint Goal
A free-text memo field on a Sprint describing what the sprint aims to accomplish.


---

# Pricing & Cost Guide

## Toban Platform

All workspaces include the full Pro feature set at no cost during beta. No credit card required.

The platform provides:

- **Manager AI** -- task proposal, sprint planning, and coordination
- **Code Review** -- structured review with quality scoring
- **Dashboard** -- real-time sprint tracking, analytics, and agent monitoring
- **Failure Database** -- accumulated review data that improves agent quality over time
- **Knowledge** -- shared memory for cross-agent context preservation

## AI Agent Costs

Toban orchestrates AI coding agents that run on your local machine. The AI API costs are billed directly by the provider (Anthropic) to your account.

### Claude Code API Credits

- Billed by Anthropic separately based on token usage
- You need an active Anthropic API subscription or Claude Code plan
- Toban does not add any markup to AI costs

### Typical Token Usage Per Task

| Task Complexity | Estimated Tokens | Description |
|---|---|---|
| Simple | ~50K tokens | Small bug fixes, config changes, single-file edits |
| Medium | ~100K tokens | Feature implementation, multi-file changes |
| Complex | ~200K tokens | Large features, architectural changes, extensive testing |

Token usage varies based on codebase size, task complexity, number of review iterations, and agent conversation length.

## Future Plans

Paid tiers and pricing will be announced before general availability.

## The Data Advantage

The longer you use Toban, the more valuable it becomes:

- **Quality Scores** -- track agent performance across tasks and sprints
- **Failure Database** -- learn from past mistakes to prevent recurring issues
- **Knowledge** -- shared memory captures design decisions and architectural context
- **ADRs** -- codify architectural decisions that guide agent behavior

This accumulated knowledge acts as your team's institutional memory, making every sprint more efficient than the last.

## FAQ

**Do I need to pay anything to try Toban?**
No. Toban is free during beta with the full Pro feature set. You only need an Anthropic account for Claude Code API usage.

**Will my data be retained after beta?**
Yes. All quality scores, failure data, and knowledge will carry over to the general release.

**Can I control AI spending?**
Token usage depends on task complexity. You can manage costs through your Anthropic account settings and by keeping tasks small and focused (which is also a best practice for code quality).