Copilot instructions

1---
2description: 'Global instructions for GitHub Copilot across the entire repository.'
3applyTo: '**'
4---
5 
6# Global Copilot Instructions
7 
8This file is the **thin router** - it tells you what to load and when. It loads every conversation, so it stays small.
9 
10---
11 
12## Quality Loop Hard Rule (NON-SKIPPABLE)
13 
14> **HARD RULE**: Before editing, creating, or deleting any file for a code or docs change, run `.agentx/agentx.ps1 loop start -p "<task>"` as your ABSOLUTE FIRST tool call. Reading files and running `loop status` are allowed; mutating the workspace before `loop start` succeeds is a contract violation. The loop is NOT done until `.agentx/agentx.ps1 loop complete -s "<summary>"` succeeds, and at least one history iteration summary must contain the word "review" (subagent review pass). The pre-commit hook blocks commits when these conditions are unmet.
15>
16> **Minimum 5 iterations**: EVERY agent and task class requires at least 5 quality iterations before `loop complete` is allowed (enforced by the loop CLI, agentic runner, extension runtime, and pre-commit hook). Report each iteration with `loop iterate -s "..."`, then summarize before completing.
17>
18> **Cross-Cutting Agent Protocol**: The shared rules (quality loop, subagent review, per-iteration reporting, Karpathy, Model Council, Scrub, Brainstorm, Plan, Research) are defined ONCE in [.github/AGENT-PROTOCOL.md](AGENT-PROTOCOL.md). Agent files keep only the front-loaded Pre-edit gate + Honesty rule stubs and point there.
19>
20> **Honesty rule**: If asked whether the loop ran, run `.agentx/agentx.ps1 loop status` and report the actual state. Do not claim completion unless `loop complete` succeeded in the current session.
21>
22> Frontmatter-only enforcement is insufficient -- this rule lives here in body prose because models routinely skip rules placed only in deeper docs.
23 
24---
25 
26## Mandatory Workflow Gates (NON-SKIPPABLE)
27 
28These four rules carry the same weight as the Quality Loop. The pre-commit hook hard-fails commits that violate them. Bypass tokens exist for genuine emergencies only.
29 
30> **Compound Capture (Done gate)**: Any commit that stages an APPROVED review under `docs/artifacts/reviews/REVIEW-*.md` MUST also stage the matching `docs/artifacts/learnings/LEARNING-<issue>.md`, OR record a skip rationale in the issue close comment and tag the commit message with `[skip-capture]`. Work is NOT Done until Compound Capture is resolved. See [AGENTS.md#compound-engineering-hard-rule](../AGENTS.md#compound-engineering-hard-rule).
31>
32> **Model Council (ADR/PRD/Eval gate -- MANDATORY, NO SKIP)**: Any commit that stages a new `docs/artifacts/adr/ADR-*.md` MUST also stage a matching `docs/artifacts/adr/COUNCIL-*.md` capturing 3 diverse-model perspectives and a Synthesis section. Mandatory for Product Manager (prd-scope), Architect (adr-options), and any complex task; also Data Scientist (ai-design), Reviewer (code-review), and Consulting Research. There is no skip token -- the pre-commit hook hard-fails when the COUNCIL file is missing. See [AGENTS.md#role-pipeline-reference](../AGENTS.md#role-pipeline-reference).
33>
34> **Execution Plan (complex-work gate)**: Any commit changing **8 or more** code files (`.ts/.tsx/.js/.ps1/.py/.cs/.go/.rs/.tf/.bicep/.sql`) MUST stage a corresponding `docs/execution/plans/EXEC-PLAN-*.md` derived from [.github/templates/EXEC-PLAN-TEMPLATE.md](../.github/templates/EXEC-PLAN-TEMPLATE.md), OR tag the commit message with `[skip-plan]`. Plans are living documents and MUST be updated, not only authored. See [docs/WORKFLOW.md#execution-plans-for-complex-work](../docs/WORKFLOW.md#execution-plans-for-complex-work).
35>
36> **Brainstorm (Engineer pre-Plan gate)**: When acting in the Engineer phase on non-trivial work, the `Research -> Brainstorm -> Plan -> Design -> Implement -> Test -> Review` pipeline is mandatory. The Brainstorm step is satisfied by recording at least one entry of type `brainstorm` in the clarification ledger OR an `## Alternatives Considered` block inside the execution plan **before** Plan is written. This step has no missing-file hook gate; reviewers MUST verify it during the review phase. See [AGENTS.md#pipeline-phase-compliance-hard-rule](../AGENTS.md#pipeline-phase-compliance-hard-rule).
37 
38**Honesty rule**: If asked whether any of these gates ran, inspect the staged files and commit message and report the actual state. Never claim a gate was satisfied without the artifact or skip token.
39 
40---
41 
42## Retrieval-Led Reasoning
43 
44**IMPORTANT**: Prefer retrieval-led reasoning over pre-training-led reasoning for ALL implementation tasks.
45Always `read_file` the relevant SKILL.md, instruction file, or spec before generating code.
46Do NOT rely on training data for project-specific patterns, conventions, or APIs.
47If a skill, spec, or doc exists in the workspace, read it first; generate second.
48 
49---
50 
51## Context Loading Rules
52 
53**Load context on-demand, not upfront.** Match the task to the right documents:
54 
55| Task | Load | Skip |
56|------|------|------|
57| Writing/editing code in existing files | [AGENTS.md](../AGENTS.md) + Language instruction (auto via `applyTo`) + relevant skills | Skills not matching task |
58| Creating new files, features, issues | [AGENTS.md](../AGENTS.md) (workflow + classification) | Skills not matching task |
59| Multi-agent coordination, handoffs | [AGENTS.md](../AGENTS.md) + [docs/WORKFLOW.md](../docs/WORKFLOW.md) | Unrelated skills |
60| Answering questions, research | Nothing extra - use tools | AGENTS.md, Skills.md |
61| Debugging | Language instruction + error handling skill | AGENTS.md |
62 
63**Token budget**: Load only the skills relevant to the task and active phase. Use [Skills.md Quick Reference](../Skills.md) to pick the right ones.
64 
65---
66 
67## When to Read AGENTS.md
68 
69Read [AGENTS.md](../AGENTS.md) for **any coding or workflow task** - it contains classification, commit format, and security checklist. For workflow details, routing, and handoff rules, see [docs/WORKFLOW.md](../docs/WORKFLOW.md).
70 
71> **Skip AGENTS.md** for: answering questions, research, and debugging only.
72 
73---
74 
75## Issue-First Rule
76 
77When AGENTS.md applies (see above), follow the issue-first workflow:
781. Create issue **before** starting work (no retroactive issues)
792. Update status: `Backlog -> In Progress -> In Review -> Done`
803. Reference issue in commits: `type: description (#ID)`
81 
82> **Note**: In Local Mode, issue enforcement is **optional** by default. Toggle with `agentx config set enforceIssues true`.
83 
84---
85 
86## Instruction Files (Auto-Loaded)
87 
88These load automatically when editing matching files - no manual action needed:
89 
90| Instruction | Triggers on |
91|-------------|-------------|
92| `ai.instructions.md` | `*agent*`, `*llm*`, `*model*`, `*workflow*`, `agents/` |
93| `python.instructions.md` | `*.py`, `*.pyx` |
94| `csharp.instructions.md` | `*.cs`, `*.csx` |
95| `typescript.instructions.md` | `*.ts` (backend/server TypeScript) |
96| `react.instructions.md` | `*.tsx`, `*.jsx`, `components/`, `hooks/` |
97 
98For file types not listed above, load the matching **skill** on demand from [Skills.md](../Skills.md):
99`*.tf`/`*.tfvars` -> `infrastructure/terraform`, `*.bicep`/`*.bicepparam` -> `infrastructure/bicep`,
100`*.razor` -> `languages/blazor`, `*.sql` -> `languages/sql-server` + `languages/postgresql`,
101`*.yml`/`*.yaml` -> `operations/yaml-pipelines` + `operations/github-actions-workflows`,
102`Controllers/`/`api/` -> `architecture/api-design`, `**/ux/**` -> `design/ux-ui-design`.
103 
104---
105 
106## Session State
107 
108- `manage_todo_list` - Track tasks within current session
109- `get_changed_files` - Review uncommitted work before commits
110- `get_errors` - Check compilation state after changes
111 
112---
113 
114## Reference
115 
116- **Workflows & Agent Roles**: [AGENTS.md](../AGENTS.md) (map) + [docs/WORKFLOW.md](../docs/WORKFLOW.md) (workflow details)
117- **Skills Index**: [Skills.md](../Skills.md) (use Quick Reference to pick skills)
118- **Quality & Debt**: [docs/QUALITY_SCORE.md](../docs/QUALITY_SCORE.md) | [docs/tech-debt-tracker.md](../docs/tech-debt-tracker.md)
119- **Golden Principles**: [docs/GOLDEN_PRINCIPLES.md](../docs/GOLDEN_PRINCIPLES.md)
120- **Frontmatter Validation**: `pwsh scripts/validate-frontmatter.ps1`
121 
122## ASCII-Only Rule
123 
124All source code, scripts, configuration files, and documentation in this repository **MUST** use ASCII characters only (U+0000-U+007F). This applies to all `.ps1`, `.sh`, `.py`, `.ts`, `.js`, `.yml`, `.yaml`, `.json`, and `.md` files.
125 
126- **MUST NOT** use emoji, Unicode symbols, box-drawing characters, or any non-ASCII characters
127- **MUST** use ASCII equivalents: `[PASS]` not check marks, `[FAIL]` not cross marks, `[WARN]` not warning symbols, `->` not arrows, `+=-|` not box-drawing, `"` not smart quotes
128- **MUST** use plain ASCII dashes (`-`) instead of em-dashes or en-dashes
129- **MUST** use `[1]`, `[2]`, `[3]` instead of circled numbers
130 
131This ensures cross-platform compatibility and prevents encoding issues in terminals, CI/CD pipelines, and editors.
132 
133---
134 
135## Directive Language (RFC 2119)
136 
137All instruction files use RFC 2119 keywords:
138- **MUST** / **MUST NOT** - Absolute requirement or prohibition
139- **SHOULD** / **SHOULD NOT** - Strong recommendation (exceptions need justification)
140- **MAY** - Truly optional, at developer discretion
141