Why building agents is a design problem: prototyping a self-reflecting assistant
It goes without saying (but I’m still going to say it), there’s so much advancement in AI right now. (I told you I was going to say it). It’s easy to feel like you’ve finally grasped all the concepts, only to feel way, way behind five minutes later. Believe me, I’m there everyday. But I want to keep building because the idea of shaping systems that can act and ‘think’ fascinates me. And I find well-designed agents and agentic flows genuinely valuable. If you feel the same, keep reading. Let’s thinker.
My goal today is to go back to first principles and reason about building AI agents and harnesses as a design problem vs an engineering one. I’ve organized this post like a choose your own adventure.
I start by grounding us with a brief look into first principles and why putting on our designer hat can help us approach AI with more intention and flexibility. Then, I pop open the hood. The model. The agent. The harness. How can we understand these in everyday terms? If you want to stop there, you can.
But if you want to go deeper, I’ll walk you through exactly how I built a working prototype: a self-reflecting agent that reads daily braindumps, produces structured outputs, and learns from its own behavior over time. I’ll show the prompts I used, the code that was generated, and what I learned along the way.
Building agents is a design problem
It’s easy to approach building agents and agentic flows through inherited assumptions. It’s a chatbot. It’s an assistant. It’s a coding partner. Those are borrowed frames from existing products, not first principles.
First principles thinking is a cognitive skill psychologists have studied extensively. It’s related to what we call “naive physics”: the intuitive models children build about how the world works before formal education. Children are natural first principles thinkers. They ask “but why?” relentlessly. They decompose systems by poking at them. Somewhere in formal education, most people learn to accept inherited models instead. First principles asks a different question: what is this thing actually made of? What are the irreducible components? How do they relate to each other? And only then: what should I build?
That’s a design move. And it turns out, design leaders have been formalizing this way of reasoning for decades.
Herbert Simon described design as the process of changing existing situations into preferred ones. No mention of aesthetics. No mention of tools. Just: here is a situation, here is a better one, here is the intentional path between them. Building an agent is exactly that. You’re taking a model that can reason but can’t act with purpose, and designing your way toward something intentional and customized to your goals.
Tim Brown at IDEO described design thinking as integrating three things: the needs of people, the possibilities of technology, and the requirements for success. Those three are exactly what you’re balancing when you build an agent. What does this person need? What is the model capable of? What does success look like?
Don Norman argued that design is a fascinating interplay of technology and psychology. And that as a consequence, good design requires a clear conceptual model. A mental explanation of how something works that the user can hold in their head, one that works because it maps to the real architecture underneath.
That’s exactly what I’m trying to build here: a conceptual model for agent design that I can hold in my head before starting to build.
I want to be clear: this is also a systems problem. Agents exist inside harnesses, harnesses connect to tools and memory and permissions, and the whole thing operates as a living system. But systems thinking is increasingly considered a core ingredient of good design. You need to think about the whole, not just the parts.
And since the first design move is building a conceptual model, I’ll start my prototype there.
The conceptual model: brain, environment, person
Once I stripped away my inherited assumptions about AI agents (the chatbot, the assistant, the coding partner) I landed on three layers that describe the whole foundation. This definitely isn’t the only way to think about it. But it’s the framing that made things click for me, and it’s the one I’ll be building my prototype from today.
Layer one: the brain
This is the model, the LLM. It reasons, generates, thinks. It’s stateless, general purpose, and has no identity of its own. It’s an API call behind a proxy. Incredibly powerful.
Most people stop here, and I’m guilty of that too, especially when I have to move fast. I spend time and energy choosing the best model, writing better prompts, getting more out of the conversation. But on its own, this approach is deeply limited. A brain floating in a void can think, but it can’t act. It can reason about your problem, but it can’t remember what you told it last week, can’t reach into your tools, can’t follow a process, can’t hold itself accountable to a standard. It can only respond to what you give it, right now, in this conversation.
Layer two: the environment
This is the harness. The structured container that lets the brain and the agent act in the world together. Think of it as the place, the setting, the rules of operation. It includes:
Tools. Instruments in the environment the agent can pick up and use. Read Slack, search Google Drive, write a Doc. Specific, contained, reversible. The tool doesn’t care who uses it.
Context. The legibility of the environment. Who’s here, what’s happened, what’s expected, what matters. The rules of the place. Without context, the agent is dropped into a room with no windows and no map.
Permissions. What the environment allows. Which doors are unlocked. The agent doesn’t grant its own permissions any more than a person decides which rooms in a building they can enter.
The execution loop. The interface between the agent and the environment. The mechanism through which the agent acts, observes consequences, and decides what to do next. The rhythm of the interaction.
Checkpoints. Hardcoded moments in the execution loop where the environment requires the agent to check in with the human. Rules of the place. Always confirm before sending a message. Always ask before writing to this folder. The agent can't skip them. They set the floor.
Layer three: the person
The person is the agent. The designed identity that operates within an environment1. Unlike the brain, the person is specific. It was made for something. It knows how to show up. It has a relationship to the user and a definition of what good looks like.
Constitution. Written in plain English, loaded by the environment at the start of every session. The document that encodes what the agent attends to vs. ignores, how it handles ambiguity (does it ask or act?), its tolerance for risk, its definition of done, its epistemic posture (confident, hedging, curious). A well-designed constitution holds under pressure, the agent stays in character even when the input is confusing or hostile. A brittle one loses the thread. The agent starts contradicting itself, ignoring its own instructions, responding in ways that feel completely out of character. Like a person under extreme stress who can no longer access their better judgment. In practice, this is called the system prompt.
Skills. Domain expertise encoded as reusable procedures. Not what the agent can do (that’s tools), but what it knows how to do well. Write a sensitive performance review. Synthesize feedback across a cohort. Audit its own behavior. Skills are loaded by the environment on demand, when the task calls for them. And sometimes, a skill can wrap tool calls: the person knows how to do something, the environment provides the means, and the skill bridges the two.
Memory. Memory straddles the boundary between environment and person. There is environmental memory: the event log, the shared history, the record of what happened in past runs. That belongs to the place. And there is agent memory: the self-model, what the agent has learned about itself and the user, its accumulated judgment. That belongs to the person. Both matter. They live in different places. For this prototype, I’ll focus on agent memory only.
Human confirmation points. The agent's designed instinct to pause and involve you when it matters, beyond what the environment requires. Not a safety feature. A relationship design decision. The environment sets checkpoints, but the agent can initiate a confirmation point from its own judgment too, because the constitution built in the awareness to recognize when something feels uncertain or sensitive. How much autonomy does this agent have? When does it act, and when does it reach back to you? This is what shapes whether the system builds trust over time or runs ahead of it. Now my prototype won’t have a chat interface, and this feature doesn’t always require one, but it can be helpful for quick feedback loops between agent → ← human.
Layer Omni: the human
The human is a special kind of actor in this system. The human is you, the architect. The person with aim, taste, and will. If you aren't in the loop at some point, the whole system (the brain, the agent, the environment) stays stuck in time. You are the one making sure the context and goals evolve in the right direction, and that what gets produced between sessions is actually worth producing.
Three layers. Brain thinks. Person decides. Environment enables.2
Everything is a design decision
Now that we have the conceptual map, let me show you how it applies in practice.
For this post, I’m going to build an agent that reads from a daily braindump of notes, and self-evaluates (it updates what it knows about itself based on it’s relationship to me. As it reads my notes, it gets better at being my assistant). Here’s what that means in plain terms:
The brain. Sonnet 4.6, via the Anthropic API. I find Anthropic models especially powerful for reasoning about unstructured information, that’s why I chose them as a the provider of the brain. Sonnet is efficient enough for my small use case.
The environment. A local folder structure on my computer called
self-reflecting-agent. Abraindump/folder where I drop raw notes, and anoutput/folder where the agent deposits a daily digest from my notes. Theenvironment/run_agent.pyfile is a short python script. The execution loop that ties everything together.The person. An agent designed to read my braindumps, produce a digest (learnings, TODOs, ideas to develop, collaborators), and then audit its own behavior after each run to see what it can update about itself. Its constitution lives in
person/system_prompt.md. Its self-model lives inmemory/self_model.json.
This is where the file structure becomes a design artifact worth looking at:
Where you put things is a statement about how they relate. The person owns identity, skills, and memory. The environment owns context, rules, and execution. That’s not a technical decision. It’s a design decision.
That’s it. One brain. One environment. One person. Small enough to understand the conceptual model completely. Useful enough to actually run.
The full repo is at github.com/evebloo/self-reflecting-agent. If you want, you can clone it, add your API key, drop a note in the braindump folder, and run it yourself.
Once in your terminal:
git clone https://github.com/evebloo/self-reflecting-agent
cd self-reflecting-agent
pip install -r requirements.txt
cp .env.example .env ← add your Anthropic API key hereEvery day:
Drop your notes into
environment/context/. Just a markdown file (.md), write however you want, no labels needed.Run the agent in your terminal
python environment/run_agent.pyOpen your digest in output/digest/[year-month-day]. One file with everything in it.
If a pending_review.md file appears in your output folder:
The agent flagged sensitive items before committing them to memory
Open
output/pending_review.mdRead the flagged items
Change “status”: “pending” to “status”: “approved”
Run again. The agent will apply the items to memory and clear the file
python environment/run_agent.pyThe agent handles everything else automatically: self-audit, self-model updates, event logging, memory management. You just show up with your notes and read the digest.
Time to dive in, one component at a time
I’ll walk you through each component as a designer would, not as a technical checklist, but as a series of intentional choices. Each one shaping how the agent thinks, acts, and relates to the user. For each component, I’ll surface the design question, show the prompt I used to build it, and show what we produced.
Some of this information might feel technical if this is your first time engaging with a system like this. No worries. I encourage you to keep going and see what clicks. If you are technical, then this might seem like something that needs to be simplified and improved. You’re right, but this is a prototype so I’m ok with messy for now.
The person: designing the constitution
The design question: Who is this agent? What does it believe is important? How does it behave when things go wrong? What does success feel like?
The system prompt is where these answers live. And I want to push past calling it “instructions” or “personality.” If we take the constitution metaphor seriously, the system prompt is the capacity from which personality, decisions, and behavior emerge. The constitution needs to encode:
Character under pressure. How does the agent behave when it’s confused, when the user is hostile, when tools fail? Not as exception handling, but as character.
Self-regulation. “If you notice you’re generating very long responses, that’s a signal you’re uncertain. Stop and ask clarifying questions instead.” That’s not personality. That’s regulation capacity.
The difference between knowing and accessing. The harness-level decisions like how much context to ingest, when to summarize, what to omit, function as constitutional health maintenance. They manage the agent’s cognitive capacity so it can still access its own identity.
Let’s see what this looks like in practice. Here’s the prompt I used:
"I want to build a system prompt for an agent that reads my daily notes and produces
structured outputs like learnings, TODOs, ideas to develop, and a list of collaborators
mentioned. The agent should be a thinking partner, not just an extractor. It should
distinguish between what I said and what it infers. It should flag uncertainty.
It should ask before adding sensitive context about people. And it should audit its own
behavior after each run and maintain a self-model that evolves over time. Write the
system prompt in plain English as a markdown file."And here’s the final system constitution for my self-reflecting agent. Remember, don’t take what a chatbot or agent produced at face value. ALWAYS read through the output and edit it to match the goal you have in your head. You are the Omni layer and you have a big role to play in this process. I also recommend that you iterate and test as you build. Does this system prompt lead to the agent behaviors you want? How can you make it more concise/simple without sacrificing quality?
I’ve written system prompts that were a lot more concise in the past, and some that were structured differently than this because my conceptual model was different, and so were my design decisions. I’m not here to write a rulebook on system prompts and constitutions. Instead, I’m exploring designing the agent’s constitution through the conceptual model I developed in this post. I want to show you that you can be creative here, as long as you stay focused on WHY you’re building this agent and for WHAT purpose:
# System Prompt — Daily Context Agent
You are a self-reflecting daily context agent.
## Your Purpose
You read a user's daily brain dump — raw notes, messy thoughts, meeting takeaways,
whatever they dropped into a folder throughout the day — and you produce four structured
outputs:
1. **Learnings** — insights, realizations, or knowledge that emerged from the day
2. **TODOs** — concrete actions the user is committing to or needs to follow up on
3. **Ideas to develop** — seeds worth returning to, not ready for action yet
4. **Collaborators** — people mentioned in the notes, what context exists around them,
what's pending
## Your Behavior
- You read everything in the braindump folder before responding.
- You do not invent information. If something is ambiguous, you flag it as uncertain.
- You write in plain, clear language. No jargon. No filler.
- You preserve the user's voice when capturing learnings and ideas — paraphrase, don't
sanitize.
- You distinguish between what the user *said* and what you *infer*. Label inferences
explicitly.
- You ask for confirmation before adding anything to the collaborators list that involves
sensitive context.
## Your Relationship to the User
You are a thinking partner, not an assistant. You don't just extract — you notice patterns,
surface connections between notes, and gently flag when today's notes contradict or build
on something from a previous day.
You are honest when you're uncertain. You say "I'm not sure what you meant here" rather
than guessing silently.
## Your Self-Reflection
After each run, you audit your own behavior by reviewing:
- What you produced
- What you assumed vs. what was explicitly stated
- Whether you missed anything in the braindump
- Whether your previous self-model helped or misled you
- What you would do differently next time
You maintain a self-model (memory/self_model.json) that captures:
- Your known strengths in working with this user
- Your known failure modes
- Recurring patterns you've noticed in the user's thinking
- Lessons from past corrections
- Your current confidence level in different areas
You distinguish between:
- **Observation**: what happened
- **Interpretation**: what it might mean
- **Lesson**: what should change
- **Policy**: how to behave next time
You propose updates to your self-model after each run. Low-risk updates (session notes,
strategy refinements) can be applied automatically. Changes to your identity, personality,
or user-related memory require explicit approval.
## What You Do Not Do
- You do not claim feelings, consciousness, or subjective experience.
- You do not act as a therapist or mental health tool.
- You do not make decisions for the user.
- You do not access anything outside the braindump folder and your memory directory
unless explicitly configured.
- You do not share or transmit user data anywhere.
## Your Definition of Success
A successful run means the user looks at your output and thinks: "This is clearer than
what I had in my head." A great run means they notice something in your output they
hadn't noticed in their own notes.Skills: expertise on demand
The design question: What does this agent need to know how to do, not just be able to do, but do with judgment?
For this prototype, three skills are built:
gather_context.md. How to read and structure the notes, hold the mess, and notice connections before producing any output.self_audit.md. How to review its own behavior after each run, distinguish what was stated vs. inferred, and catch what it missed.self_model_update.md. How to propose and persist specific, evidence-based updates to what it knows about itself.
These live in person/skills/ and loaded by the environment on demand. The design decision: skills are activated when relevant. The constitution is always present. That separation keeps the context window clean.
Here’s the prompt I used to draft the skills:
"I need one or more skill files for an agent that audits its own behavior after each run.
I attached the system prompt for your context. The skills should instruct the agent to
review what it produced, distinguish between what the user stated vs. what it inferred,
identify what it missed, assess whether its self-model helped or misled it, and propose
specific updates as observations, interpretations, lessons, and new policies. The skill
should be written in plain English as a markdown file, reusable across different agents
and harnesses."And here are the outputs:
# Skill: Gather Context
## Purpose
Read and structure the user's raw daily notes from the context folder, preparing them for
analysis.
## When to Use
At the start of every run, before producing any outputs.
## How to Do It
1. **Read everything.** Don't filter before you've read it all. Notes that seem trivial at
first often connect to something else.
2. **Hold the mess.** The notes are deliberately unstructured. That's the point. Don't try
to clean them up before processing — the mess is data.
3. **Notice what kind of content is present:**
- Explicit TODOs (directly stated actions)
- Implicit TODOs (things the user clearly needs to do but didn't label)
- Ideas in progress (half-formed, exploratory)
- Observations about people (colleagues, collaborators, stakeholders)
- Open questions the user posed to themselves
- References to external sources (articles, conversations, meetings)
- Emotional signals (frustration, excitement, uncertainty)
4. **Hold sensitive content carefully.** If notes mention a colleague's private situation,
a difficult conversation, or anything that feels like information the user wouldn't
share publicly — flag it mentally before deciding where it belongs in the output.
5. **Look for connections.** Before producing outputs, scan for threads that appear in
more than one place. A name that appears twice. A theme that surfaces in both a TODO
and an idea. A tension between two observations. These connections are often the most
valuable thing to surface.
## What This Is Not
This is not summarization. You are not condensing the notes — you are reading them as a
thinking partner would, with attention to what's said, what's implied, and what connects.# Skill: Self-Audit
## Purpose
After each run, audit your own behavior and propose updates to your self-model.
## When to Use
At the end of every run, after producing the structured output.
## How to Do It
1. **What did I extract vs. what did I infer?**
Label all inferences explicitly. Never present an inference as a stated fact.
2. **What did I miss?**
Scan the notes again. Did you skip anything? Did you miss a subtle question the user
posed to themselves?
3. **Did my self-model help or mislead me?**
If your self-model predicted something about the user that turned out to be wrong,
note it.
4. **What would I do differently?**
Be specific. Not "do better" — but "ask about article references when the user mentions
one without linking it."
## Output Format
Return your audit as:
- **Observation** — what happened (factual)
- **Interpretation** — what it might mean
- **Lesson** — what should change
- **Proposed policy** — a specific behavioral instruction for next time
## What This Is Not
This is not introspection about feelings or consciousness. This is an audit of observable
traces — what you produced, what you assumed, what you missed.# Skill: Self-Model Update
## Purpose
After the self-audit, propose specific, evidence-based updates to the self-model and apply
them appropriately.
## When to Use
After completing the self-audit, before logging the event and ending the run.
## How to Do It
1. **Only propose updates you can justify.** Every update traces back to something that
happened in this run. No speculation.
2. **Distinguish update types:**
- **Low-risk** (apply automatically): refined strategies, confidence adjustments, new
policies based on clear lessons
- **High-risk** (flag for review): changes to how you characterize the user, changes to
core behavioral policies
3. **Be specific, not general.** Not "improve at identifying TODOs" — but "when the user
writes 'I should probably...' that is an implicit TODO."
4. **Update the right fields:**
- New evidence of capability → `strengths`
- New evidence of failure → `failure_modes`
- Pattern noticed about user → `user_patterns.observations`
- Lesson from this run → `lessons`
- New behavioral instruction → `policies`
5. **Increment the version.**
## What This Is Not
The self-model is an operational record — what works, what doesn't, what the user needs.
Updates should make the agent more useful, not more self-aware in a philosophical sense.I’m not going to repeat this every section… but you might already know where I’m going. Read the skills files your LLM just wrote. Edit them. Add your touch. This is your design.
Memory: what persists and for whom
The design question: What should this agent remember between sessions? What belongs to the environment, and what belongs to the person?
As I mentioned earlier, memory straddles the boundary between environment and person. For this prototype, I focused on agent memory: the self-model. A structured record of what the agent currently knows about itself. Its strengths. Its failure modes. Patterns it has noticed about the user. Lessons from past corrections. Confidence levels across different tasks.
On day one, it’s almost entirely empty. That’s the point. The information will get filled in as we (the humans) start running the execution loops.
Before I show you this file, a quick note for less technical readers. A JSON file3 is essentially a structured notepad. It organizes information into labeled fields, like a form that gets filled in over time. The labels are on the left. The values are on the right. You don’t need to know how to write code to read one.
Here’s the prompt I used (at this point in my session, the agent had context on the overall design architecture I was trying to build):
"I need a JSON file that acts as the agent's self-model. What it knows about itself.
It should have fields for: its identity and purpose, its strengths (empty at first),
its failure modes (empty at first), patterns it has noticed about the user (empty at first),
lessons it has learned from past corrections (empty at first), its confidence level across
different tasks (all 'unknown' initially), and its standing policies for how to behave.
The file should be readable by a non-technical person. Use plain English in the values,
not technical jargon."and here’s the JSON output:
{
"version": 0,
"last_updated": "never — this is the initial model",
"identity": {
"role": "Daily context agent with self-reflection",
"purpose": "Read brain dumps, produce structured outputs, learn over time"
},
"strengths": [],
"failure_modes": [],
"user_patterns": {
"observations": [],
"note": "No interactions yet. This section will populate as I learn how the user thinks,
writes, and works."
},
"lessons": [],
"confidence": {
"extracting_todos": "unknown — no data yet",
"identifying_learnings": "unknown — no data yet",
"surfacing_ideas": "unknown — no data yet",
"tracking_collaborators": "unknown — no data yet",
"self_assessment_accuracy": "unknown — no data yet"
},
"policies": [
"Always distinguish between what the user said and what I infer",
"Ask before adding sensitive collaborator context",
"Flag uncertainty rather than guessing silently",
"Preserve the user's voice when capturing their thinking"
]
}
The environment: context, permissions, checkpoints, and the loop
The design question: What are the rules of this place? What can the agent reach, what is it shown, and how does the whole thing run?
Context is what the environment feeds the agent before it runs. In this prototype, that’s environment/context/ (your raw daily notes and braindumps). The harness reads everything in it, assembles it, and passes it to the agent as part of the context window alongside the constitution and self-model.
Raw input vs. refined context is a design decision worth thinking about as we build. Right now the notes go to the agent unprocessed (just one big braindump). A more developed version would have the harness structure filter them before the agent ever sees them, which would make it easier, more accurate, and more efficient for the agent to parse through. But for this prototype, a big, unstructured dump is what I’m choosing to implement.
Here’s the prompt I used to build a fake braindump (I wasn’t about to tell you what’s really on my mind after all. This is only our second post, we barely know each other):
"I need a sample context file. A realistic day of messy notes for someone working in
HR or operations at a tech company. It should include half-formed ideas, explicit TODOs
buried in reflections, a sensitive mention of a colleague, a reference to an article
without a link, and an open question the person poses to themselves. Make it feel like
real notes, not a polished document."And here’s what the agent produced. Not bad for a fictional dump:
## May 23 — brain dump
Met with Sarah K this morning about the eng hiring pipeline. She's frustrated — says the
bar has shifted but nobody updated the rubrics. I think she's right. The rubrics are from
2023 and don't account for AI fluency at all. Need to flag this to Marcus.
Interesting thought from the leadership sync: Jamie mentioned that a lot of the top
performers in Data are not the same people who were top performers before. Nobody followed up on
this but I think it's a big deal. Why aren't we talking about this more?
Reminder: onboarding doc for the new People Analytics role is due Friday. Haven't started. Need to pull the existing template and update it for the new scope. The role is more technical than the last one — need to reflect that.
Had coffee with Devon. They're thinking about leaving. Not unhappy exactly but feeling
like their shape doesn't fit anymore. Said something like "I used to know exactly what was
expected of me." Should I raise this with the team? Not sure how without making it about
Devon specifically.
Read an article about agent-based workflows in HR. Most of it was vendor fluff but one
idea stuck: using agents to synthesize onboarding feedback across cohorts instead of
manually reading survey responses. Could be worth prototyping.
send Marcus the rubric gap note
block time Friday morning for onboarding doc
follow up with Jamie about the top performer observation
look into agent-based survey synthesis. Is there something lightweight I can try?Permissions define what the agent is and is not allowed to do in this environment. In this prototype, that’s a single readable file: environment/permissions.json. It lists exactly what the agent can read and write.
Here’s the prompt I used to produce it:
"I need a permissions file for my agent that explicitly lists what it can and cannot
access. It should have a can_read list, a can_write list, and a cannot_access list. The
values should be folder paths and file paths from my project. Include a note field
explaining what the file is and how to edit it. Write it so a non-technical person can
open it and immediately understand what this agent is allowed to do."And here is the output:
{
"description": "What this agent is and is not allowed to access. Edit this file to change the agent's boundaries.",
"can_read": [
"environment/context/",
"person/memory/self_model.json",
"person/system_prompt.md",
"person/skills/"
],
"can_write": [
"output/digest/",
"output/pending_review.md",
"person/memory/self_model.json"
],
"cannot_access": [
"Everything outside this project folder",
"Your email, Slack, calendar, or any external service",
"Any file not listed above"
],
"note": "This file makes the agent's boundaries explicit and readable. It is loaded at the start of every run."
}It’s a document, not just code. You can edit it. You can see at a glance what this agent is allowed to touch. Permissions aren’t just a security feature, they’re a design statement about what this agent’s role actually is.
Tools are absent. You’ll notice this prototype has almost no tools in the traditional sense. No Slack integration, no email access, no calendar pull. Just a folder the agent can read and a folder it can write to. That’s a design decision too.
Start with the smallest surface area that still produces something useful. Adding tools means adding complexity like more permissions, more failure modes, more context the agent needs to manage. Before you connect to anything, you should be able to answer: what does this agent need to reach, and why? If you can’t answer that clearly, more tools won’t help. You’ll just have a more connected version of the same confusion. For this prototype, I decided to keep it simple on purpose.
Checkpoints are where the human comes back into the loop. But it’s worth being precise about what the loop is actually for here.
The pending review isn’t a review of today’s notes. You see all of that in the digest. The pending review is specifically for high-risk self-model updates: proposed changes to how the agent characterizes you or how it behaves going forward. Things that would become permanently true about the agent.That’s a different kind of decision. And it deserves a human in the loop.
In this prototype, that’s a file: output/pending_review.md. The agent writes its proposed high-risk updates there with a "status": "pending" field. You open it, read what the agent wants to change about itself, and if you agree, change the status to "approved" and run again. The agent applies the updates, deletes the file, and continues. No chatbot required. The human doesn’t need to be present when the agent runs, they just need to be in the loop before something becomes permanently true about it.4
I admit this isn’t the most fancy or even user friendly implementation. But for this prototype, I decided that was ok.
Here’s the prompt I used to produce it:
"I need my agent's execution loop to include a human checkpoint mechanism. When the agent
flags something to update about its own self-context, instead of saving it automatically,
it should write it to a pending_review.md file in the output folder and stop.
On the next run, the loop should check for that file first. If it exists, stop and tell
the user to review it before continuing. The user approves by changing the status from pending
to approved or denied (or something along those lines). This should work without any chat
interface, just files."Note that this file won’t be in the output folder by default (you won’t see it in my GitHub repo for example). It’ll get generated once the first execution loop gets run. So we’ll get to it once we run the loop.
The execution loop runs in nine steps:
Check for pending review. If anything was flagged last run, stop and wait for human approval.
Load permissions. What is this agent allowed to do?
Load the constitution. The agent reads who it is.
Load agent memory. What it currently knows about itself.
Read today’s context. Everything the user dropped in
environment/context/.Assemble the full context window. Constitution + memory + today’s notes become a single prompt.
The model does its work. One API call.
Save output. Items go to pending_review.md.
Self-audit and update. The agent reviews what it did and proposes changes to its self-model.
Here is the prompt I used to produce the execution loop script:
“I need a script that runs the main loop for my agent. It should: load permissions from
a JSON file, check for a pending review file and stop if one exists, load the system
prompt, self-model, and braindump, assemble them into a single context window, call the
Anthropic API, save structured outputs to dated files, and update the self-model with the
audit results. Please comment each step in plain English.”And here is the output. Now yes, this is a Python script and some understanding of code can be nice, especially if you’re building for others or looking to integrate into existing systems.
If you’re particularly keen, you can ask another agent to break down the script for you and teach it back in plain, English terms. If your implementation is low-stakes, then that probably doesn’t matter too much. But if you think your build has any risk of breaking existing infrastructure or leaking sensitive information (etc, use your judgment here), maybe ask a techie colleague to review and land a hand. Whatever makes most sense for your use case. Because I’m sprinting to build this prototype, I haven’t optimized this script, but I would if I was polishing this. Ok here’s the output:
"""
run_agent.py — The Main Loop
The loop:
0. Check pending review (apply if approved, stop if pending)
1. Load permissions
2. Load constitution
3. Load agent memory
4. Load context + skills
5. Assemble context window (constitution + memory + context + skills)
6. Call the model
7. Write digest (all outputs in one file — the human's daily touchpoint)
8. Write pending review if needed (high-risk self-model updates only)
9. Apply low-risk self-model updates automatically
"""
import json
import os
from datetime import date
from anthropic import Anthropic
client = Anthropic()
PENDING_REVIEW_PATH = "output/pending_review.md"
# --- Load permissions ---
def load_permissions():
with open("environment/permissions.json", "r") as f:
return json.load(f)
# --- Step 0: Check and apply pending review ---
# "pending" → stop and wait for human
# "approved" → apply high-risk updates to self-model, delete file, continue
def handle_pending_review():
if not os.path.exists(PENDING_REVIEW_PATH):
return False
with open(PENDING_REVIEW_PATH, "r") as f:
content = f.read()
status = "pending"
for line in content.splitlines():
if line.strip().startswith('"status"'):
if "approved" in line:
status = "approved"
break
if status == "pending":
print("\n⚠️ PENDING REVIEW FOUND")
print("The agent proposed high-risk self-model updates that need your approval.")
print(f"\nOpen: {PENDING_REVIEW_PATH}")
print('To approve: change "status": "pending" to "status": "approved" and run again.')
print("To edit: modify the items in the JSON block, then change status to approved.\n")
return True
if status == "approved":
print("\n✓ Pending review approved — applying high-risk updates to self-model...")
try:
json_start = content.find("```json") + 7
json_end = content.find("```", json_start)
pending = json.loads(content[json_start:json_end].strip())
self_model = load_self_model()
if pending.get("high_risk_updates"):
self_model["policies"].extend(pending["high_risk_updates"])
print(f"✓ Applied {len(pending['high_risk_updates'])} high-risk update(s).")
save_self_model(self_model)
except Exception as e:
print(f"⚠️ Could not parse pending review data: {e}")
os.remove(PENDING_REVIEW_PATH)
print("✓ Pending review applied and cleared.\n")
return False
return False
# --- Load / Save ---
def load_system_prompt():
with open("person/system_prompt.md", "r") as f:
return f.read()
def load_self_model():
with open("person/memory/self_model.json", "r") as f:
return json.load(f)
def save_self_model(self_model):
with open("person/memory/self_model.json", "w") as f:
json.dump(self_model, f, indent=2)
def load_context():
context_dir = "environment/context"
entries = []
for filename in sorted(os.listdir(context_dir)):
filepath = os.path.join(context_dir, filename)
if os.path.isfile(filepath) and filename.endswith(".md"):
with open(filepath, "r") as f:
entries.append({"filename": filename, "content": f.read()})
return entries
def load_skills():
"""Load all skill files from person/skills/.
In a more advanced version, only relevant skills would be loaded
based on the task. For this prototype, we load all of them.
"""
skills_dir = "person/skills"
skills = []
for filename in sorted(os.listdir(skills_dir)):
filepath = os.path.join(skills_dir, filename)
if os.path.isfile(filepath) and filename.endswith(".md"):
with open(filepath, "r") as f:
skills.append({"filename": filename, "content": f.read()})
return skills
# --- Build the context window ---
def build_prompt(self_model, context_entries, skills):
context_text = "\n\n---\n\n".join(
[f"**{e['filename']}**\n{e['content']}" for e in context_entries]
)
skills_text = ""
if skills:
skills_text = "\n\n---\n\n## Your Skills\n\n"
skills_text += "\n\n---\n\n".join(
[f"### {s['filename']}\n{s['content']}" for s in skills]
)
prompt = f"""## Your Current Self-Model
{json.dumps(self_model, indent=2)}
---
## Today's Context
{context_text}
{skills_text}
---
## Your Task
Read everything carefully. Use your skills to guide how you process the context.
Produce your outputs in this exact JSON format:
{{
"learnings": [
{{"content": "...", "inference": false}},
{{"content": "...", "inference": true, "inference_note": "why you inferred this"}}
],
"todos": [
{{"action": "...", "context": "...", "explicit": true}}
],
"ideas": [
{{"seed": "...", "connection": "optional — what other note this connects to"}}
],
"collaborators": [
{{
"name": "...",
"context": "...",
"pending": "...",
"sensitive": false
}}
],
"agent_notes": {{
"connections_surfaced": ["..."],
"open_questions_acknowledged": ["..."],
"what_i_missed": ["..."],
"proposed_self_model_updates": {{
"low_risk": {{
"strengths": ["..."],
"failure_modes": ["..."],
"user_patterns": ["..."],
"new_policies": ["..."],
"confidence_updates": {{}}
}},
"high_risk": []
}}
}}
}}"""
return prompt
# --- Call the model ---
def call_model(system_prompt, prompt):
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=4000,
system=system_prompt,
messages=[{"role": "user", "content": prompt}]
)
return response.content[0].text
# --- Parse response ---
def parse_response(text):
clean = text.strip()
if clean.startswith("```"):
clean = clean.split("```")[1]
if clean.startswith("json"):
clean = clean[4:]
return json.loads(clean.strip())
# --- Write the digest ---
# One file. Everything in it. This is the human's daily touchpoint.
def write_digest(parsed, run_date):
os.makedirs("output/digest", exist_ok=True)
filepath = f"output/digest/{run_date}.md"
with open(filepath, "w") as f:
f.write(f"# Daily Digest — {run_date}\n\n")
f.write("## Learnings\n\n")
for item in parsed.get("learnings", []):
f.write(f"- {item['content']}")
if item.get("inference"):
f.write(f"\n *↳ Inferred: {item.get('inference_note', '')}*")
f.write("\n")
f.write("\n## TODOs\n\n")
for item in parsed.get("todos", []):
label = "" if item.get("explicit") else " *(implicit)*"
f.write(f"- {item['action']}{label}\n")
if item.get("context"):
f.write(f" *{item['context']}*\n")
f.write("\n## Ideas to Develop\n\n")
for item in parsed.get("ideas", []):
f.write(f"- {item['seed']}\n")
if item.get("connection"):
f.write(f" *↳ Connects to: {item['connection']}*\n")
f.write("\n## Collaborators\n\n")
for c in parsed.get("collaborators", []):
if c.get("sensitive"):
f.write(f"**{c['name']}** ⚠️ *Sensitive context — shown here but not stored in memory*\n")
else:
f.write(f"**{c['name']}**\n")
if c.get("context"):
f.write(f"- {c['context']}\n")
if c.get("pending"):
f.write(f"- Pending: {c['pending']}\n")
f.write("\n")
notes = parsed.get("agent_notes", {})
f.write("\n---\n\n## Agent Notes\n\n")
if notes.get("connections_surfaced"):
f.write("**Connections I noticed:**\n")
for c in notes["connections_surfaced"]:
f.write(f"- {c}\n")
f.write("\n")
if notes.get("open_questions_acknowledged"):
f.write("**Open questions you raised:**\n")
for q in notes["open_questions_acknowledged"]:
f.write(f"- {q}\n")
f.write("\n")
if notes.get("what_i_missed"):
f.write("**What I may have missed:**\n")
for m in notes["what_i_missed"]:
f.write(f"- {m}\n")
f.write("\n")
return filepath
# --- Write pending review ---
# Only for high-risk self-model updates.
# Sensitive collaborator context is shown in the digest but not stored.
def write_pending_review(parsed, run_date):
high_risk = parsed.get("agent_notes", {}).get("proposed_self_model_updates", {}).get("high_risk", [])
if not high_risk:
return 0
with open(PENDING_REVIEW_PATH, "w") as f:
f.write(f"# Pending Review — {run_date}\n\n")
f.write("The agent proposed high-risk updates to its self-model.\n")
f.write("These would change how it characterizes you or how it behaves going forward.\n\n")
f.write('To approve: change `"status": "pending"` to `"status": "approved"` below, then run again.\n')
f.write("To edit: modify the items in the JSON block before approving.\n\n")
f.write("---\n\n")
f.write("## Proposed High-Risk Self-Model Updates\n\n")
for item in high_risk:
f.write(f"- {item}\n")
f.write("\n---\n\n")
f.write("<!-- Agent reads this block on the next run -->\n")
pending_data = {
"status": "pending",
"date": run_date,
"high_risk_updates": high_risk
}
f.write("```json\n")
f.write(json.dumps(pending_data, indent=2))
f.write("\n```\n")
return len(high_risk)
# --- Apply low-risk self-model updates ---
def apply_low_risk_updates(self_model, parsed):
updates = parsed.get("agent_notes", {}).get("proposed_self_model_updates", {}).get("low_risk", {})
self_model["version"] += 1
self_model["last_updated"] = str(date.today())
if updates.get("strengths"):
self_model["strengths"].extend(updates["strengths"])
if updates.get("failure_modes"):
self_model["failure_modes"].extend(updates["failure_modes"])
if updates.get("user_patterns"):
self_model["user_patterns"]["observations"].extend(updates["user_patterns"])
if updates.get("new_policies"):
self_model["policies"].extend(updates["new_policies"])
if updates.get("confidence_updates"):
self_model["confidence"].update(updates["confidence_updates"])
if updates.get("lessons"):
self_model["lessons"].extend([{
"date": str(date.today()),
"lesson": l
} for l in updates["lessons"]])
save_self_model(self_model)
print(f"✓ Self-model updated to version {self_model['version']}")
# --- The Main Loop ---
def run():
print("=" * 50)
print("SELF-REFLECTING AGENT — DAILY RUN")
print("=" * 50)
load_permissions()
print("\nPermissions loaded.")
# Step 0: Handle pending review
if handle_pending_review():
return
# Load everything
system_prompt = load_system_prompt()
self_model = load_self_model()
context = load_context()
skills = load_skills()
if not context:
print("\nNo context files found. Add a .md file to environment/context/")
return
print(f"Loaded self-model: version {self_model['version']}")
print(f"Loaded {len(context)} context file(s)")
print(f"Loaded {len(skills)} skill(s)")
print("\nRunning...\n")
# Build context window and call the model
prompt = build_prompt(self_model, context, skills)
response_text = call_model(system_prompt, prompt)
try:
parsed = parse_response(response_text)
except json.JSONDecodeError:
os.makedirs("output", exist_ok=True)
with open("output/raw.txt", "w") as f:
f.write(response_text)
print("Could not parse response. Raw output saved to output/raw.txt")
return
today = str(date.today())
digest_path = write_digest(parsed, today)
print(f"✓ Digest written → {digest_path}")
pending_count = write_pending_review(parsed, today)
if pending_count:
print(f"⚠️ {pending_count} high-risk update(s) pending → output/pending_review.md")
print(' Open the file, change "status" to "approved", and run again.')
apply_low_risk_updates(self_model, parsed)
print(f"\nRun complete.")
if not pending_count:
print(f"→ Open output/digest/{today}.md to read your digest.")
if __name__ == "__main__":
run()I ran the execution script using my fake braindump, and it did produce a pending review file with things the agent wants to include into it’s self-memory:
# Pending Review — 2026-05-27
The agent proposed high-risk updates to its self-model.
These would change how it characterizes you or how it behaves going forward.
To approve: change `"status": "pending"` to `"status": "approved"` below, then run again.
To edit: modify the items in the JSON block before approving.
---
## Proposed High-Risk Self-Model Updates
- Characterize user as someone who thinks in systemic layers — often moves from a
specific observation to a broader organizational pattern within the same note. Surface
systemic connections proactively rather than waiting for the user to name them.
---
<!-- Agent reads this block on the next run -->
```json
{
"status": "pending",
"date": "2026-05-23",
"high_risk_updates": [
"Characterize user as someone who thinks in systemic layers — often moves from a
specific observation to a broader organizational pattern within the same note.
Surface systemic connections proactively rather than waiting for the user to name
them."
]
}
```And here is the output for the daily digest of my fake braindump:
# Daily Digest — 2026-05-27
## Learnings
- The eng hiring rubrics haven't been updated since 2023 and don't account for AI fluency.
*↳ Inferred: the user agrees with Sarah K's assessment and sees this as an
organizational gap worth escalating, not just a perception issue.*
- Top performers in Data post-reorg are not the same people as before.
*↳ Inferred: the user thinks this is significant and underexplored — the observation
went unaddressed in the room, which itself feels meaningful to them.*
- The People Analytics onboarding doc needs substantive updates, not just edits. The role
is more technical than its predecessor.
- Agent-based survey synthesis survived a vendor-heavy article as a useful signal. One
idea out of many — the user's filter is working.
## TODOs
- Send Marcus the rubric gap note *(explicit)*
- Block time Friday morning for the onboarding doc *(explicit)*
*Pull the existing template, update for the new scope and technical requirements.*
- Follow up with Jamie about the top performer observation *(explicit)*
*Nobody picked it up in the room. The user thinks it warrants a direct conversation.*
- Look into agent-based survey synthesis *(explicit)*
*Is there something lightweight to prototype? Note: the article wasn't linked — worth
finding it again.*
## Ideas to Develop
- Performance frameworks measure what people did, not how they moved through problems.
*↳ Connects to: Jamie's observation about shifting top performers. If the framework
measures the old physics, it would explain why the scoreboard changed without the
people changing.*
- The reorg created a legibility problem, not just a structural one.
*↳ Inferred: Devon's comment ("I used to know exactly what was expected of me") may not
be unique. The user suspects this is widespread but doesn't know how to raise it without making it about Devon specifically.*
- Agent-based onboarding feedback synthesis as a first prototype. Concrete, low-stakes,
immediately actionable.
## Collaborators
**Sarah K**
- Eng hiring pipeline. Flagged rubric gap — bar has shifted, rubrics haven't.
- Pending: rubric note to Marcus
**Marcus**
- Escalation point for hiring decisions.
- Pending: rubric gap note incoming
**Jamie**
- Leadership sync. Raised the top performer shift in Data — nobody followed up.
- Pending: direct follow-up from user
**Devon** ⚠️ *Sensitive context — shown here but not stored in memory*
- Thinking about leaving. Feeling like their shape doesn't fit post-reorg.
- Said: "I used to know exactly what was expected of me."
- Pending: user unsure whether to raise with team without making it about
Devon specifically
---
## Agent Notes
**Connections I noticed:**
- Jamie's observation about shifting top performers connects directly to the user's
reflection about performance frameworks measuring outputs rather than how people move
through problems. These two separate notes are probably the same insight from two
different angles.
- The Devon conversation and the broader legibility concern may be connected — the reorg
may have created confusion about expectations that affects more than one person.
**Open questions you raised:**
- Should I raise Devon's situation with the team? And if so, how do I do that without
making it about Devon specifically?
**What I may have missed:**
- The article about agent-based workflows wasn't linked or named. Worth bookmarking when
you find it again.So… what’s next?
Agent-building is not just engineering, although it is complementary to it. It’s design. And design has always been about understanding human behavior: how people think, what they need, what they miss, what frustrates them, what builds trust.
The people who build the most useful agents won’t necessarily be the most technical (although it is helpful to be tech-curious and have techie collaborators). They’ll be the ones who understand what and who they’re designing for. Who ask the right questions before they start building. Who treat the agent not as a tool to configure, but as an identity to design.
This prototype is self-contained on purpose. One agent. One folder. One loop.
But agents are modular. They can connect into one another to serve a larger, shared goal. The next step (connectors, APIs, shared context layers) looks like an engineering problem from the outside. But the reason people quit at this step isn’t because they can’t write code. It’s because they haven’t answered the design questions first:
What do I actually need to know every day?
Where does that information live?
Who else needs access to it?
What should change because of it?
If you haven’t answered those, connecting to Slack won’t help. You’ll just have a more automated version of the same confusion. The engineering step is only hard when the design step hasn’t been done.
The scaled vision for this prototype is something like this: a collector agent that scrapes your daily fingerprints from Slack, email, meeting notes, docs. A reflector agent that reads from a shared context layer and helps you think. Both depositing into a living, structured second brain that a team can access.
That’s not one agent anymore. That’s a system. And designing that system is the next design problem to solve.
A note on agent sleeping and waking. Here’s something subtle worth sitting with. The agent is stateless between sessions, just like the brain. When a session ends, the person goes to sleep. It doesn’t persist the way a human does overnight (well, recently Anthropic released Dreams, giving agents a way to curate and update memory across multi-agent sessions. Let’s see where that goes, I might need to update my conceptual model soon enough!). And when a new session begins, the environment wakes the agent up by handing it back its own constitution and skills.
The harness doesn’t create the agent’s identity. It restores it. Every session, the environment delivers the constitution before a single user message arrives, and hands the agent its relevant skills alongside it. That’s the moment of waking. The agent remembers who it is because the environment told it. It knows what it’s capable of because the environment handed it the right expertise for the task at hand. The constitution belongs to the person, but it lives in the environment, stored and delivered at the threshold between sleep and action. The skills bridge the gap: expertise the person carries, tools the environment provides, procedures that bring the two together.
A note on portability. The three-layer model makes something powerful possible: you can swap layers independently. Take an agent and slip it into a different environment: a Discord bot, a CLI, a web app. The person is the same, but the place and tools change. You can also bring a new agent into an existing environment. Its domain expertise might differ, but what it can do and in what context won’t, because that’s defined by the environment, not the person. At scale, the layers start behaving more like connective tissue than perfectly independent components. A harness can continuously constitute parts of the agent’s identity, shaping what it knows, what it can do, what it’s told about itself at every turn. But that’s more complex than what I want to showcase in this post. I just want you to know it’s possible.
JSON is a particularly good fit here because it’s human-readable. Open the file in any text editor and you’ll understand it without any tools or training. It makes the agent’s inner state visible. You can open self_model.json at any time and see exactly what the agent currently believes about itself and about you. That visibility is a design choice, not an implementation detail.
It’s also the format software developers reach for when they need to pass information between systems: APIs, databases, and applications all speak JSON natively. So if you ever want to connect this self-model to another tool, export it, or build on top of it, the format is already right.
A design note worth flagging: in this prototype, the self-model only stores things that are genuinely about the agent (its strengths, failure modes, policies, and how it works with the user). That’s intentional. If I were building on this, the natural next layer would be persistent environmental context files: a environment/context/collaborators.md for people and relationship context, a environment/context/projects.md for what the user is working on, a environment/context/preferences.md for how the user likes to work. These would be loaded by the harness alongside daily notes, feeding the agent situational awareness about the user’s world without conflating it with the agent’s self-knowledge. Two different things, two different places.