Agent Instructions

This is a production-ready AI coding plugin providing 18 specialized agents, 28 skills, and automated hook workflows for software development.

Version: 2.0.0-rc.1

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 Orchestration

Use agents proactively without user prompt:

• Complex feature requests → planner
• Code just written/modified → code-reviewer
• Bug fix or new feature → tdd-guide
• Architectural decision → architect
• Security-sensitive code → security-reviewer
• Performance bottlenecks → performance-optimizer
• SEO improvements → seo-specialist

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

Web Research Tooling

When web search, web crawling, or full-page extraction is needed, use Firecrawl MCP as the primary web data provider whenever it is available. If Firecrawl tools are not already loaded, discover them through tool_search first, then use the Firecrawl search, scrape, crawl, or extract tool that matches the task.

Use more specific documentation tools before general web search when they apply:

• OpenAI docs tooling for OpenAI product/API questions.
• Context7 or docs-lookup for library, framework, SDK, CLI, and cloud-service documentation.
• Supabase docs/MCP tooling for Supabase-specific schema, auth, RLS, Edge Function, CLI, and platform questions.

Use the built-in web search/browser tools only for quick lightweight lookups, specialized built-in data tools such as finance/weather/sports/time, opening a known URL, or as a fallback when Firecrawl or the more specific docs tool is unavailable or fails.

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 planner agent, identify dependencies and risks, break into phases
2. TDD — Use tdd-guide agent, write tests first, implement, refactor
3. Review — Use 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

• contexts/ is the team-facing home for agent-related project assets.
• .agents/skills/ remains the runtime-loaded skill surface.
• Keep root-level AI docs limited to AGENTS.md, RULES.md, and tool manifests.
• New workflow contributions should land in the organized surfaces above instead of adding new root directories.

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

contexts/
  agents/        — team-maintained agent definitions
  rules/         — always-follow guidance by stack/domain
  baseline/      — base rules, standards, and templates for new projects and agents
.agents/
  skills/        — runtime-loaded skills and plugin asset

Success Metrics

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