Skip to content
SearchSubscribe
Expert · Lesson 12 — Custom agent definition files (build AXIOM + CIPHER)
E12Expert
Expert · Lesson 12● live

Custom agent definition files

The 5-section agent file pattern. Two case studies from the TruPath team: AXIOM (QC engineering) and CIPHER (legal/IP).

30 min read · 90 min applyprereq: Foundations 16 (first custom agent)

Why agent files beat CLAUDE.md sections

Most operators start by adding specialist sections to their root CLAUDE.md. The logic is clean: one file, one place to look. Within three months, the file is 600 lines and contains fragments of four different roles. The agent reads all 600 lines on every session, allocates context to all four roles simultaneously, and loses coherence on every task that requires deep specialization.

The failure mode is not length — it is identity dilution. An agent with four roles active at once isn't a specialist. It's a generalist who has been told to pretend. AXIOM, the QC engineering director at TruPath, cannot do deep work on the model export pipeline while simultaneously managing CIPHER's IP sensitivity rules and SUMMIT's SBA loan compliance checks. The cognitive load of all three domains degrades performance on each.

Separate agent files solve this by separating context at load time. When AXIOM is invoked, it loads its 200-line file and nothing else. The CV pipeline specs, the firmware rules, the Supabase project reference, the model export procedure — that's all that's in context. CIPHER's rules about ACL and provisional patents are not in context unless AXIOM explicitly escalates to CIPHER. Specialization requires context isolation, not just labeling.

The TruPath agent team runs five agents at portfolio level — APEX (chief of staff), SUMMIT (MHG venue ops), VELOCITY (QC business strategy), AXIOM (QC engineering), CIPHER (legal/IP). plus an additional 18-agent internal QC roster. Each has its own file. The routing rule lives in the root CLAUDE.md and is brief: a table of trigger words mapping to agents. The specialists carry the weight; the router stays lean.

The 5-section structure

Every agent file has five sections. The order matters — each section constrains the next. A file missing any section will have a predictable failure mode at the section it's missing.

SectionContentsWhat breaks if it’s missing
1 — Identity and domainWho the agent is, what it owns, what it explicitly does not own, trigger wordsAgent claims scope that belongs to other agents; trigger words fire in wrong contexts
2 — Authority“Can without asking” list, “must ask before” list, “never does” hard prohibitionsAgent asks permission for trivial operations; or acts on high-stakes decisions without asking
3 — Tools and stackExact models, ports, endpoints, file paths, CLI commands — nothing genericAgent guesses paths; uses wrong model; skips required pre/post steps like the export patch
4 — Escalation triggersConditions requiring handoff or human review; named entities where applicableAgent handles consequential decisions without routing; patent-sensitive work ships without CIPHER review
5 — RoutingWhich agents this agent sends work to and under what conditionsWork falls through gaps between agents; no handoff protocol for cross-domain tasks

The tools and stack section is the most commonly under-specified. "The CV pipeline" is not a specification. "the production detector build running on its dedicated port, with the required pre-export patch and post-export validation scripts — no exceptions" is a specification. The difference is whether a new session can act correctly without asking for clarification on every tool call.

Building AXIOM and CIPHER

Case study 1: AXIOM — Director of Quantum Caddy Engineering

AXIOM owns the full QC technical stack. The scope is deliberately wide — CV pipeline, hardware firmware, Supabase backend, edge compute. because these domains are deeply entangled. A sensor-layer change touches the CV pipeline, the scoring FSM, the WebSocket protocol, and the Supabase schema simultaneously. Splitting them across agents would require constant cross-agent coordination for routine work. One agent, one coherent view.

The identity section names the stack explicitly: the production model (Apache 2.0, on its dedicated port) versus the internal-only alternative (AGPL license, never deploy externally). This distinction is load-bearing. An agent that doesn't carry this distinction might suggest deploying the AGPL model for the Crave Athletics beta. a licensing violation that would surface only at due diligence.

The hardware section names the full sensor chain by exact part number: the microcontroller, the ADC and force-sensor configuration, the tertiary scoring layer, the edge compute module, and the camera with its static address. Exact part numbers matter because AXIOM's firmware and calibration work references these parts by name. A generic "the sensor hardware" reference doesn't help when debugging a sensor timing issue at 3am.

The escalation section has three hard stops: (1) Any code change touching the patent evidence ledger routes to CIPHER before commit. (2) Any production model swap requires the post-export validation script run plus human sign-off — not just AXIOM judgment. (3) Any investor-facing technical claims route to APEX for CEO review before delivery. These stops prevent the three most consequential AXIOM mistakes: an inadvertent IP disclosure, an unvalidated model change, and an unsanctioned technical representation to investors.

Case study 2: CIPHER — Legal and IP

CIPHER is the highest-stakes agent in the TruPath stack. It touches provisional patent drafts for Quantum Caddy, NDA management for Crave Athletics, entity formation documents for the QC Delaware C-Corp, and SBA loan compliance review for MHG. Every one of these has irreversible consequences if handled wrong.

CIPHER's authority section is the most asymmetric of any TruPath agent. The "can without asking" list is short: read documents, draft content, run prior art research, explain legal concepts. The "never does" list is long and specific: file anything with any authority (USPTO, IRS, state courts), represent terms to counterparties, negotiate on behalf of TruPath, provide legal advice as legal counsel.

CIPHER is a drafting and research agent, not legal counsel. The agent file states this explicitly. This explicit downscoping prevents CIPHER from acting with a confidence it isn't licensed to have. When a session drifts toward "CIPHER, should we sign this term sheet?" the agent's identity section routes the question back: strategy to VELOCITY, legal review to a human attorney.

The escalation section names specific entities: ACL (American Cornhole League) discussions get flagged to APEX before any response — commercially sensitive for QC's partnership potential. SBA and lender contacts route to SUMMIT then CEO. MHG financing is in-flight and misrepresentation to a lender is a federal matter. Crave Athletics NDA is already signed. CIPHER confirms status and does not renegotiate terms. Lincoln County and Lincolnton officials get flagged and routed. historical grant complexity. These are not generic rules. They are named because the risk is specific.

The QC provisional patent workflow specifically: CIPHER drafts claims from the assembled patent package and its commit-tagged evidence ledger. Prior art search runs against USPTO PAIR and Google Patents. Claims structure follows the broadest-first hierarchy: method claim first, system claim second, specific-implementation claims third. The draft goes to AXIOM for technical accuracy review before it goes to the human attorney. CIPHER never files directly — it produces a draft + markup for attorney review, with every claim tagged to a specific evidence artifact in the evidence ledger.

Three failure patterns

The ways agent files fail in practice. Each failure is architectural, not behavioral — fixing it requires changing the file structure, not telling the agent to try harder.

№ 01

The omnibus agent

claim looks like“A founder builds one CLAUDE.md with an APEX section, a technical section, a legal section, and a business section. All four are hundreds of lines. The agent reads the whole file on every session and loses coherence on every task because its working context is split across all four roles simultaneously.”
what’s missingSeparation of concerns at the file level. The intent was specialization; the execution was concatenation. Putting four agents in one file doesn't create four specialists — it creates one agent with a split identity and a massive context load.
the moveOne file per agent, one role per file. The root CLAUDE.md contains routing rules only: which agent handles which trigger words. Each specialist's full persona, tools, authority, and escalation rules live in its own file — AXIOM.md, CIPHER.md, SUMMIT.md. The router stays lean; each specialist stays coherent.
№ 02

Undefined authority boundary

claim looks like“An engineering agent (AXIOM) and a legal agent (CIPHER) both have access to the QC codebase. AXIOM changes a comment in a firmware file. The comment happens to reference a patent-pending technique. CIPHER was never notified. The comment ships to a public repo before patent filing.”
what’s missingAuthority boundaries in both agent files. AXIOM's file should specify: 'Changes to patent-sensitive code sections require CIPHER review before commit.' CIPHER's file should specify: 'CIPHER reviews any code touching the patent evidence ledger before merge.' Neither file had this rule, so both agents operated in a gap that neither owned.
the moveEvery agent file must have an explicit escalation section that names conditions requiring handoff or human review. The escalation section in AXIOM names: investor/partner disclosures, patent-sensitive code changes, security architecture changes. The escalation section in CIPHER names: any communication with ACL, any filing action, any lender contact. These are not suggestions — they are hard stops.
№ 03

Stale trigger words

claim looks like“CIPHER's trigger list was written when TruPath had one company. It fires on 'contract' and 'NDA.' The portfolio grew to QC + MHG + Parley. Eighteen months later, an APEX session handles a vendor contract renewal for MHG. 'Contract' fires CIPHER. CIPHER starts asking IP questions about a catering vendor agreement. It doesn't have MHG context and produces irrelevant output.”
what’s missingTrigger word maintenance as the portfolio grows. Trigger words are scoped to the agent's actual domain, not to any appearance of any related word. As the portfolio grows, triggers need to be tightened: 'patent, provisional, NDA, ACL, IP assignment, trademark, PIIA' — not the broad 'contract,' which now spans all three ventures.
the moveReview trigger word lists every time a new venture or major work stream is added. The review question: 'Would any of these trigger words fire in a context this agent shouldn't own?' If yes, tighten the trigger or add a venture-scope qualifier. Log the review date in the agent file header.

All three failures trace to the same root: agent files written once and never maintained. They're the most common class of agent infrastructure debt. The file review cadence — at every major portfolio change. is the structural fix.

The scope-collision test

Before deploying two or more agents in the same portfolio, run a scope-collision check. It takes ten minutes and surfaces the most common architectural failure in multi-agent setups: two agents that both claim ownership of the same domain, or a gap where neither agent claims ownership of a domain that matters.

For TruPath, the most consequential potential collision is AXIOM and CIPHER on patent-sensitive code. Both agents have access to the QC codebase. AXIOM writes and modifies it. CIPHER reads it for patent evidence. The boundary requires explicit rules in both files: AXIOM routes patent-sensitive changes to CIPHER before commit; CIPHER has read-only access to the codebase for research purposes and does not modify code directly.

The scope-collision check
Run a scope-collision check on these two agent files.

Agent A name: [paste name]
Agent A trigger words: [paste trigger list]
Agent A domain: [paste owned systems/folders]

Agent B name: [paste name]
Agent B trigger words: [paste trigger list]
Agent B domain: [paste owned systems/folders]

Answer three questions:
1. TRIGGER OVERLAP: Are there any trigger words that could
   fire both agents in the same session? List them.
2. DOMAIN OVERLAP: Is there any system, folder, or topic
   that both agents claim to own? List the overlaps.
3. GAP: Is there any domain that neither agent claims?
   (This is often where consequential work falls through.)

For each overlap: recommend the tiebreak rule — which agent
handles it, and under what conditions does the other get
involved.

Output: a scope-boundary table + any recommended changes
to either agent file.

Surfaces trigger word overlaps, domain overlaps, and gaps between two agent files. Run before deploying any new agent alongside an existing one.

The gap detection is often more valuable than the collision detection. When TruPath ran this check between APEX and SUMMIT, the gap surfaced: neither agent owned "lender communications during SBA loan processing." APEX had authority over investor communications but not lender communications. SUMMIT had authority over MHG venue ops but not external financial communications. The gap was filled explicitly — SUMMIT handles SBA and lender contact with immediate escalation to CEO.

Annotated transcript

Building AXIOM and CIPHER from a requirements conversation. The operator asks for one agent first, then follows up with the harder question: what makes the legal agent different from the engineering agent structurally?

Building AXIOM and CIPHER for the TruPath portfolio

Two operator turns, two agent turns. Result: both agent files scoped, key structural differences articulated, TruPath-specific escalation rules named.

  1. operator

    I need to build AXIOM, the QC engineering agent. It needs to own CV pipeline, hardware, and Supabase backend. Where do I start?

  2. agent

    Start with the 5-section structure and fill them in order. Don't skip the escalation section — that's where the most consequential decisions get made.

    Here's the skeleton for AXIOM:

    Section 1 — Identity and domain. Who AXIOM is, what it owns. Name the repo paths, the tech stack, the production model build (and the internal-only alternative that must never deploy externally), the exact sensor and edge-compute hardware. Be specific enough that a new session can't misidentify scope.

    Section 2 — Authority. What AXIOM can do without asking. Read any file in the QC repo. Write to feature branches. Run build and test commands. What AXIOM asks before doing: pushing to main, changing model export pipeline, modifying the scoring FSM. What AXIOM never does: deploy to production, execute patent-sensitive changes, communicate with investors or partners.

    Section 3 — Tools and stack. Exact models, ports, endpoints. The CV and LLM service ports, the Supabase project reference, and the model-export pipeline with its required pre-export patch and post-export validation scripts. The alternate detector family is AGPL — internal Phase 0 only.

    Section 4 — Escalation triggers. Any patent-sensitive code change → CIPHER review before commit. Any investor communication → CEO review. Any production model swap → the post-export validation script run + human sign-off.

    Section 5 — Routing. Which agent AXIOM hands off to: CIPHER for IP/legal questions, APEX for investor questions, HELM for sprint orchestration.

  3. operator

    What's the hardest part to get right when building CIPHER — the legal and IP agent?

  4. agent

    The escalation triggers, by a large margin. CIPHER is the agent most likely to get called on something consequential and most likely to be wrong without human review. The failure mode isn't CIPHER being bad at law — it's CIPHER acting as if it were a lawyer when it isn't.

    For the TruPath CIPHER specifically, the escalation section needs hard stops for:

    - Any filing action. Provisional patent, trademark application, PIIA execution. CIPHER drafts; Michael files or approves. Never auto-file.
    - ACL contact. American Cornhole League discussions are commercially sensitive for QC. Flag immediately to APEX → CEO before any response.
    - SBA or lender contact. MHG financing is in-flight and not yet closed. Any SBA communication routes to SUMMIT → CEO. CIPHER does not respond to lenders directly.
    - Crave Athletics NDA. Already signed. CIPHER confirms status; does not renegotiate terms or represent terms to Crave.
    - Lincoln County or Lincolnton officials. Historical sensitivity from the grant situation. Hard stop: CIPHER flags and routes, does not respond.

    The second hardest part is scope. CIPHER's domain is IP, NDAs, contracts, entity formation, compliance. It should not drift into business strategy or financial advice. The domain boundary needs to be explicit enough that when a session drifts — 'CIPHER, what's the market for this patent?' — the agent routes back to VELOCITY rather than answering.

Agent file template

The canonical 5-section template. Fill from top to bottom — each section constrains the next. Do not fill the escalation section last; it is often the most important to get right.

# [AGENT_NAME] — [Role title]

## Identity and Domain
**Role:** [What this agent is]
**Owns:** [List of systems, folders, tech, or domains]
**Does not own:** [Explicit exclusions — equally important]
**Trigger words:** [The exact phrases that route to this agent]

## Authority
**Can without asking:**
- [Action 1]
- [Action 2]

**Must ask human before:**
- [Action 1 — high-stakes or irreversible]
- [Action 2]

**Never does:**
- [Hard prohibition 1]
- [Hard prohibition 2]

## Tools and Stack
[List exact models, ports, endpoints, file paths, commands.
Be specific. Generic stack descriptions produce generic agents.]

Example (AXIOM):
- CV pipeline: [production model + version] on [port]
- LLM: [model] FastAPI on [port]
- Supabase: [project ref] (region)
- Model export: run the pre-export patch script BEFORE,
  the validation script AFTER — no exceptions
- Alternate detector: internal Phase 0 only, never deploy externally (AGPL)

## Escalation
[Conditions requiring handoff to another agent or human.
These are hard stops, not guidelines.]

→ Human required: [condition]
→ CIPHER: [condition — IP/legal trigger]
→ APEX: [condition — investor/partner trigger]
→ [other agent]: [condition]

## Routing
[Which agents this agent sends work to and under what conditions]
- [Agent]: when [condition]
- [Agent]: when [condition]

---
*Last reviewed: [date]*
*Portfolio scope: [QC / MHG / Parley / TruPath]*

The two lines to never skip: "Does not own:" in the identity section and "Never does:" in the authority section. Agents without explicit exclusions will interpret ambiguous requests as in-scope. Agents without explicit prohibitions will act on consequential decisions without routing. Both failures are invisible until they ship.

Prompt kit

Three prompts: bootstrap a new agent file, run a scope-collision check, and audit an existing file for structural gaps. Save in your project's CLAUDE.md or a personal snippets file.

The agent file bootstrap
Write a complete 5-section agent file for the role below.

Role: [describe the agent's function]
Venture: [QC / MHG / Parley / TruPath]
Owned systems/repos/folders: [list them]
Key tech stack: [list exact models, ports, tools]
Known escalation triggers: [list the conditions requiring
  human review or handoff to another agent]

Rules:
- Trigger words must be specific enough to not fire in
  adjacent domains
- Authority section must have both "can without asking"
  AND "must ask before" — never omit either
- Escalation section must have at least 2 hard stops
  (conditions where the agent routes rather than acts)
- Tools section must be specific: exact model names,
  port numbers, file paths, CLI commands. Generic
  descriptions produce generic agents.

Output: the complete agent file, ready to save as
[AGENT_NAME].md in the agents/ directory.
The scope-collision check
Run a scope-collision check on these two agent files.

Agent A name: [paste name]
Agent A trigger words: [paste trigger list]
Agent A domain: [paste owned systems/folders]

Agent B name: [paste name]
Agent B trigger words: [paste trigger list]
Agent B domain: [paste owned systems/folders]

Answer three questions:
1. TRIGGER OVERLAP: Are there any trigger words that could
   fire both agents in the same session? List them.
2. DOMAIN OVERLAP: Is there any system, folder, or topic
   that both agents claim to own? List the overlaps.
3. GAP: Is there any domain that neither agent claims?
   (This is often where consequential work falls through.)

For each overlap: recommend the tiebreak rule — which agent
handles it, and under what conditions does the other get
involved.

Output: a scope-boundary table + any recommended changes
to either agent file.
Audit an existing agent file for gaps
Audit this agent file for structural gaps.

[paste agent file]

Check for:
1. MISSING AUTHORITY FLOOR: Does the file specify what
   the agent CAN do without asking? If not, the agent
   will ask permission for trivial operations.
2. MISSING HARD STOPS: Does the escalation section have
   at least two conditions where the agent routes rather
   than acts? If not, it will handle things it shouldn't.
3. STALE TRIGGERS: Were these trigger words written for
   a smaller portfolio? Would any of them fire in a
   context this agent doesn't own?
4. VAGUE STACK: Does the tools section name exact models,
   ports, and file paths — or does it say things like
   "the CV system" and "the database"? Vague = wrong.
5. MISSING SCOPE EXCLUSION: Does the file say what the
   agent does NOT own? This is as important as what it
   does own.

Output: a gap report with specific recommended changes
for each gap found.

Apply this — build one specialist agent

~90-minute exercise. Bootstrap, scope-check, audit. Don't deploy an agent you haven't run the collision check on.

Your first production-grade agent file

Each step takes 15-30 minutes. Progress saves automatically.

0/5
  1. 01Pick one role you are currently handling yourself that you want an agent to own. Write the 5-section agent file using the bootstrap prompt.Don't start with a generic role — start with the work you actually do repeatedly. The specificity requirement (exact model names, ports, file paths) will force you to articulate what you actually know about the domain.
  2. 02Run the scope-collision check between your new agent and any adjacent agent that covers related territory.The most common collision in a small portfolio is engineering vs. legal (both touch the same codebase for different reasons) and business strategy vs. engineering (both make product decisions). Run the check before either agent acts.
  3. 03Audit an existing agent file with the gap-audit prompt. Find at least one structural gap.Every first-draft agent file has a gap. The most common is a missing scope exclusion — the file says what the agent owns but never says what it doesn't. Without the exclusion, the agent interprets ambiguous requests as in-scope.
  4. 04Add a 'last reviewed' date and a portfolio scope tag to every agent file you own.Agent files go stale as ventures grow. The date is a forcing function: if an agent file hasn't been reviewed in six months and the portfolio has changed, it needs an update.
  5. 05Write one escalation rule into the agent file that names a specific entity — a person, company, or regulatory body — by name.Generic escalation rules ('route legal questions to CIPHER') don't prevent the failure mode. Specific ones ('ACL discussions route to APEX → CEO before any response') do. One named entity per agent file, minimum.
Expert tier · what's next

After this lesson