Two harnesses, one repo: the collision is at the root docs and in our unguarded delete — not in the tool directories

[BaseInfinity]

Maintainer, 2026-08-08: "we should make sure that we never nuke the skills or overwrite files
— like Codex fucks up a file for Claude and vice versa, cuz maybe both write to the same
AGENTS.md file. CLAUDE.md should be isolated and there should be a Codex one too right?"

I scanned both installers before writing this. The premise is right and the specific worry is
mostly already handled — but there are two real problems, and neither is the one named.

What is already safe (do not spend work here)

The two harnesses write to disjoint namespaces:

	writes
claude-sdlc-harness (cli/init.js)	.claude/settings.json, .claude/hooks/*.sh, .claude/skills/{sdlc,setup,update,feedback}/, CLAUDE_CODE_SDLC_WIZARD.md
codex-sdlc-wizard (install.sh)	.codex/hooks.json, .codex/hooks/*, $CODEX_HOME/skills/, AGENTS.md, START-SDLC.md

Neither installer touches the other's directory. Skills in particular are not at risk from the
other tool: ours go to repo-local .claude/skills/, theirs to $CODEX_HOME/skills/ (user
level, not repo level). Both also protect installed files by content hash — ours marks a
changed file PRESERVE unless --force; theirs backs a skill up to
backups/skills/<name>.bak.<epoch> before replacing it.

And AGENTS.md specifically already has the most carefully designed policy of anything either
side does. install.sh distinguishes generated this run / matches the wizard baseline /
wizard-managed / user-owned or customized, and preserves the last. We have no equivalent
for any shared file.

Problem 1 — the repo root is a shared namespace and nobody declared it one

Both harnesses generate documents into the consumer's repo root, under the same filenames,
from different doctrines. codex-sdlc-wizard ships templates/ for AGENTS.md,
SDLC.md, TESTING.md, ARCHITECTURE.md, GOALS.md. Our setup skill generates SDLC.md,
TESTING.md, ARCHITECTURE.md too.

So the collision is not .claude/ vs .codex/. It is TESTING.md — a file both sides believe
they author, whose content encodes each tool's testing doctrine, in a repo where a user may
reasonably run both. Second install wins, or the user is left hand-merging two philosophies.

There is a read-side version of this that is worse, and it is the one worth researching
first: recent Claude Code reads AGENTS.md. If that is true here, a Codex-authored AGENTS.md
is loaded into Claude's context alongside CLAUDE.md — two SDLC doctrines active at once,
free to contradict each other on model/effort guidance, the review protocol, or the merge
policy, with no precedence rule anywhere. Nothing writes over anything; the damage is entirely
in what the agent believes. Verify this against the installed Claude Code version before
designing anything — the whole shape of the fix depends on the answer.

Problem 2 — our obsolete-path delete has no customization guard, and theirs does

cli/init.js:

const OBSOLETE_PATHS = [ '.claude/skills/testing' ];   // consolidated into /sdlc in v1.17.0
fs.rmSync(fullPath, { recursive: true, force: true });

Recursive, forced, unconditional. No hash check, no backup, no PRESERVE branch — the
protection every installed file gets does not apply to a retired one. A user who wrote
their own .claude/skills/testing/SKILL.md loses it silently on upgrade. Today the list has
one entry, so blast radius is small; the defect is that the mechanism has no guard at all, and
lists grow.

codex-sdlc-wizard/lib/remove-retired-files.cjs solves the same problem properly: hash the
file against a managed-files manifest, and emit Preserved customized retired file or
Preserved retired file still referenced by a retained hook instead of deleting. It also
refuses to proceed when a retained hook still references a retired path.

Their design is better than ours and this is a direct port, not a redesign. Same lesson as
the opencode sweep: when the sibling is a literal port, diffing against it beats a fresh audit.

Research split

• This repo (done, above): what each installer writes and deletes, where the namespaces
  actually overlap, and which retirement logic is safer.
• codex-sdlc-wizard (maintainer to run there): the same audit from the other side —
  what it assumes about a repo that already has CLAUDE.md/.claude/, whether its
  AGENTS.md policy anticipates a second harness, and whether $CODEX_HOME/skills being
  user-level rather than repo-level is deliberate.
• Then consolidate into one shared-surface contract.

Open questions for that contract

1. Does Claude Code read AGENTS.md at the installed version? If yes, is a shared AGENTS.md
   the feature (one cross-tool standard, as CLAUDE_CODE_SDLC_WIZARD.md already argues) or
   the bug (two doctrines, no precedence)?
2. Should root docs be namespaced per tool, or shared with per-tool sections and one owner per
   section? Namespacing duplicates facts, which is exactly what this milestone exists to stop.
3. Should either installer detect the other harness and say so, rather than each behaving
   as if it is alone in the repo? Cheapest real improvement, and it needs no shared format.
4. Is TESTING.md divergence actually harmful, or do both harnesses say close enough to the
   same thing that one file with two contributors is fine?

Not in scope

Merging the two harnesses, or a shared format spec. Refs #429 (portable sdlc-mcp vs per-host
skills), #433 (Codex CLI parity), #499 (AGENTS.md audit — overlaps, resolve together).

[BaseInfinity]

Correction — Claude Code does NOT read AGENTS.md. The issue body above is wrong on this point.

I flagged the read-side claim as needing verification before anyone designed against it. I
verified it, and it does not hold. Leaving the original text in place with this correction on
top, because the wrong version is what a reader would otherwise act on.

Official docs, verbatim: "Claude Code reads CLAUDE.md, not AGENTS.md."
(https://code.claude.com/docs/en/memory, § AGENTS.md)

Confirmed against the installed binary (v2.1.221). AGENTS.md appears 7 times, and none of
them is a memory-discovery path:

• the /import importer (v2.1.213+), which copies a Codex AGENTS.md into CLAUDE.md
  as a one-time operation — note it maps AGENTS.override.md → CLAUDE.local.md, and skips
  when the target already exists
• /init's codebase scan, which reads AGENTS.md (plus .cursorrules,
  .github/copilot-instructions.md, .clinerules, …) to generate CLAUDE.md
• Codex-adapter notes about project_doc_fallback_filenames having no Claude Code equivalent

So there is no silent two-doctrine merge at session start. Problem 1's read-side half is
retracted. The write-side half stands: both harnesses still generate TESTING.md,
SDLC.md, ARCHITECTURE.md into the consumer's repo root under the same filenames from
different doctrines, and second-install-wins is a real outcome.

Problem 2 is unaffected and is now the only mechanical defect here — OBSOLETE_PATHS in
cli/init.js does fs.rmSync(recursive, force) with no hash check and no backup, while
codex-sdlc-wizard/lib/remove-retired-files.cjs hashes against a manifest and preserves a
customized file. That port is the concrete work item.

The sharing question has a documented answer, and it is the good one

Anything genuinely shared can and should stay shared — via an import, not duplication:

<!-- CLAUDE.md -->
@AGENTS.md

## Claude Code
Use plan mode for changes under `src/billing/`.

@AGENTS.md loads at session start; Claude-specific instructions sit below it. A symlink
(ln -s AGENTS.md CLAUDE.md) works when nothing Claude-specific is needed, though not on
Windows without Developer Mode. Shared facts live in one file; per-tool divergence lives in
the tool's own file. That is exactly the "one place per fact" property this milestone is for,
and it needs no new format.

Two caveats worth carrying into the design:

1. An import in a project-level memory file that resolves outside the working directory
   triggers a one-time approval dialog. @AGENTS.md at the repo root is inside it, so this
   does not bite — but it rules out pointing at a shared file in $HOME from a committed
   CLAUDE.md without every teammate approving a prompt.
2. The docs warn that contradictory instructions are resolved arbitrarily — "if two rules
   contradict each other, Claude may pick one arbitrarily." So the two-doctrine risk is real,
   it just needs someone to actually write the import; it is not automatic.

Revised open questions

1. Does Claude Code read AGENTS.md? Answered: no. Superseded by: should our setup
   skill offer to write the @AGENTS.md import when it detects an existing AGENTS.md?
   CLAUDE_CODE_SDLC_WIZARD.md already describes a 3-way dual-maintain/merge/skip prompt from
   feat(hooks): PreCompact seam gate — block mid-cycle manual /compact (#208) #205 phase (a); phase (b) was "offer to also write AGENTS.md" and is unbuilt. The import
   line is a strictly better phase (b) than content duplication or a symlink.
2. Root-doc ownership (TESTING.md, SDLC.md, ARCHITECTURE.md) — unchanged, still open.
3. Should either installer detect the other harness and say so? Still the cheapest real
   improvement, and now more clearly the right one: the tools genuinely cannot see each other.
4. Is /import (v2.1.213+) a supported migration path we should point users at rather than
   inventing our own?

[BaseInfinity]

Separation of concerns: which layer owns which fact

Maintainer, 2026-08-08: "remember the 3 layers... AGENTS.md would be global and loads
alongside CLAUDE... we gotta research if this is okay, if we can share stuff or if they should
be separate and maybe some stuff is shared? And host-specific stuff stays in CLAUDE.md."
Plus: "Claude Code CLI and Codex CLI are the canonical version in their respective repos and
host."

Both points are right and they resolve the design. Recording the scope map and the ownership
rule so the research has something concrete to attack.

The layers already correspond, and Anthropic has already published the mapping

Claude Code's /import (v2.1.213+) maps Codex config into Claude config. Its source mapping,
read from the v2.1.221 binary, is the scope correspondence — we do not have to invent one:

Scope	Claude Code	Codex	Shared with
Managed policy	/Library/Application Support/ClaudeCode/CLAUDE.md (macOS)	(no known equivalent)	everyone on the machine
User / global	~/.claude/CLAUDE.md	$CODEX_HOME/AGENTS.md	just you, all projects
Project	./CLAUDE.md or ./.claude/CLAUDE.md	./AGENTS.md	the team, via git
Personal project	./CLAUDE.local.md (gitignored)	./AGENTS.override.md	just you, this repo

So AGENTS.md is not "global" in the sense of overriding everything — a repo-root
AGENTS.md is project scope, peer to CLAUDE.md, and $CODEX_HOME/AGENTS.md is the
global one. And per the correction above, Claude never reads either one unless a CLAUDE.md
imports it. Nothing loads alongside anything by accident.

The rule that falls out: shared = facts about the REPO, host-specific = facts about the AGENT

This is the separation of concerns, stated as a test you can apply to any line:

Belongs in the shared layer (AGENTS.md, imported)	Belongs in the host layer (CLAUDE.md / Codex's own)
build, test and lint commands	which model and effort to run (Opus 5 high vs gpt-5.6-sol high)
architecture, module layout, domain rules	tool names — TaskCreate, TodoWrite, plan mode; Codex has different ones or none
conventions: TDD, Testing Diamond, DRY, no legacy fallbacks	hook event names — PreToolUse/Stop do not exist as such in Codex
what must never be committed; branch and PR policy	skill invocation syntax and where skills live (.claude/skills/ vs $CODEX_HOME/skills/)
the review doctrine: adversarial cross-model review is required	who the reviewer IS

That last row is the killer example and it settles the "can we just share it?" question: the
cross-model reviewer inverts per host. In this repo Fable decides and Codex is the
adversarial check. In codex-sdlc-wizard the roles swap. Import that line unfiltered into the
wrong host and you get an agent instructed to have itself adversarially review itself — the
same circularity --dual-certified (#511) spends a whole gate closing. Any sharing scheme that
cannot express "this fact is host-relative" is wrong on its face.

Ownership: each repo is canonical for its own host, and neither writes the other's file

Directly from the maintainer's second point, and it has a concrete consequence:

• claude-sdlc-harness is canonical for Claude Code CLI. It owns CLAUDE.md guidance,
  .claude/, and the Claude-flavoured skills. It must never generate AGENTS.md — today
  it does not, and that should become an explicit invariant with a test, not an accident.
• codex-sdlc-wizard is canonical for Codex CLI. It owns AGENTS.md, .codex/, and its
  own skills. It already has the more careful AGENTS.md policy (baseline hash → wizard-managed
  vs user-owned); that stays its call.
• The shared layer needs a named owner, and neither harness should assume it. Open
  question: is the shared layer a third file both import, or does AGENTS.md become it with
  CLAUDE.md reduced to @AGENTS.md plus a Claude-only section?

Revised proposal to test

claude-sdlc-harness's setup skill, on detecting an existing AGENTS.md, offers to write only
this into CLAUDE.md — never to copy content, never to touch AGENTS.md:

@AGENTS.md

## Claude Code
<!-- host-specific only: model/effort, tool names, hook wiring, reviewer identity -->

One place per fact for everything repo-shaped; per-host divergence isolated to the host's own
file; each repo still canonical for its host; and no installer writes a file it does not own.

What still has to be researched before building any of it

1. Does the shared/host split survive contact with the actual content? Take our real
   CLAUDE.md and the real AGENTS.md and classify every line. If a large fraction is
   genuinely ambiguous, the split is too clean to be useful and the answer is separate files.
2. Reviewer-identity inversion — is it the only host-relative doctrine fact, or the first
   of many? If many, the shared layer may need per-host sections rather than being tool-neutral
   prose, which changes the whole shape.
3. Managed-policy layer — Codex appears to have no equivalent. Anything an org must enforce
   cannot live in the shared layer at all.
4. Import approval dialog — an import resolving outside the working directory triggers a
   one-time per-user approval. @AGENTS.md at the repo root is inside it and safe; a shared
   file in $HOME referenced from a committed CLAUDE.md would prompt every teammate. That
   rules out one otherwise-attractive design.
5. Precedence when both exist and disagree — the docs are explicit that contradictory
   instructions are resolved arbitrarily. So the split has to prevent contradiction by
   construction; there is no precedence rule to fall back on.

[BaseInfinity]

Decision: /import is a migration tool, not a coexistence mechanism. Not built into /sdlc.

Routed to both models independently. Both returned (c): do not wrap /import in the SDLC
workflow and do not depend on its output. Recording the reasoning so this is not re-litigated.

Why it is the wrong tool for this problem

/import copies. @AGENTS.md references. That is the whole argument.

A copy drifts from the moment it is made. Building a copy mechanism into shipped guidance would
contradict this milestone's own doctrine — one place per fact — in the release after we named
it. Coexistence needs a live reference that reloads every session; migration needs a copy.
/import is built for the second problem, and we have the first.

The concrete failure, which settles it

In a repo running both harnesses, /import pastes the Codex doctrine into CLAUDE.md —
including "the adversarial reviewer is Claude." That is the reviewer-identity inversion
from the comment above, self-inflicted by a copy. The result is an agent instructed to have
itself adversarially review itself: the exact circularity --dual-certified (#511) spends an
entire gate closing. One command, and the review topology eats itself.

The distrust instinct is right, but aimed one notch off

The maintainer's framing was "we manage that shit ourselves in each repo and I don't trust
them." Half right, and worth separating:

• "We don't control it" proves too much. /import is a Claude Code built-in, not a third
  party. This harness already depends wholesale on CC built-ins — hooks, skills, settings
  precedence. If not-controlling-it disqualified /import, it would disqualify the foundation.

• The real hazard is the transform itself, described by its own warnings, verbatim from the
  v2.1.221 binary:

  • "Codex tool restrictions dropped (tool names differ); the imported agent has access to all
    Claude Code tools. Review before enabling."
  • "Skill directories are copied as-is — any allowed-tools frontmatter or bundled scripts
    become active in Claude Code. Unchecked by default; review SKILL.md before importing."
  • It refuses to port anything containing a ```! or !`…` marker, because that
    syntax is inert in Codex and live in Claude Code.

  Those are privilege-escalation semantics, honestly disclosed. To its credit /import names
  them and refuses the worst case. But a transform that turns inert text executable and drops
  tool restrictions is a thing a human reviews once, not a thing a workflow automates. That
  justifies never automating it — not never mentioning it.

It also violates the ownership rule already recorded here: each harness is canonical for its
own host, and neither writes the other's file.

Where the two verdicts diverged, and the resolution

Narrow, and worth recording rather than smoothing over. Fable would allow one sentence in
the wizard doc naming /import as the one-time onboarding path for users arriving from
Codex. Codex says do not recommend it in shipped guidance at all, leaning partly on the
support-burden argument — the same not-controlling-it leg discounted above.

Resolved as: describe, do not recommend. A sentence saying "/import exists, it is a
one-time migration copy, we do not use it and nothing in /sdlc depends on it" is a warning,
not a recommendation, and satisfies both positions. A user arriving from Codex will find the
command with or without us; being silent about it is not neutrality.

The testable rule this becomes

Nothing in /sdlc may depend on /import's output, and the setup skill only ever writes the
@AGENTS.md reference line into CLAUDE.md — its own file, never the other harness's.

Both halves are mechanically checkable and belong in tests/test-doc-consistency.sh when this
issue is picked up.

Revisit trigger

Reopen this decision only if /import gains a documented reference-based mode that
preserves a single source of truth, together with a stable, machine-verifiable privilege
mapping. Absent both, the answer does not change.

[BaseInfinity]

Triaged to v2.0.0 as the first item. The unguarded delete is confirmed in code.

Both review legs triaged the backlog on 2026-08-11. Codex ranked this #1; Fable initially ranked it 8th off the title's two-harness framing and conceded once it read the body: "the real content is 'our unguarded delete' — a data-loss path in the shipped installer. Codex read the issue; I pattern-matched the title."

Verified in the source, not inferred. cli/init.js:229-241:

function removeObsoletePaths(targetDir, { dryRun }) {
  const removed = [];
  for (const rel of OBSOLETE_PATHS) {
    const fullPath = path.join(targetDir, rel);
    if (fs.existsSync(fullPath)) {
      if (!dryRun) {
        fs.rmSync(fullPath, { recursive: true, force: true });
      }

There is no content-hash check on this path. The install path immediately above it marks a modified file PRESERVE unless --force; this one deletes recursively with force: true regardless. So the protection the issue body correctly credits the installer with does not extend to retired paths.

Consequence: a consumer who customized a skill that later gets retired loses it silently on their next init. No prompt, no backup, no diff — the sibling installer at least writes backups/skills/<name>.bak.<epoch> before replacing.

That is why this outranks the prose batch. Fable, conceding the milestone order: "My prose-first ordering loses to a verified data-loss path."

Scope stays local — fix the deletion, not the sibling-repo architecture. Full reconciliation: #578.