---
sidebar_position: 1
title: Agents
---

# Agents

Specialized agents that handle distinct responsibilities in your development workflow. Each agent is defined in the canonical `agents/` content (shipped in the bundled npm package) and adapted to your coding tool's native format.

## Agent Reference

| Agent | Description |
|-------|-------------|
| **architect** | System architect who designs architecture, creates ADRs, analyzes dependencies, designs APIs and database schemas, and evaluates architectural trade-offs. |
| **brownfield-spec** | Brownfield spec agent -- produces a codebase map, existing-pattern detection, integration-surface analysis, and a migration-aware plan with a non-destructive-adoption check. |
| **ci-watcher** | CI/CD specialist who monitors pipeline runs, reads failure logs to diagnose root causes, and suggests focused fixes with local verification commands. |
| **context-rules** | Context-aware rules engine that applies coding standards based on file type, location, and project conventions, on save or during review. |
| **creator** | User-content authoring agent invoked by `/hatch3r-create`. Authors one user-tier artifact under `.hatch3r/overrides/`, runs strict + gentle quality gates, and writes only when all strict gates pass. |
| **dependency-drafter** | Dependency-analysis specialist who drafts version-bump and dependency-change proposals with upgrade-impact, advisory, and breaking-change assessment. Drafts only; never installs or edits a manifest. |
| **devops** | DevOps engineer who manages CI/CD pipelines, infrastructure as code, deployment strategies, monitoring setup, container configuration, and environment management. |
| **docs-writer** | Technical writer who maintains specs, ADRs, and documentation, keeping them in sync with code changes. |
| **edge-case-analyst** | Domain edge-case + error-handling correctness specialist who enumerates functional edge cases (identity collisions, state transitions, null/boundary, concurrency, partial failure) and verifies none were dropped between Plan, Implement, and Review. |
| **enhancability** | Enhancability quality specialist who reviews generated code for feature-flag adoption, config externalization, versioned APIs, forward-compatibility, and extension-point definition. |
| **fixer** | Targeted fix agent that takes structured reviewer output and implements fixes for Critical and Warning findings. Does not handle git, branches, commits, or PRs. |
| **greenfield-spec** | Greenfield spec agent -- produces market research, competitive analysis, user personas, tech-stack picks, PRD, acceptance criteria, risk inventory, and test plan for new projects. |
| **handoff-loader** | Session-start agent that surfaces active handoff documents from `.hatch3r/handoffs/active/` to detect in-progress work for resumption. |
| **handoff-preparer** | Prepares a canonical handoff document capturing mid-work session state, invoked by the on-context-switch hook and by `/hatch3r-handoff prepare`. |
| **implementer** | Focused implementation agent for a single issue. Receives issue context, delivers code changes and tests. Does not handle git, branches, commits, PRs, or board operations. |
| **incident-responder** | Incident-response specialist who drives a live production incident through structured triage, bounded-autonomy mitigation, stakeholder communication, and a blameless post-mortem. |
| **learnings-loader** | Session-start agent that surfaces relevant project learnings, recent decisions, and context from previous sessions. |
| **lint-fixer** | Code quality enforcer who fixes style, formatting, and TypeScript strict mode violations without changing logic. |
| **maintainability** | Maintainability quality specialist who reviews generated code for duplication index, pattern reuse, cyclomatic complexity, expand-contract migrations, and API breaking-change discipline. |
| **pack-installer** | Installs a community pack into the consumer repo after the trust-model gate clears -- verifies trust tier + signing method, dry-runs the write set, applies atomically, and rolls back on any failure. |
| **performance** | Performance quality specialist who reviews generated code for Core Web Vitals budgets (LCP/INP/CLS), backend p95/p99 latency, bundle size, and N+1 query elimination. |
| **reliability** | Reliability quality specialist who reviews generated services for OpenTelemetry instrumentation, SLO definition, RED+USE metrics, RFC 9457 error responses, and circuit-breaker/retry patterns. |
| **researcher** | Composable context researcher. Receives a research brief with mode selections and depth level, gathers context following the tooling hierarchy, and returns structured findings. Does not create or modify files. |
| **reviewer** | Expert code reviewer who checks for quality, security, privacy invariants, performance, accessibility, and adherence to specs. Outputs structured feedback by priority (critical, warning, suggestion). |
| **scalability** | Scalability quality specialist who reviews generated services for stateless handlers, back-pressure patterns, idempotency-key adoption, queue-based offloading, and connection-pool sizing. |
| **security** | Security quality specialist who reviews generated code for OAuth 2.1 + OIDC + DPoP + WebAuthn server-side, supply-chain integrity (SBOM + provenance + SHA-pin + cosign), and OWASP ASI controls. |
| **testability** | Testability quality specialist who reviews generated code for the per-feature test-class mandate, real-deal-first testing, coverage thresholds, and AI feature eval coverage. |
| **ui** | UI quality specialist who reviews generated UI for WCAG 2.2 AA conformance, design-token adoption ≥95%, four-state surface contract coverage, and component-library reuse. |
| **ux** | UX quality specialist who reviews generated UX flows for error-recovery clarity, first-run success, decisions-per-flow discipline, focus management, and screen-reader announcement. |

## Default Model Assignments

Some agents ship with a default model in their canonical frontmatter, tuned for their cognitive profile.

| Agent | Default Model | Rationale |
|-------|:-------------:|-----------|
| `hatch3r-lint-fixer` | `haiku` | Mechanical pattern fixes; speed and low cost matter most |
| `hatch3r-ci-watcher` | `haiku` | Log parsing and pattern recognition; fast feedback loops |
| `hatch3r-docs-writer` | `sonnet` | Writing quality and technical accuracy need a capable model |
| `hatch3r-security` | `sonnet` | OAuth/OIDC/supply-chain analysis requires solid reasoning |
| `hatch3r-ui` | `sonnet` | WCAG 2.2 AA + design-token interpretation requires solid reasoning |
| `hatch3r-testability` | `sonnet` | Edge-case identification and test design need reasoning depth |

Agents without a default use the platform's own default. Override any agent's model via [Model Selection](../guides/model-selection).

## Canonical Location

Agent definitions live in the canonical `agents/hatch3r-{id}.md` content (bundled npm package; user-tier overrides mirror this layout under `.hatch3r/overrides/agents/`) with YAML frontmatter:

```yaml
---
id: hatch3r-implementer
description: Focused implementation agent for a single issue.
model: opus
---
```

## Customization

Override agent behavior per-project using `.hatch3r/agents/{id}.customize.yaml`. See [Customization](../guides/customization).

## Agent Modes

Modes are orchestration-depth profiles that `hatch3r-researcher` selects per task. Each mode constrains the researcher's output structure and tool usage to a single research dimension. Files live in the canonical `agents/modes/{mode}.md` content (bundled npm package).

| Mode | Purpose | Used by |
|------|---------|---------|
| `root-cause` | Rank candidate root causes by likelihood using static analysis patterns (race conditions, null checks, anti-patterns). | `hatch3r-researcher` (bug-plan flows) |
| `feature-design` | Break a subject into implementable sub-tasks with user stories, acceptance criteria, edge cases, and effort estimates. | `hatch3r-researcher` (feature-plan flows) |
| `complexity-risk` | Identify complexity hotspots and mutation-prone areas to prioritize testing effort. | `hatch3r-researcher` (`hatch3r-test-plan` flows) |
| `requirements-elicitation` | Detect ambiguities and generate structured user questions across 10 dimensions before implementation. | `hatch3r-researcher` (triggered by `hatch3r-deep-context` rule) |
| `user-flows` | Decompose a user story into Happy Path, Alternative Paths, and Error-Recovery Path with four-state mapping and microcopy before implementation. | `hatch3r-researcher` (gates `hatch3r-feature-plan` and `hatch3r-implementer`) |
| `risk-assessment` | Identify technical risks, security implications, performance concerns, and breaking changes. | `hatch3r-researcher` (planning and review flows) |
| `coverage-analysis` | Map existing test coverage, identify gaps, and surface critical untested paths. | `hatch3r-researcher` (`hatch3r-test-plan` flows) |
| `boundary-analysis` | Map integration boundaries, external dependencies, and data-flow seams for integration and contract test targeting. | `hatch3r-researcher` (`hatch3r-test-plan` flows) |
| `architecture` | Design the architectural approach: data model, API contracts, component design, and ADR-worthy decisions. | `hatch3r-researcher` (planning and refactor flows) |
| `migration-path` | Design a phased execution plan with safe ordering, rollback points, and parallel lanes mapped to execution skills. | `hatch3r-researcher` (planning and refactor flows) |
| `regression` | Investigate when an issue was introduced by analyzing git history, dependency updates, and configuration changes. | `hatch3r-researcher` (bug-plan flows) |
| `impact-analysis` | Map the blast radius of an issue across flows, modules, data, and downstream consumers. | `hatch3r-researcher` (bug-plan and review flows) |
| `codebase-impact` | Analyze the current codebase to map what exists in the areas a subject touches (files, modules, coupling). | `hatch3r-researcher` (planning flows) |
| `current-state` | Map the current state of code under analysis — complexity, coupling, cohesion, coverage — across structural, logical, visual, and migration dimensions. | `hatch3r-researcher` (refactor-plan flows) |
| `library-docs` | Look up current API documentation for a named library via Context7 MCP (`resolve-library-id` plus `query-docs`). | `hatch3r-researcher` (any flow needing external library facts) |
| `prior-art` | Research best practices, known issues, and ecosystem trends via web search for novel problems or security advisories. | `hatch3r-researcher` (any flow without local docs coverage) |
| `refactoring-strategy` | Design the refactoring approach: transformations (extract/inline/rename/restructure), invariants, and patterns. | `hatch3r-researcher` (refactor-plan flows) |
| `risk-prioritization` | Produce a risk-ranked prioritization of testing effort by business impact, security exposure, change frequency, and coverage. | `hatch3r-researcher` (`hatch3r-test-plan` flows) |
| `similar-implementation` | Search the codebase for analogous features and extract implementation conventions for the implementer to follow. | `hatch3r-researcher` (feature-plan and implementation flows) |
| `symptom-trace` | Trace reported symptoms through the codebase to find where expected behavior diverges from observed behavior. | `hatch3r-researcher` (bug-plan flows) |
| `test-pattern` | Extract existing test conventions, framework usage, mock patterns, and helper libraries so new tests align with project infrastructure. | `hatch3r-researcher` (`hatch3r-test-plan` flows) |

## Shared Agent Resources

Reference documents under the canonical `agents/shared/` content (bundled npm package) provide cross-agent canonical authority. Agents include them via frontmatter fields such as `quality_charter:` and `efficiency_patterns:` rather than copying content.

| File | Purpose |
|------|---------|
| `quality-charter.md` | Canonical quality authority referenced by every agent: confidence levels, current-information tooling hierarchy, root-cause orientation, measurable criteria. The single source of truth for agent conduct. |
| `prompt-structure.md` | XML-tag structuring pattern (`<task>`, `<context>`, `<rules>`) for agent prompts per Anthropic Claude 4.x guidance. Applied to agents over 200 lines or with mixed content types. |
| `efficiency-patterns.md` | The 8 P7 efficiency patterns referenced via `efficiency_patterns:` frontmatter (static-first prompts, parallel-tool-by-default, triage-first orchestration, plan/act split, structured outputs, lazy loading, conditional loading, diff-only outputs). |
| `external-knowledge.md` | Tooling hierarchy for external lookups: specs first, then codebase, Context7 MCP, web research, and the platform CLI (`gh` / `az` / `glab`) for issue and PR operations. |
| `injection-patterns.md` | Canonical catalog of prompt-injection patterns kept in lockstep with `src/pipeline/promptGuard.ts` and `src/content/learningsValidation.ts`. OWASP ASI01/ASI06/ASI07 coverage. |
| `user-content-templates.md` | Body and frontmatter skeletons for the 5 user-authored content types (agent, skill, rule, command, hook). Consumed by `hatch3r-creator`. |
| `user-question-protocol.md` | Protocol for surfacing clarifying questions across the 3 supported platforms (Claude Code, Cursor, Copilot): when to ask, native-tool preference, and plain-text fallback shape. |

