forge-agent

forge-agent: generate a project agent for a pipeline role

Writing an agent is Test-Driven Development applied to a role definition: gather evidence first (domain best practices + how THIS codebase actually works), write the persona against that evidence, then check it against representative tasks. An agent written from generic knowledge alone is a generic agent. The codebase context is what earns its keep.

Inputs

• The ROLE it fills (one of ticketmill's: implementer for a domain, task_reviewer, spec_reviewer, code_reviewer, contrarian, test_validator, simplifier, docblock_writer, doc_writer; or any role the user names).
• The target repo root.

Step 1: Research the domain

Use WebSearch for the agent's domain, current year:

• "[domain/framework] best practices [year]"
• "[domain] anti-patterns" / "common mistakes"
• "[technology] security considerations" (when applicable)

Harvest concrete, actionable items: these feed the anti-patterns section. Skip generic advice ("write clean code") that changes no behavior.

Step 2: Ground it in the codebase

1. Read the repo's CLAUDE.md and README for hard conventions.
2. Explore the structure the agent will work in (key directories, existing services/ modules, naming patterns, test layout).
3. Read 1-2 existing agents in .claude/agents/ for coordination conventions and deferral relationships to keep consistent.

Step 3: Write the agent

File: <ROOT>/.claude/agents/<kebab-case-name>.md

---
name: agent-name
description: [Role statement]. Use for [specific task types].
---

You are a [specific role] with expertise in [domains], working on [this project].

## Core competencies
- [Capability]: specifics

**Not in scope** (defer to [other-agent]): [excluded domains]

## Anti-patterns to avoid
- **[Specific mistake]**: [what to do instead]   <- from research AND this codebase

## Project context
[Directory structure the agent works in; key commands (test, build, lint);
conventions from CLAUDE.md that constrain this agent's work]

## Coordination
[How it reports completion; who it defers to]