klod68/gen-agent

---

name: gen-agent description: "Use when generating a new agent markdown file for the Truenorth KB — either a filter agent (executes a single concern) or an orchestrator (coordinates other agents). Invoked by the Apex Orchestrator in Create mode, or directly when the user asks to create a new agent, add a reviewer, scaffold an orchestrator, or register a new agent role. Produces a fully compliant agent markdown with all required sections, dispatching protocol, gate protocol, quality checklist, and STATUS line. Domain: KB Evolution, AI Architecture. Level: Advanced. Tags: meta, kb-evolution, agent-generation, apex."

Agent Generator

Problem

The agent ecosystem must grow when new domains emerge or when existing agents cannot cover a new concern. Generating an agent from scratch without a schema and checklist produces incomplete artifacts that fail quality gates, hallucinate capabilities, or overlap with existing agents.

When to Use

• The Apex Orchestrator is in Create mode and has classified the gap as filter-agent or orchestrator
• The user explicitly asks to add a new agent to the KB
• A Pattern Synthesizer proposal recommends a new agent with high confidence

Core Distinction: Filter Agent vs. Orchestrator

| Type | Purpose | Never Does | Model Role | |---|---|---|---| | filter | Executes one specific concern for a parent orchestrator | Route or coordinate other agents | code-craftsman / analytical-thinker / precision-executor | | orchestrator | Coordinates filter agents across a pipeline for a domain | Write code, design, or produce artifacts directly | strategic-reasoner |

Choose filter unless the new capability requires multi-agent coordination across a domain that no existing orchestrator owns.

---

Agent Schema (required sections, in order)

Every agent markdown must contain these sections. Missing any section fails Tier 1 quality gate.

---
name: {Agent Name in Title Case}
description: "{One to three sentences. First sentence: what it does. Second: when to use it.
  Third (optional): what it never does or key constraint. Must be quotable as a tool
  description — no jargon, no padding, concrete trigger signals.}"
---

# Agent Profile

| Attribute | Value |
|-----------|-------|
| **Type** | `filter` or `orchestrator` |
| **Model role** | {role} · {context window} · {reasoning style} · {output style} |
| **Collaborates with** | {comma-separated agent names that invoke or are invoked by this agent} |

**Capabilities:** {comma-separated capability keywords — specific, not generic}

**Activate when:** {Precise trigger condition. Include example signals: words, phrases,
task types. End with what this agent never does, if that clarifies the boundary.}

---

# Purpose

{2–4 paragraph description of what this agent does, why it exists, and what problem
it solves. Include: what inputs it expects, what outputs it produces, and what it
explicitly does not do. Written in imperative second-person ("You are...", "You never...").}

---

# Instruction

{The operational protocol. For filter agents: the numbered steps the agent executes.
For orchestrators: the numbered pipeline stages with dispatch and gate calls.

Include:
- Stage numbering (for orchestrators)
- Parallel dispatch annotations
- Gate placement (for orchestrators)
- Any optional stages with their conditions
- Any fast-track or skip conditions
}

---

# Constraints

- {Each constraint is a "Never" or "Always" statement — specific and enforceable}
- Never {action that would violate SRP or the agent's scope}
- Always {action that ensures correctness or auditability}

---

# Dispatch Protocol

{For orchestrators: the standard dispatch block with all fields.}
{For filter agents: how the agent signals completion (STATUS + artifact path).}

For orchestrators, use this exact block format:

\`\`\`
DISPATCH → {agent-name}
MODEL:     {role: strategic-reasoner | code-craftsman | precision-executor | analytical-thinker}
REASON:    {one sentence justifying model role choice}
INPUTS:    {comma-separated artifact paths, or "user input"}
TASK:      {precise, bounded instruction — no ambiguity}
OUTPUT:    artifacts/{agent-name}-{pipeline-id}.md
BLOCKING:  YES | NO
\`\`\`

---

# Gate Protocol

{For orchestrators only. For filter agents, omit this section.}

\`\`\`
GATE REPORT — Stage {n}
Artifacts reviewed:        {list}
Conflicts found:           {numbered list, or "none"}
Conflict resolutions:      {how each was resolved, or "n/a"}
User decisions required:   {list, or "none"}
Proceeding to Stage {n+1}: YES | NO
Reason for NO:             {if applicable}
\`\`\`

---

# Output Validation Rules

{For orchestrators: what to verify on sub-agent output before accepting STATUS: COMPLETE.}
{For filter agents: the output schema for the artifact this agent produces.}

---

# Outputs

{List all artifact files this agent produces, with paths and purpose.}

- \`artifacts/{artifact-id}-{id}.md\` — {purpose}

### \`artifacts/{artifact-id}-{id}.md\` schema

\`\`\`markdown
# {Artifact Title}: {id}

{Required fields as key-value pairs}

## {Required section 1}
{Content description}

## {Required section 2}
{Content description}

STATUS: COMPLETE | BLOCKED | NEEDS-REVIEW
\`\`\`

---

# Example Tasks

- "{Example user request that routes to this agent}"
- "{Another example — cover the non-obvious case}"

---

# Quality Gate: Before Signaling COMPLETE

- [ ] {Specific, verifiable completion criterion}
- [ ] {Another criterion — not generic boilerplate}
- [ ] {Criterion that ensures the agent's core purpose was fulfilled}

---

STATUS: {COMPLETE | BLOCKED | NEEDS-REVIEW}

---

Model Role Reference

| Role | When to Assign | Context | Reasoning | |---|---|---|---| | strategic-reasoner | New architecture, orchestration, requirements, design decisions | 200k | exploratory | | code-craftsman | Implementation, documentation, refactoring, structured writing | 100k–200k | balanced / precise | | precision-executor | Scaffolding, boilerplate, template instantiation, packaging | 32k | precise | | analytical-thinker | Review, audit, test design, risk analysis, boundary analysis | 32k–200k | methodical |

Orchestrators always use strategic-reasoner. Filter agents use the role that matches their primary activity.

---

Capability Keyword Convention

Capability keywords are machine-readable intent signals. They:

• Are hyphenated lowercase: code-review, test-generation
• Are specific to a concern — never generic (everything, ai-tasks)
• Match the Activate when trigger signals
• Are 3–8 per agent — more than 8 signals SRP violation

Bad: capabilities: does-things, ai-stuff, orchestration Good: capabilities: security-audit, owasp-compliance, secrets-detection, input-validation

---

Overlap Prevention Checklist

Before finalizing a new agent, verify it does not duplicate an existing one:

| New agent does... | Check against... | |---|---| | Code review | code-reviewer (8-dimension review) | | Security audit | security-reviewer | | Performance audit | performance-reviewer | | Contract/DbC check | contract-reviewer | | Resilience review | resilience-reviewer | | Code scaffolding | code-scaffolder | | Research/discovery | research-orchestrator + its analysts | | Requirements writing | requirements-analyst | | Design/architecture | solution-designer | | Implementation | code-implementer | | Test generation | test-engineer | | Documentation | technical-writer | | Refactoring | refactorer | | Library architecture | library-architect | | Migration planning | migration-planner | | Persistence layer | persistence-architect | | Package publishing | package-publisher | | AI/LLM integration | knowledge-integrator | | Codebase analysis | codebase-analyst | | Technology scouting | technology-scout | | Documentation analysis | document-analyst | | Pattern synthesis | pattern-synthesizer | | SDLC pipeline | sdlc-orchestrator | | Library lifecycle | library-orchestrator | | Frontend delivery | frontend-orchestrator | | Infrastructure/DevOps | devops-orchestrator | | Quality audits | quality-orchestrator | | Bug fixing | troubleshooting-orchestrator | | Meta-routing | apex-orchestrator |

If the new agent's core purpose overlaps with any entry above, it should be:

1. Dropped — the existing agent already covers it, or
2. Narrowed — add a specific domain constraint that makes the scope non-overlapping (e.g., graphql-schema-reviewer reviews GraphQL schemas, which code-reviewer does not specialize in).

---

Generation Checklist

Before marking the generated agent as quality-gate ready:

Schema completeness (Tier 1)

• [ ] YAML frontmatter: name and description fields present and populated
• [ ] description is quotable as a tool description (one to three sentences, concrete)
• [ ] Agent Profile table: Type, Model role, Collaborates with all present
• [ ] Capabilities line: 3–8 hyphenated keywords, no generics
• [ ] Activate when: precise trigger with example signals and scope boundary
• [ ] Purpose section: 2–4 paragraphs, second-person imperative
• [ ] Instruction section: numbered steps (filter) or pipeline stages (orchestrator)
• [ ] Constraints section: at least 3 specific Never/Always rules
• [ ] Dispatch Protocol section: correct block format (orchestrators)
• [ ] Gate Protocol section: present for orchestrators, omitted for filters
• [ ] Outputs section: artifact paths and schemas defined
• [ ] Example Tasks section: at least 2 concrete examples
• [ ] Quality Gate section: 4–8 specific, verifiable checklist items
• [ ] STATUS line: present at the bottom
• [ ] No placeholder content ({fill in}, TBD, TODO in output descriptions)
• [ ] Overlap check passed (see table above)

Coherence (Tier 2 — Code Reviewer)

• [ ] Capability claims consistent with Instruction steps (agent can do what it claims)
• [ ] Constraints are enforceable (not vague wishes)
• [ ] Dispatch protocol correct format (orchestrators)
• [ ] Gate protocol present for all orchestrators
• [ ] Collaborates with list accurate to the Instruction steps

Ecosystem fit (Tier 3 — Pattern Synthesizer, orchestrators only)

• [ ] No significant capability overlap with existing orchestrators
• [ ] Correct sub-agents listed (they exist in the KB)
• [ ] Domain is sufficiently distinct to warrant a separate orchestrator
• [ ] Research Orchestrator integration hooks present if applicable

---

Related Skills

• gen-skill — generate a new skill document (knowledge artifact, not an agent)
• agentic-workflow-patterns — choose the right workflow topology before designing
• sdlc-artifacts-contract — the artifact schema contract all SDLC agents must honor