---
name: Per-Project Agent Configuration and Role Definitions
---
# Story 34: Per-Project Agent Configuration and Role Definitions

## User Story
As a user, I want to define a team of named agents for my project — each with a specific role, model, tool permissions, and budget — so that the orchestrator can spawn the right agents with the right capabilities when working on stories.

## Context
Spike 1 proved that Claude Code agents communicate via PTY and support per-agent configuration through CLI flags (`--model`, `--allowedTools`, `--max-turns`, `--max-budget-usd`, `--append-system-prompt`). Story 30 introduced a basic single `[agent]` section in `config.toml`. This story replaces that with a multi-agent configuration system where each project defines a named roster of agents with distinct roles.

## Acceptance Criteria
- [ ] A project-level config file (`.story_kit/config.toml`) supports defining multiple named agents, each with: name, role description, model, allowed tools, max turns, max budget, and a system prompt supplement.
- [ ] Agent definitions are parsed and validated on server startup; invalid configs produce clear error messages.
- [ ] A Rust struct (`AgentConfig`) represents a single agent definition, and an `AgentRoster` holds the full set of agents for the project.
- [ ] The existing `AgentPool` is updated to spawn agents using their `AgentConfig` (model, tools, budget, system prompt) rather than hardcoded defaults.
- [ ] A REST endpoint (`GET /agents/config`) returns the current agent roster so the frontend can display available agents and their roles.
- [ ] The frontend displays the configured agent roster (name, role, model) somewhere visible (e.g., a sidebar panel or settings view).
- [ ] At least one predefined role template exists as a documented example: `supervisor` (Opus, all tools, higher budget) and `coder` (Sonnet, restricted tools, lower budget).
- [ ] Agent configs are hot-reloadable: editing `config.toml` and hitting a reload endpoint (or restarting) picks up changes without losing running agent state.

## Configuration Format

```toml
# .story_kit/config.toml

[[component]]
name = "server"
path = "."
setup = ["cargo check"]
teardown = []

[[component]]
name = "frontend"
path = "frontend"
setup = ["pnpm install"]
teardown = []

[[agent]]
name = "supervisor"
role = "Coordinates work across agents. Reviews PRs, decomposes stories, assigns tasks."
model = "opus"
allowed_tools = ["Read", "Glob", "Grep", "Bash"]
max_turns = 50
max_budget_usd = 10.00
system_prompt = "You are a senior engineering lead. Coordinate the coder agents, review their work, and ensure quality."

[[agent]]
name = "coder-1"
role = "Implements backend features in Rust."
model = "sonnet"
allowed_tools = ["Read", "Edit", "Write", "Bash", "Glob", "Grep"]
max_turns = 30
max_budget_usd = 5.00
system_prompt = "You are a backend engineer. Write clean, tested Rust code. Follow the project's STACK.md conventions."

[[agent]]
name = "coder-2"
role = "Implements frontend features in TypeScript/React."
model = "sonnet"
allowed_tools = ["Read", "Edit", "Write", "Bash", "Glob", "Grep"]
max_turns = 30
max_budget_usd = 5.00
system_prompt = "You are a frontend engineer. Write clean, tested TypeScript/React code. Follow the project's STACK.md conventions."

[[agent]]
name = "reviewer"
role = "Reviews code changes, runs tests, checks quality gates."
model = "sonnet"
allowed_tools = ["Read", "Glob", "Grep", "Bash"]
max_turns = 20
max_budget_usd = 3.00
system_prompt = "You are a code reviewer. Read the diff, run tests, check linting, and provide actionable feedback."
```

## How Agent Config Maps to PTY Flags

Each `AgentConfig` field maps directly to a Claude Code CLI flag when spawning via PTY:

| Config Field | CLI Flag |
|---|---|
| `model` | `--model sonnet` |
| `allowed_tools` | `--allowedTools "Read,Edit,Bash"` |
| `max_turns` | `--max-turns 30` |
| `max_budget_usd` | `--max-budget-usd 5.00` |
| `system_prompt` | `--append-system-prompt "..."` |

## Out of Scope
- Agent-to-agent communication protocol (future story).
- Automatic agent assignment to stories (supervisor does this manually for now).
- Worktree creation/teardown (Story 30).
- Dynamic port management (Story 32).
- Runtime role enforcement beyond CLI flag restrictions (agents are trusted to follow their system prompt).
- UI for editing agent configs (edit `config.toml` directly for now).
