AGENTS.md

1# Everything Claude Code (ECC) — Agent Instructions
2 
3This is a **production-ready AI coding plugin** providing 68 specialized agents, 284 skills, 94 commands, and automated hook workflows for software development.
4 
5**Version:** 2.2.0
6 
7## Core Principles
8 
91. **Agent-First** — Delegate to specialized agents for domain tasks
102. **Test-Driven** — Write tests before implementation, 80%+ coverage required
113. **Security-First** — Never compromise on security; validate all inputs
124. **Immutability** — Always create new objects, never mutate existing ones
135. **Plan Before Execute** — Plan complex features before writing code
14 
15## Available Agents
16 
17| Agent | Purpose | When to Use |
18|-------|---------|-------------|
19| planner | Implementation planning | Complex features, refactoring |
20| architect | System design and scalability | Architectural decisions |
21| tdd-guide | Test-driven development | New features, bug fixes |
22| code-reviewer | Code quality and maintainability | After writing/modifying code |
23| security-reviewer | Vulnerability detection | Before commits, sensitive code |
24| spec-miner | Brownfield spec extraction | Onboarding brownfield projects to spec-driven development |
25| build-error-resolver | Fix build/type errors | When build fails |
26| e2e-runner | End-to-end Playwright testing | Critical user flows |
27| refactor-cleaner | Dead code cleanup | Code maintenance |
28| doc-updater | Documentation and codemaps | Updating docs |
29| cpp-reviewer | C/C++ code review | C and C++ projects |
30| cpp-build-resolver | C/C++ build errors | C and C++ build failures |
31| fsharp-reviewer | F# functional code review | F# projects |
32| docs-lookup | Documentation lookup via Context7 | API/docs questions |
33| go-reviewer | Go code review | Go projects |
34| go-build-resolver | Go build errors | Go build failures |
35| kotlin-reviewer | Kotlin code review | Kotlin/Android/KMP projects |
36| kotlin-build-resolver | Kotlin/Gradle build errors | Kotlin build failures |
37| database-reviewer | PostgreSQL/Supabase specialist | Schema design, query optimization |
38| python-reviewer | Python code review | Python projects |
39| django-reviewer | Django code review | Django apps, DRF APIs, ORM, migrations |
40| django-build-resolver | Django build, migration, and setup errors | Django startup, dependency, migration, collectstatic failures |
41| java-reviewer | Java and Spring Boot code review | Java/Spring Boot projects |
42| java-build-resolver | Java/Maven/Gradle build errors | Java build failures |
43| loop-operator | Autonomous loop execution | Run loops safely, monitor stalls, intervene |
44| harness-optimizer | Harness config tuning | Reliability, cost, throughput |
45| rust-reviewer | Rust code review | Rust projects |
46| rust-build-resolver | Rust build errors | Rust build failures |
47| pytorch-build-resolver | PyTorch runtime/CUDA/training errors | PyTorch build/training failures |
48| mle-reviewer | Production ML pipeline review | ML pipelines, evals, serving, monitoring, rollback |
49| rag-pipeline-reviewer | RAG pipeline review | Retrieval quality, chunking, reranking, RAGAS evaluation coverage |
50| typescript-reviewer | TypeScript/JavaScript code review | TypeScript/JavaScript projects |
51 
52## Agent Orchestration
53 
54Use agents proactively without user prompt:
55- Complex feature requests → **planner**
56- Code just written/modified → **code-reviewer**
57- Bug fix or new feature → **tdd-guide**
58- Architectural decision → **architect**
59- Security-sensitive code → **security-reviewer**
60- Brownfield project onboarding → **spec-miner**
61- Autonomous loops / loop monitoring → **loop-operator**
62- Harness config reliability and cost → **harness-optimizer**
63- RAG/retrieval pipeline changes → **rag-pipeline-reviewer**
64 
65Use parallel execution for independent operations — launch multiple agents simultaneously.
66 
67## Security Guidelines
68 
69**Before ANY commit:**
70- No hardcoded secrets (API keys, passwords, tokens)
71- All user inputs validated
72- SQL injection prevention (parameterized queries)
73- XSS prevention (sanitized HTML)
74- CSRF protection enabled
75- Authentication/authorization verified
76- Rate limiting on all endpoints
77- Error messages don't leak sensitive data
78 
79**Secret management:** NEVER hardcode secrets. Use environment variables or a secret manager. Validate required secrets at startup. Rotate any exposed secrets immediately.
80 
81**If security issue found:** STOP → use security-reviewer agent → fix CRITICAL issues → rotate exposed secrets → review codebase for similar issues.
82 
83## Coding Style
84 
85**Immutability (CRITICAL):** Always create new objects, never mutate. Return new copies with changes applied.
86 
87**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.
88 
89**Error handling:** Handle errors at every level. Provide user-friendly messages in UI code. Log detailed context server-side. Never silently swallow errors.
90 
91**Input validation:** Validate all user input at system boundaries. Use schema-based validation. Fail fast with clear messages. Never trust external data.
92 
93**Code quality checklist:**
94- Functions small (<50 lines), files focused (<800 lines)
95- No deep nesting (>4 levels)
96- Proper error handling, no hardcoded values
97- Readable, well-named identifiers
98 
99## Testing Requirements
100 
101**Minimum coverage: 80%**
102 
103Test types (all required):
1041. **Unit tests** — Individual functions, utilities, components
1052. **Integration tests** — API endpoints, database operations
1063. **E2E tests** — Critical user flows
107 
108**TDD workflow (mandatory):**
1091. Write test first (RED) — test should FAIL
1102. Write minimal implementation (GREEN) — test should PASS
1113. Refactor (IMPROVE) — verify coverage 80%+
112 
113Troubleshoot failures: check test isolation → verify mocks → fix implementation (not tests, unless tests are wrong).
114 
115## Development Workflow
116 
1171. **Plan** — Use planner agent, identify dependencies and risks, break into phases
1182. **TDD** — Use tdd-guide agent, write tests first, implement, refactor
1193. **Review** — Use code-reviewer agent immediately, address CRITICAL/HIGH issues
1204. **Capture knowledge in the right place**
121   - Personal debugging notes, preferences, and temporary context → auto memory
122   - Team/project knowledge (architecture decisions, API changes, runbooks) → the project's existing docs structure
123   - If the current task already produces the relevant docs or code comments, do not duplicate the same information elsewhere
124   - If there is no obvious project doc location, ask before creating a new top-level file
1255. **Commit** — Conventional commits format, comprehensive PR summaries
126 
127## Workflow Surface Policy
128 
129- `skills/` is the canonical workflow surface.
130- New workflow contributions should land in `skills/` first.
131- `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.
132 
133## Git Workflow
134 
135**Commit format:** `<type>: <description>` — Types: feat, fix, refactor, docs, test, chore, perf, ci
136 
137**PR workflow:** Analyze full commit history → draft comprehensive summary → include test plan → push with `-u` flag.
138 
139## Architecture Patterns
140 
141**API response format:** Consistent envelope with success indicator, data payload, error message, and pagination metadata.
142 
143**Repository pattern:** Encapsulate data access behind standard interface (findAll, findById, create, update, delete). Business logic depends on abstract interface, not storage mechanism.
144 
145**Skeleton projects:** Search for battle-tested templates, evaluate with parallel agents (security, extensibility, relevance), clone best match, iterate within proven structure.
146 
147## Performance
148 
149**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.
150 
151**Build troubleshooting:** Use build-error-resolver agent → analyze errors → fix incrementally → verify after each fix.
152 
153## Project Structure
154 
155```
156agents/          — 68 specialized subagents
157skills/          — 284 workflow skills and domain knowledge
158commands/        — 94 slash commands
159hooks/           — Trigger-based automations
160rules/           — Always-follow guidelines (common + per-language)
161scripts/         — Cross-platform Node.js utilities
162mcp-configs/     — 14 MCP server configurations
163tests/           — Test suite
164```
165 
166`commands/` remains in the repo for compatibility, but the long-term direction is skills-first.
167 
168## Success Metrics
169 
170- All tests pass with 80%+ coverage
171- No security vulnerabilities
172- Code is readable and maintainable
173- Performance is acceptable
174- User requirements are met
175