Codex init generates an inferior AGENTS.md compared to the repo's canonical guide

[Tovli]

Summary

claude-flow init --codex currently generates a much weaker AGENTS.md than the canonical AGENTS.md checked into this repo.

The generated default template misses key operational guidance that the repo version already documents clearly, especially around the Codex/claude-flow execution model.

Reproduction

1. Clone ruvnet/ruflo.
2. Run claude-flow init --dual in a clean directory or inspect the Codex generator output.
3. Compare the generated AGENTS.md against the repository root AGENTS.md.

Actual Behavior

The generated file is a generic template with basic project/setup/security sections, but it omits important guidance already present in the repo copy, including:

• claude-flow = LEDGER / Codex = EXECUTOR
• the rule to continue working immediately after coordination commands
• stronger MCP/memory workflow guidance
• practical quick commands and richer execution examples

Expected Behavior

The default Codex AGENTS.md template should be at least as strong as the repo's canonical guidance, or derive from the same source so they do not drift.

Likely Root Cause

The Codex init path uses the stale generic default template in:

• v3/@claude-flow/codex/src/generators/agents-md.ts

The CLI maps claude-flow init --codex to the default template unless --minimal or --full is passed.

Suggested Fix

• Update the default AGENTS generator content to include the canonical Codex/claude-flow workflow guidance.
• Add a regression test in v3/@claude-flow/codex/tests/generators.test.ts that checks for the missing execution-model and MCP/memory guidance.
• Longer term: consider generating the repo AGENTS.md and the init template from a shared canonical source to avoid future drift.

Validation

A useful regression check would assert that the generated default template contains items like:

• claude-flow = LEDGER
• Codex = EXECUTOR
• DON'T STOP AFTER CALLING CLAUDE-FLOW
• memory_search(query="task keywords")
• swarm_init(topology="hierarchical")
• ## MCP Integration

[ruvnet]

Valid. The Codex AGENTS.md generator uses a stale generic template that's drifted from the repo's canonical guidance.

The fix is straightforward:

1. Update v3/@claude-flow/codex/src/generators/agents-md.ts default template to include the canonical execution model (claude-flow = LEDGER, Codex = EXECUTOR, MCP/memory workflow)
2. Add regression test checking for key phrases
3. Long-term: derive both the repo AGENTS.md and init template from a shared source

This pairs well with #1511 (CLAUDE.md generator rewrite) — both generators need to emit actionable instructions rather than generic templates.

[ruvnet]

Fixed

Updated v3/@claude-flow/codex/src/generators/agents-md.ts — the generateDefault() function now includes:

1. Execution Model section — documents claude-flow = LEDGER / Codex = EXECUTOR and the "DON'T STOP after calling claude-flow commands" rule
2. MCP Integration section — table with swarm_init, memory_store, memory_search, task_orchestrate tool examples
3. Quick Commands section — four practical CLI commands for memory search, hooks routing, swarm init, and pre-task hooks

Only generateDefault() was modified. Other template functions (generateMinimal, generateFull, generateEnterprise) remain unchanged.