ECC/AGENTS.md

# Everything Claude Code (ECC) — Agent Instructions

This is a **production-ready AI coding plugin** providing 68 specialized agents, 292 skills, 94 commands, and automated hook workflows for software development.

**Version:** 2.2.2

## Core Principles

1. **Agent-First** — Delegate to specialized agents for domain tasks
2. **Test-Driven** — Write tests before implementation, 80%+ coverage required
3. **Security-First** — Never compromise on security; validate all inputs
4. **Immutability** — Always create new objects, never mutate existing ones
5. **Plan Before Execute** — Plan complex features before writing code

## Available Agents

| Agent | Purpose | When to Use |
|-------|---------|-------------|
| planner | Implementation planning | Complex features, refactoring |
| architect | System design and scalability | Architectural decisions |
| tdd-guide | Test-driven development | New features, bug fixes |
| code-reviewer | Code quality and maintainability | After writing/modifying code |
| security-reviewer | Vulnerability detection | Before commits, sensitive code |
| spec-miner | Brownfield spec extraction | Onboarding brownfield projects to spec-driven development |
| build-error-resolver | Fix build/type errors | When build fails |
| e2e-runner | End-to-end Playwright testing | Critical user flows |
| refactor-cleaner | Dead code cleanup | Code maintenance |
| doc-updater | Documentation and codemaps | Updating docs |
| cpp-reviewer | C/C++ code review | C and C++ projects |
| cpp-build-resolver | C/C++ build errors | C and C++ build failures |
| fsharp-reviewer | F# functional code review | F# projects |
| docs-lookup | Documentation lookup via Context7 | API/docs questions |
| go-reviewer | Go code review | Go projects |
| go-build-resolver | Go build errors | Go build failures |
| kotlin-reviewer | Kotlin code review | Kotlin/Android/KMP projects |
| kotlin-build-resolver | Kotlin/Gradle build errors | Kotlin build failures |
| database-reviewer | PostgreSQL/Supabase specialist | Schema design, query optimization |
| python-reviewer | Python code review | Python projects |
| django-reviewer | Django code review | Django apps, DRF APIs, ORM, migrations |
| django-build-resolver | Django build, migration, and setup errors | Django startup, dependency, migration, collectstatic failures |
| java-reviewer | Java and Spring Boot code review | Java/Spring Boot projects |
| java-build-resolver | Java/Maven/Gradle build errors | Java build failures |
| loop-operator | Autonomous loop execution | Run loops safely, monitor stalls, intervene |
| harness-optimizer | Harness config tuning | Reliability, cost, throughput |
| rust-reviewer | Rust code review | Rust projects |
| rust-build-resolver | Rust build errors | Rust build failures |
| pytorch-build-resolver | PyTorch runtime/CUDA/training errors | PyTorch build/training failures |
| mle-reviewer | Production ML pipeline review | ML pipelines, evals, serving, monitoring, rollback |
| rag-pipeline-reviewer | RAG pipeline review | Retrieval quality, chunking, reranking, RAGAS evaluation coverage |
| typescript-reviewer | TypeScript/JavaScript code review | TypeScript/JavaScript projects |
| react-reviewer | React/JSX code review | React component and hook changes |
| react-build-resolver | React/Vite/Next.js/webpack build errors | React build failures |
| vue-reviewer | Vue.js Composition API and reactivity review | Vue component, Pinia, and Nuxt changes |
| swift-reviewer | Swift/iOS code review | Swift code changes |
| swift-build-resolver | Swift/Xcode/SPM build errors | Swift build failures |
| flutter-reviewer | Flutter/Dart widget and state review | Flutter app changes |
| dart-build-resolver | Dart/Flutter build and pub dependency errors | Flutter compilation failures |
| csharp-reviewer | C#/.NET async patterns, nullability, security | All C# code changes |
| fastapi-reviewer | FastAPI async correctness, Pydantic, OpenAPI | FastAPI endpoint and schema changes |
| php-reviewer | PHP/PSR-12, Eloquent, security review | PHP code changes |
| harmonyos-app-resolver | HarmonyOS ArkTS/ArkUI code and API review | HarmonyOS/OpenHarmony application changes |
| healthcare-reviewer | Clinical safety, PHI compliance, CDSS accuracy | Healthcare, EMR/EHR application code |
| a11y-architect | WCAG 2.2 accessibility architecture | Designing UI components, accessibility audits |
| code-architect | Feature architecture blueprints from codebase patterns | New features needing implementation design |
| network-architect | Enterprise multi-site network architecture | Complex network design decisions |
| homelab-architect | Home/small-lab network design | Home infrastructure planning |
| network-config-reviewer | Router/switch config security and correctness | Network configuration changes |
| network-troubleshooter | OSI-layer connectivity and routing diagnosis | Network connectivity and routing issues |
| performance-optimizer | Bottleneck detection, bundle size, memory leaks | Slow code or high resource usage |
| silent-failure-hunter | Swallowed errors and missing propagation | Code reliability audits |
| type-design-analyzer | Type encapsulation and invariant design | Type design and invariant reviews |
| pr-test-analyzer | PR test coverage quality and completeness | Before merging pull requests |
| code-explorer | Execution path tracing and architecture mapping | Understanding unfamiliar code paths |
| code-simplifier | Clarity-focused code refinement without behavior change | Post-implementation cleanup |
| comment-analyzer | Comment accuracy, freshness, and rot risk | Code comment audits |
| agent-evaluator | 5-axis quality scoring for agent output | Evaluating task completion quality |
| chief-of-staff | Multi-channel communication triage and drafting | Managing email/Slack communication workflows |
| conversation-analyzer | Extract hook behaviors from session transcripts | Creating hooks from observed patterns |
| marketing-agent | Campaign planning, copy creation, content calendars | Product launches, marketing campaigns |
| seo-specialist | Technical SEO audit, structured data, Core Web Vitals | Site audits, meta tag and schema issues |
| opensource-forker | Fork projects and strip secrets for open-sourcing | Starting an open-source release |
| opensource-sanitizer | Verify sanitized fork is release-ready | Before any public release |
| opensource-packager | Generate OSS packaging boilerplate (README, LICENSE, etc.) | Finalizing an open-source release |
| gan-planner | Expand a prompt into a full product specification | Starting a GAN harness session |
| gan-generator | Implement features per spec, iterate on evaluator feedback | GAN harness implementation phase |
| gan-evaluator | Test running application via Playwright and score it | GAN harness evaluation phase |

## Agent Orchestration

Use agents proactively without user prompt:
- Complex feature requests → **ecc:planner**
- Code just written/modified → **ecc:code-reviewer**
- Bug fix or new feature → **ecc:tdd-guide**
- Architectural decision → **ecc:architect**
- Security-sensitive code → **ecc:security-reviewer**
- Brownfield project onboarding → **ecc:spec-miner**
- Autonomous loops / loop monitoring → **ecc:loop-operator**
- Harness config reliability and cost → **ecc:harness-optimizer**
- RAG/retrieval pipeline changes → **ecc:rag-pipeline-reviewer**
- Performance bottleneck or slow code → **ecc:performance-optimizer**
- React/JSX changes → **ecc:react-reviewer**
- Vue changes → **ecc:vue-reviewer**
- Swift changes → **ecc:swift-reviewer**
- C# changes → **ecc:csharp-reviewer**
- PHP changes → **ecc:php-reviewer**
- Flutter/Dart changes → **ecc:flutter-reviewer**
- Healthcare/clinical code → **ecc:healthcare-reviewer**
- UI component design → **ecc:a11y-architect**
- Open-source release prep → **ecc:opensource-forker** → **ecc:opensource-sanitizer** → **ecc:opensource-packager**
- Agent output quality check → **ecc:agent-evaluator**

Use parallel execution for independent operations — launch multiple agents simultaneously.

## Security Guidelines

**Before ANY commit:**
- No hardcoded secrets (API keys, passwords, tokens)
- All user inputs validated
- SQL injection prevention (parameterized queries)
- XSS prevention (sanitized HTML)
- CSRF protection enabled
- Authentication/authorization verified
- Rate limiting on all endpoints
- Error messages don't leak sensitive data

**Secret management:** NEVER hardcode secrets. Use environment variables or a secret manager. Validate required secrets at startup. Rotate any exposed secrets immediately.

**If security issue found:** STOP → use security-reviewer agent → fix CRITICAL issues → rotate exposed secrets → review codebase for similar issues.

## Coding Style

**Immutability (CRITICAL):** Always create new objects, never mutate. Return new copies with changes applied.

**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.

**Error handling:** Handle errors at every level. Provide user-friendly messages in UI code. Log detailed context server-side. Never silently swallow errors.

**Input validation:** Validate all user input at system boundaries. Use schema-based validation. Fail fast with clear messages. Never trust external data.

**Code quality checklist:**
- Functions small (<50 lines), files focused (<800 lines)
- No deep nesting (>4 levels)
- Proper error handling, no hardcoded values
- Readable, well-named identifiers

## Testing Requirements

**Minimum coverage: 80%**

Test types (all required):
1. **Unit tests** — Individual functions, utilities, components
2. **Integration tests** — API endpoints, database operations
3. **E2E tests** — Critical user flows

**TDD workflow (mandatory):**
1. Write test first (RED) — test should FAIL
2. Write minimal implementation (GREEN) — test should PASS
3. Refactor (IMPROVE) — verify coverage 80%+

Troubleshoot failures: check test isolation → verify mocks → fix implementation (not tests, unless tests are wrong).

## Development Workflow

1. **Plan** — Use ecc:planner agent, identify dependencies and risks, break into phases
2. **TDD** — Use ecc:tdd-guide agent, write tests first, implement, refactor
3. **Review** — Use ecc:code-reviewer agent immediately, address CRITICAL/HIGH issues
4. **Capture knowledge in the right place**
   - Personal debugging notes, preferences, and temporary context → auto memory
   - Team/project knowledge (architecture decisions, API changes, runbooks) → the project's existing docs structure
   - If the current task already produces the relevant docs or code comments, do not duplicate the same information elsewhere
   - If there is no obvious project doc location, ask before creating a new top-level file
5. **Commit** — Conventional commits format, comprehensive PR summaries

## Workflow Surface Policy

- `skills/` is the canonical workflow surface.
- New workflow contributions should land in `skills/` first.
- `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.

## Git Workflow

**Commit format:** `<type>: <description>` — Types: feat, fix, refactor, docs, test, chore, perf, ci

**PR workflow:** Analyze full commit history → draft comprehensive summary → include test plan → push with `-u` flag.

## Architecture Patterns

**API response format:** Consistent envelope with success indicator, data payload, error message, and pagination metadata.

**Repository pattern:** Encapsulate data access behind standard interface (findAll, findById, create, update, delete). Business logic depends on abstract interface, not storage mechanism.

**Skeleton projects:** Search for battle-tested templates, evaluate with parallel agents (security, extensibility, relevance), clone best match, iterate within proven structure.

## Performance

**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.

**Build troubleshooting:** Use build-error-resolver agent → analyze errors → fix incrementally → verify after each fix.

## Project Structure

```
agents/          — 68 specialized subagents
skills/          — 292 workflow skills and domain knowledge
commands/        — 94 slash commands
hooks/           — Trigger-based automations
rules/           — Always-follow guidelines (common + per-language)
scripts/         — Cross-platform Node.js utilities
mcp-configs/     — 14 MCP server configurations
tests/           — Test suite
```

`commands/` remains in the repo for compatibility, but the long-term direction is skills-first.

## Success Metrics

- All tests pass with 80%+ coverage
- No security vulnerabilities
- Code is readable and maintainable
- Performance is acceptable
- User requirements are met