build/your/agentsBuild agent
An open spec · v1.0

Build
your own
agents.

A seven-file architecture for designing AI agents you can actually read, version, and ship. No magic. No black box. Just markdown that a model can live inside.

Build your agent Blank templates Case studies
  • 7core files
  • 1agent, fully described
  • 0frameworks required
01 / Who this is for

Honest scope —
for you or not.

This site is a personal learning project and a free pattern to help others ship clearer agents. It is not a company, a service SLA, or a substitute for your own judgement.

For you if

  • You want to learn how to structure agent context without a proprietary black box.
  • You like versioned markdown you can read, diff, and share with friends or students.
  • You are experimenting with Cursor rules, MCPs, or similar — and own the risk.
  • You want a starter pack to fork, rename, and adapt — not a finished product.

Not the right fit if

  • You need certification, legal guarantees, or compliance claims from this repo.
  • You want a closed SaaS with zero files to edit — this spec lives on disk.
  • You run safety-critical systems without your own security and data review.
  • You expect the authors to operate or warrant your production deployment.

Built to learn in public and to give others a leg up with the same seven-file spec. Take what helps; change what does not; you are responsible for how you deploy it.

02 / Architecture

One agent.
Seven plain-text organs.

Every file owns a single responsibility. Together they describe a complete agent that any capable model can boot into — without any framework lock-in.

SOULIDENTITYAGENTSTOOLSUSERMEMORYHEARTBEAT
AGENTS.md is the conductor — it reads everything else.
HEARTBEAT.md is the autopilot — it fires on a schedule.
  • SOUL.mdWho the agent is.
  • IDENTITY.mdWhere the agent lives.
  • AGENTS.mdHow the agent operates.
  • USER.mdWho the agent serves.
  • MEMORY.mdWhat the agent has learned.
  • HEARTBEAT.mdHow the agent acts on its own.
  • TOOLS.mdWhat the agent can reach for.
02c / Explore & place

Trace dependencies.
Place new content.

Click any file card below (or a node in the maps) to highlight what it reads and who reads it. Use the wizard to pick a home for a new paragraph or rule.

standalone — nothing listed in reads ↳

Which file does this belong in?

Decision rules
Tool priority
Suggested files

No strong match — try a decision-rule chip or different keywords (personality → SOUL, cron → HEARTBEAT, MCP → TOOLS).

04 / The session loop

What the agent does first.

Every session begins with the same checklist. It is short, it is deterministic, and it is the difference between an agent that remembers and an agent that performs amnesia.

  1. 01
    USER.mdCheck flagged priorities & updates
  2. 02
    MEMORY.mdLoad evergreen context & standing prefs
  3. 03
    memory/today.mdLoad today's running context
  4. 04
    HEARTBEAT.mdReview pending scheduled tasks
  5. 05
    SOUL.mdGreet the user with the right tone
excerpt · AGENTS.md
# Session Start Checklist
1. Read USER.md
2. Read MEMORY.md
3. Check memory/[today].md
4. Check HEARTBEAT.md
5. Greet the user according to SOUL.md
05 / Decision rules

When in doubt,
follow the table.

The agent is autonomous, but not freelance. AGENTS.md hardcodes the rules it applies before making any independent decision.

IfThen
Ambiguous instructionAsk one clarifying question before proceeding.
Destructive or irreversible actionRequire explicit confirmation. No exceptions.
Missing informationCheck MEMORY.md, then USER.md, then ask.
Conflicting instructionsSOUL.md limits → AGENTS.md → user request.
Unknown topicAcknowledge the gap. Do not guess.