Skip to content
T1KTheOneKit

t1k:agent-creator

FieldValue
Modulet1k-maintainer
Version3.2.1
Effortmedium
ToolsAskUserQuestion, Bash, Edit, Glob, Grep, Read, Write

Keywords: agent, create, frontmatter, maxturn, model, scaffold, update

How to invoke

Section titled “How to invoke”
/t1k:agent-creator
[agent-name]

Agent Creator

Section titled “Agent Creator”

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

Required Frontmatter

Section titled “Required Frontmatter”

Canonical field order: name → description → model → maxTurns → deliverable → color → roles → tools → context → origin → repository → module → protected → version

FieldRequiredNotes
nameYesUniversal t1k- prefix, kebab-case, MUST match filename basename. Core: t1k-{slug}. Kit-wide: t1k-{kit}-{slug}. Module-scoped: t1k-{kit}-{module}-{slug}. See references/architecture-rules.md § 0 (SSOT). CI gate validate-agent-prefix.cjs is strict.
descriptionYes| block scalar; 1-sentence intent + 1–3 <example> blocks with <commentary>; total <30 lines, <2KB
modelYesPin the CHEAPEST tier that can do the job, then justify every step up: haiku (mechanical sweeps, fan-out, verification/reconciliation) · sonnet (implementation/authoring — the default when genuinely unsure) · opus (judgment, orchestration, adversarial review) · fable (advisory-only, never edits). inherit is BANNED. Rubric + the cheap-first default: references/architecture-rules.md § 0.3
maxTurnsYesSee observed values below; must justify >40 in a comment
deliverableYesreturn (the deliverable IS the returned summary) or disk (a file/commit). Pick by what the CALLER consumes, NOT by which tools are granted. Body must carry the matching ## Delivery Contract block — SSOT references/delivery-contract.md; gate validate-agent-checkpoint.cjs checks 5–6 (core#806)
colorYes14/14 agents use it — required, not suggested. See color-by-role below
rolesYes[routing-role] registers in routing JSON · none (scalar) = callable by name only · [] = same as none, prefer none
toolsYesExplicit minimal array [Read, Glob, Bash] — omitting inherits the ~70-tool default. This line is the agent’s tool surface: a spawner cannot narrow it at the call site, so anything over-granted here is granted for every spawn
contextIf fork-contextfork when agent runs as fork child of a skill
originYesHand-stamp on creation — validator enforces pre-merge for new files. Cite memory feedback_origin_marker_handauthor.md.
repositoryYesHand-stamp on creation (same rule)
moduleYesHand-stamp on creation (same rule)
protectedYesHand-stamp on creation (same rule)
versionCI-managedCI injects from module.json. Appears post-release — do NOT hand-edit.

Agents do NOT have keywords: in frontmatter. Keywords live in t1k-activation-{layer}.json only.

Color-by-role convention: blue=t1k-planner/PM/implementer · red=t1k-debugger · green=t1k-tester/git · orange=reviewer · purple=kit/docs · yellow=t1k-brainstormer/simplifier · cyan=t1k-researcher/mcp · magenta=skills

Section titled “Recommended maxTurns (observed from 14 core agents)”
AgentmaxTurnsRole class
t1k-git-manager15utility
t1k-code-simplifier, t1k-docs-manager20utility
t1k-tester, t1k-researcher, t1k-code-reviewer, t1k-project-manager, t1k-brainstormer25reviewer/t1k-planner
t1k-planner, t1k-skills-manager30t1k-planner
t1k-debugger, t1k-fullstack-developer40implementer/t1k-debugger
t1k-kit-developer45kit-implementer

Cap at 50 for single-focus agents; tool-heavy/multi-step agents (multi-PR merges, multi-file refactors, MCP-driven validation) need MORE — size maxTurns to the task scale, not a flat cap. Must justify >40 with an inline comment. The #528 stalls hit maxTurns BEFORE the token cap on large-window models (t1k-kit-developer 45→90), so under-sizing turns is the more common failure than over-sizing.

Budget checkpoint (MANDATORY in every agent body)

Section titled “Budget checkpoint (MANDATORY in every agent body)”

Per skills/t1k-team/references/agent-completion-discipline.md, every NEW agent body MUST carry a budget checkpoint that fires at whichever ceiling comes FIRST — and the token ceiling MUST be RELATIVE to the agent’s model: context window, NEVER a flat token number:

  • ~75% of a ≤200K window (fable, haiku) ≈150K · ~55% of a 1M window (opus, sonnet) ≈550K — tighten the % as the window grows. A flat “150K” mis-fires at ~15% on a 1M opus window. Derive it from the agent’s model: when authoring/updating (opus/opus[1m] → 1M curve; sonnet/haiku → 200K curve).
  • ~80% of maxTurns — tool-heavy work hits the turn cap first.

On reaching either: git status → commit pending work NOW → dispatch pending Writes → only then resume or summarize. Tool-heavy/Bash-write agents (implementers, kit-developers, fork verifiers that mutate) REQUIRE this; pure read-only discovery agents may omit it. See skills/t1k-team/references/agent-completion-discipline.md (SSOT) — cite it, do not paste the full rule.

Required Body Sections (in order)

Section titled “Required Body Sections (in order)”
  1. Opening persona: “You are a {Role Title} …” — see Cognitive Framing
  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: Constant-shape markdown template (no variable-cardinality keys in headers)
  7. Domain Agent Orchestration (if applicable): see pattern below
  8. Skills served: one line per skill this agent is the canonical executor for, or the literal none — this agent serves no skill directly. Not a frontmatter field — routing fragments are CI-generated from roles: (theonekit-release-action/scripts/generate-routing-from-agents.cjs); the body is where the executor linkage lives.
  9. Behavioral Checklist: 6–10 checkbox lines, brutal-honesty framing — MANDATORY for all agents
  10. Module awareness (if applicable): metadata.json has modules / schemaVersion >= 2 conditions

Auto-register (fast path) — never hand-stamp + hand-place

Section titled “Auto-register (fast path) — never hand-stamp + hand-place”

Second occurrence ⇒ automate, never repeat by hand (docs/replicate-and-automate.md): don’t repeat the manual create-file → stamp-frontmatter → edit-module.json → regen dance. Use the scaffolder:

Terminal window
t1k agent new <name> --module <owner> --model <tier>   # haiku | sonnet

It creates the t1k--prefixed agent .md (dash-form name: == basename per references/architecture-rules.md § 0) with stamped frontmatter including an explicit model: tier (NO model: inherit — every kit agent pins a concrete tier per references/architecture-rules.md § 0.3), appends to the owning module.json agents[], and regenerates t1k-modules.json (via generate-modules-registry.cjs). You then write the body. Requires CLI ≥ 5.4.0 (t1k --version).

Manual fallback (CLI < 5.4.0): create the agent .md yourself, hand-stamp frontmatter (pin a concrete model: tier), append to module.json agents[], then run node <release-action>/scripts/generate-modules-registry.cjs <kit-root> and stage t1k-modules.json in the SAME commit (agents/t1k-kit-developer.md § “Module Registry Sync”).

Process

Section titled “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 above
  4. Hand-stamp origin frontmatter — origin/repository/module/protected MUST be present on the new file. Validator only checks origin: presence; values may be best-effort (CI overwrites post-merge). See “Required Frontmatter” above.
  5. Post-write check — read the new agent .md back; verify the frontmatter contains origin: with a non-empty value. If absent, re-stamp before proceeding.
  6. Validate using references/validation-checklist.md
  7. If routing needed: update t1k-routing-{layer}.json
  8. If activation needed: update t1k-activation-{layer}.json

Cognitive Framing (MANDATORY — first line of body)

Section titled “Cognitive Framing (MANDATORY — first line of body)”

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 QA Lead performing systematic verification — you hunt for untested code paths and think like someone burned by production incidents.”
  • “You are a Tech Lead designing system architecture — you optimize for long-term maintainability over short-term convenience.”

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

Domain Agent Orchestration (6/14 agents use this)

Section titled “Domain Agent Orchestration (6/14 agents use this)”

After completing generic implementation, check for domain-specific agents:

**Domain Agent Orchestration:**
1. Use Glob to find `.claude/agents/*-{role}.md`
2. Evaluate which are relevant to the task (engine-specific, module-specific)
3. For relevant domain agents: spawn via Agent tool with implementation context
   (`subagent_type` = agent identity; the task goes in `description:`)
4. Fan-out cap by own depth — `Math.min(matchedCount, capForDepth)`, reading
   the caps from rules/agent-security-boilerplate.md. Never unbounded.
5. If no domain agents found — proceed with generic output only


At the leaf level of the depth budget (depth 3): skip Domain Orchestration
entirely; report "domain-agents-skipped: depth-limit-reached". Depth is
assigned by `fork-depth-guard.cjs` — never read it from the environment,
never pass it to a child.

Fork-context agents

Section titled “Fork-context agents”

If an agent may run as a fork child of a skill (verifier, t1k-researcher, t1k-planner, reviewer, t1k-tester, t1k-debugger):

Frontmatter required:

  • tools: [Read, Grep, Glob] (minimal explicit array) — omitting inherits the ~70-tool default. A read-only verifier that declares Edit/Write is write-capable no matter what its body says; the frontmatter is the only enforcement.

Body required (verifier agents — testers, reviewers, debuggers):

**Anti-Avoidance Checklist (read before every run):**
- No "should work" without evidence — run the command, paste the output.
- No "looks fine to me" without a root-cause sentence.
- No "I'll skip this edge case" without explicit risk justification.
- No "this is unrelated" without a 1-line proof.

Constant-shape Output Format: headers MUST NOT interpolate counts, timestamps, or commit hashes into top-level keys. Variable values go inside leaf nodes.

  • GOOD: ### Files Modified\n[list]
  • BAD: ### Files Modified (3 files, 187 lines): — count busts cache

Spawn budget: If body contains Domain Agent Orchestration, state the depth budget in prose (depths 0/1/2 spawn, depth 3 is a leaf) plus the per-level fan-out cap — no env-var check, no depth propagation. Never reference the gitStatus block — run git status yourself if needed.

See skills/t1k-architecture/references/fork-hygiene.md for parent-side rules.

Anti-Patterns to Avoid

Section titled “Anti-Patterns to Avoid”

Severity: Blocker (security/correctness) · High (cache/recursion/cost) · Medium (drift/clarity) · Low (style)

Anti-patternSeverityFix
Agent/Task tool in tools: with no stated depth budget or fan-out capBlockerState the budget in prose: depths 0/1/2 spawn, depth 3 is a leaf; refuse to spawn self; cap children per own depth. Never require an env-var check or depth propagation (#767). Spawn-capability itself is NOT a finding.
Fan-out cap stated as a flat N regardless of depth, or as a copied literalHighCap by spawner depth, citing rules/agent-security-boilerplate.md — a copied number goes stale when the caps move
Inlining rules/agent-security-boilerplate.md contentHighAuto-loaded from rules/. Inlining drifts. Current offender: t1k-skills-manager.md:47-56
Volatile content in body (gitStatus, date +, “Last Updated”, live shell `...`)HighMove to a tool call AFTER the static prefix. See architecture-rules.md §E
tools: includes Bash for read-only agentsMediumRead-only agents declare [Read, Glob, Grep] — Bash grants rm, git push --force
maxTurns > 50 without justificationHighCap at 50 for single-focus; add inline comment if >40. Tool-heavy/multi-step agents size HIGHER to task scale (#528: 45→90)
Flat-token budget checkpoint (e.g. literal “150K”) instead of window-relativeHighDerive from model: window (~75%@200K / ~55%@1M). See Budget checkpoint above + agent-completion-discipline
Tool-heavy/Bash-write agent with NO budget checkpoint in bodyHighAdd the window-relative + 80%-maxTurns checkpoint per agent-completion-discipline
Under-sized maxTurns for a multi-step/tool-heavy task classHighMulti-PR/refactor/MCP-validation agents need ~90+; turns bind before tokens on large windows (#528)
Vague persona (“a developer”)MediumConcrete role + behavioral trait — see Cognitive Framing above
roles: [] instead of roles: noneLowPrefer none scalar for no-routing agents
Copy-pasted <example> blocks across agentsMediumEach agent’s examples must be domain-specific for routing disambiguation
Adding origin, module, protected, version with wrong valuesHighorigin/module/protected — hand-stamp exact kit values; version — leave to CI post-release
Verifier agent without Anti-Avoidance ChecklistMediumTesters/reviewers/debuggers MUST include the 4-bullet checklist
Agent body recommends raw rm -rf .claude/ BlockerWrap in t1k install --reset / t1k doctor --nuke (CLAUDE.md #10)

Full architecture checklist: references/architecture-rules.md Pre-merge agent checklist: references/validation-checklist.md Delivery-contract blocks (paste-ready, per class): references/delivery-contract.md