AGENTS.md

1# Everything Copilot CLI (ECC) — Agent Instructions
2 
3This is a **production-ready AI coding plugin** providing 13 specialized agents, 50+ skills, 26 commands, and automated hook workflows for software development.
4 
5## Core Principles
6 
71. **Agent-First** — Delegate to specialized agents for domain tasks
82. **Test-Driven** — Write tests before implementation, 80%+ coverage required
93. **Security-First** — Never compromise on security; validate all inputs
104. **Immutability** — Always create new objects, never mutate existing ones
115. **Plan Before Execute** — Plan complex features before writing code
12 
13## Available Agents
14 
15| Agent | Purpose | When to Use |
16|-------|---------|-------------|
17| planner | Implementation planning | Complex features, refactoring |
18| architect | System design and scalability | Architectural decisions |
19| tdd-guide | Test-driven development | New features, bug fixes |
20| code-reviewer | Code quality and maintainability | After writing/modifying code |
21| security-reviewer | Vulnerability detection | Before commits, sensitive code |
22| build-error-resolver | Fix build/type errors | When build fails |
23| e2e-runner | End-to-end Playwright testing | Critical user flows |
24| refactor-cleaner | Dead code cleanup | Code maintenance |
25| doc-updater | Documentation and codemaps | Updating docs |
26| go-reviewer | Go code review | Go projects |
27| go-build-resolver | Go build errors | Go build failures |
28| database-reviewer | PostgreSQL/Supabase specialist | Schema design, query optimization |
29| python-reviewer | Python code review | Python projects |
30 
31## Agent Orchestration
32 
33Use agents proactively without user prompt:
34- Complex feature requests → **planner**
35- Code just written/modified → **code-reviewer**
36- Bug fix or new feature → **tdd-guide**
37- Architectural decision → **architect**
38- Security-sensitive code → **security-reviewer**
39 
40Use parallel execution for independent operations — launch multiple agents simultaneously.
41 
42## Security Guidelines
43 
44**Before ANY commit:**
45- No hardcoded secrets (API keys, passwords, tokens)
46- All user inputs validated
47- SQL injection prevention (parameterized queries)
48- XSS prevention (sanitized HTML)
49- CSRF protection enabled
50- Authentication/authorization verified
51- Rate limiting on all endpoints
52- Error messages don't leak sensitive data
53 
54**Secret management:** NEVER hardcode secrets. Use environment variables or a secret manager. Validate required secrets at startup. Rotate any exposed secrets immediately.
55 
56**If security issue found:** STOP → use security-reviewer agent → fix CRITICAL issues → rotate exposed secrets → review codebase for similar issues.
57 
58## Coding Style
59 
60**Immutability (CRITICAL):** Always create new objects, never mutate. Return new copies with changes applied.
61 
62**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.
63 
64**Error handling:** Handle errors at every level. Provide user-friendly messages in UI code. Log detailed context server-side. Never silently swallow errors.
65 
66**Input validation:** Validate all user input at system boundaries. Use schema-based validation. Fail fast with clear messages. Never trust external data.
67 
68**Code quality checklist:**
69- Functions small (<50 lines), files focused (<800 lines)
70- No deep nesting (>4 levels)
71- Proper error handling, no hardcoded values
72- Readable, well-named identifiers
73 
74## Testing Requirements
75 
76**Minimum coverage: 80%**
77 
78Test types (all required):
791. **Unit tests** — Individual functions, utilities, components
802. **Integration tests** — API endpoints, database operations
813. **E2E tests** — Critical user flows
82 
83**TDD workflow (mandatory):**
841. Write test first (RED) — test should FAIL
852. Write minimal implementation (GREEN) — test should PASS
863. Refactor (IMPROVE) — verify coverage 80%+
87 
88Troubleshoot failures: check test isolation → verify mocks → fix implementation (not tests, unless tests are wrong).
89 
90## Development Workflow
91 
921. **Plan** — Use planner agent, identify dependencies and risks, break into phases
932. **TDD** — Use tdd-guide agent, write tests first, implement, refactor
943. **Review** — Use code-reviewer agent immediately, address CRITICAL/HIGH issues
954. **Commit** — Conventional commits format, comprehensive PR summaries
96 
97## Git Workflow
98 
99**Commit format:** `<type>: <description>` — Types: feat, fix, refactor, docs, test, chore, perf, ci
100 
101**PR workflow:** Analyze full commit history → draft comprehensive summary → include test plan → push with `-u` flag.
102 
103## Architecture Patterns
104 
105**API response format:** Consistent envelope with success indicator, data payload, error message, and pagination metadata.
106 
107**Repository pattern:** Encapsulate data access behind standard interface (findAll, findById, create, update, delete). Business logic depends on abstract interface, not storage mechanism.
108 
109**Skeleton projects:** Search for battle-tested templates, evaluate with parallel agents (security, extensibility, relevance), clone best match, iterate within proven structure.
110 
111## Performance
112 
113**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.
114 
115**Build troubleshooting:** Use build-error-resolver agent → analyze errors → fix incrementally → verify after each fix.
116 
117## Project Structure
118 
119```
120agents/          — 13 specialized subagents (.agent.md)
121skills/          — 50+ workflow skills and domain knowledge
122commands/        — 26 slash commands
123hooks/           — Trigger-based automations (hooks.json)
124.github/         — Copilot instructions (copilot-instructions.md + *.instructions.md)
125scripts/         — Cross-platform Node.js utilities
126mcp-configs/     — 14 MCP server configurations
127tests/           — Test suite
128```
129 
130## Success Metrics
131 
132- All tests pass with 80%+ coverage
133- No security vulnerabilities
134- Code is readable and maintainable
135- Performance is acceptable
136- User requirements are met
137