📁 Anatomy of a portable workspace
AGENTS.md, context/, tasks/, handoffs/. The previous module said the durable layer is plain Markdown inside the project. This module shows exactly which files, what goes in each one, who reads them and in what order. It is the tree the kit installs with init-core.sh and that the mega-prompts tell you to build. Names are a convention: none of this gets loaded on its own, and you will see how to solve that.
📄 README.md vs AGENTS.md: human vs agent
A portable workspace starts with two files at the root, and it is easy to mix them up. README.md is for people: human onboarding, how to run, how to test, what is in each folder. AGENTS.md is for agents: concise instructions, stable rules and, at the top, an explicit reading order that tells the agent which files to open before acting.
This is the full tree the kit proposes. You will recognize each folder throughout this module:
meu-projeto/
├── README.md # human onboarding
├── AGENTS.md # instructions + reading order (Codex, Gemini, GLM)
├── CLAUDE.md # "@AGENTS.md" + Claude-specific residue
├── context/
│ ├── overview.md # what it is, verified facts, preferences, hypotheses
│ ├── current-state.md # what works and what is pending
│ ├── sources.md # where each piece of information came from + refresh rule
│ └── decisions/ # one accepted decision per file
├── tasks/
│ └── current.md # goal, owner, definition of done, next action
├── handoffs/
│ └── latest.md # continuation for the next session
├── .agents/
│ └── skills/ # the project's canonical skills
└── scripts/
└── check.sh # minimal verificationThe big box is the project. On the first row, the entry files: README for people, AGENTS.md for agents, and CLAUDE.md dashed because only AGENTS.md matters. On the second row, the five portable folders the rest of the module explains.
New here? "README" is the file every repository shows on its home page; it is written for a person arriving with no context. "AGENTS.md" is a convention adopted by Codex, Gemini and others: an instructions file the agent reads when it starts in the project. The two may say similar things, but the README explains and the AGENTS.md commands.
✓ Goes in AGENTS.md
- ✓Reading order: "read 1) this file, 2) context/overview.md, 3) current-state, 4) tasks/current.md, 5) handoffs/latest.md".
- ✓Stable rules: commit author, versioning, where the keys live, what never to do.
- ✓Owners table: who updates each file and when.
✗ Does not go in AGENTS.md
- ✗Installation tutorial and long prose: that is README.
- ✗Current state and the task in progress: they change every session and have their own files.
- ✗Anything specific to one runtime (plugin, hook, interactive menu): that is CLAUDE.md residue.
Key concepts
Human onboarding. Explains.
Concise instructions for agents. Commands.
Explicit list at the top of AGENTS.md.
First line of CLAUDE.md: imports the portable one.
🧭 context/overview.md and current-state.md
The context/ folder is the project's durable knowledge. The first two files answer different questions. overview.md answers "what is this?": what the project does, for whom, the verified facts (each with source and date), the owner's preferences and the hypotheses not yet confirmed. It changes slowly. current-state.md answers "how is it right now?": what works, what is broken or pending, what has changed since the overview. It changes every session.
New here? "Overview" is the stable big picture. "Current state" is the snapshot of the moment. Keeping them apart avoids the classic mistake of a single file that mixes "the project is X" with "today the build is broken": the agent cannot tell what still holds. A verified fact is one with a source and a date next to it; without those, it is a hypothesis.
overview.md
# Overview
- ID: overview | Scope: project
- Source: | Observation date:
- Status: draft | Review by:
## What it is
## For whom
## Verified facts (with source and date)
## Preferences (from the project owner)
## Hypotheses (not verified)Header with ID, scope, source, date and status. It is what lets you tell whether the file still holds.
current-state.md
# Current state — YYYY-MM-DD
- Last session:
- What works:
- What is broken / pending:
- Facts that changed since the overview:Short and dated. If a fact here stabilizes, it moves up to the overview; if a fact in the overview changes, the current-state flags it.
📊 Real example: the kit's own overview (2026-09-13)
- •Verified fact: "Codex CLI 0.154.0 has no import command; the 'one-click' import belongs to the desktop app."
- •Verified fact: "Claude Code 2.1.270 with 116 skills; Codex with 27."
- •Hypothesis: "The heuristic classification of 71 skills as reusable is correct for most of them; it needs sampling."
- •Notice: the fact has a version and a date; the hypothesis says what is missing for it to become a fact.
Key concepts
"What is this?" Stable, with dated facts.
"How is it right now?" Changes every session.
Has a source and a date. Without those it is a hypothesis.
ID, scope, source, date, status, review by.
🔗 context/sources.md and context/decisions/
Two files almost nobody creates, and that solve the most common context problem: "which of the several versions of this information is the right one?" sources.md is a table of where each thing came from: path or URL, type (local file, dated export or live connection), date, scope and the refresh rule. The decisions/ folder holds one accepted decision per file, with context, the decision itself and the consequences.
The kit's sources.md, as it stands today
| ID | Source | Type | Date | Scope | Refresh |
|---|---|---|---|---|---|
| S1 | docs/migrar-claude-para-codex...md | local export | 2026-09-13 | philosophy | manual |
| S3 | docs/mega-prompts.pdf | local export | 2026-09-13 | A/B prompts | manual |
| S4 | relatorios/auditoria-*.md | script-generated | every run | local machine | run script |
| S5 | wifi/DIAGNOSTICO-CLAUDE-CODEX...md | diagnostic | 2026-09-14 | local machine | run doctor/audit |
When two pieces of information conflict, you look at the table: which one has the more reliable source and the more recent refresh rule. Not which one has the bigger timestamp.
New here? "Sources" is the provenance record: without it, a fact is just a loose sentence. "Decisions" are short, dated records of what was decided and why; the pattern comes from ADRs, "architecture decision records", used in engineering. A "dated export" is a copy of an external document taken on a given date; a "live connection" is when the agent fetches from the original system every time.
✓ A good decision in decisions/
- ✓Dated name:
2026-09-13-docs-fora-do-git.md. - ✓Explicit status: proposed, accepted or revoked.
- ✓Context, decision and consequences in three short blocks.
- ✓Never deleted: if it changes, a new decision revokes it.
✗ What doesn't work
- ✗A decision buried in the middle of a 300-turn chat.
- ✗Editing the old decision in place: you lose the history of why it changed.
- ✗No status: the agent doesn't know if it still applies or is just an idea.
- ✗A source without a date: impossible to know whether it has gone stale.
Key concepts
Provenance table with a refresh rule.
One dated decision per file, with status.
Conflicts are resolved by source, not by the later date.
The decision history is part of the context.
🎯 tasks/current.md: owner and definition of done
The original text notes that many people talk about memory and handoff, but forget the current work. tasks/current.md is exactly that: what we are doing now, who is responsible and what the definition of done is. It makes the agent understand not just the history, but what needs to happen in this session. And it is the file that readback question 1 ("what is the goal and the acceptance criterion?") goes looking for.
This is the kit's real tasks/current.md, on the day this course was written. Notice that each line answers a question a new agent would ask:
# Current task
- Goal: validate the pilot — the `session-handoff` skill ported to Codex
via polyskill and readback passing in both runtimes.
- Owner: Nei (decides pilot and skills); the agent executes.
- Definition of done: `scripts/readback-test.sh . both` produces answers that
cite AGENTS.md/tasks/handoffs in both; `scripts/sync-skills.sh drift`
with no DRIFT.
- Next concrete action: Phase 0 of the plan in
`~/projetos/wifi/DIAGNOSTICO-CLAUDE-CODEX-2026-09-14.md` —
`scripts/adapt-instructions.sh ~/.claude`, review, write
`~/.codex/AGENTS.md`, readback in `~/projetos/wifi`.
- Blockers: none (publication already done; docs/ stays out of git).New here? "Definition of done" (or acceptance criterion) is the sentence that lets you say, without argument, whether the task is finished. A good criterion is verifiable: "command X produces output Y". A bad criterion is opinion: "it's fine". "Owner" is who decides; the agent executes, but doesn't change the goal on its own. "Next concrete action" is the first command or edit, not an intention.
The human defines
Goal, owner and definition of done are written by whoever runs the project. The agent can propose, not decide.
The agent marks
During the session, the agent updates "next action" and "blockers" as it progresses, and records what it ran.
Done only with evidence
The task closes when the criterion has been run and the result is in the handoff. "It should work" closes nothing.
Key concepts
The work of right now, not the history.
Who decides the goal and the criterion.
Verifiable by command, not by opinion.
The first command, with its path.
🔁 handoffs/latest.md: the continuation
The handoff is the file that closes one session and opens the next. The original text describes the flow: session → /handoff → Markdown → /prime → new session. The handoff command analyzes the session looking for decisions made, unfinished tasks, next steps and file paths, and saves it all in Markdown. A file called latest.md always points to the most recent one. /prime reads that context back in. That way you don't go hunting for information in JSONL files, and the summary travels to any provider.
Read from left to right: the new session opens AGENTS.md, which tells it to read the next four in order, and reaches the highlighted handoff, from where it continues. The dashed arrow going back is the cycle: on closing, a new handoff is written.
📝 The seven sections of the kit's handoff template
what this session covered
points to tasks/current.md
what is confirmed, with commit
paths, not vague descriptions
passed / failed / not run
what only the owner decides
the command the next session runs first
💡 Practical tip
A good handoff preserves the unresolved failures and doesn't claim that uncommitted changes "are available" somewhere else. When Claude did the readback of the kit itself, it pointed out exactly that: the handoff said "initial commit" while six files were edited without a commit. The handoff was fixed, not the yardstick.
Key concepts
Always the most recent; the next session starts here.
Write on closing, read on opening.
Claude writes, Codex resumes, and vice versa.
The structured summary replaces rereading the raw log.
🧩 .agents/skills/, scripts/ and the convention rule
The last two folders hold capability, not knowledge. .agents/skills/ is where the project's canonical skills live (Codex already looks there; Claude gets a generated copy). scripts/ holds reproducible commands, like the check.sh that checks whether the required files exist and aren't empty. And here comes the most important warning of the module, straight from Prompt B: these names are conventions; tell each agent explicitly what to read. Don't assume they load on their own.
New here? "Auto-load" (automatic loading) is when the runtime reads a file without anyone asking. Claude Code does this with CLAUDE.md; Codex, with AGENTS.md. That's it. A folder called context/ looks nice, but no agent opens it on its own. A "convention" is a name agreed between humans; it becomes behavior only when AGENTS.md tells the agent to read it.
✓ Loads on its own
- ✓
CLAUDE.mdin Claude Code (global and project-level). - ✓
AGENTS.mdin Codex (and in Gemini). - ✓Skills in
~/.claude/skills,~/.codex/skills,.agents/skills/: discovered by name.
✗ Doesn't load on its own
- ✗
context/,tasks/,handoffs/: only if AGENTS.md tells the agent to read them. - ✗
README.md: the agent may not even open it. - ✗Any nice-looking folder like
brain/,knowledge/,memory/without an explicit instruction.
⚠️ The mistake to avoid
Building the whole tree, feeling proud of the structure and never testing whether the agent uses it. Prompt B is explicit: a generated directory is not proof that an agent reads it. The proof is the readback (module 2.5): new session, five questions, and the answers citing AGENTS.md, tasks/current.md and handoffs/latest.md.
🔬 How the kit solves this
- •The template's
AGENTS.mdopens with the sentence: "Reading order for any agent: 1) this file, 2) context/overview.md, 3) context/current-state.md, 4) tasks/current.md, 5) handoffs/latest.md. These names are a convention of this repo, they are not loaded automatically: read them." - •The
scripts/check.shchecks that the seven required files exist and are not empty:[ok]or[MISSING]. - •The
readback-test.shproves that the agent read it, not just that the file exists.
Key concepts
The project's canonical skills; Codex already looks here.
Minimal check: files exist and are not empty.
An agreed name; it only becomes behavior through instruction.
Only CLAUDE.md and AGENTS.md. The rest, AGENTS.md tells the agent to read.
Self-check (optional): you created context/overview.md and tasks/current.md in a project. Will Codex read them on startup?
🎯 Module summary
Next module:
1.5 — Owners of information: fact, preference, hypothesis, decision