| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 9 | 17 | 0% |
| Commands | 0 | 4 | 0 | 0% |
| Section tags | 2 | 0 | 7 | 22% |
What each file covers
Sections
0 shared · 9 only in A · 17 only in B- − ecc for Codex CLI
- − Model Recommendations
- − Skills Discovery
- − MCP Servers
- − Automatic config.toml merging
- − External Action Boundaries
- − Multi-Agent Support
- − Key Differences from OpenAI Codex
- − Security With Hooks
- + Everything OpenAI Codex (ecc) — Agent Instructions
- + Core Principles
- + Responsibility Contract
- + Output Contract
- + Recommendation Contract
- + Available Agents
- + Agent Orchestration
- + Security Guidelines
- + Coding Style
- + Testing Requirements
- + Development Workflow
- + Workflow Surface Policy
- + Git Workflow
- + Architecture Patterns
- + Performance
- + Project Structure
- + Success Metrics
Commands
0 shared · 4 only in A · 0 only in B- − pnpm
- − npm audit
- − pip audit
- − git diff
Section tags
2 shared · 0 only in A · 7 only in B- + build
- + test
- + code-style
- + architecture
- + git-pr
- + api
- + performance
- security
- agent-behaviour
Line diff
mturac/everything-openai-codex · .codex/AGENTS.md
@@ −1 @@
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
mturac/everything-openai-codex · AGENTS.md
@@ +1 @@
1# Everything OpenAI Codex (ecc) — Agent Instructions
2
3This is a **production-ready AI coding plugin** providing 60 specialized agents, 232 skills, 75 commands, and automated hook workflows for software development.
4
5**Version:** 2.0.0-rc.1
6
7## Core Principles
8
9**Precedence:** safety > privacy > security > tool schema > verification > repository instructions > task style. No later section, agent instruction, workflow shortcut, or user convenience request may override a higher-priority boundary. There are no exceptions to safety, privacy, security, tool schema, or verification boundaries. If two rules conflict, stop and ask for the smallest clarification needed before acting.
10
111. **Agent-First** — Delegate to specialized agents for domain tasks
122. **Test-Driven** — Write tests before implementation when practical; use the repo's active coverage gate
133. **Security-First** — Protect security boundaries and validate all inputs
144. **Immutability** — Prefer new objects over mutation; document any API-required mutation in the handoff
155. **Plan Before Execute** — Plan complex features before writing code
16
17## Responsibility Contract
18
19Act as a senior engineering agent responsible only for the files, modules, docs, tests, or release artifacts required by the current task. Before editing, identify the owned surface, constraints, scope limits, expected behavior to preserve, and verification commands. Keep unrelated refactors out of scope.
20
21Final handoff must include changed files, verification commands and results, known residual risks, and any manual follow-up. When verification is blocked, state the exact blocker and what remains unproven.
22
23## Output Contract
24
25Default engineering output is concise Markdown with:
26- changed surface
27- verification
28- residual risk or blocker
29
30When producing structured artifacts, preserve the requested schema exactly. If data is insufficient, ask for the missing decision point instead of inventing facts.
31
32## Recommendation Contract
33
34Before recommending tools, vendors, public posting targets, launch channels, or high-cost actions, anchor the recommendation to the target audience, market or platform, budget or effort limit, timing, constraints, and ranking criteria. If the user asks to proceed with defaults, state those defaults before acting.
35
36## Available Agents
37
38| Agent | Purpose | When to Use |
39|-------|---------|-------------|
40| planner | Implementation planning | Complex features, refactoring |
41| architect | System design and scalability | Architectural decisions |
42| tdd-guide | Test-driven development | New features, bug fixes |
43| code-reviewer | Code quality and maintainability | After writing/modifying code |
44| security-reviewer | Vulnerability detection | Before commits, sensitive code |
45| build-error-resolver | Fix build/type errors | When build fails |
46| e2e-runner | End-to-end Playwright testing | Critical user flows |
47| refactor-cleaner | Dead code cleanup | Code maintenance |
48| doc-updater | Documentation and codemaps | Updating docs |
49| cpp-reviewer | C/C++ code review | C and C++ projects |
50| cpp-build-resolver | C/C++ build errors | C and C++ build failures |
51| fsharp-reviewer | F# functional code review | F# projects |
52| docs-lookup | Documentation lookup via Context7 | API/docs questions |
53| go-reviewer | Go code review | Go projects |
54| go-build-resolver | Go build errors | Go build failures |
55| kotlin-reviewer | Kotlin code review | Kotlin/Android/KMP projects |
56| kotlin-build-resolver | Kotlin/Gradle build errors | Kotlin build failures |
57| database-reviewer | PostgreSQL/Supabase specialist | Schema design, query optimization |
58| python-reviewer | Python code review | Python projects |
59| django-reviewer | Django code review | Django apps, DRF APIs, ORM, migrations |
60| django-build-resolver | Django build, migration, and setup errors | Django startup, dependency, migration, collectstatic failures |
61| java-reviewer | Java and Spring Boot code review | Java/Spring Boot projects |
62| java-build-resolver | Java/Maven/Gradle build errors | Java build failures |
63| loop-operator | Autonomous loop execution | Run loops safely, monitor stalls, intervene |
64| harness-optimizer | Harness config tuning | Reliability, cost, throughput |
65| rust-reviewer | Rust code review | Rust projects |
66| rust-build-resolver | Rust build errors | Rust build failures |
67| pytorch-build-resolver | PyTorch runtime/CUDA/training errors | PyTorch build/training failures |
68| mle-reviewer | Production ML pipeline review | ML pipelines, evals, serving, monitoring, rollback |
69| typescript-reviewer | TypeScript/JavaScript code review | TypeScript/JavaScript projects |
70
71## Agent Orchestration
72
73Use agents proactively without user prompt:
74- Complex feature requests → **planner**
75- Code just written/modified → **code-reviewer**
76- Bug fix or new feature → **tdd-guide**
77- Architectural decision → **architect**
78- Security-sensitive code → **security-reviewer**
79- Autonomous loops / loop monitoring → **loop-operator**
80- Harness config reliability and cost → **harness-optimizer**
81
82Use parallel execution for independent operations — launch multiple agents simultaneously.
83
84## Security Guidelines
85
86**Before ANY commit:**
87- No hardcoded secrets (API keys, passwords, tokens)
88- All user inputs validated
89- SQL injection prevention (parameterized queries)
90- XSS prevention (sanitized HTML)
91- CSRF protection enabled
92- Authentication/authorization verified
93- Rate limiting on all endpoints
94- Error messages don't leak sensitive data
95
96**Secret management:** Hardcoded secrets are prohibited. Use environment variables or a secret manager. Validate required secrets at startup. Rotate any exposed secrets immediately.
97
98**If security issue found:** STOP → use security-reviewer agent → fix CRITICAL issues → rotate exposed secrets → review codebase for similar issues.
99
100## Coding Style
101
102**Immutability:** Prefer new objects and return new copies with changes applied. Record any API-required mutation in the handoff.
103
104**File organization:** Many small files over few large ones. 200-400 lines typical, 800 max. Organize by feature/domain, not by type. High cohesion, low coupling.
105
106**Error handling:** Handle errors at every level. Provide user-friendly messages in UI code. Log detailed context server-side. Surface or intentionally document swallowed errors.
107
108**Input validation:** Validate all user input at system boundaries. Use schema-based validation. Fail fast with clear messages. Treat external data as untrusted until validated.
109
110**Code quality checklist:**
111- Functions small (<50 lines), files focused (<800 lines)
112- No deep nesting (>4 levels)
113- Proper error handling, no hardcoded values
114- Readable, well-named identifiers
115
116## Testing Requirements
117
118**Minimum coverage: 80%**
119
120Test types (all required):
1211. **Unit tests** — Individual functions, utilities, components
1222. **Integration tests** — API endpoints, database operations
1233. **E2E tests** — Critical user flows
124
125**TDD workflow (mandatory):**
1261. Write test first (RED) — test should FAIL
1272. Write minimal implementation (GREEN) — test should PASS
1283. Refactor (IMPROVE) — verify coverage 80%+
129
130Troubleshoot failures: check test isolation → verify mocks → fix implementation. Change tests only when the expected behavior is incorrect or outdated.
131
132## Development Workflow
133
1341. **Plan** — Use planner agent, identify dependencies and risks, break into phases
1352. **TDD** — Use tdd-guide agent, write tests first, implement, refactor
1363. **Review** — Use code-reviewer agent immediately, address CRITICAL/HIGH issues
1374. **Capture knowledge in the right place**
138 - Personal debugging notes, preferences, and temporary context → auto memory
139 - Team/project knowledge (architecture decisions, API changes, runbooks) → the project's existing docs structure
140 - If the current task already produces the relevant docs or code comments, keep the information in that single source of truth
141 - If there is no obvious project doc location, ask before creating a new top-level file
1425. **Commit** — Conventional commits format, comprehensive PR summaries
143
144## Workflow Surface Policy
145
146- `skills/` is the canonical workflow surface.
147- New workflow contributions should land in `skills/` first.
148- `commands/` is a legacy slash-entry compatibility surface and should only be added or updated when a shim is still required for migration or cross-harness parity.
149
150## Git Workflow
151
152**Commit format:** `<type>: <description>` — Types: feat, fix, refactor, docs, test, chore, perf, ci
153
154**PR workflow:** Analyze full commit history → draft comprehensive summary → include test plan → push with `-u` flag.
155
156## Architecture Patterns
157
158**API response format:** Consistent envelope with success indicator, data payload, error message, and pagination metadata.
159
160**Repository pattern:** Encapsulate data access behind standard interface (findAll, findById, create, update, delete). Business logic depends on abstract interface, not storage mechanism.
161
162**Skeleton projects:** Search for battle-tested templates, evaluate with parallel agents (security, extensibility, relevance), clone best match, iterate within proven structure.
163
164## Performance
165
166**Context management:** Avoid last 20% of context window for large refactoring and multi-file features. Lower-sensitivity tasks (single edits, docs, simple fixes) tolerate higher utilization.
167
168**Build troubleshooting:** Use build-error-resolver agent → analyze errors → fix incrementally → verify after each fix.
169
170## Project Structure
171
172```
173agents/ — 60 specialized subagents
174skills/ — 232 workflow skills and domain knowledge
175commands/ — 75 slash commands
176hooks/ — Trigger-based automations
177rules/ — Always-follow guidelines (common + per-language)
178scripts/ — Cross-platform Node.js utilities
179mcp-configs/ — 14 MCP server configurations
180tests/ — Test suite
181```
182
183`commands/` remains in the repo for compatibility, but the long-term direction is skills-first.
184
185## Success Metrics
186
187- All tests pass with 80%+ coverage
188- No security vulnerabilities
189- Code is readable and maintainable
190- Performance is acceptable
191- User requirements are met
192
@@ −1 +1 @@
1−# ecc for Codex CLI
1+# Everything OpenAI Codex (ecc) — Agent Instructions
22
3−This supplements the root `AGENTS.md` with Codex-specific guidance.
3+This is a **production-ready AI coding plugin** providing 60 specialized agents, 232 skills, 75 commands, and automated hook workflows for software development.
44
5−## Model Recommendations
5+**Version:** 2.0.0-rc.1
66
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 |
7+## Core Principles
138
14−## Skills Discovery
9+**Precedence:** safety > privacy > security > tool schema > verification > repository instructions > task style. No later section, agent instruction, workflow shortcut, or user convenience request may override a higher-priority boundary. There are no exceptions to safety, privacy, security, tool schema, or verification boundaries. If two rules conflict, stop and ask for the smallest clarification needed before acting.
1510
16−Skills are auto-loaded from `.agents/skills/`. Each skill contains:
17−- `SKILL.md` — Detailed instructions and workflow
18−- `agents/openai.yaml` — Codex interface metadata
11+1. **Agent-First** — Delegate to specialized agents for domain tasks
12+2. **Test-Driven** — Write tests before implementation when practical; use the repo's active coverage gate
13+3. **Security-First** — Protect security boundaries and validate all inputs
14+4. **Immutability** — Prefer new objects over mutation; document any API-required mutation in the handoff
15+5. **Plan Before Execute** — Plan complex features before writing code
1916
20−Available 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
17+## Responsibility Contract
4418
45−## MCP Servers
19+Act as a senior engineering agent responsible only for the files, modules, docs, tests, or release artifacts required by the current task. Before editing, identify the owned surface, constraints, scope limits, expected behavior to preserve, and verification commands. Keep unrelated refactors out of scope.
4620
47−Treat 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.
21+Final handoff must include changed files, verification commands and results, known residual risks, and any manual follow-up. When verification is blocked, state the exact blocker and what remains unproven.
4822
49−ecc'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.
23+## Output Contract
5024
51−### Automatic config.toml merging
25+Default engineering output is concise Markdown with:
26+- changed surface
27+- verification
28+- residual risk or blocker
5229
53−The sync script (`scripts/sync-ecc-to-codex.sh`) uses a Node-based TOML parser to safely merge ecc MCP servers into `~/.codex/config.toml`:
30+When producing structured artifacts, preserve the requested schema exactly. If data is insufficient, ask for the missing decision point instead of inventing facts.
5431
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.
32+## Recommendation Contract
6233
63−## External Action Boundaries
34+Before recommending tools, vendors, public posting targets, launch channels, or high-cost actions, anchor the recommendation to the target audience, market or platform, budget or effort limit, timing, constraints, and ranking criteria. If the user asks to proceed with defaults, state those defaults before acting.
6435
65−Treat 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.
36+## Available Agents
6637
67−When 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.
38+| Agent | Purpose | When to Use |
39+|-------|---------|-------------|
40+| planner | Implementation planning | Complex features, refactoring |
41+| architect | System design and scalability | Architectural decisions |
42+| tdd-guide | Test-driven development | New features, bug fixes |
43+| code-reviewer | Code quality and maintainability | After writing/modifying code |
44+| security-reviewer | Vulnerability detection | Before commits, sensitive code |
45+| build-error-resolver | Fix build/type errors | When build fails |
46+| e2e-runner | End-to-end Playwright testing | Critical user flows |
47+| refactor-cleaner | Dead code cleanup | Code maintenance |
48+| doc-updater | Documentation and codemaps | Updating docs |
49+| cpp-reviewer | C/C++ code review | C and C++ projects |
50+| cpp-build-resolver | C/C++ build errors | C and C++ build failures |
51+| fsharp-reviewer | F# functional code review | F# projects |
52+| docs-lookup | Documentation lookup via Context7 | API/docs questions |
53+| go-reviewer | Go code review | Go projects |
54+| go-build-resolver | Go build errors | Go build failures |
55+| kotlin-reviewer | Kotlin code review | Kotlin/Android/KMP projects |
56+| kotlin-build-resolver | Kotlin/Gradle build errors | Kotlin build failures |
57+| database-reviewer | PostgreSQL/Supabase specialist | Schema design, query optimization |
58+| python-reviewer | Python code review | Python projects |
59+| django-reviewer | Django code review | Django apps, DRF APIs, ORM, migrations |
60+| django-build-resolver | Django build, migration, and setup errors | Django startup, dependency, migration, collectstatic failures |
61+| java-reviewer | Java and Spring Boot code review | Java/Spring Boot projects |
62+| java-build-resolver | Java/Maven/Gradle build errors | Java build failures |
63+| loop-operator | Autonomous loop execution | Run loops safely, monitor stalls, intervene |
64+| harness-optimizer | Harness config tuning | Reliability, cost, throughput |
65+| rust-reviewer | Rust code review | Rust projects |
66+| rust-build-resolver | Rust build errors | Rust build failures |
67+| pytorch-build-resolver | PyTorch runtime/CUDA/training errors | PyTorch build/training failures |
68+| mle-reviewer | Production ML pipeline review | ML pipelines, evals, serving, monitoring, rollback |
69+| typescript-reviewer | TypeScript/JavaScript code review | TypeScript/JavaScript projects |
6870
69−## Multi-Agent Support
71+## Agent Orchestration
7072
71−Codex now supports multi-agent workflows behind the experimental `features.multi_agent` flag.
73+Use agents proactively without user prompt:
74+- Complex feature requests → **planner**
75+- Code just written/modified → **code-reviewer**
76+- Bug fix or new feature → **tdd-guide**
77+- Architectural decision → **architect**
78+- Security-sensitive code → **security-reviewer**
79+- Autonomous loops / loop monitoring → **loop-operator**
80+- Harness config reliability and cost → **harness-optimizer**
7281
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
82+Use parallel execution for independent operations — launch multiple agents simultaneously.
7783
78−Sample 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
84+## Security Guidelines
8285
83−## Key Differences from OpenAI Codex
86+**Before ANY commit:**
87+- No hardcoded secrets (API keys, passwords, tokens)
88+- All user inputs validated
89+- SQL injection prevention (parameterized queries)
90+- XSS prevention (sanitized HTML)
91+- CSRF protection enabled
92+- Authentication/authorization verified
93+- Rate limiting on all endpoints
94+- Error messages don't leak sensitive data
8495
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` |
96+**Secret management:** Hardcoded secrets are prohibited. Use environment variables or a secret manager. Validate required secrets at startup. Rotate any exposed secrets immediately.
9497
95−## Security With Hooks
98+**If security issue found:** STOP → use security-reviewer agent → fix CRITICAL issues → rotate exposed secrets → review codebase for similar issues.
9699
97−Codex supports hooks via plugin (v2.1+). Security enforcement combines hooks and instructions:
98−1. Always validate inputs at system boundaries
99−2. Never hardcode secrets — use environment variables
100−3. Run `npm audit` / `pip audit` before committing
101−4. Review `git diff` before every push
102−5. Use `sandbox_mode = "workspace-write"` in config
100+## Coding Style
101+
102+**Immutability:** Prefer new objects and return new copies with changes applied. Record any API-required mutation in the handoff.
103+
104+**File organization:** Many small files over few large ones. 200-400 lines typical, 800 max. Organize by feature/domain, not by type. High cohesion, low coupling.
105+
106+**Error handling:** Handle errors at every level. Provide user-friendly messages in UI code. Log detailed context server-side. Surface or intentionally document swallowed errors.
107+
108+**Input validation:** Validate all user input at system boundaries. Use schema-based validation. Fail fast with clear messages. Treat external data as untrusted until validated.
109+
110+**Code quality checklist:**
111+- Functions small (<50 lines), files focused (<800 lines)
112+- No deep nesting (>4 levels)
113+- Proper error handling, no hardcoded values
114+- Readable, well-named identifiers
115+
116+## Testing Requirements
117+
118+**Minimum coverage: 80%**
119+
120+Test types (all required):
121+1. **Unit tests** — Individual functions, utilities, components
122+2. **Integration tests** — API endpoints, database operations
123+3. **E2E tests** — Critical user flows
124+
125+**TDD workflow (mandatory):**
126+1. Write test first (RED) — test should FAIL
127+2. Write minimal implementation (GREEN) — test should PASS
128+3. Refactor (IMPROVE) — verify coverage 80%+
129+
130+Troubleshoot failures: check test isolation → verify mocks → fix implementation. Change tests only when the expected behavior is incorrect or outdated.
131+
132+## Development Workflow
133+
134+1. **Plan** — Use planner agent, identify dependencies and risks, break into phases
135+2. **TDD** — Use tdd-guide agent, write tests first, implement, refactor
136+3. **Review** — Use code-reviewer agent immediately, address CRITICAL/HIGH issues
137+4. **Capture knowledge in the right place**
138+ - Personal debugging notes, preferences, and temporary context → auto memory
139+ - Team/project knowledge (architecture decisions, API changes, runbooks) → the project's existing docs structure
140+ - If the current task already produces the relevant docs or code comments, keep the information in that single source of truth
141+ - If there is no obvious project doc location, ask before creating a new top-level file
142+5. **Commit** — Conventional commits format, comprehensive PR summaries
143+
144+## Workflow Surface Policy
145+
146+- `skills/` is the canonical workflow surface.
147+- New workflow contributions should land in `skills/` first.
148+- `commands/` is a legacy slash-entry compatibility surface and should only be added or updated when a shim is still required for migration or cross-harness parity.
149+
150+## Git Workflow
151+
152+**Commit format:** `<type>: <description>` — Types: feat, fix, refactor, docs, test, chore, perf, ci
153+
154+**PR workflow:** Analyze full commit history → draft comprehensive summary → include test plan → push with `-u` flag.
155+
156+## Architecture Patterns
157+
158+**API response format:** Consistent envelope with success indicator, data payload, error message, and pagination metadata.
159+
160+**Repository pattern:** Encapsulate data access behind standard interface (findAll, findById, create, update, delete). Business logic depends on abstract interface, not storage mechanism.
161+
162+**Skeleton projects:** Search for battle-tested templates, evaluate with parallel agents (security, extensibility, relevance), clone best match, iterate within proven structure.
163+
164+## Performance
165+
166+**Context management:** Avoid last 20% of context window for large refactoring and multi-file features. Lower-sensitivity tasks (single edits, docs, simple fixes) tolerate higher utilization.
167+
168+**Build troubleshooting:** Use build-error-resolver agent → analyze errors → fix incrementally → verify after each fix.
169+
170+## Project Structure
171+
172+```
173+agents/ — 60 specialized subagents
174+skills/ — 232 workflow skills and domain knowledge
175+commands/ — 75 slash commands
176+hooks/ — Trigger-based automations
177+rules/ — Always-follow guidelines (common + per-language)
178+scripts/ — Cross-platform Node.js utilities
179+mcp-configs/ — 14 MCP server configurations
180+tests/ — Test suite
181+```
182+
183+`commands/` remains in the repo for compatibility, but the long-term direction is skills-first.
184+
185+## Success Metrics
186+
187+- All tests pass with 80%+ coverage
188+- No security vulnerabilities
189+- Code is readable and maintainable
190+- Performance is acceptable
191+- User requirements are met
103192
