← graph

fix-wg-init-2

Fix: wg init should install both CLAUDE.md and AGENTS.md by default (lock-step copies)

Metadata

Statusdone
Assignedagent-2336
Agent identityf51439356729d112a6c404803d88015d5b44832c6c584c62b96732b63c2b0c7e
Modelcodex:gpt-5.5
Created2026-05-04T17:16:12.889310329+00:00
Started2026-05-04T17:17:21.265875235+00:00
Completed2026-05-04T18:24:13.191583308+00:00
Tagsfix,init,docs,onboarding, eval-scheduled
Eval score0.92
└ blocking impact0.90
└ completeness0.94
└ coordination overhead0.88
└ correctness0.97
└ downstream usability0.90
└ efficiency0.83
└ intent fidelity0.85
└ style adherence0.92

Description

Description

wg init writes a default CLAUDE.md to the project root for the claude agent's context. It does NOT write AGENTS.md (codex's equivalent). Result: codex agents in fresh projects have no project-specific context, while claude agents do. Asymmetry is exactly the kind of 'claude-first, codex/nex parity missed' bug class flagged earlier (fix-codex-token-tracking, fix-evaluator-role, etc.).

User report 2026-05-04: 'we should be installing AGENTS.md by default with wg init right? same as CLAUDE.md'

Spec

wg init writes BOTH files by default:

  • CLAUDE.md — for Claude Code / Claude CLI sessions
  • AGENTS.md — for codex sessions

Per fix-agents-md (already shipped), both files are kept lock-step: identical content. Each delegates to wg agent-guide for the universal role contract; each provides project-specific layer-2 context.

Implementation options

A. Two separate files with identical content. wg init writes both. Lock-step maintained going forward by ensuring any update to one updates the other (helper or test guard). Slight risk of drift over time.

B. AGENTS.md as a symlink to CLAUDE.md. wg init writes CLAUDE.md, then ln -s CLAUDE.md AGENTS.md. No drift risk. Slight cross-platform concern (Windows symlink handling, though wg is primarily Unix).

C. AGENTS.md as a one-line stub that says 'see CLAUDE.md'. Cheap, but defeats the purpose — codex's CLI may not follow the indirection.

Recommend A (two separate files with identical content). Lock-step is enforced by:

  • Both written by wg init from the same template at init time
  • A test in the codebase that asserts CLAUDE.md == AGENTS.md byte-for-byte (or by content hash) — runs in CI to catch drift
  • Documentation in CLAUDE.md/AGENTS.md saying 'kept in lock-step with the other'

The fix-agents-md task already established this pattern in the workgraph repo itself (CLAUDE.md and AGENTS.md are 5389 bytes each, lock-step). Generalize that pattern: every project that runs wg init gets both files.

Validation

  • wg init (any route) writes BOTH CLAUDE.md and AGENTS.md to the project root
  • Both files are byte-for-byte identical (or content-hash identical, accounting for any per-file boilerplate that mentions the file's own name)
  • Live smoke: mkdir /tmp/wg-init-test && cd /tmp/wg-init-test && wg init --route claude-cli — both files present
  • Same for --route codex-cli and --route local and any other routes
  • Test (unit or integration) that asserts the lock-step invariant — fails if drift introduced
  • No regression of fix-agents-md (lock-step preserved in workgraph repo itself)
  • cargo build + cargo test pass
  • cargo install --path . was run before claiming done

Coordinate with adjacent work

  • fix-agents-md established the lock-step pattern in workgraph itself
  • The README chain (in flight) doesn't directly depend on this — but if the README chain mentions 'agents read CLAUDE.md / AGENTS.md', this fix makes that statement true for new projects too
  • sweep-normalize-naming (just filed) — naming consistency in the templates this task writes; coordinate so the templates use canonical workgraph lowercase naming

Process note

Same class as fix-codex-token-tracking, fix-evaluator-role: claude-first features that didn't get codex parity. The structural fix (per fix-codex-agent-2's process note) is to extend the doc-sync function template's audit-terminology-consistency to include 'cross-handler parity' checks. Until that lands, these one-off fixes are how parity gets caught.

Depends on

Required by

Log