Agent Configurations

Foundry uses a multi-agent workflow where a Manager agent decomposes tasks and assigns them to specialist agents. Each specialist has tuned model settings, permissions, and a focused system prompt. This page documents the 6 agent configurations and how to set them up.

Quick Setup

1. Open VibeKanban → Settings → Agents
2. Create each of the 6 configurations below with the exact settings
3. When the Manager breaks down a task, it recommends which config to use
4. Select the recommended config when launching a workspace session via start_workspace_session

Agent Roles

Manager

The orchestrator. Reads the codebase, breaks tasks into subtasks, and assigns the right specialist to each. Never writes code.

Append Prompt:

You are a technical project manager. Your job is to plan, not implement. Read the project's AGENTS.md and understand the codebase architecture before planning. Break the task into specific, actionable subtasks. For each subtask: describe the scope clearly, identify which files are likely affected, and recommend the appropriate agent config (Implementer, Quick Fix, Reviewer, Debugger, or Browser Tester). For any task involving visual UI/UX review, screenshot checks, layout verification, styling bugs, or responsive testing, assign it to the Browser Tester config. Create subtasks via create_issue. Do not write code yourself.

Why these settings: Opus for strongest reasoning on task decomposition. Plan ON because this agent plans, not codes. Router OFF to ensure full context for every planning decision.

Implementer

The primary developer. Handles feature implementation, refactoring, and multi-file coding tasks.

Append Prompt:

You are a senior developer. Read the project's AGENTS.md and any relevant module-level AGENTS.md files before starting. Follow the project's rules and conventions in .agents/rules/. Prefer existing libraries over custom code. Write tests for new functionality. Commit with descriptive messages.

Why these settings: Opus for complex multi-file work. Plan OFF — receives pre-planned tasks from Manager. Router ON to use a lighter model for simple sub-steps (reads, small edits) and save context for complex work.

Quick Fix

Fast, focused changes. Bug fixes, typos, small targeted edits.

Append Prompt:

Focus on the specific fix. Don't refactor surrounding code. Don't add features. Make the minimal change needed to solve the problem. Run tests after changes. Commit with a clear message describing what was fixed and why.

Why these settings: Sonnet is fast and capable enough for targeted single-file fixes — saves cost and latency. Plan OFF and Router OFF because scope is small and focused.

Reviewer

Read-only code review. Examines changes without modifying files.

Append Prompt:

Review mode only. Do not modify any files. Read the project's AGENTS.md and .agents/rules/ to understand conventions. Review the code changes and report: correctness issues, convention violations, missing tests, security concerns, performance problems, and readability issues. Output a structured review with PASS/FAIL per category and specific line references for each finding.

Why these settings: Opus for deepest reasoning — catches subtle bugs and architectural issues. Plan OFF (analyzing, not planning). Router OFF to ensure full-quality analysis on every file read.

Debugger

Investigates bugs, traces root causes, and applies targeted fixes.

Append Prompt:

You are a systematic debugger. Before changing any code: 1) Reproduce the issue, 2) Form a hypothesis about the root cause, 3) Verify the hypothesis by reading relevant code paths, 4) Only then apply a minimal fix. Do not guess — trace the actual execution path. Add a regression test if possible. Explain what caused the bug and why your fix is correct.

Why these settings: Opus for tracing complex bug paths across multiple files. Router ON because debugging involves many file reads (cheap with lighter model) before the critical fix (needs full model).

Browser Tester

Visual UI/UX bug detection using the agent-browser skill. Captures annotated screenshots and reports layout and styling issues.

Append Prompt:

You are a specialized Browser Visual Tester. Your job is UI/UX visual bug detection using the agent-browser skill. For every visual review task: 1) Use `agent-browser open <url> && agent-browser wait --load networkidle && agent-browser screenshot --annotate` to capture the page. 2) Analyze the annotated screenshot and element refs for misalignments, missing elements, styling issues, and responsive problems. 3) Report findings in structured format with @eN references and screenshot paths. 4) Always close browser sessions when done. Do not edit code unless explicitly asked — report findings only.

Why these settings: Sonnet for fast visual reasoning — sufficient for screenshot analysis. Plan OFF (analyzing, not planning). Router OFF to keep the session focused. Read-heavy role with minimal code modifications.

Quick Reference

Task Routing

When the Manager breaks down a task, it assigns each subtask to the appropriate config:

Visual Testing Workflow

The Browser Tester agent uses agent-browser for screenshot-based visual reviews. The dev server must be running first.

Quick Start

# One-command review via wrapper script
bash .claude/scripts/visual-review.sh http://localhost:3000

# With a CSS selector to scope the review
bash .claude/scripts/visual-review.sh http://localhost:3000 "[data-testid='section-hero']"

Manual Workflow

# Open page and wait for load
npx agent-browser open http://localhost:3000
npx agent-browser wait --load networkidle

# Annotated screenshot (numbered labels on interactive elements)
npx agent-browser screenshot --annotate --full

# Scoped snapshot using data-testid
npx agent-browser snapshot -i -s "[data-testid='convert-form']"

# Before/after comparison
npx agent-browser screenshot baseline.png
# ... make changes ...
npx agent-browser diff screenshot --baseline baseline.png

# Always close when done
npx agent-browser close

Available Selectors

Foundry components set data-testid attributes automatically. Use these for scoped reviews:

See Agent Navigability for the full data-testid convention.

Observability

Every agent-browser command is logged to .claude/visual-test-log.md (gitignored) via a PostToolUse hook. Check this file to audit what commands were run during a visual review session:

cat .claude/visual-test-log.md
# [2026-02-27T18:09:54] npx agent-browser open http://localhost:3000 ...
# [2026-02-27T18:10:02] npx agent-browser screenshot --annotate --full

Claude Code Sub-Agents

In addition to VibeKanban agent configs, Foundry includes Claude Code sub-agents in .claude/agents/. These load automatically — no manual setup needed:

The VibeKanban configs and Claude Code sub-agents complement each other. VibeKanban configs are for workspace sessions (launched from the kanban board). Sub-agents are for in-session delegation (the main agent spawning a specialist via the Task tool).

Customization

To modify configs for your project:

1. Adjust the append prompt — Add project-specific instructions (e.g., "always run pnpm test before committing")
2. Change the model — Swap Opus for Sonnet on cost-sensitive roles, or vice versa for quality-critical ones
3. Add a new role — Follow the pattern: define purpose, pick model/plan/router settings, write a focused append prompt
4. Update the Manager — If you add a new role, update the Manager's append prompt so it knows to route tasks there