AGENTS.md

1---
2description: 'AI Agent Guidelines - map of all resources, quick-reference rules, and pointers to detailed docs.'
3applyTo: '**'
4---
5 
6# AI Agent Guidelines
7 
8> **Single source of truth for repository workflow guidance.**
9 
10> **Map to all AgentX resources.** For workflow details, see [docs/WORKFLOW.md](docs/WORKFLOW.md).
11> For agent role definitions, see individual files in `.github/agents/`.
12 
13---
14 
15## Retrieval-Led Reasoning
16 
17**IMPORTANT**: Prefer retrieval-led reasoning over pre-training-led reasoning for ALL implementation tasks.
18Always `read_file` the relevant SKILL.md, instruction file, or spec before generating code.
19Do NOT rely on training data for project-specific patterns, conventions, or APIs.
20If a skill, spec, or doc exists in the workspace, read it first; generate second.
21 
22---
23 
24## Quick Reference
25 
26### Issue-First Rule
27 
28Every piece of work SHOULD start with an issue. See [docs/WORKFLOW.md](docs/WORKFLOW.md) for full flow.
29 
30```bash
31# GitHub Mode
32gh issue create --title "[Story] Add /health" --label "type:story"  # Creates #42
33git commit -m "feat: add health endpoint (#42)"
34 
35# Local Mode (issues optional by default)
36git commit -m "feat: add user login"
37```
38 
39Toggle enforcement: `.agentx/agentx.ps1 config set enforceIssues true`
40 
41### Classification
42 
43| Type | Label | Route To |
44|------|-------|----------|
45| Broken? | `type:bug` | Engineer |
46| Research? | `type:spike` | Architect |
47| Docs only? | `type:docs` | Engineer |
48| Pipeline/deploy? | `type:devops` | DevOps Engineer |
49| ML/AI/eval? | `type:data-science` | Data Scientist |
50| Testing/cert? | `type:testing` | Tester |
51| Power BI? | `type:powerbi` | Power BI Analyst |
52| Large/vague? | `type:epic` | Product Manager |
53| Single capability? | `type:feature` | Architect |
54| Otherwise | `type:story` | Engineer |
55 
56### Commit Format
57 
58```
59type: description (#issue-number)
60```
61 
62Types: `feat`, `fix`, `docs`, `test`, `refactor`, `perf`, `chore`
63 
64For final delivery in GitHub mode, plain `(#123)` is traceability only. Use `fixes #123`, `closes #123`, or `resolves #123` in the final PR body or delivery commit so GitHub closes the issue automatically.
65 
66### Security Checklist
67 
68- [PASS] No hardcoded secrets
69- [PASS] SQL parameterization (NEVER concatenate)
70- [PASS] Input validation on all endpoints
71- [PASS] Dependencies scanned
72- Blocked commands: `rm -rf /`, `git reset --hard`, `drop database`
73 
74### Local Files First Rule
75 
76All agents MUST create deliverable files locally using `editFiles` -- MUST NOT use `mcp_github_create_or_update_file` or `mcp_github_push_files` to push files directly to GitHub. Users must be able to review files locally before committing.
77 
78### Quality Loop Hard Rule
79 
80> HARD RULE: Every agent MUST run `.agentx/agentx.ps1 loop start -p "<task description>"` as the ABSOLUTE FIRST action before any file edit or tool call. Minimum 5 iterations means at least 5 loop passes before completion is allowed; the loop is NOT done until `.agentx/agentx.ps1 loop complete -s "<summary>"` succeeds. No exceptions. The pre-commit hook blocks review artifacts when no completed loop exists.
81 
82> Cross-cutting concerns shared by all agents (quality loop + minimum 5 iterations, subagent review, per-iteration reporting, Karpathy, Model Council, Scrub, Brainstorm, Plan, Research) are defined ONCE in [.github/AGENT-PROTOCOL.md](.github/AGENT-PROTOCOL.md). Agent definition files keep only the front-loaded Pre-edit gate + Honesty rule stubs and point there; they MUST NOT restate the full prose.
83 
84### Compound Engineering Hard Rule
85 
86> HARD RULE: Every agent MUST resolve Compound Capture before declaring work Done. After delivery and review are complete, classify the capture decision:
87> - **Mandatory**: Work produces reusable workflow, architecture, review, or operator guidance -> create `docs/artifacts/learnings/LEARNING-<issue>.md`
88> - **Optional**: Narrow or low-leverage work -> capture is helpful but not required
89> - **Skip**: Trivial, transient, or duplicated -> record skip rationale in the issue close comment
90>
91> Work is NOT Done until Compound Capture is resolved. The pre-commit hook validates LEARNING file structure when staged. See [docs/WORKFLOW.md](docs/WORKFLOW.md) for the full Compound Capture contract.
92 
93### Pipeline Phase Compliance Hard Rule
94 
95> HARD RULE: Every agent MUST follow their prescribed pipeline phases IN SEQUENCE. No phase may be skipped. Each phase has a completion gate -- the gate MUST pass before advancing to the next phase. Agents MUST NOT write deliverables before completing research phases, MUST NOT implement before planning, MUST NOT approve before verifying all checks.
96>
97> See the Role Pipeline Reference table (below the Agents table) for each role's phases and key delivery gate. The pre-commit hook validates deliverable structure for key artifacts (PRD, ADR, UX). Use `.agentx/agentx.ps1 workflow <agent>` to print the phase list for any role.
98 
99### CLI Quick Reference
100 
101```powershell
102.\.agentx\agentx.ps1 loop start -p "Task description"  # FIRST command - start before any work
103.\.agentx\agentx.ps1 loop iterate -s "Progress summary"  # After each verification pass
104.\.agentx\agentx.ps1 loop complete -s "All gates passed"  # LAST command - required before handoff
105.\.agentx\agentx.ps1 ready                    # Show unblocked work
106.\.agentx\agentx.ps1 state -a engineer -s working -i 42
107.\.agentx\agentx.ps1 deps 42                  # Check blockers
108.\.agentx\agentx.ps1 workflow engineer        # Show workflow steps
109.\.agentx\agentx.ps1 loop status                # Check quality loop status
110.\.agentx\agentx.ps1 config show               # View configuration
111```
112 
113---
114 
115## Agents (24 total)
116 
117Agent definitions live in `.github/agents/*.agent.md` (13 visible) and `.github/agents/internal/*.agent.md` (11 internal sub-agents). Each file contains the role's constraints, boundaries, deliverables, and self-review checklist.
118 
119| Agent | File | Deliverable |
120|-------|------|-------------|
121| Agent X (Hub) | `agent-x.agent.md` | Autonomous orchestration and direct execution across the full workflow |
122| Product Manager | `product-manager.agent.md` | PRD at `docs/artifacts/prd/` |
123| UX Designer | `ux-designer.agent.md` | Wireframes + HTML prototypes at `docs/ux/` |
124| Architect | `architect.agent.md` | ADR + Tech Specs at `docs/artifacts/adr/`, `docs/artifacts/specs/` |
125| Engineer | `engineer.agent.md` | Code + Tests (80% coverage) |
126| Reviewer | `reviewer.agent.md` | Review at `docs/artifacts/reviews/` (code reviews + standalone architecture doc reviews) |
127| Auto-Fix Reviewer | `reviewer-auto.agent.md` | Review + safe auto-fixes |
128| DevOps Engineer | `devops.agent.md` | Pipelines at `.github/workflows/` |
129| Data Scientist | `data-scientist.agent.md` | ML pipelines + evals at `docs/data-science/` |
130| Tester | `tester.agent.md` | Test suites + certification at `docs/testing/` |
131| Power BI Analyst | `powerbi-analyst.agent.md` | Reports at `reports/`, `datasets/` |
132| Consulting Research | `consulting-research.agent.md` | Research briefs at `docs/coaching/` |
133| Agile Coach | `agile-coach.agent.md` | Stories at `docs/coaching/` |
134 
135**Internal sub-agents** (spawned by parent agents, not user-invokable):
136GitHub Ops, ADO Ops, AzDO PRD to WIT, Functional Reviewer, Architecture Reviewer, Prompt Engineer, Eval Specialist, Ops Monitor, RAG Specialist, Diagram Specialist, Prototype Auditor.
137 
138---
139 
140## Role Pipeline Reference
141 
142Each role follows a prescribed phase pipeline. All phases are mandatory. No phase may be skipped without an explicit documented reason. The pre-commit hook validates artifact structure for PRD, ADR, and UX deliverables as a mechanical enforcement layer.
143 
144| Role | Pipeline Phases (in order) | Key Delivery Gate |
145|------|---------------------------|-------------------|
146| **Agent X (Hub)** | Classify -> Route -> Execute specialist phases -> Validate handoffs | All specialist phase gates pass before advancing |
147| **Product Manager** | Research (5 phases) -> Classify Intent -> Model Council (prd-scope) -> PRD -> Backlog (Epic, Feature, User Stories) -> Self-Review -> Commit | PRD has all required sections; Backlog items (Epic, Features, User Stories) linked to PRD; Model Council convened or skip rationale recorded |
148| **UX Designer** | Read PRD -> Design Research -> UX Spec -> HTML/CSS Prototypes -> Self-Review -> Commit | WCAG 2.1 AA prototypes exist at `docs/ux/prototypes/` |
149| **Architect** | Research (6 phases) -> ADR (3+ options) -> Model Council (adr-options) -> Tech Spec -> AI Spec Alignment (if `needs:ai`) -> PM Fit Validation -> GenAI Assessment -> Self-Review -> Commit | ADR + Spec exist; ADR Decision matches a council-consensus option (or override rationale documented); AI-bearing specs include Data Scientist implementation-depth alignment; PM requirement-fit validation complete; zero code examples in Spec |
150| **Engineer** | Research -> Brainstorm -> Plan -> Design -> Conditional Design Alignment -> Implement -> Test -> Review | Loop complete + coverage >=80% + score >=70% + required Architect/Data Scientist alignment captured |
151| **Reviewer** | Read Context -> Verify Loop -> Functional Review -> Code Review -> Run Tests -> Model Council (code-review) -> Write Review -> Decision | Review doc complete; approval/rejection explicitly stated; Model Council convened or skip rationale recorded; Findings/Severity/Decision reflect council Synthesis (or override rationale documented) |
152| **Auto-Fix Reviewer** | Read Context -> Verify Loop -> Review Code -> Apply Safe Fixes -> Document -> Self-Review -> Decision | All auto-fixes pass full test suite; review doc complete |
153| **DevOps Engineer** | Read Context -> Design Pipeline -> Implement Workflows -> Validate -> Self-Review -> Commit | Pipelines pass lint + execution; deployment docs updated |
154| **Data Scientist** | Research (6 phases) -> Model Council (ai-design) -> Pipeline Design -> Eval Plan -> Implementation -> Drift Monitoring -> Self-Review -> Commit | Eval baseline + model card exist; Model Council convened or skip rationale recorded |
155| **Tester** | Read Context -> Write Tests -> Execute Suite -> Report Defects -> Certification Report -> Commit | Test pyramid complete; certification report signed off |
156| **Power BI Analyst** | Read Context -> Semantic Model -> DAX Measures -> Power Query -> Report Layout -> Optimize -> Docs -> Self-Review -> Commit | Semantic model validated; DAX measures tested |
157| **Consulting Research** | Understand Request -> Research (7 phases) -> Model Council (research) -> Calibrate Audience -> Create Deliverable | All key claims sourced + triangulated; deliverable complete; Model Council convened or skip rationale recorded |
158| **Agile Coach** | Mode Selection -> Create/Refine/Decompose Story -> Confirm -> Output | INVEST criteria met; ACs in Given/When/Then format |
159 
160---
161 
162## Deep References
163 
164| Document | Purpose |
165|----------|---------|
166| [docs/WORKFLOW.md](docs/WORKFLOW.md) | Workflow, routing, handoff, status transitions, architecture |
167| [Skills.md](Skills.md) | 128 production code skills index (load only relevant skills per task) |
168| [docs/GUIDE.md](docs/GUIDE.md) | Quickstart, setup, troubleshooting, local mode |
169| [docs/QUALITY_SCORE.md](docs/QUALITY_SCORE.md) | Graded quality assessment of every component |
170| [docs/GOLDEN_PRINCIPLES.md](docs/GOLDEN_PRINCIPLES.md) | Mechanical rules enforced by linters and agents |
171| [docs/tech-debt-tracker.md](docs/tech-debt-tracker.md) | Known gaps and deferred work |
172| `.github/agents/` | 21 agent definition files |
173| `.github/skills/` | 128 skill files across 14 categories |
174| `.github/instructions/` | 7 instruction files (auto-loaded by file pattern) |
175| `.github/schemas/` | Handoff message JSON Schema + communication protocol |
176| `.github/templates/` | 15 templates (PRD, ADR, Spec, UX, Review, Arch Review, Security Plan, Progress, Roadmap, Exec Plan, Contract, Evidence Summary, Backlog, Design System, Learning) |
177| `.github/prompts/` | 21 reusable prompt templates |
178| `.agentx/` | CLI utilities (agentx.ps1, agentx.sh, agentic-runner.ps1) |
179| `scripts/modules/` | Shared PowerShell modules |
180| `packs/` | Agent pack bundles |
181 
182### Instruction Files (Auto-Loaded)
183 
184| Instruction | Triggers on |
185|-------------|-------------|
186| `ai.instructions.md` | `*agent*`, `*llm*`, `*model*`, `*workflow*`, `agents/` |
187| `python.instructions.md` | `*.py`, `*.pyx` |
188| `csharp.instructions.md` | `*.cs`, `*.csx` |
189| `typescript.instructions.md` | `*.ts` (backend/server TypeScript) |
190| `react.instructions.md` | `*.tsx`, `*.jsx`, `components/`, `hooks/` |
191| `memory.instructions.md` | `**` (all files) |
192| `project-conventions.instructions.md` | `**` (all files) |
193 
194---
195 
196## ASCII-Only Rule
197 
198All source code, scripts, configuration files, and documentation MUST use ASCII characters only (U+0000-U+007F). Use `[PASS]` not checkmarks, `[FAIL]` not cross marks, `->` not arrows, `-` not em-dashes.
199 
200## Directive Language (RFC 2119)
201 
202- **MUST** / **MUST NOT** - Absolute requirement or prohibition
203- **SHOULD** / **SHOULD NOT** - Strong recommendation (exceptions need justification)
204- **MAY** - Truly optional
205