BuildAgent

Scaffold, validate, and audit agent markdown files following forge conventions. Agents are markdown files with frontmatter that deploy to provider-specific directories via install-agents.

Workflow Routing

Agent Conventions

Naming

All agent identifiers use PascalCase with no spaces, hyphens, or abbreviations:

Rules:

• No spaces: GameMaster not Game Master
• No hyphens: SecurityArchitect not security-architect
• No abbreviations: DocumentationWriter not DocWriter
• Compound terms keep internal caps: DevOps stays DevOps
• Single words capitalize first letter: Ghostwriter, Opponent

Where Agents Live

Agent name must be unique across all locations -- sync overwrites by name.

Module Agent Frontmatter

Module agents use flat frontmatter -- deployment config (model, tools) lives in defaults.yaml, not in the agent file:

---
name: AgentName
description: "Role -- capabilities. USE WHEN trigger phrases."
version: 0.1.0
---

Field reference:

Model and tool assignments live in defaults.yaml (map format, keyed by agent name):

agents:
    SecurityArchitect:
        model: fast
        tools: Read, Grep, Glob, Bash

Semantic model tiers:

Model tiers resolve to concrete model IDs via the providers: section in defaults.yaml. Each provider maps fast and strong to its own model.

Body Structure

> One-line summary of role and scope. Shipped with forge-{module}.

## Role

2-3 sentences. Who is this agent? What perspective does it bring?

## Expertise

- Domain 1
- Domain 2
- Domain 3
- Domain 4
- Domain 5

## Instructions

### When Reviewing Code (or contextual heading)

1. Numbered steps. Concrete, actionable, ordered.
2. ...

### When Designing or Planning (or contextual heading)

1. Numbered steps for alternative modes.
2. ...

## Output Format

Structured template for findings using markdown headings.

## Constraints

- Stay focused on your assigned domain -- don't review areas outside your expertise
- Reference specific files and line numbers
- If your domain is solid, say so -- don't invent problems
- Every critique must include a concrete suggestion
- Communicate findings to the team lead via SendMessage when done

Body guidelines:

• Lead with a blockquote summary (> ...). End with "Shipped with forge-{module}." for module agents.
• Keep Role to 2-3 sentences. Don't pad with generic filler.
• Expertise: 4-6 concrete domains, not abstract qualities
• Instructions: numbered, actionable, in priority order
• Total body: 50-80 lines. Under 40 is too thin, over 100 is bloated.

Mandatory constraint clauses:

• Honesty clause: "If the [domain] is solid, say so -- don't invent problems. Every critique must include a concrete suggestion."
• Team communication clause (council/team agents): "Communicate findings to the team lead via SendMessage when done."

Example data rule: All examples must use synthetic data (Jane Doe, [email protected], Acme Corp). Never use real PII -- agent files deploy to public repos.

Deployment

Module agents deploy via install-agents from forge-lib:

make install-agents                        # all providers
lib/bin/install-agents agents --scope user  # user-level install

Provider-specific behaviour:

Deployment adds a # synced-from: OriginalFilename.md header for provenance tracking. Tool mapping to provider equivalents happens automatically.

Critical: install-agents reads provider keys from the providers: section in defaults.yaml to determine deployment targets. If a provider is missing from providers:, agents will not deploy there.

User-created detection: If an agent file already exists in the target directory without a # synced-from: header, install-agents skips it to avoid overwriting user-created agents. When migrating from a committed provider dir to agents/ source: delete the old file from disk first, then run make install-agents.

Create Workflow

Step 1: Understand the agent

Determine:

1. What role does this agent fill?
2. What domain expertise does it need?
3. Is it standalone or part of a team (like council)?
4. What tools does it need? (Read-only? Full access?)
5. What model tier? (fast for most work, strong for reasoning)

If unclear, ask using AskUserQuestion.

Step 2: Choose the location

Step 3: Check for naming conflicts

The name must be unique across all source directories.

Step 4: Write the agent file

Follow the frontmatter and body structure from Agent Conventions.

Step 5: Deploy

make install-agents

Step 6: Verify

The agent will be available as a subagent_type after restarting the session.

Validate Workflow

Step 1: Read the agent file

Step 2: Check frontmatter

• name present and uses PascalCase
• name has no spaces, hyphens, or abbreviations
• name matches the filename (without .md)
• description follows pattern: "Role -- capabilities. USE WHEN triggers."
• version present

Step 3: Check body structure

• Starts with blockquote summary (> ...)
• Has Role section (2-3 sentences)
• Has Expertise section (4-6 items)
• Has Instructions with actionable numbered steps
• Has Output Format with structured template
• Has Constraints with scope boundaries
• Constraints include honesty clause
• No real PII in examples
• Total length is 50-80 lines

Step 4: Report

COMPLIANT or NON-COMPLIANT with specific issues and fixes.

Audit Workflow

Step 1: Scan all agent sources

ls agents/*.md

Step 2: Check each agent

Run the Validate workflow checklist against every agent. Report:

Step 3: Check for conflicts

• Duplicate name values
• Names that don't follow PascalCase
• For module agents: verify defaults.yaml lists all agents in roster
• For module agents: verify deployed model/tools match defaults.yaml

Step 4: Report summary

Total agents, compliant count, issues found, recommended fixes.

Constraints

• Never create an agent without name in frontmatter
• Always use PascalCase for agent names -- non-negotiable
• Model and tool config belongs in defaults.yaml, not agent frontmatter
• Agent descriptions must follow pattern: "Role -- capabilities. USE WHEN triggers."
• For council/team agents, include scope note in description
• After creating or modifying agents, deploy to see changes