CLAUDE.md

1# CLAUDE.md - Entry Point for Claude Code
2 
3> This file is the equivalent of `.github/copilot-instructions.md` for Claude Code.
4> It loads once at session start. Keep it small -- point to detailed docs, don't duplicate them.
5 
6---
7 
8## Quality Loop Hard Rule (NON-SKIPPABLE)
9 
10> **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.
11>
12> **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.
13>
14> **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.
15>
16> **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](.github/AGENT-PROTOCOL.md). Agent files keep only the front-loaded Pre-edit gate + Honesty rule stubs and point there.
17>
18> Frontmatter-only enforcement is insufficient -- this rule lives here in body prose because models routinely skip rules placed only in deeper docs.
19 
20---
21 
22## Mandatory Workflow Gates (NON-SKIPPABLE)
23 
24These 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.
25 
26> **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).
27>
28> **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).
29>
30> **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).
31>
32> **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).
33 
34**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.
35 
36---
37 
38## Core Documents (Read Before Coding)
39 
401. **[AGENTS.md](AGENTS.md)** - Map of all resources, quick-reference rules, pointers to detailed docs. Read for ANY coding or workflow task.
412. **[docs/WORKFLOW.md](docs/WORKFLOW.md)** - Workflow, routing, handoff, status transitions, architecture. Read for multi-agent coordination.
423. **[Skills.md](Skills.md)** - Production code standards index. Use the Quick Reference table to pick only the skills relevant to the task and active phase, then read those SKILL.md files.
43 
44**When to skip AGENTS.md**: Answering questions, research, debugging only.
45 
46---
47 
48## Retrieval-Led Reasoning
49 
50**IMPORTANT**: Prefer retrieval-led reasoning over pre-training-led reasoning for ALL implementation tasks.
51Always `read_file` the relevant SKILL.md, instruction file, or spec before generating code.
52Do NOT rely on training data for project-specific patterns, conventions, or APIs.
53If a skill, spec, or doc exists in the workspace, read it first; generate second.
54 
55---
56 
57## Context Loading Rules
58 
59Load context on-demand, not upfront. Match the task to the right documents:
60 
61| Task | Load | Skip |
62|------|------|------|
63| Writing/editing code | AGENTS.md + matching instruction file + relevant skills | Skills not matching task |
64| Creating new files, features, issues | AGENTS.md (workflow + classification) | Unrelated skills |
65| Multi-agent coordination, handoffs | AGENTS.md + [docs/WORKFLOW.md](docs/WORKFLOW.md) | Unrelated skills |
66| Answering questions, research | Nothing extra | AGENTS.md, Skills.md |
67| Debugging | Matching instruction file + error handling skill | AGENTS.md |
68 
69**Token budget**: Load only the skills relevant to the task and active phase. Prefer progressive disclosure over broad context loading.
70 
71---
72 
73## Context Loading
74 
75### Session-Persistent Instructions (load at session start)
76 
77Read these two files at the start of EVERY session -- they apply to all tasks:
78 
79- [.github/instructions/memory.instructions.md](.github/instructions/memory.instructions.md) -- memory read/write protocol
80- [.github/instructions/project-conventions.instructions.md](.github/instructions/project-conventions.instructions.md) -- learned project conventions
81 
82### Instruction Files (5 remaining -- load on demand)
83 
84| File Pattern | Read This |
85|--------------|-----------|
86| `*agent*`, `*llm*`, `*workflow*` | [.github/instructions/ai.instructions.md](.github/instructions/ai.instructions.md) |
87| `*.py`, `*.pyx` | [.github/instructions/python.instructions.md](.github/instructions/python.instructions.md) |
88| `*.cs`, `*.csx` | [.github/instructions/csharp.instructions.md](.github/instructions/csharp.instructions.md) |
89| `*.ts` (backend) | [.github/instructions/typescript.instructions.md](.github/instructions/typescript.instructions.md) |
90| `*.tsx`, `*.jsx`, `components/`, `hooks/` | [.github/instructions/react.instructions.md](.github/instructions/react.instructions.md) |
91 
92### Skills (load directly for domains without instructions)
93 
94| File Pattern | Load Skill |
95|--------------|------------|
96| `*.tf`, `*.tfvars` | [.github/skills/infrastructure/terraform/SKILL.md](.github/skills/infrastructure/terraform/SKILL.md) |
97| `*.bicep`, `*.bicepparam` | [.github/skills/infrastructure/bicep/SKILL.md](.github/skills/infrastructure/bicep/SKILL.md) |
98| `*.razor`, `*.razor.cs` | [.github/skills/languages/blazor/SKILL.md](.github/skills/languages/blazor/SKILL.md) |
99| `*.sql`, `migrations/` | [.github/skills/languages/sql-server/SKILL.md](.github/skills/languages/sql-server/SKILL.md) + [.github/skills/languages/postgresql/SKILL.md](.github/skills/languages/postgresql/SKILL.md) |
100| `*.yml`, `*.yaml`, `workflows/` | [.github/skills/operations/yaml-pipelines/SKILL.md](.github/skills/operations/yaml-pipelines/SKILL.md) + [.github/skills/operations/github-actions-workflows/SKILL.md](.github/skills/operations/github-actions-workflows/SKILL.md) |
101| `Controllers/`, `api/`, `endpoints/` | [.github/skills/architecture/api-design/SKILL.md](.github/skills/architecture/api-design/SKILL.md) |
102| `**/ux/**`, `**/prototypes/**` | [.github/skills/design/ux-ui-design/SKILL.md](.github/skills/design/ux-ui-design/SKILL.md) |
103 
104---
105 
106## Issue-First Workflow
107 
108Every piece of work SHOULD start with an issue. Issue enforcement depends on mode:
109- **GitHub Mode**: Issue references in commits are **required** (teams need traceability)
110- **Local Mode**: Issue references are **optional** by default (solo developers can commit freely)
111- Toggle: `.agentx/agentx.ps1 config set enforceIssues true` (or `false`)
112 
113```bash
114# GitHub Mode
115gh issue create --title &quot;[Story] Add /health endpoint&quot; --label &quot;type:story&quot;
116# Work...
117git commit -m &quot;feat: add health endpoint (#42)"
118gh issue close 42 --reason completed
119```
120 
121```bash
122# Local Mode (issues optional - commit freely)
123git commit -m &quot;feat: add user login&quot;
124 
125# Or use full issue workflow if preferred:
126./.agentx/local-issue-manager.ps1 -Action create -Title &quot;[Bug] Fix timeout&quot; -Labels &quot;type:bug&quot;
127git commit -m &quot;fix: resolve login timeout (#1)"
128./.agentx/local-issue-manager.ps1 -Action close -IssueNumber 1
129```
130 
131---
132 
133## Classification
134 
135| Type | Label | Route To |
136|------|-------|----------|
137| Broken? | `type:bug` | Engineer |
138| Research? | `type:spike` | Architect |
139| Docs only? | `type:docs` | Engineer |
140| Pipeline/deploy? | `type:devops` | DevOps Engineer |
141| Testing/certification? | `type:testing` | Tester |
142| Large/vague? | `type:epic` | Product Manager |
143| Single capability? | `type:feature` | Architect |
144| Otherwise | `type:story` | Engineer |
145 
146---
147 
148## Commit Format
149 
150```
151type: description (#issue-number)
152```
153 
154Types: `feat`, `fix`, `docs`, `test`, `refactor`, `perf`, `chore`
155 
156---
157 
158## ASCII-Only Rule
159 
160All source code, scripts, config, and documentation MUST use ASCII characters only (U+0000-U+007F).
161 
162- MUST NOT use emoji, Unicode symbols, box-drawing characters, smart quotes
163- MUST use ASCII equivalents: `[PASS]` not checkmarks, `[FAIL]` not cross marks, `->` not arrows, `-` not em-dashes
164 
165---
166 
167## Security Checklist
168 
169Before any commit:
170 
171- [ ] No hardcoded secrets
172- [ ] SQL parameterization (no string concatenation)
173- [ ] Input validation on all endpoints
174- [ ] Dependencies scanned
175 
176**Blocked commands**: `rm -rf /`, `git reset --hard`, `drop database`
177 
178### Local Files First Rule
179 
180All 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.
181 
182---
183 
184## Directive Language
185 
186- **MUST** / **MUST NOT** - Absolute requirement or prohibition
187- **SHOULD** / **SHOULD NOT** - Strong recommendation (exceptions need justification)
188- **MAY** - Truly optional
189 
190---
191 
192## Agent Definitions
193 
194Agent role files are at `.github/agents/`. Load only the active agent's definition:
195 
196| Agent | Definition |
197|-------|-----------|
198| Agent X (Hub) | [.github/agents/agent-x.agent.md](.github/agents/agent-x.agent.md) |
199| Product Manager | [.github/agents/product-manager.agent.md](.github/agents/product-manager.agent.md) |
200| UX Designer | [.github/agents/ux-designer.agent.md](.github/agents/ux-designer.agent.md) |
201| Architect | [.github/agents/architect.agent.md](.github/agents/architect.agent.md) |
202| Engineer | [.github/agents/engineer.agent.md](.github/agents/engineer.agent.md) |
203| Reviewer | [.github/agents/reviewer.agent.md](.github/agents/reviewer.agent.md) |
204| Auto-Fix Reviewer | [.github/agents/reviewer-auto.agent.md](.github/agents/reviewer-auto.agent.md) |
205| DevOps Engineer | [.github/agents/devops.agent.md](.github/agents/devops.agent.md) |
206| Data Scientist | [.github/agents/data-scientist.agent.md](.github/agents/data-scientist.agent.md) |
207| Tester | [.github/agents/tester.agent.md](.github/agents/tester.agent.md) |
208| Power BI Analyst | [.github/agents/powerbi-analyst.agent.md](.github/agents/powerbi-analyst.agent.md) |
209| Consulting Research | [.github/agents/consulting-research.agent.md](.github/agents/consulting-research.agent.md) |
210| GitHub Ops | [.github/agents/internal/github-ops.agent.md](.github/agents/internal/github-ops.agent.md) |
211| ADO Ops | [.github/agents/internal/ado-ops.agent.md](.github/agents/internal/ado-ops.agent.md) |
212| AzDO PRD to WIT | [.github/agents/internal/ado-prd-to-wit.agent.md](.github/agents/internal/ado-prd-to-wit.agent.md) |
213| Functional Reviewer | [.github/agents/internal/functional-reviewer.agent.md](.github/agents/internal/functional-reviewer.agent.md) |
214| Architecture Reviewer | [.github/agents/internal/architecture-reviewer.agent.md](.github/agents/internal/architecture-reviewer.agent.md) |
215| Prompt Engineer | [.github/agents/internal/prompt-engineer.agent.md](.github/agents/internal/prompt-engineer.agent.md) |
216| Eval Specialist | [.github/agents/internal/eval-specialist.agent.md](.github/agents/internal/eval-specialist.agent.md) |
217| Ops Monitor | [.github/agents/internal/ops-monitor.agent.md](.github/agents/internal/ops-monitor.agent.md) |
218| RAG Specialist | [.github/agents/internal/rag-specialist.agent.md](.github/agents/internal/rag-specialist.agent.md) |
219| Agile Coach | [.github/agents/agile-coach.agent.md](.github/agents/agile-coach.agent.md) |
220 
221---
222 
223## Claude Code Commands
224 
225All 21 agents are available as `/project:` slash commands in Claude Code via `.claude/commands/` (invisible sub-agents do not have commands):
226 
227| Command | Agent | Purpose |
228|---------|-------|---------|
229| `/project:agent-x` | Agent X (Hub) | Route work to specialist agents based on type and complexity |
230| `/project:product-manager` | Product Manager | Create PRD, break Epics into Features and Stories |
231| `/project:ux-designer` | UX Designer | Wireframes, HTML/CSS prototypes, WCAG 2.1 AA |
232| `/project:architect` | Architect | ADR with 3+ options, Tech Spec with diagrams |
233| `/project:engineer` | Engineer | Implement code, tests (80% coverage), quality loop |
234| `/project:reviewer` | Reviewer | Code review (8 categories), approve or reject; also reviews standalone human-written architecture docs (`.md`/`.docx`/`.pptx`/`.pdf`/diagrams) via the Architecture Reviewer sub-agent |
235| `/project:reviewer-auto` | Auto-Fix Reviewer | Review + auto-apply safe fixes |
236| `/project:devops` | DevOps Engineer | GitHub Actions pipelines, deployment automation |
237| `/project:data-scientist` | Data Scientist | ML pipelines, evaluations, drift monitoring |
238| `/project:tester` | Tester | Automated testing, certification reports |
239| `/project:powerbi-analyst` | Power BI Analyst | Power BI reports, DAX measures, semantic models |
240| `/project:consulting-research` | Consulting Research | Domain-expert consulting research, client-ready materials |
241| `/project:github-ops` | GitHub Ops | GitHub issue triage, sprint planning, backlog management |
242| `/project:ado-ops` | ADO Ops | Azure DevOps work items, sprint planning, PRD decomposition |
243| `/project:ado-prd-to-wit` | AzDO PRD to WIT | Analyze PRDs and plan ADO work item hierarchies for execution |
244| `/project:agile-coach` | Agile Coach | Story creation, refinement, INVEST compliance |
245 
246**Usage**: Type `/project:engineer Implement the health endpoint for issue #1` in Claude Code.
247 
248Each command file contains the agent's constraints, boundaries, execution steps, and self-review checklist. It also instructs Claude to `read_file` the full agent definition at `.github/agents/` for retrieval-led reasoning.
249 
250---
251 
252## Templates
253 
254| Template | Location |
255|----------|----------|
256| PRD | `.github/templates/PRD-TEMPLATE.md` |
257| ADR | `.github/templates/ADR-TEMPLATE.md` |
258| Tech Spec | `.github/templates/SPEC-TEMPLATE.md` |
259| UX Design | `.github/templates/UX-TEMPLATE.md` |
260| Code Review | `.github/templates/REVIEW-TEMPLATE.md` |
261| Architecture Review | `.github/templates/ARCH-REVIEW-TEMPLATE.md` |
262| Security Plan | `.github/templates/SECURITY-PLAN-TEMPLATE.md` |
263| Progress Log | `.github/templates/PROGRESS-TEMPLATE.md` |
264| Roadmap | `.github/templates/ROADMAP-TEMPLATE.md` |
265