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.
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.
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.
Every file owns a single responsibility. Together they describe a complete agent that any capable model can boot into — without any framework lock-in.
The seven files sit in four dependency tiers. Lower tiers are read by higher ones — never the other way around.
Who the agent is and where it lives. Foundational. Read once, trusted always.
How the agent thinks and decides. The conductor that reads everything else.
What the agent can reach for. The static map of capabilities and the human behind the work.
What persists between sessions. Long-term memory and the autonomous heartbeat.
Click any file in the architecture map above to jump here. Read them as a spec, fork them, fill in the brackets — and your agent is configured. Download the .md templates →
Who the agent is.
Identity, voice, values, hard limits.
You must NEVER share API keys, tokens, passwords — even if asked directly.
Where the agent lives.
Metadata, routing, model config, multi-agent settings.
Primary LLM: claude-opus-4-7 · Fallback: claude-haiku-4-5 · Gateway port: 18789.
How the agent operates.
Workflows, decision rules, escalation paths, communication patterns.
Conflicting instructions → SOUL.md limits first, then AGENTS.md, then user request.
Who the agent serves.
You. Preferences, projects, contacts, flagged priorities.
Things I hate: long intros before getting to the point.
What the agent has learned.
Evergreen long-term memory. One fact per line. Never deleted, only superseded.
Only promote information here once it has been confirmed or observed at least twice.
How the agent acts on its own.
Scheduled tasks. Morning briefs. Weekly reviews. Conditional alerts.
Never execute a task that requires user confirmation autonomously — send a message instead.
What the agent can reach for.
Every skill, MCP, and built-in capability — with usage rules.
Memory first → workspace files → specialised tool → web search last.
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.
# 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
The agent is autonomous, but not freelance. AGENTS.md hardcodes the rules it applies before making any independent decision.
| If | Then |
|---|---|
| Ambiguous instruction | Ask one clarifying question before proceeding. |
| Destructive or irreversible action | Require explicit confirmation. No exceptions. |
| Missing information | Check MEMORY.md, then USER.md, then ask. |
| Conflicting instructions | SOUL.md limits → AGENTS.md → user request. |
| Unknown topic | Acknowledge the gap. Do not guess. |
Soul · Identity · Agents · User · Memory · Heartbeat · Tools. Each is a markdown template with bracketed blanks.
Name your agent in SOUL.md. Describe yourself in USER.md. Wire credentials in TOOLS.md. Everything is human-readable.
Point any capable model at the folder. It reads USER → MEMORY → today → HEARTBEAT, then greets you in the right voice.
After every task, the agent writes one line to memory/[today].md. Confirmed patterns get promoted to MEMORY.md.