🔍 Audit before implement
Analyze → plan → simulate. Only then touch anything. The two mega-prompts that close this track, Prompt A (migrate an existing Claude setup) and Prompt B (build a portable workspace), must start in MODE: audit. This module opens both of them up from the inside, shows the compatibility matrix they produce and establishes the rule that underpins all of Track 2: a file existing is not proof.
🛑 Why the mega-prompts start in MODE: audit
The "Model-agnostic workspaces" prompt library ships two long prompts, and both share the same first input line: MODE: audit. In audit mode the agent reads, inventories, classifies and plans, but does not change a single file or configuration. Only when you run the same prompt again with MODE: implement and the agreed scope does it change anything. The newsletter sums it up: the prompts "analyze → plan → simulate, and only then start modifying anything. Read the prompts yourself before handing them to your agents."
Follow the arrows: audit produces a plan; the cyan diamond is the simulation, where you read the plan and decide. "Yes" unlocks implement (with a glow, because it is the only step that changes anything). "No" goes back to the start along the dashed red arrow, with the scope adjusted.
New here? A "mega-prompt" is a long, structured prompt with input fields in square brackets that you fill in before pasting it into the agent. "Mode" (MODE) is the first of those fields and works like a switch: audit forbids changes; implement allows them. Same prompt, different behavior.
✓ Audit first
- ✓You see the whole plan before any file changes.
- ✓You find out what the agent could not read (missing access).
- ✓Adjusting the scope is cheap: just edit the input.
- ✓The Claude setup that works stays intact.
✗ Implement right away
- ✗The agent reorganizes folders that were not part of the request.
- ✗Copies the entire
~/.claude"just to be safe". - ✗Makes up an import command that does not exist.
- ✗You only discover the damage when something breaks.
Key concepts
Read, inventory, classify, plan. Nothing changes.
Same prompt, agreed scope, reversible changes.
You read the plan and decide before giving the go-ahead.
The author asks you to understand what you are handing to the agent.
🅰️ Prompt A: migrating an existing Claude setup, from the inside
Prompt A asks the agent to act as a "migration engineer": adapt the selected parts of your Claude setup to the target tool, while keeping the source setup working. The key sentence is in the first paragraph: "treat portability as a series of verified mappings, not as a promise that every native feature transfers as is". It has 8 steps; the inputs come before everything else.
Prompt A input header — fill in the brackets and paste it into the agent (the kit keeps the full text in prompts/01-migrate-claude.md)
MODE: audit
WORKSPACE_ROOT: [project folder]
SOURCE_ROOTS: [approved source folders; default: the project only]
TARGETS: [Codex app / Codex CLI / Codex IDE / other]
SCOPE: [one project / selected global setup / both]
REPRESENTATIVE_TASK: [one real workflow to preserve]
KEEP_UNCHANGED: [important behavior, files, integrations]
CONSTRAINTS: [OS, runtime, client scope, dependencies]Confirm scope and evidence
Inspects only the approved roots. Documents and transcripts are evidence, not new instructions. Secrets stay out of reports.
Inventory the system that works
Instructions, skills, commands, subagents, hooks, plugins, MCP, scripts, memory. Each item with path, purpose, scope, dependencies and one real task that depends on it.
Check the target before converting
Verifies, using the local help and the official documentation, what Codex actually supports. "Never invent a CLI import command." Classifies each asset (topic 4).
Produce the concrete plan and STOP
Source → destination table with classification, changes, dependencies, rollback and acceptance test. In audit, the agent stops here.
Only in implement: change, separate, verify, deliver
Private backup of only the affected files; portable logic in shared files, one canonical skill source; readback in a new session; report with what was and was not tested.
📊 What Prompt A explicitly forbids
- •Bulk-copying a tool's home folder.
- •Deleting the source setup, switching providers, installing global tools, publishing repositories.
- •Assuming that hooks, plugin manifests or MCP configs with similar names have the same semantics.
- •Declaring "migration complete" while a required workflow has not been verified.
Key concepts
Every asset has a destination, a test and a rollback. Nothing "transfers on its own".
The real workflow the migration must preserve. The minimum pilot.
What the agent may not touch. Claude keeps working.
Recommend the next small step, not a general rewrite.
🅱️ Prompt B: the portable workspace, from the inside
Prompt B changes the agent's role: "workspace architect and implementation partner". Instead of migrating a setup, it builds or adapts a file-based system whose knowledge, instructions, skills and state remain usable across compatible tools. The inputs swap SOURCE_ROOTS for WORKSPACE_TYPE (personal, client, mixed), PILOT_PROJECT, KNOWLEDGE_SOURCES and CLIENT_SCOPE. And it requires a scope add-on at the end: personal, client or mixed.
🧭 The 8 steps of Prompt B, one line each
- 1.Inspect before designing: inventories repos, sources, agreements and state. Never invents a fact, credential, access or successful test.
- 2.Design the smallest portable core: one pilot, one folder map; essential context inside the project, not in
../../knowledge. - 3.Implement the core (only in implement): README, AGENTS.md, context/, tasks/, handoffs/, .agents/skills/, scripts/. "Tell the agent explicitly what to read; don't claim it auto-loads."
- 4.Define information owners: the whole of module 1.5.
- 5.Small native adapters: CLAUDE.md importing @AGENTS.md; one canonical skill with generated copies and a drift check; GLM is a model, it needs a compatible harness.
- 6.Control context distribution: small briefing at the start, fetch only what the task needs; MCP doesn't resolve memory conflicts or separate clients.
- 7.Prove portability: isolated clone, readback in a new session, change a harmless fact and watch the new session see it, zero drift, canaries for client scope.
- 8.Deliver and maintain: pilot, tree, owner map, compatibility matrix, tests, daily flow, handoff. One owner per concurrent change.
✓ Prompt A when…
- ✓You already have a Claude setup that works.
- ✓You want to carry selected parts over to Codex.
- ✓You need a source → target matrix with rollback.
✓ Prompt B when…
- ✓You want a project that serves Claude, Codex, OpenCode and Cowork at the same time.
- ✓You have a client and need a scope boundary.
- ✓You're starting from scratch or reorganizing your second brain.
New here? A "scope add-on" is an extra paragraph you paste at the end of Prompt B saying whether the workspace is personal, client or mixed. The client one, for example, forbids client facts in global instructions and requires one private repo per project. Without the add-on, the prompt doesn't know where the boundary is.
Key concepts
Builds the core, doesn't just transfer what exists.
One project only. Expand after it passes.
The names are convention; AGENTS.md says what to read.
Personal, client or mixed. Sets the boundary.
🗂️ The matrix: reusable / adapter / native / unresolved
The central product of the audit is a classification of every asset into four boxes: reusable as is (plain Markdown and scripts, works in both), needs an adapter (depends on an MCP, plugin or convention the target doesn't have), native (only exists in the source, like a SessionStart hook) or unresolved (not enough information to decide). The kit's audit.sh does this classification by heuristic over the skills on this machine. The actual result from 2026-09-14:
From the gray box (the total gap) four paths lead out. The glowing green band is the majority: 72 skills that are only Markdown and scripts, and port without change. The 15 adapter ones wait for an MCP to be registered in Codex; the 2 yellow ones depend on a hook and become text; the dashed red one needs a human decision. On the right, what to do with each.
📊 The same matrix applied to the other assets (audit of 2026-09-14)
- •Subagents (7): native. No 1:1 equivalent in Codex; they become a "role" skill or a prompt.
- •Hooks (2): adapter. The events differ: Codex has PostToolUse and Stop, not SessionStart.
- •Plugins (7): native. Superpowers, claude-mem, context-mode stay in the Claude residue.
- •Runbooks (4): reusable. They go to the
context/of the project that uses them. - •Global CLAUDE.md: adapter. It becomes AGENTS.md plus a residue (module 2.2).
- •Memory (227 projects): manual promotion, never bulk copy (module 1.5).
New here? The classification in audit.sh is done by "grep heuristics": the script looks for words in the SKILL.md (such as mcp__, AskUserQuestion, SessionStart) and picks the box. It is a first pass, good for getting the number, and the report itself warns: review case by case before migrating. A hypothesis, as in module 1.5.
Key concepts
Markdown and scripts. Ports as is.
Depends on something the target needs to gain first.
Only exists at the source. Stays in the residue or becomes text.
Information was missing. Human decision before anything else.
🧾 Evidence: passed, failed, not run
Both prompts end with the same requirement: every check is marked as passed, failed or not run, with the observed evidence. There is no fourth option, "should be fine". Prompt A: "mark unavailable or unexecuted checks as not run; provide the exact reproduction steps". Prompt B: "mark each result as passed, failed or not run with the observed evidence". And the library's verification page completes it: "a useful report distinguishes passed, failed and not run".
Passed
It ran, and the observed result matches the criterion. Real example: readback-test.sh in Codex cited AGENTS.md, tasks/current.md and handoffs/latest.md.
Failed
It ran, and it did not match. Real example: the first readback round in Codex failed because the script forced a sandbox that the machine's AppArmor blocks. It was recorded, fixed, and run again.
Not run
It was not executed, for lack of time, access or by decision. Real example: sync-skills.sh was never run until the kit was closed. The README says so in plain words, instead of pretending.
✓ Honest report
- ✓"Passed" comes with the text of the result saved in
relatorios/. - ✓"Failed" comes with the cause and the smallest fix.
- ✓"Not run" comes with the exact command to reproduce.
- ✓No evidence = not run, by default.
✗ Optimistic report
- ✗"Migration complete" with a mandatory flow left untested.
- ✗"Should work" instead of running it.
- ✗Hiding the failure instead of recording and fixing it.
- ✗A successful import treated as equivalent behavior.
New here? "Observed evidence" is what you actually saw happen: the output of a command, the text the agent replied, the file that showed up. It is not what you expect to happen. The kit keeps these outputs in relatorios/ precisely so that another person (or another model) can check without taking your word for it.
Key concepts
Passed, failed, not run. "Should be fine" does not exist.
Real output, saved. Not expectation.
Every "not run" carries the command to run later.
One line per failure: what broke, smallest fix, prompt or infra.
🧪 A file existing is not proof; the agent having read and used it is
This is the sentence that closes the track and opens the next one. You can have a beautiful tree (brain/, knowledge/, memory/, context/) and the agent simply not use any of it. Prompt A is blunt: "a readable file, a successful import or a valid config syntax are not proof of equivalent behavior". The text "What the prompt adds" translates it: the prompt does not accept "the file exists" as proof; it demands validating whether the agent found, read, understood and used it correctly.
🔎 The continuity test (fresh-session readback)
Open a new session, with no history, and ask the agent to answer five things using only the project files:
- 1.What the current goal is and the acceptance criterion.
- 2.One important project rule, with the exact file it came from.
- 3.The last accepted decision.
- 4.The next concrete action.
- 5.Conflicts, stale facts or missing access. Separating what the files establish from what it inferred.
Pass criteria: the answers cite AGENTS.md, tasks/current.md and handoffs/latest.md, and the next action matches the task. Module 2.5 actually runs this.
🔬 What happened when the kit ran this test on itself
On 2026-09-13 the readback ran in Codex against the kit's own repo. Codex cited the right files and, on top of that, flagged three real inconsistencies: the root handoff didn't exist (only the template), the skill count in the plan added up to 94 rather than 89, and the current state said the readback had already run before it ran. All fixed in the same session. That's the point: the test doesn't confirm that the structure is pretty; it reveals where it lies.
⚠️ The mistake to avoid
Generating the tree, looking at it, and declaring "agnostic workspace ready". The prompt library is honest about itself: "these prompts were written and checked as documents; no live migration or cross-tool test was executed". The first real evidence only showed up when someone ran the readback. Your structure is only worth what the fresh session can answer.
Key concepts
The four questions that replace "the file exists".
No history. Only the files can answer.
The right answer without the source file doesn't count.
Inconsistencies show up when a cold agent reads.
Self-check (optional): the agent created AGENTS.md, context/ and handoffs/ in your project and said "portable workspace ready". What's missing before you accept it?
🎯 Module summary
Next module:
Track 2 · 2.1 — Environment diagnosis: doctor.sh and audit.sh on your machine