Architecture Update: Project Memory for Codex

The Short Idea

architecture-update is a global Codex skill that maintains project memory after meaningful work. Its purpose is not to produce documentation for its own sake. Its purpose is to make sure the next AI agent, the next Codex session, or another compatible coding agent can quickly understand:

• what the project is;
• where the important parts live;
• which modules own which responsibilities;
• how runtime, data, content, and deployment flows work;
• where to start for specific changes;
• which operations already have runbooks;
• which project-specific AI skills already exist;
• what is known and what still needs verification.

The central rule is: preserve durable facts, reject noise.

The skill should not turn AGENTS.md into a large reference manual. Instead, it separates project memory into layers:

This reduces repeated project discovery. If a future session needs to publish an article, deploy a release, or modify a data flow, the agent does not need to inspect the repository from zero. It reads the relevant memory layer.

Why architecture-update Exists

Long-running projects lose context between AI sessions. Even if an agent learns today where blog posts live, how imports work, or how production deployment is wired, a fresh session tomorrow often starts from almost nothing. That costs tokens, time, and correctness.

architecture-update solves this as a maintenance skill:

1. After meaningful work, it checks whether the session produced durable project knowledge.
2. It rejects one-off details, temporary hacks, unproven assumptions, and secrets.
3. It chooses the correct artifact for each surviving fact.
4. It updates the smallest useful file.
5. It connects ARCHITECTURE.md, runbooks, project skills, and AGENTS.md without duplication.

This is not a task-execution skill. It does not publish articles, deploy code, or refactor modules. It runs after work so project memory catches up with reality.

Why Everything Should Not Live in AGENTS.md

AGENTS.md is always-on project guidance for Codex. That means its contents influence the agent constantly. If the file contains the full architecture, all deployment procedures, all publishing steps, and all module-specific details, it becomes heavy and noisy.

The practical risks are:

• the agent loads irrelevant context for simple tasks;
• important rules are buried under details;
• the file becomes difficult to maintain;
• architecture facts get mixed with operational procedures;
• project-specific workflows start competing with global guidance.

For that reason, architecture-update keeps AGENTS.md compact. It should only contain a pointer:

The idea is simple: AGENTS.md tells the agent where to look, but does not try to become the whole project.

The Core Model: One Fact, One Layer

architecture-update behaves like a router. It does not merely ask, "Should this be documented?" It asks the more important question: which single layer should own this knowledge?

This prevents documentation from becoming a mixed pile. If the whole article publishing procedure is pasted into ARCHITECTURE.md, architecture becomes bloated. If architecture is placed inside a runbook, the runbook stops being operational. If everything is copied into AGENTS.md, the context becomes too heavy.

Default Outcome: No Changes

The most important behavior of the skill is conservatism.

architecture-update should default to no changes. If the completed work did not produce stable knowledge that future sessions are likely to need, the skill should leave files untouched.

It should not update memory for:

• minor wording changes;
• one-off bugs;
• temporary workarounds;
• local experiments;
• assumptions not proven by code or accepted decisions;
• private tokens, payloads, credentials, or secrets;
• details already obvious from existing code;
• cosmetic "cleanup" with no future value.

This matters. If the skill writes everything down, ARCHITECTURE.md becomes as noisy as a long chat history.

When to Update ARCHITECTURE.md

ARCHITECTURE.md is updated when the session changed or discovered a durable fact about how the project works.

Good reasons:

• a new major directory appears;
• a runtime entrypoint changes;
• build, start, or deploy behavior changes;
• a new content pipeline is introduced;
• blog, CMS, or uploads behavior changes;
• a new external integration is added;
• data model or storage changes;
• a durable invariant is discovered;
• an important gotcha is found;
• a new runbook is created;
• a new project skill is created.

Bad reasons:

• "we changed a button today";
• "we found and fixed a local bug";
• "deployment probably works like this";
• "let's record the session history";
• "just in case".

ARCHITECTURE.md should answer: how is the project built, and where do important changes start?

The Structure of ARCHITECTURE.md

The skill defines a standard file shape. The shape is not bureaucracy. It lets different AI agents orient themselves in any project quickly.

Purpose

Explains what the file is for.

It should say:

• this file is the factual project map;
• it is not README.md;
• it is not AGENTS.md;
• it is not a runbook;
• it is not a session log;
• unverified facts belong in Unknowns.

Example:

System Snapshot

A compact passport for the project.

The Evidence column is important. It forces the file to distinguish proven facts from guesses.

Repository Map

A map of directories and responsibilities.

This is one of the most useful sections for AI. It answers: "Where should I start if I need to change X?"

Runtime Entry Points

Process and application entrypoints.

This section is especially important for projects with multiple processes: frontend, backend, worker, cron, queue consumer, and admin panel.

Core Flows

Descriptions of the main flows.

Example:

A flow should be concrete. Not "data goes through the backend," but which data, from where, through which files, to what output, and how to verify it.

Content / Blog / CMS Pipeline

This section is especially important for content-heavy projects.

If the project publishes articles, this section should make clear:

• where to put .md files;
• what frontmatter is expected;
• where images live;
• how slugs are produced;
• which code renders pages;
• where the content appears in production;
• how to verify publishing.

Integrations And External Systems

All external systems.

Secrets must not be written here. Only env variable names and code locations belong here.

Data Model And Storage

Where data lives.

Deployment And Environments

How the project reaches runtime.

If production details are not proven, they must not be invented. Put them in Unknowns.

Change Map

The most practical section for future agents.

This reduces repeated repository searches.

Runbooks

An index of procedures.

ARCHITECTURE.md should not copy the entire runbook. It should link to it and explain when to read it.

Project Skills

An index of local AI skills.

This matters for fresh sessions: the agent can see that special project skills exist without loading all skill bodies up front.

Invariants And Gotchas

Rules that must not be broken.

Examples:

• Slugs must remain stable after publication.
• Uploaded images must live under public/blog.
• Migrations must be generated before schema-dependent code is merged.
• Admin routes must never be statically generated.

Invariants should be concrete and verifiable.

Verification Matrix

Commands and checks.

Documentation Relationships

Explains what each document owns.

Unknowns

A place for honest uncertainty.

This is better than guessing. A good ARCHITECTURE.md does not need to know everything. It needs to separate known facts from unknowns.

When to Create a Runbook

A runbook is a step-by-step guide for a repeatable operation.

architecture-update creates or updates a runbook when the operation:

• repeats;
• has multiple steps;
• has side effects;
• requires verification;
• can be risky if done incorrectly;
• is likely to be requested again by a human or AI.

Good candidates:

• docs/runbooks/publish-blog-post.md;
• docs/runbooks/deploy-production.md;
• docs/runbooks/rollback-release.md;
• docs/runbooks/import-products.md;
• docs/runbooks/rotate-api-key.md;
• docs/runbooks/restore-backup.md.

Bad candidates:

• "how to change this one text";
• "how we fixed this specific bug";
• "how we ran a command today";
• "how to do something already obvious from README".

A standard runbook should include:

• purpose;
• when to use;
• prerequisites;
• steps;
• verification;
• rollback or recovery when relevant;
• a link to the relevant ARCHITECTURE.md section.

When to Create a Project Skill

A project skill is a local skill inside the repository:

.agents/skills/<skill-name>/SKILL.md

It is useful when an AI agent will often perform a repository-specific operation and a simple runbook is not enough.

The threshold is high. A skill is created only if:

1. the workflow is specific to this repository;
2. future AI agents are likely to repeat it;
3. the trigger can be clearly described in description;
4. the procedure is not obvious from the code;
5. a runbook alone would not make execution reliable enough;
6. the skill is narrow and does not try to cover the whole project.

Good example:

.agents/skills/publish-blog-post/SKILL.md

If article publishing requires special frontmatter fields, image placement, slug rules, build verification, and production checks, this is a good project skill.

Bad example:

.agents/skills/change-button/SKILL.md

"Change a button" is too broad. But if the project has a strict repeatable workflow for adding action buttons through a shared primitive, registry, stories, and tests, then a more specific skill can be valid:

.agents/skills/add-design-system-action-button/SKILL.md

How architecture-update Connects to end-session

end-session is the session shutdown hub. It should not implement architecture decisions itself. Its job is to invoke the right skills in the right order.

After the change, the sequence is:

1. Update the active ExecPlan if one exists.
2. Rewrite Summarizations.md as a compact handoff.
3. Invoke project-diary-write.
4. Invoke architecture-update.
5. Only then decide whether repo-level guidance should be updated through create-agents-md / promote-lessons.

This order matters for two reasons.

First, architecture memory is updated after the session summary and diary have helped clarify what actually matters.

Second, AGENTS.md stays as the final guidance layer. It is not updated just because something happened. It changes only when there is a durable repo-level lesson or a compact pointer to new or updated architecture memory.

How architecture-update Connects to new-session

new-session is a bootstrapper. It starts a fresh session and reads the minimum useful context.

Important: new-session does not create ARCHITECTURE.md, runbooks, or project skills. That is not its job.

It may read ARCHITECTURE.md, but only when:

• the file exists;
• it is relevant to the request;
• it is referenced by AGENTS.md or Summarizations.md;
• the task involves cross-module, deployment, content/CMS, data model, or integration work.

It should also avoid loading every .agents/skills/*/SKILL.md body at startup. Project skills should remain trigger-based. The agent reads a specific skill only when the task matches that skill's description.

Why AGENTS.override.md and Instruction Chains Matter

Codex project guidance is not always just one ./AGENTS.md file.

The effective logic:

• Codex reads from project root to the current directory;
• each directory may provide an instruction file;
• AGENTS.override.md takes priority over AGENTS.md in the same directory;
• fallback names may exist if configured;
• closer instructions can refine broader ones.

Therefore, architecture-update must not blindly create or edit any AGENTS.md. It should:

• prefer the root instruction file for broad architecture pointers;
• avoid creating AGENTS.override.md for normal updates;
• respect an existing override;
• avoid fallback files unless the project clearly uses them;
• update a nested instruction file only when the architecture fact belongs to that subtree.

This prevents rules from being written into the wrong effective location.

Evidence Standard: Proof Beats Guessing

architecture-update should prefer facts from:

• changed files;
• git diff;
• existing docs;
• build, deploy, and CI configs;
• package manifests;
• routes;
• entrypoints;
• schema and migration files;
• tests;
• explicit user decisions in the current session.

If a fact is not proven, it should not be written as truth in the main sections.

The correct route is:

This keeps the file honest. For AI agents, this is critical: if documentation confidently states false facts, the agent will make faster and more confident mistakes.

Anti-Patterns

Anti-Pattern 1: ARCHITECTURE.md as a Session Log

Bad:

Good:

Anti-Pattern 2: A Runbook Inside Architecture

Bad:

Good:

Anti-Pattern 3: A Project Skill for a Vague Task

Bad:

.agents/skills/fix-frontend/SKILL.md

Good:

.agents/skills/add-design-system-action-button/SKILL.md

Anti-Pattern 4: Invented Production Facts

Bad:

If this is not proven, write:

Practical Example: A Blog

Suppose a project has a blog. During work, the agent learns:

• articles live in content/blog;
• images live in public/blog;
• markdown is parsed by src/lib/blog.ts;
• pages are generated as /blog/:slug;
• publishing requires build verification.

What does architecture-update do?

In ARCHITECTURE.md

It adds the map:

In docs/runbooks/publish-blog-post.md

If publishing is repeatable, it creates a procedure:

In .agents/skills/publish-blog-post/SKILL.md

If agents will often publish posts themselves, and the project rules are specific enough, it creates a project skill:

In AGENTS.md

It adds only a compact pointer if one does not already exist:

Practical Example: Buttons

If the project changed one button, architecture-update does nothing.

If the session discovered a stable UI workflow:

• all buttons must use src/components/ui/Button.tsx;
• actions are registered in src/features/actions/registry.ts;
• layout rows use ActionRow;
• stories and tests must be updated;
• the pattern repeats often,

then the skill can add this to ARCHITECTURE.md:

And, if AI agents will often do this directly:

.agents/skills/add-design-system-action-button/SKILL.md

But the skill is not created merely because "there are many buttons." It is created only when there is a repeatable, project-specific procedure.

Why This Saves Tokens Over Time

Without architecture-update, every new session pays for discovery again:

• searching directories;
• reading package and config files;
• understanding routing;
• reading deployment scripts;
• studying the content pipeline;
• reconstructing decisions from chat history.

With architecture-update, the project gradually gains an index:

• ARCHITECTURE.md says where to look;
• a runbook says how to perform an operation;
• a project skill tells AI how to repeat a project workflow reliably;
• AGENTS.md points agents to the right layers;
• new-session reads only what is relevant;
• end-session keeps memory current.

This does not remove the need to read code. It reduces wasteful rediscovery.

The Skill's Final Logic

architecture-update is a strict router:

1. Find the real project root.
2. Check existing memory artifacts.
3. Inspect the completed work.
4. Extract durable knowledge candidates.
5. Reject noise.
6. Route each surviving fact to exactly one layer.
7. Create or update the smallest useful file.
8. Verify paths and references.
9. Put unproven facts in Unknowns.
10. Report briefly.

The goal is not "more documentation." The goal is preserving only the project memory that reduces future uncertainty.

Final Formula

architecture-update is not about beautiful markdown files. It is about stopping AI sessions from starting with archaeology every time.

Good architecture memory is:

• compact in always-on context;
• detailed in the right file;
• evidence-based;
• separated into maps, procedures, and automation;
• honest about unknowns;
• updated after meaningful work;
• unchanged by default.

That is the role of the sequence:

end-session -> architecture-update -> ARCHITECTURE.md / runbooks / project skills -> new-session

It turns one-time discoveries into durable project navigation.