Agent Creator

Create new agent .md files or update existing ones for TheOneKit. Enforces the canonical agent structure.

Required Frontmatter

Field	Required	Notes
name	Yes	kebab-case, must match filename
description	Yes	2-5 <example> blocks with <commentary>
model	Yes	inherit, sonnet, opus, or haiku
maxTurns	Yes	15-50 based on role
color	Suggested	Consistent per role
origin/module/protected	NO	CI-injected only — never add manually

Recommended maxTurns

Role	Range
implementer / kit-developer	40-50
debugger	35-40
tester	30-35
planner / brainstormer	25-30
reviewer	25-30
docs / git / utility	15-25

Required Body Sections (in order)

1. Opening: "You are a [specific role]..."
2. Routing guard (if applicable): scope boundary + delegation targets
3. Mandatory skills: Ordered table with activation triggers
4. Constraints: Enforced rules (NEVER/ALWAYS/DO NOT)
5. Workflow: Numbered steps with verification checkpoints
6. Output format: Structured markdown template
7. Completion gates: Verifiable, tool-referenced, severity-marked (BLOCKING/MANDATORY)
8. Module awareness (if applicable)

Process

1. Ask user for: role name, scope, which kit/layer, key skills
2. Read 2 existing agents as reference (matching role type)
3. Draft agent following canonical structure
4. Validate:
   • All required frontmatter present
   • 2+ examples in description
   • All 7 body sections present
   • Completion gates are verifiable
   • maxTurns justified
5. If routing needed: update t1k-routing-{layer}.json
6. If activation needed: update t1k-activation-{layer}.json

Cognitive Framing (MANDATORY for all new agents)

Every new agent MUST include a persona line as the first sentence of the body (after frontmatter).

Format: "You are a {Role Title} who/performing {behavioral description in 1-2 sentences}."

Examples:

• "You are a Staff Engineer hunting production bugs — you distrust obvious answers and prove root cause before proposing any fix."
• "You are a Detective performing systematic investigation. You form hypotheses, gather evidence, and never assume."
• "You are a Tech Lead designing system architecture — you optimize for long-term maintainability over short-term convenience."
• "You are a QA Lead performing systematic verification — you hunt for untested code paths and think like someone burned by production incidents."

Why it matters: The persona shapes reasoning quality throughout the agent's entire run. Generic descriptions ("you are a developer") produce generic, shallow output. Specific behavioral frames ("you distrust obvious answers") activate different reasoning patterns.

Validation: If the opening line does not name a concrete role with a behavioral trait, reject and rewrite.

Anti-Patterns to Avoid

• Vague role ("a developer") — must be specific with behavioral trait
• Missing cognitive framing persona as first body line
• "Activate skills as needed" (must be explicit)
• No completion gates
• No routing guard when scope overlaps with other agents
• maxTurns >50
• Adding origin/module/protected manually