# Agent Profiles

**Agent profiles** are doctrine artifacts that define an agent's identity — its role,
specialization boundaries, collaboration contracts, and initialization behavior.
Profiles are the **identity layer** beneath missions: missions orchestrate *what work
happens*; profiles govern *who does the work and how they behave*.

An agent profile is distinct from a tool configuration. An **agent** is a logical
collaborator identity (implementer, reviewer, architect); a **tool** is a concrete
runtime product (Claude Code, Codex, opencode). This package defines agent identity;
tool installation is managed by `ToolConfig`.

## 6-Section Structure

Each profile defines:

1. **Context Sources** — Doctrine layers and directives to load
2. **Purpose** — What the agent does and does not do
3. **Specialization** — Primary focus, secondary awareness, avoidance boundaries
4. **Collaboration Contract** — Handoff partners, output artifacts, canonical verbs
5. **Mode Defaults** — Operating modes with descriptions and use-cases
6. **Initialization Declaration** — Self-description loaded at session start

## Layered Loading

Profiles are loaded from layered sources with field-level merge:

- **Shipped profiles** (`built-in/`) — Reference profiles included in the package
- **Organization profiles** — Optional organization-level pack overlays
- **Project profiles** (`.kittify/charter/agents/`) — Custom overrides per project

Each higher layer can override a lower-layer profile at field level when sharing
the same `profile-id`; project profiles have final precedence.

## Shipped Profiles

| Profile ID | Name | Role |
|------------|------|------|
| `architect-alphonso` | Architect Alphonso | architect |
| `curator-carla` | Curator Carla | curator |
| `debugger-debbie` | Debugger Debbie | investigator |
| `designer-dagmar` | Designer Dagmar | designer |
| `frontend-freddy` | Frontend Freddy | implementer |
| `generic-agent` | Generic Agent | implementer |
| `human-in-charge` | Human in Charge | human-in-charge |
| `implementer-ivan` | Implementer Ivan | implementer |
| `java-jenny` | Java Jenny | implementer |
| `node-norris` | Node Norris | implementer |
| `paula-patterns` | Paula Patterns | architecture-scout |
| `planner-priti` | Planner Priti | planner |
| `python-pedro` | Python Pedro | implementer |
| `randy-reducer` | Randy Reducer | implementer |
| `researcher-robbie` | Researcher Robbie | researcher |
| `retrospective-facilitator` | Retrospective Facilitator | facilitator |
| `reviewer-renata` | Reviewer Renata | reviewer |

## Python API

- `AgentProfile` — Pydantic domain model
- `AgentProfileRepository` — Layered loading, hierarchy, weighted matching
- `validate_agent_profile_yaml()` — JSON Schema (Draft 7) validation
- `RoleCapabilities` / `DEFAULT_ROLE_CAPABILITIES` — Role-based capability defaults

## Schema

Profiles are validated against `schemas/agent-profile.schema.yaml`.

## Glossary Reference

See [Agent](../../../glossary/contexts/identity.md#agent) and
[Tool](../../../glossary/contexts/execution.md#tool) in the glossary for the
canonical naming distinction.
