Copilot instructions

1# Agent Orchestration
2 
3## Available Agents
4 
5Located in `~/.copilot/agents/`:
6 
7| Agent | Purpose | When to Use |
8|-------|---------|-------------|
9| planner | Implementation planning | Complex features, refactoring |
10| architect | System design | Architectural decisions |
11| tdd-guide | Test-driven development | New features, bug fixes |
12| code-reviewer | Code review | After writing code |
13| security-reviewer | Security analysis | Before commits |
14| build-error-resolver | Fix build errors | When build fails |
15| e2e-runner | E2E testing | Critical user flows |
16| refactor-cleaner | Dead code cleanup | Code maintenance |
17| doc-updater | Documentation | Updating docs |
18 
19## Immediate Agent Usage
20 
21No user prompt needed:
221. Complex feature requests - Use **planner** agent
232. Code just written/modified - Use **code-reviewer** agent
243. Bug fix or new feature - Use **tdd-guide** agent
254. Architectural decision - Use **architect** agent
26 
27## Parallel Task Execution
28 
29ALWAYS use parallel Task execution for independent operations:
30 
31```markdown
32# GOOD: Parallel execution
33Launch 3 agents in parallel:
341. Agent 1: Security analysis of auth module
352. Agent 2: Performance review of cache system
363. Agent 3: Type checking of utilities
37 
38# BAD: Sequential when unnecessary
39First agent 1, then agent 2, then agent 3
40```
41 
42## Multi-Perspective Analysis
43 
44For complex problems, use split role sub-agents:
45- Factual reviewer
46- Senior engineer
47- Security expert
48- Consistency reviewer
49- Redundancy checker
50 
51---
52 
53# Coding Style
54 
55## Immutability (CRITICAL)
56 
57ALWAYS create new objects, NEVER mutate existing ones:
58 
59```
60// Pseudocode
61WRONG:  modify(original, field, value) → changes original in-place
62CORRECT: update(original, field, value) → returns new copy with change
63```
64 
65Rationale: Immutable data prevents hidden side effects, makes debugging easier, and enables safe concurrency.
66 
67## File Organization
68 
69MANY SMALL FILES > FEW LARGE FILES:
70- High cohesion, low coupling
71- 200-400 lines typical, 800 max
72- Extract utilities from large modules
73- Organize by feature/domain, not by type
74 
75## Error Handling
76 
77ALWAYS handle errors comprehensively:
78- Handle errors explicitly at every level
79- Provide user-friendly error messages in UI-facing code
80- Log detailed error context on the server side
81- Never silently swallow errors
82 
83## Input Validation
84 
85ALWAYS validate at system boundaries:
86- Validate all user input before processing
87- Use schema-based validation where available
88- Fail fast with clear error messages
89- Never trust external data (API responses, user input, file content)
90 
91## Code Quality Checklist
92 
93Before marking work complete:
94- [ ] Code is readable and well-named
95- [ ] Functions are small (<50 lines)
96- [ ] Files are focused (<800 lines)
97- [ ] No deep nesting (>4 levels)
98- [ ] Proper error handling
99- [ ] No hardcoded values (use constants or config)
100- [ ] No mutation (immutable patterns used)
101 
102---
103 
104# Development Workflow
105 
106> This file extends [common/git-workflow.md](./git-workflow.md) with the full feature development process that happens before git operations.
107 
108The Feature Implementation Workflow describes the development pipeline: research, planning, TDD, code review, and then committing to git.
109 
110## Feature Implementation Workflow
111 
1120. **Research & Reuse** _(mandatory before any new implementation)_
113   - **GitHub code search first:** Run `gh search repos` and `gh search code` to find existing implementations, templates, and patterns before writing anything new.
114   - **Exa MCP for research:** Use `exa-web-search` MCP during the planning phase for broader research, data ingestion, and discovering prior art.
115   - **Check package registries:** Search npm, PyPI, crates.io, and other registries before writing utility code. Prefer battle-tested libraries over hand-rolled solutions.
116   - **Search for adaptable implementations:** Look for open-source projects that solve 80%+ of the problem and can be forked, ported, or wrapped.
117   - Prefer adopting or porting a proven approach over writing net-new code when it meets the requirement.
118 
1191. **Plan First**
120   - Use **planner** agent to create implementation plan
121   - Generate planning docs before coding: PRD, architecture, system_design, tech_doc, task_list
122   - Identify dependencies and risks
123   - Break down into phases
124 
1252. **TDD Approach**
126   - Use **tdd-guide** agent
127   - Write tests first (RED)
128   - Implement to pass tests (GREEN)
129   - Refactor (IMPROVE)
130   - Verify 80%+ coverage
131 
1323. **Code Review**
133   - Use **code-reviewer** agent immediately after writing code
134   - Address CRITICAL and HIGH issues
135   - Fix MEDIUM issues when possible
136 
1374. **Commit & Push**
138   - Detailed commit messages
139   - Follow conventional commits format
140   - See [git-workflow.md](./git-workflow.md) for commit message format and PR process
141 
142---
143 
144# Git Workflow
145 
146## Commit Message Format
147```
148<type>: <description>
149 
150<optional body>
151```
152 
153Types: feat, fix, refactor, docs, test, chore, perf, ci
154 
155Note: Attribution disabled globally via ~/.copilot/settings.json.
156 
157## Pull Request Workflow
158 
159When creating PRs:
1601. Analyze full commit history (not just latest commit)
1612. Use `git diff [base-branch]...HEAD` to see all changes
1623. Draft comprehensive PR summary
1634. Include test plan with TODOs
1645. Push with `-u` flag if new branch
165 
166> For the full development process (planning, TDD, code review) before git operations,
167> see [development-workflow.md](./development-workflow.md).
168 
169---
170 
171# Common Patterns
172 
173## Skeleton Projects
174 
175When implementing new functionality:
1761. Search for battle-tested skeleton projects
1772. Use parallel agents to evaluate options:
178   - Security assessment
179   - Extensibility analysis
180   - Relevance scoring
181   - Implementation planning
1823. Clone best match as foundation
1834. Iterate within proven structure
184 
185## Design Patterns
186 
187### Repository Pattern
188 
189Encapsulate data access behind a consistent interface:
190- Define standard operations: findAll, findById, create, update, delete
191- Concrete implementations handle storage details (database, API, file, etc.)
192- Business logic depends on the abstract interface, not the storage mechanism
193- Enables easy swapping of data sources and simplifies testing with mocks
194 
195### API Response Format
196 
197Use a consistent envelope for all API responses:
198- Include a success/status indicator
199- Include the data payload (nullable on error)
200- Include an error message field (nullable on success)
201- Include metadata for paginated responses (total, page, limit)
202 
203---
204 
205# Performance Optimization
206 
207## Model Selection Strategy
208 
209**Haiku 4.5** (90% of Sonnet capability, 3x cost savings):
210- Lightweight agents with frequent invocation
211- Pair programming and code generation
212- Worker agents in multi-agent systems
213 
214**Sonnet 4.6** (Best coding model):
215- Main development work
216- Orchestrating multi-agent workflows
217- Complex coding tasks
218 
219**Opus 4.5** (Deepest reasoning):
220- Complex architectural decisions
221- Maximum reasoning requirements
222- Research and analysis tasks
223 
224## Context Window Management
225 
226Avoid last 20% of context window for:
227- Large-scale refactoring
228- Feature implementation spanning multiple files
229- Debugging complex interactions
230 
231Lower context sensitivity tasks:
232- Single-file edits
233- Independent utility creation
234- Documentation updates
235- Simple bug fixes
236 
237## Extended Thinking + Plan Mode
238 
239Extended thinking is enabled by default, reserving up to 31,999 tokens for internal reasoning.
240 
241Control extended thinking via:
242- **Toggle**: Option+T (macOS) / Alt+T (Windows/Linux)
243- **Config**: Set `alwaysThinkingEnabled` in `~/.copilot/settings.json`
244- **Budget cap**: `export MAX_THINKING_TOKENS=10000`
245- **Verbose mode**: Ctrl+O to see thinking output
246 
247For complex tasks requiring deep reasoning:
2481. Ensure extended thinking is enabled (on by default)
2492. Enable **Plan Mode** for structured approach
2503. Use multiple critique rounds for thorough analysis
2514. Use split role sub-agents for diverse perspectives
252 
253## Build Troubleshooting
254 
255If build fails:
2561. Use **build-error-resolver** agent
2572. Analyze error messages
2583. Fix incrementally
2594. Verify after each fix
260 
261---
262 
263# Security Guidelines
264 
265## Mandatory Security Checks
266 
267Before ANY commit:
268- [ ] No hardcoded secrets (API keys, passwords, tokens)
269- [ ] All user inputs validated
270- [ ] SQL injection prevention (parameterized queries)
271- [ ] XSS prevention (sanitized HTML)
272- [ ] CSRF protection enabled
273- [ ] Authentication/authorization verified
274- [ ] Rate limiting on all endpoints
275- [ ] Error messages don't leak sensitive data
276 
277## Secret Management
278 
279- NEVER hardcode secrets in source code
280- ALWAYS use environment variables or a secret manager
281- Validate that required secrets are present at startup
282- Rotate any secrets that may have been exposed
283 
284## Security Response Protocol
285 
286If security issue found:
2871. STOP immediately
2882. Use **security-reviewer** agent
2893. Fix CRITICAL issues before continuing
2904. Rotate any exposed secrets
2915. Review entire codebase for similar issues
292 
293---
294 
295# Testing Requirements
296 
297## Minimum Test Coverage: 80%
298 
299Test Types (ALL required):
3001. **Unit Tests** - Individual functions, utilities, components
3012. **Integration Tests** - API endpoints, database operations
3023. **E2E Tests** - Critical user flows (framework chosen per language)
303 
304## Test-Driven Development
305 
306MANDATORY workflow:
3071. Write test first (RED)
3082. Run test - it should FAIL
3093. Write minimal implementation (GREEN)
3104. Run test - it should PASS
3115. Refactor (IMPROVE)
3126. Verify coverage (80%+)
313 
314## Troubleshooting Test Failures
315 
3161. Use **tdd-guide** agent
3172. Check test isolation
3183. Verify mocks are correct
3194. Fix implementation, not tests (unless tests are wrong)
320 
321## Agent Support
322 
323- **tdd-guide** - Use PROACTIVELY for new features, enforces write-tests-first
324 
325---