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:

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:

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

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:

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