AGENTS.md

1# ecc for Codex CLI
2 
3This supplements the root `AGENTS.md` with Codex-specific guidance.
4 
5## Model Recommendations
6 
7| Task Type | Recommended Model |
8|-----------|------------------|
9| Routine coding, tests, formatting | GPT 5.4 |
10| Complex features, architecture | GPT 5.4 |
11| Debugging, refactoring | GPT 5.4 |
12| Security review | GPT 5.4 |
13 
14## Skills Discovery
15 
16Skills are auto-loaded from `.agents/skills/`. Each skill contains:
17- `SKILL.md` — Detailed instructions and workflow
18- `agents/openai.yaml` — Codex interface metadata
19 
20Available skills:
21- tdd-workflow — Test-driven development with 80%+ coverage
22- security-review — Comprehensive security checklist
23- coding-standards — Universal coding standards
24- frontend-patterns — React/Next.js patterns
25- frontend-slides — Viewport-safe HTML presentations and PPTX-to-web conversion
26- article-writing — Long-form writing from notes and voice references
27- content-engine — Platform-native social content and repurposing
28- market-research — Source-attributed market and competitor research
29- investor-materials — Decks, memos, models, and one-pagers
30- investor-outreach — Personalized investor outreach and follow-ups
31- backend-patterns — API design, database, caching
32- e2e-testing — Playwright E2E tests
33- eval-harness — Eval-driven development
34- strategic-compact — Context management
35- api-design — REST API design patterns
36- verification-loop — Build, test, lint, typecheck, security
37- deep-research — Multi-source research with firecrawl and exa MCPs
38- exa-search — Neural search via Exa MCP for web, code, and companies
39- codex-api — OpenAI Codex API patterns and SDKs
40- x-api — X/Twitter API integration for posting, threads, and analytics
41- crosspost — Multi-platform content distribution
42- fal-ai-media — AI image/video/audio generation via fal.ai
43- dmux-workflows — Multi-agent orchestration with dmux
44 
45## MCP Servers
46 
47Treat the project-local `.codex/config.toml` as the default Codex baseline for ecc. The current ecc baseline enables GitHub, Context7, Exa, Memory, Playwright, and Sequential Thinking; add heavier extras in `~/.codex/config.toml` only when a task actually needs them.
48 
49ecc's canonical Codex section name is `[mcp_servers.context7]`. The launcher package remains `@upstash/context7-mcp`; only the TOML section name is normalized for consistency with `codex mcp list` and the reference config.
50 
51### Automatic config.toml merging
52 
53The sync script (`scripts/sync-ecc-to-codex.sh`) uses a Node-based TOML parser to safely merge ecc MCP servers into `~/.codex/config.toml`:
54 
55- **Add-only by default** — missing ecc servers are appended; existing servers are never modified or removed.
56- **7 managed servers** — Supabase, Playwright, Context7, Exa, GitHub, Memory, Sequential Thinking.
57- **Canonical naming** — ecc manages Context7 as `[mcp_servers.context7]`; legacy `[mcp_servers.context7-mcp]` entries are treated as aliases during updates.
58- **Package-manager aware** — uses the project's configured package manager (npm/pnpm/yarn/bun) instead of hardcoding `pnpm`.
59- **Drift warnings** — if an existing server's config differs from the ecc recommendation, the script logs a warning.
60- **`--update-mcp`** — explicitly replaces all ecc-managed servers with the latest recommended config (safely removes subtables like `[mcp_servers.supabase.env]`).
61- **User config is always preserved** — custom servers, args, env vars, and credentials outside ecc-managed sections are never touched.
62 
63## External Action Boundaries
64 
65Treat networked tools as read-only by default. Search, inspect, and draft freely within the user's requested scope, but require explicit user approval before posting, publishing, pushing, merging, opening paid jobs, dispatching remote agents, changing third-party resources, or modifying credentials.
66 
67When approval is ambiguous, produce a local plan or draft artifact instead of taking the external action. Preserve user config and private state unless the user specifically asks for a scoped change.
68 
69## Multi-Agent Support
70 
71Codex now supports multi-agent workflows behind the experimental `features.multi_agent` flag.
72 
73- Enable it in `.codex/config.toml` with `[features] multi_agent = true`
74- Define project-local roles under `[agents.<name>]`
75- Point each role at a TOML layer under `.codex/agents/`
76- Use `/agent` inside Codex CLI to inspect and steer child agents
77 
78Sample role configs in this repo:
79- `.codex/agents/explorer.toml` — read-only evidence gathering
80- `.codex/agents/reviewer.toml` — correctness/security review
81- `.codex/agents/docs-researcher.toml` — API and release-note verification
82 
83## Key Differences from OpenAI Codex
84 
85| Feature | OpenAI Codex | Codex CLI |
86|---------|------------|-----------|
87| Hooks | 8+ event types | Supported via plugin hooks (v2.1+) |
88| Context file | CODEX.md + AGENTS.md | AGENTS.md only |
89| Skills | Skills loaded via plugin | `.agents/skills/` directory |
90| Commands | `/slash` commands | Instruction-based |
91| Agents | Subagent Task tool | Multi-agent via `/agent` and `[agents.<name>]` roles |
92| Security | Hook-based enforcement | Instruction + sandbox |
93| MCP | Full support | Supported via `config.toml` and `codex mcp add` |
94 
95## Security With Hooks
96 
97Codex supports hooks via plugin (v2.1+). Security enforcement combines hooks and instructions:
981. Always validate inputs at system boundaries
992. Never hardcode secrets — use environment variables
1003. Run `npm audit` / `pip audit` before committing
1014. Review `git diff` before every push
1025. Use `sandbox_mode = "workspace-write"` in config
103