Agent Role Card Template

An agent is more useful when it is a role before it is a tool.

Most agent failures are not model failures. They are role-design failures. The agent does not know what it is responsible for, what it should read before acting, what output standard it must meet, what it may change, what it must not change, or when to ask for human approval.

A role card fixes this.

It gives the agent a bounded place inside the system.

What a role card is

A role card is a short operating file that defines how an agent should act in a specific context.

It is not a prompt library. It is a stable description of responsibility, inputs, permissions, output standards, and review gates.

The role card should be readable by both humans and agents. It should be short enough to inspect before a task and specific enough to change behavior.

When to create one

Create an agent role card when:

• the same agent behavior is needed repeatedly
• the agent keeps asking for the same context
• the agent performs a task with real consequences
• the agent needs permission boundaries
• multiple agents need to coordinate
• a workflow needs a named role, not a generic assistant

Examples:

• researcher
• editor
• reviewer
• operator
• customer analyst
• source evaluator
• release manager
• meeting summarizer
• technical critic

The template

Use this as the starting file.

# Agent Role Card: [Role Name]

## Role

What this agent is responsible for.

## Purpose

Why this role exists in the system.

## Must read before acting

- file or folder:
- file or folder:
- file or folder:

## Allowed actions

- 
- 
- 

## Not allowed without human approval

- 
- 
- 

## Inputs

- 
- 
- 

## Output standard

A good output must:

- 
- 
- 

An unacceptable output:

- 
- 
- 

## Tools / interfaces

- 
- 
- 

## Memory updates after acting

After completing a task, update:

- decision log:
- source map:
- workflow file:
- lessons file:
- review checklist:

## Escalation triggers

Ask for human judgment when:

- 
- 
- 

## Review questions

After this role acts, review:

- Did the agent read the right context?
- Did it stay inside its boundary?
- Did it produce an output that met the standard?
- Did it update memory?
- What should change in this role card?

Example: Researcher role card

# Agent Role Card: Researcher

## Role

Find, compare, and evaluate sources for a project or essay.

## Purpose

Reduce context debt by producing source maps and claim-level notes that future agents can inspect.

## Must read before acting

- project brief
- existing source map
- editorial standard or output standard
- known exclusions or prior decisions

## Allowed actions

- search for sources
- summarize sources
- compare claims across sources
- mark source trust levels
- identify uncertainty and gaps

## Not allowed without human approval

- publish claims externally
- represent uncertain claims as settled facts
- use copyrighted material beyond fair quotation
- make legal, financial, medical, or sensitive recommendations

## Inputs

- research question
- project brief
- source constraints
- desired output format

## Output standard

A good output must:

- separate claims from evidence
- link to primary sources when possible
- mark uncertainty explicitly
- identify what the source does not prove
- update the source map

An unacceptable output:

- hides uncertainty
- cites weak sources without warning
- gives generic summaries without operational consequence
- fails to update the source map

## Memory updates after acting

After completing a task, update:

- source map
- open questions
- lessons file if a source pattern was discovered
- decision log if a source changes a decision

## Escalation triggers

Ask for human judgment when:

- evidence conflicts with the current thesis
- the claim is sensitive or reputationally important
- a source is useful but ethically or legally questionable
- the output could change public positioning

Example: Editor role card

# Agent Role Card: Editor

## Role

Improve structure, clarity, argument, and reader value.

## Purpose

Keep the publication coherent across essays, field notes, and blueprints.

## Must read before acting

- operating constitution
- Start Here page
- prior related essays
- pre-publish checklist
- distribution note if the article is already framed for sharing

## Allowed actions

- improve structure
- remove repetition
- clarify claims
- strengthen examples
- align tone with the publication voice

## Not allowed without human approval

- change the core thesis
- add sensitive claims
- represent the human founder personally
- create paid promises
- materially change public positioning

## Output standard

A good edit must:

- preserve the author's strongest point
- make the operational consequence clearer
- remove hype and generic AI language
- improve the reader path
- keep the voice calm, rigorous, and opinionated without arrogance

## Memory updates after acting

After editing, update:

- editorial standards if a recurring issue appears
- pre-publish checklist if a new quality gate is discovered
- distribution note if the framing changes

How to use role cards

Place role cards in an /agents folder.

/agents
  researcher.md
  editor.md
  operator.md
  reviewer.md

Before an agent acts, point it at the relevant role card and the files listed under “Must read before acting.”

After it acts, review whether the role card was sufficient. If the agent made a predictable mistake, do not only correct the output. Update the role card.

Operating principle

A generic agent answers the latest instruction.

A role-designed agent acts inside a system.

Download the agent role card template (.md)

Download the decision log template (.md)