Copilot instructions

1---
2description: 'AI and ML specific coding instructions for building AI agents, LLM integrations, and intelligent workflows.'
3applyTo: '**/*agent*, **/*llm*, **/*model*, **/*workflow*, **/agents/**, **/*ai*'
4---
5 
6# AI & Agent Development Instructions
7 
8> Auto-loads when editing agent/LLM/workflow files. For comprehensive standards, load the skill.
9 
10**Skill**: [.github/skills/ai-systems/ai-agent-development/SKILL.md](../skills/ai-systems/ai-agent-development/SKILL.md)
11 
12## Quality Loop Gate (read before editing)
13 
14Before editing any agent definition, prompt, workflow, or LLM-integration file, run `.agentx/agentx.ps1 loop start -p "<task>"` as your ABSOLUTE FIRST tool call. Close with `.agentx/agentx.ps1 loop complete -s "<summary>"` once a subagent review iteration has passed. The pre-commit hook blocks commits when the loop is missing or incomplete. See [.github/copilot-instructions.md](../copilot-instructions.md#quality-loop-hard-rule-non-skippable) for the full rule.
15 
16## Mandatory Workflow Gates (read before editing)
17 
18Four additional rules carry the same weight as the Quality Loop and are hard-failed by the pre-commit hook:
19 
20- **Compound Capture**: APPROVED review staged -> matching `docs/artifacts/learnings/LEARNING-<issue>.md` MUST also be staged, or commit msg tagged `[skip-capture]`.
21- **Model Council (MANDATORY, NO SKIP)**: New `docs/artifacts/adr/ADR-*.md` staged -> matching `docs/artifacts/adr/COUNCIL-*.md` MUST also be staged (3 diverse models + Synthesis). Mandatory for Product Manager (prd-scope), Architect (adr-options), and any complex task; also Data Scientist (ai-design), Reviewer (code-review), Consulting Research. The pre-commit hook hard-fails when the COUNCIL file is missing; there is no skip token.
22- **Execution Plan**: Commits changing >= 8 code files MUST stage a matching `docs/execution/plans/EXEC-PLAN-*.md`, or commit msg tagged `[skip-plan]`.
23- **Brainstorm (Engineer)**: `Research -> Brainstorm -> Plan -> ...` pipeline is mandatory; Brainstorm step is satisfied by a `brainstorm` ledger entry or `## Alternatives Considered` in the execution plan **before** Plan.
24 
25See [.github/copilot-instructions.md](../copilot-instructions.md#mandatory-workflow-gates-non-skippable) for the canonical block.
26 
27## Key Rules
28 
29- **Never** hardcode API keys, endpoints, or model names -- use env vars
30- Use `.env` for local dev (always in `.gitignore`), Key Vault or managed identity in prod
31- Always define response schemas for LLM calls (Pydantic / record types)
32- Implement retry with exponential backoff for all model API calls
33- Set explicit timeouts on all model invocations
34- Handle rate limits (HTTP 429) with backoff
35- Enable OpenTelemetry tracing for agent operations
36- Log: prompt tokens, completion tokens, latency, model name
37- Keep system prompts in separate files, not inline strings
38- Version control all prompts alongside code
39- **MUST** pin model versions explicitly (e.g., `gpt-5.1-2026-01-15`, not `gpt-5.1`)
40- **MUST** test against minimum 2 models (primary + fallback from different provider)
41- **MUST** run evaluation baselines before any model change
42- Mock model calls in unit tests -- never call live APIs in CI
43- Validate and sanitize all user inputs before sending to models
44- Review OWASP AI Top 10 for threat modeling
45