AGENTS.md

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