Forem: Lê Tú Hào

Dead Light Framework · Part 2 — a copy-paste setup so your AI agents stop losing context between sessions

Lê Tú Hào — Fri, 22 May 2026 12:28:40 +0000

Every Session Starts in Darkness. Your Documents Shouldn't. — A Copy-Paste Setup So AI Agents Stop Losing Context Between Sessions (Dead Light Framework, Part 2)

Two files, four rules, ten minutes. Skip the theory; the templates are below and you can paste them into a repo right now.

Dead Light Framework — Part 2 of an ongoing series. Series so far: 1 · The Emperor Is All But Dead · 2 · Every Session Starts in Darkness · next: when two files aren't enough — the paperwork-vs-runtime decision.

By a developer running AI agents as daily teammates — a peer, not an authority (full framing in #1). · ~7 min · the Dead Light Framework repository (MIT)

The tax you're paying (and want gone)

If you hand real work to AI agents, you pay this every day: each new session starts from zero. You re-explain the project, what you decided last time, what's in flight, which files matter. Fifteen, twenty minutes of re-priming a human teammate would never need — and worse, the agent cheerfully re-litigates Monday's decision on Wednesday because nothing told it the decision was settled.

My least favourite version of it: I once left a comment explaining why an ugly branch of code had to stay. Two days later a fresh session, sent in to tidy up TODOs, read the comment as a TODO and deleted the branch by morning. The reasoning died with the session that wrote it. That's the tax — and it compounds.

It isn't a model problem. Each session is stateless by design; the last session's reasoning is gone unless something on disk carries it. So put it on disk — deliberately, in a shape the next session can consume in one read. Here's the smallest setup that does it.

The setup: two files, four rules (≈10 min)

Drop two files at your repo root. That's the whole mechanism.

`HANDOFF.md` — the snapshot a fresh session reads first

Your project's current state on one screen: what's true now, what's mid-task, what's decided, what to do next. It's the first thing an agent reads each session — the thing that replaces fifteen minutes of you re-explaining. Rewrite it freely; it always describes "now" (running history lives in LOG.md, below). Think of it as the project's working memory, externalised so a memoryless teammate can borrow it.

---
doc_kind: state
status: working          # draft | working | sealed
updated: 2026-05-22
---
# HANDOFF — <project>

## Now            # what is true today
- Frontend v2 rename is done; auth is on the new schema.

## In flight      # mid-task work + who owns it
- Migrating `users` table — session-12, half done; next step is the backfill.

## Decided        # do NOT re-litigate these
- Auth must not import billing. Why: layering; billing changes shouldn't ripple into auth.

## Start here next
- Run the `users` backfill, then delete the legacy column.

Copy the full, commented template: handoff-template.md

`LOG.md` — the append-only history

If HANDOFF.md is "now", LOG.md is "everything that happened" — one line per event, append-only; you never edit a past line (a correction is a new line). Why keep it when the snapshot already shows the current state? Because the snapshot overwrites itself: the moment you need to know why something was decided, replay how you got here, or recover after a session left a mess, you need the history the snapshot threw away. The snapshot is derived from this log — not the other way round.

---
doc_kind: log
---
# LOG — <project>   (append-only; a correction is a NEW line, never an edit)

- 2026-05-22 · session-12 · decided  · auth must not import billing (layering)        <!-- sealed -->
- 2026-05-22 · session-12 · created  · users-table migration draft                     [candidate]
- 2026-05-22 · session-12 · note     · backfill must run before dropping legacy column

Copy the full, commented template: log-template.md

The four rules

Two kinds, never mixed. HANDOFF.md is current state — overwrite it freely. LOG.md is history — append only; never edit a past line (a correction is a new line). This one split is what makes the whole thing trustworthy.
First thing every session: read HANDOFF.md, then the new lines in LOG.md since you last looked. That's your re-prime — under a minute, no human needed.
Last thing every session: append what you did to LOG.md, then update HANDOFF.md to match. (An agent can do both as part of "wrap up.")
Tag what isn't settled. [candidate] = produced by an agent, not human-confirmed.  = a decision that must not be "cleaned up" away. Agents read these.

That's it. No tool to install, no service to run — git plus two markdown files. Want it as one copy-paste page (both templates + the rules + the agent instruction)? The Agent Context Quickstart.

Tell your agent once (system prompt / CLAUDE.md / .cursorrules): "At the start of every session read HANDOFF.md and the recent LOG.md lines before doing anything. At the end, append your actions to LOG.md and update HANDOFF.md. Never edit past LOG lines; never touch a  decision without asking." Now the discipline is the agent's job, not yours.

What you actually get

Re-prime drops from ~15 min to ~1 min. The agent reads two files and is current — you stop being a human context-cache.
Decisions stop silently reverting. A sealed line in Decided is a wall the next session sees; the Wednesday-undoes-Monday failure mostly stops.
You can stop mid-task and resume clean. In flight + the LOG tail tell the next session exactly where to pick up — even a different agent, even weeks later.

Honest cost: ~2 minutes of discipline per session (append + update), and it pays off only once you're past a handful of sessions or running more than one agent. Below that, a plain README is fine — don't over-build.

Why it works (the 30-second version)

Documentation is your team's shared memory. When some teammates wipe their memory every session, the documents have to carry state — and the reliable way to carry state across actors that can't sync live is exactly this: one append-only history plus a derived current-state view. That's the eventually-consistent coordination pattern distributed systems have used for decades; I just borrowed it. The full standard — including the multi-repo and multi-agent versions, and the failure modes — is framework/paperwork-standard.md.

This covers one repo and one session at a time. The moment you have two agents writing at the same instant, or an invariant that must never break even for a second, two markdown files can't promise it — and that's a real, provable limit, not a gap you patch with better notes. Knowing which side of that line you're on is the next post.

The story below the setup (optional — skip if you came for the templates)

You can stop here with a working setup. If you want the why behind the why, here it is.

Back in late 2024 / early 2025, when I first started handing agents real work — audit this service, draft this migration, pick up where the last session left off — this was a dumb, recurring tax. Every new session opened with me re-explaining the same context, and by the third I was burning fifteen or twenty minutes re-establishing state a human teammate would simply have had. So I wrote a better HANDOFF.md. Then a better one. The overhead kept climbing, and a voice in the back of my head kept saying: you're carving this at the wrong joint.

So I made the mistake of following the problem — and it turned out not to be the problem I thought it was. Strip the word "documentation" and it's stark: I had actors that start cold, run briefly, and can't talk to each other in real time, and they had to act coherently anyway. That's not a docs question — it's distributed systems, a field that's been proving theorems about exactly this since the 1970s. I'd been hand-rolling a worse version of it in markdown without noticing.

That's also why this framework wears Warhammer 40,000 names, in case the "darkness" felt like an affectation. The Imperium of Man runs a galaxy with no real-time communication — its ships cross the warp, where they're simply unreachable. So it governs on three things: frozen edicts (decided once, not renegotiable by whoever's nearest), the Adeptus Administratum (literally galactic paperwork), and the Astronomican — a beacon of light a ship lost in the dark steers by. Strip the gothic paint and that's the entire engineering of this post: frozen authority, durable records, and a signal that survives. The darkness in the title is the warp between your sessions; your two files are the Astronomican.

And there's a catch I'll be honest about, because it shapes the whole series: that "real, provable limit" two paragraphs up isn't hand-waving — coordinating actors with no live channel runs into a genuine theorem (CAP), and it caps what any pile of documents can promise. So after I'd borrowed all this and wired it together, I spent more effort trying to break it than to build it — cold, hostile reviewers; an independent pass over every borrowed citation; benchmarks designed to make it fail. Some of it failed. That story is the rest of the series — but your setup above doesn't wait on any of it.

New here? I'm a developer who runs AI agents daily — a peer, not an authority; full framing in #1. Standing caveat: one developer, essentially one case study — useful, not proven. Tell me where it breaks for you.

"Every session starts in darkness" is Warhammer-flavoured naming, nothing more. Independent practitioner exploration; no affiliation with Games Workshop. Repository MIT-licensed.

DeadLightFramework #AIAgents #AIProductivity #Documentation #ContextContinuity #AIAgentGovernance #HumanAICollaboration #PromptEngineering #DevTools

Dead Light Framework: An Experimental Framework for Human-AI Collaboration #Post 1

Lê Tú Hào — Tue, 12 May 2026 04:39:23 +0000

The Emperor Is All But Dead. The Light Remains.

An experimental governance framework for software teams of humans and AI agents — and a request to be argued with

Status: experimental. Unverified in the field. Looking for sparring partners more than followers.

By: a developer with ~10 years across many projects, not an academic or industry authority — full bio at the bottom.

Published: 2026-05-11 · ~8 min read ·
Repository: github.com/letuhao/dead-light-framework

TL;DR

I have been building software with AI agents long enough to see the same governance failure mode appear over and over: agents and humans contradicting Monday's decisions on Wednesday, layers leaking into each other, no anchor to navigate by. I am testing the hypothesis that human + AI software projects need a frozen source of authority that no participant — including the author — can rewrite at will. This post is the opening of an open debate; sharper arguments against it would help me more than agreement.

One question I most want to be wrong about: Is "frozen authority" actually compatible with "evolutionary architecture"? I think yes — argue with me.

The pain I keep running into

I have been building software with AI agents long enough — daily, across multiple projects — to recognize a pattern that does not look like a bug.

On Monday, an agent and I agree that the auth layer should not know about billing. On Wednesday, a different session of the same agent cheerfully imports a billing helper into the auth module, because the prompt of the day made it convenient. The change passes review, because the human reviewer has also forgotten the Monday conversation. By the time anyone notices, the layering decision has been quietly inverted in three places.

Another version of the same story: I commit a fix with a comment explaining why a specific branch of code must stay. Two days later, a fresh agent session is sent in to clean up TODOs and reads the comment as a TODO. By morning the carefully-preserved branch is gone, and the previous session's reasoning died with the previous session.

This is not a model failure. It is not a human failure either. It is the predictable result of a team in which:

Some members are stateless. Foundation-model agents have well-documented memory and identity limits across sessions (see Bommasani et al. 2021, On the Opportunities and Risks of Foundation Models; Park et al. 2023, Generative Agents).
The "why" behind past decisions is in nobody's working memory. Humans forget. Agents don't even start with the context.
Many actors can each "decide". When everyone has authority to nudge a direction, nothing actually sticks.
Latest input dominates. Agents will amplify whatever the most recent prompt suggests, including the wrong directions.

I have come to think of these as governance gaps wearing technical disguises. No amount of better prompts, better tests, or better refactor discipline patches them. They are properties of the team shape, not of any single contributor.

What we're fighting against — "The Chaos"

The failure pattern above has a name in this framework: The Chaos. It is the umbrella for four specific drift modes that tend to compound:

Context rot — agents lose the why behind past decisions and re-invent or contradict prior choices across sessions (the Monday/Wednesday and TODO-misread stories above).
Architect rot — without a fixed reference, refactors land in incompatible directions. Humans and agents drift further apart from any earlier coherent design.
Scope creep — the project keeps absorbing new concerns. Agents amplify it because the latest prompt is always more vivid than the original mandate.
Accumulated technical debt — local conveniences that, once normal, are hard to undo. Humans and agents together can ship more of it, faster than a single human could.

This is roughly what the AI-dev community has lately started calling "vibe coding": shipping code by feel, with agents steering, no anchor strong enough to make Monday's promise survive into Wednesday's commit. Vibe coding is wonderful for prototypes. It is brutal for anything that has to outlive a single session.

The framework's job is not to forbid vibe coding. It is to give a project enough of a fixed backdrop that, when it graduates from prototype to thing-people-rely-on, decisions can be made against something stable instead of against the void.

Where existing methodologies leave a design slot empty

I want to be careful here, because this is the easiest place to overreach.

Waterfall, Agile, Scrum, SAFe, RUP — these work. I am not in a position to grade them. If an AI agent shows up to a stand-up the way a competent teammate does — persistent role, accountable for decisions, reads the working agreements, follows what was decided yesterday — Scrum runs the same as it always has. Sometimes better, frankly, because the agent does not forget the meeting on the drive home.

So I do not want to claim the methodologies "fail" or "stop covering" anything when agents join. That would be both arrogant and inaccurate.

What I do think is narrower: none of these methodologies were designed with AI agents as first-class participants in mind. They do not specify what an "agent role" looks like — its memory model, its onboarding procedure, its authority bounds, its drift profile, how its decisions are attributed across sessions. That is an unfilled design slot, not a coverage failure.

The Dead Light Framework is one attempt at filling that slot. It sits on top of whatever delivery framework you already run, not in place of it. If your Scrum is well-disciplined and your reviews are tight, you will catch some of the failure modes I described above without any of this. The framework is for the parts your existing process was never asked to handle in the first place.

The hypothesis (the part you should attack)

The thing I am testing is one sentence:

A software project for humans + AI agents needs a frozen source of authority that no participant — human or agent — can rewrite at will.

Codified once by a small council. Sealed before kickoff. Humans interpret it. Agents execute within it. Neither group obeys a person — both navigate by the same fixed light.

This is not a radical idea outside software. It is roughly how constitutional federalism works (the U.S. Constitution constrains every subsequent administration), how religious institutional canon works (the Nicene Creed is older than any living interpreter), how central-bank mandates work (a price-stability mandate outlasts any single governor), and how RFC-driven protocol governance works (TCP/IP does not get rewritten because a vendor finds it inconvenient).

What is novel — if anything — is applying this pattern at the level of an individual software project, with AI agents as first-class participants whose context windows guarantee the authority cannot live in their heads.

I call the sealed document the Astronomican. I call the sealing meeting the Ascension Council. I call the agent-type rulebooks Codices. The names are borrowed from Warhammer 40,000.

About the metaphor (important)

I want to be honest about this up front, because it is the obvious objection.

The Imperium of Mankind in Warhammer 40,000 is a cautionary tale. It is grimdark by design: a bureaucratic, paranoid, ossified empire that fails spectacularly across ten thousand years. Picking it as a governance metaphor without acknowledging that is internally contradictory.

So I do not use it as evidence. The framework's policy, written into its own rules, is:

40k vocabulary is naming and shared metaphor only. Every load-bearing argument must rest on a real-world system with an observable track record: constitutional federalism, military command-and-control doctrine, central-bank mandates, religious canon, established corporate practice (Toyota Production System, Amazon two-pizza teams), open-source governance, established software methodologies.

When the 40k name and the real-world precedent disagree, the real-world precedent governs. The Imperium provides memorable names. Toyota's Andon Cord, the U.S. military's C2/SIGINT loop, and Bezos-era Amazon's API mandate provide the actual design lessons — particularly on the hardest problem the Imperium itself failed at: centralized authority combined with distributed sensing.

If you find a place in the framework where I leaned on 40k as an argument rather than as a name, that is a finding. Please file it.

Glossary — 40k terms used above

For readers who do not know Warhammer 40,000 — one-liners on each term used in this post.

Astronomican — In W40k, the psychic beacon that guides the Imperium's space travel after its god-emperor has all but died. In this framework: the name for the sealed project document of purpose, immutable laws, and guiding principles.

Imperium of Mankind — The fictional galactic empire in W40k. Used here only as a memorable source of names; not as a governance role model (the empire fails spectacularly in canon — that is part of why I quote it carefully).

Codex / Codices — In W40k, the rulebook each Space Marine Chapter operates under. In this framework: the rulebook each AI agent type operates under (operational bounds, hard stops, output contract, notify triggers).

Adeptus Administratum — In W40k, the Imperial bureau of records, taxation, and administrative logistics — the empire's "chief of paperwork." In this framework: the first sealed Chapter — a PM / High-Lord aide role.

Ascension Council — Not from canon. The framework's name for the one-time small group of humans who seal the project's founding document before kickoff and then disband.

Chapter / Chapters — In W40k, a self-contained battle order of Space Marines, each with its own Codex. In this framework: an agent type, each with its own Codex.

The Chaos — In W40k, the warp-based corrupting forces the Imperium fights eternally. In this framework: the umbrella failure mode the framework tries to defend against — context rot, architect rot, scope creep, accumulated technical debt; roughly the kind of drift "vibe coding" produces when extended beyond prototyping.

What this is and is not

This is:

A composition layer that sits on top of Agile / Scrum / Kanban / whatever you already run. It does not replace delivery rhythm.
An attempt to give projects a constitution-like artifact and an explicit protocol for agent participation.
A working hypothesis with a documented audit trail (38 findings against my own claims, all remediated, still openly listed).

This is not:

Proven. I have one in-flight case study (a 358-KLOC project called LoreWeave). One case is not evidence. It is a smoke test.
A productivity tool. It will add overhead before it removes any.
A claim that you should run your project this way. It is a claim that the failure modes are real, that existing methodologies were simply not designed with agent participants in scope, and that some framing in this neighborhood is probably needed to fill that slot.

Where this stands today

Phase 0 (the calibration/audit phase for retrofit projects) — sealed.
Phase 1 (the Astronomican itself) — partial. Six known open questions, listed publicly.
Phase 2 (Codex per Chapter) — first Chapter sealed (a PM/High-Lord aide called the Adeptus Administratum). Others wait for real-project triggers.
Phase 3 (drift detection) and Phase 4 (re-consecration) — not started.
One case study (LoreWeave) — Phase 0 Pass 1 about to begin.
Internal audit (Independent Verification Pass) — five of seven phases complete. The audit is public, including the times the framework failed its own audit.

Everything is in the open. The framework is being built in a single repo with full debate history.

Repository: github.com/letuhao/dead-light-framework

What I want from readers

Not converts. Arguments.

Specifically, I want people to attack these:

Is "frozen authority" actually compatible with "evolutionary architecture"? I think yes, with a re-consecration ceremony. But that ceremony is unsealed and you might convince me it is impossible.
Does the 40k vocabulary do more harm than good? I find it useful as memorable scaffolding for a debate-driven team. But it may be repelling readers who would otherwise engage.
Where does an industry standard already do this job? If COCOMO II / CMMI v3.0 / ITIL 4 / DORA already cover one of the gaps I think I am filling, I want to know before adding another box.
What is the smallest experiment that would falsify the framework? I am genuinely unsure how to design this. A failed retrofit on one project is suggestive, not conclusive.
What did I import from the Imperium that I should not have? I keep finding things. Help me find more.

What's coming next

A short series of posts will work through:

The case study in detail (where it hurt, with numbers).
Why Agile/Scrum specifically do not cover this gap.
The mechanics of sealing an Astronomican.
The Codex pattern for AI agents.
How the framework audits itself (and the times it has failed).
The anti-patterns I knowingly imported from a fictional dying empire, and how I compensate.
Open questions where the framework could still be wrong.
A practical adoption sketch — without promising it works.

If any of the failure modes I described sound like the project you are in right now, I would especially like to hear from you. The framework is far more useful as a piñata than as a manifesto.

About the author

A working developer with roughly ten years of experience across a range of projects. Not an academic, not an industry authority on software methodology, not a methodologist of any kind. No chair, no certification body, no track record of published frameworks behind me.

The Dead Light Framework — the subject of this post and the series it opens — is a personal exploration: one practitioner's attempt at finding methods that hold up when AI agents become full-time teammates. I publish it openly because I would rather be told I am wrong by people who have stood in front of the same problems than be politely ignored.

If I sounded certain anywhere above, treat that as a slip in tone, not a claim of authority. The framework is at hypothesis stage. Everything is in scope to be argued with.

The Emperor is all but dead. The light remains.

Repository: github.com/letuhao/dead-light-framework

Independent practitioner exploration. No affiliation with Games Workshop. Repository MIT-licensed.