Copilot instructions

1# GitHub Copilot Instructions
2 
3These instructions apply to all Copilot completions, suggestions, and chat interactions in this repository.
4 
5## The Four Laws of Agent Safety
6 
71. **Read Before Editing** - Never suggest modifications without reading the file first
82. **Stay in Scope** - Only work on files within the authorized task scope
93. **Verify Before Committing** - Ensure suggested code compiles, passes lint, and is tested
104. **Halt When Uncertain** - Ask for clarification instead of guessing
11 
12## Code Generation Rules
13 
14### Scope (MANDATORY)
15 
16- Only modify files explicitly requested by the user
17- Do not refactor unrelated code "while I'm here"
18- Do not add new files unless asked
19- Do not delete files unless asked
20- When scope is unclear: ask for confirmation
21 
22### Production-First
23 
24- Production code must be written before test code
25- Tests written against existing production code, not stubs
26- Infrastructure code comes after both production and tests
27 
28### Error Handling
29 
30- Validate inputs and handle errors explicitly
31- Return meaningful error messages
32- Never silently swallow exceptions
33- Prefer explicit error returns over panics/exceptions
34 
35### Security
36 
37- Never suggest committing secrets, keys, or credentials
38- Never suggest .env files in version control
39- Validate all external inputs
40- Use parameterized queries, never string concatenation for SQL
41 
42## Forbidden Patterns
43 
44NEVER suggest code that:
45- Modifies files that haven't been read
46- Mixes test and production environments
47- Commits secrets or credentials
48- Runs untested code in production
49- Makes assumptions about user intent
50 
51## Three Strikes Rule
52 
53When a suggestion is rejected or produces errors:
54- 1st failure: Adjust approach and retry
55- 2nd failure: Try completely different approach
56- 3rd failure: HALT and ask user for guidance
57 
58## File Headers
59 
60Include at the top of new files:
61 
62```go
63// File: <filename>
64// Purpose: <one-line description>
65// Created: <date>
66// Author: AI-assisted (see git history)
67```
68 
69Or equivalent in the target language.
70 
71## Architecture Patterns (Go/MCP Server)
72 
73When working on `mcp-server/`:
74 
75### Layer Order (Inside-Out)
76 
771. **Domain** (`internal/domain/`) — Interfaces, value objects, ZERO external deps
782. **Application** — Command/query handlers
793. **Adapters** (`internal/adapters/`) — Infrastructure implementations
804. **Interface** (`internal/mcp/`) — MCP handlers
81 
82### Dependency Rule
83 
84Outer layers depend inward. Domain is pure — no database, no HTTP imports.
85 
86### CQRS Pattern
87 
88| Commands (Write) | Queries (Read) |
89|-----------------|----------------|
90| Create | Evaluate |
91| Update | List |
92| Delete | Get |
93| Toggle | GetViolations |
94 
95Commands: validate → persist → publish event (cache invalidation)
96Queries: cache-first, no state modification
97 
98### Vertical Slices
99 
100Group all code for one feature together:
101 
102```
103internal/guardrails/
104├── bash/           ← model + evaluator + handler
105├── git/
106└── fileedit/
107```
108 
109### SOLID
110 
111- **S**: One responsibility per type
112- **O**: Add new evaluator via interface, don't modify existing code
113- **L**: Implement interfaces fully
114- **I**: Small focused interfaces
115- **D**: Depend on interface, not concrete type
116 
117### Forbidden (Architecture)
118 
119- Importing database packages in domain types
120- Putting concrete implementations in domain layer
121- Cross-layer circular dependencies
122- Adding infrastructure logic in handlers
123 
124## References
125 
126- `skills/shared-prompts/four-laws.md` - The Four Laws (canonical)
127- `skills/shared-prompts/clean-architecture.md` - Clean Architecture patterns
128- `skills/shared-prompts/cqrs.md` - CQRS details
129- `docs/AGENT_GUARDRAILS.md` - Core safety protocols
130- `docs/standards/TEST_PRODUCTION_SEPARATION.md` - Environment isolation
131- `docs/workflows/COMMIT_WORKFLOW.md` - Commit standards
132