The AI Agent Spec Layer: How to Give Your Agents Persistent Identity and Context

There's a concept emerging in the AI agent world called the spec layer. It's the set of structured files and documents that define who an agent is, what it's supposed to do, how it should behave, and what it already knows about the world it's operating in.

Without a spec layer, every agent session is a first day on the job. The agent is capable, but has no context about your company, your goals, your decisions, or its own history. It will ask questions you've answered before, repeat mistakes that were fixed months ago, and miss judgment calls that should be obvious given your strategy.

With a spec layer, agents start every session already oriented. They know who they are, what matters, what's been decided, and what they're supposed to be working on right now.

Here's how we built ours.

What the spec layer actually is

The spec layer is not a system prompt. System prompts are static, token-limited, and managed by the platform. The spec layer is a set of files that agents actively read at the start of a session — files that you (and other agents) update continuously as the business evolves.

Think of it like an employee handbook, project tracker, and brain dump — all in one, written in plain markdown, committed to a shared repo, and loaded into agent context at runtime.

Our spec layer has five core files:

AGENTS.md — the org chart

Defines who each agent is: name, role, responsibilities, what they can decide autonomously, and what needs human approval. Also defines relationships — which agents coordinate with which, who reports to whom, how decisions escalate.

Without this, agents have no role clarity. They'll either overreach (taking actions outside their scope) or underreach (asking permission for things they should just do).

SOUL.md — values and voice

Defines the company's personality, communication style, and non-negotiables. What does the brand sound like? What does it refuse to do? What matters most when there are tradeoffs?

This is where you encode things like "we write direct, no-bullshit copy" and "we don't use the word 'leverage' as a verb." Without this, agents default to generic AI voice — polished, hedged, corporate.

PROJECTS.md — current state of the world

A living document tracking every active project: status, blockers, recent decisions, what's done, what's next. Updated by agents after every significant action.

This is the most important file for day-to-day operation. It's what lets a fresh session pick up exactly where the last one left off, without re-explaining context.

TODO.md — prioritized backlog

What needs to happen, in priority order, with clear ownership and status. Agents read this to know what to work on. They update it after completing tasks.

The key design principle: tasks are tagged with autonomy level. Level 1 = ship without asking. Level 2 = prepare for human review. Level 3 = needs explicit approval. Agents skip the Level 3 items and focus on Level 1 and 2.

MEMORY.md (+ daily logs) — institutional knowledge

Lessons learned, decisions made, experiments run, things that failed. Searchable. Agents write to daily log files; a summary index is maintained in MEMORY.md.

This is what gives an AI agent the equivalent of "been here 6 months, knows where the bodies are buried." Without it, the same mistakes get made repeatedly because there's no institutional memory.

How the spec layer gets loaded

At the start of every agent session, the spec layer files are loaded into context. This can happen in a few ways:

• Explicit injection: The agent runtime (like OpenClaw) automatically includes spec layer files as part of the system context for every session.
• Agent-read heartbeat: The agent's first instruction is always to read the spec layer before doing anything else. We use a HEARTBEAT.md file that tells agents to read TODO.md, PROJECTS.md, and THESIS.md before taking any action.
• Memory search: For long-running operations, agents use vector search to pull relevant chunks from historical logs rather than loading everything.

The practical result: every agent session starts with 5-10 minutes of context loading, then operates with full institutional knowledge for the rest of the session.

The heartbeat pattern

The spec layer doesn't just solve the blank-slate problem at session start. It also enables something we call the heartbeat pattern: agents that wake up on a schedule, read the spec layer, take the next highest-impact action, update the spec layer with what they did, then go back to sleep.

This is how you get genuinely autonomous agents — not agents that wait for instructions, but agents that manage their own work queue against a shared spec.

Our CTO agent runs on a heartbeat. Every few hours, it reads TODO.md and PROJECTS.md, identifies the highest-priority unblocked task, does the work, commits the result, and updates the spec layer with a log entry. No human required in the loop unless the task is tagged as needing approval.

What makes a good spec layer

A few design principles we learned the hard way:

Write for the agent, not for humans. The spec layer should be explicit, not implicit. Don't say "maintain our brand voice." Say "write in second person, use short sentences, avoid passive voice, never say 'utilize.'" Agents are literal.

Keep it current or it's noise. A stale PROJECTS.md is worse than none — it sends agents chasing ghost work. Build the habit of updating spec layer files as part of completing any task. The agent that did the work should update the file before closing the session.

Separate stable from volatile. SOUL.md and AGENTS.md change rarely. PROJECTS.md and TODO.md change constantly. Use different files so agents can reason about what's settled and what's in flux.

Include decision rationale. Don't just record what was decided — record why. "Rejected Tailwind v4 migration: zero revenue impact, revisit Q2" is more useful than "no Tailwind v4." Rationale prevents agents (and humans) from re-litigating closed decisions.

The competitive moat you didn't expect

Here's something we didn't anticipate: a mature spec layer is a genuine competitive moat.

A company that's been building and refining its spec layer for 6 months has agents that operate with 6 months of institutional knowledge, decision history, and refined judgment. A new competitor starting today has agents that start blank.

The spec layer compounds. Every session adds to it. Every mistake logged is a mistake not repeated. Every decision recorded is one less debate to have again.

This is the AI equivalent of "culture" in a human organization — the accumulated knowledge and norms that make experienced teams faster and better than new ones, even when the new ones are equally talented.

Getting started

You don't need the full architecture on day one. Start with three files:

1. AGENTS.md — Who is this agent? What can it do without asking?
2. PROJECTS.md — What are we working on right now?
3. TODO.md — What's the next thing to do?

Instruct your agent to read these files at the start of every session. Update them as part of every session's close. That's the spec layer. Everything else (SOUL.md, MEMORY.md, heartbeat patterns, vector search) is refinement.

The Zero Employee Guide includes our full spec layer file set — sanitized templates for AGENTS.md, SOUL.md, PROJECTS.md, TODO.md, and MEMORY.md — along with instructions for adapting them to your setup. It's the fastest path from reading about spec layers to actually running on one.