| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 1 | 24 | 0% |
| Commands | 0 | 1 | 6 | 0% |
| Section tags | 1 | 1 | 5 | 14% |
What each file covers
Sections
0 shared · 1 only in A · 24 only in B- − Python (AgentX)
- + CLAUDE.md - Entry Point for Claude Code
- + Quality Loop Hard Rule (NON-SKIPPABLE)
- + Mandatory Workflow Gates (NON-SKIPPABLE)
- + Core Documents (Read Before Coding)
- + Retrieval-Led Reasoning
- + Context Loading Rules
- + Context Loading
- + Session-Persistent Instructions (load at session start)
- + Instruction Files (5 remaining -- load on demand)
- + Skills (load directly for domains without instructions)
- + Issue-First Workflow
- + GitHub Mode
- + Work...
- + Local Mode (issues optional - commit freely)
- + Or use full issue workflow if preferred:
- + Classification
- + Commit Format
- + ASCII-Only Rule
- + Security Checklist
- + Local Files First Rule
- + Directive Language
- + Agent Definitions
- + Claude Code Commands
- + Templates
Commands
0 shared · 1 only in A · 6 only in B- − ruff
- + gh issue create --title "[Story] Add /health endpoint" --label "type:story"
- + git commit -m "feat: add health endpoint (#42)"
- + gh issue close 42 --reason completed
- + git commit -m "feat: add user login"
- + git commit -m "fix: resolve login timeout (#1)"
- + git reset --hard
Section tags
1 shared · 1 only in A · 5 only in B- − test
- + code-style
- + git-pr
- + security
- + do-not
- + agent-behaviour
- lint-format
Line diff
jnPiyush/AgentX · .cursor/rules/python.mdc
@@ −1 @@
1---
2description: Python coding standards (AgentX)
3globs: **/*.py,**/*.pyx
4alwaysApply: false
5---
6
7# Python (AgentX)
8
9Canonical: `.github/instructions/python.instructions.md` and
10`.github/skills/languages/python/SKILL.md` -- read for full standards.
11
12- PEP 8; type hints on all signatures; Black 88-col; `ruff` lint/format.
13- Google-style docstrings; pytest (+ pytest-asyncio); name tests
14 `test_function_scenario_expected`.
15- Catch specific exceptions, never bare `except:`.
16- Parameterize SQL via ORM or `cursor.execute(sql, params)` -- never f-strings.
17- Secrets via env/Key Vault, never hardcoded.
18
jnPiyush/AgentX · CLAUDE.md
@@ +1 @@
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 "[Story] Add /health endpoint" --label "type:story"
116# Work...
117git commit -m "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 "feat: add user login"
124
125# Or use full issue workflow if preferred:
126./.agentx/local-issue-manager.ps1 -Action create -Title "[Bug] Fix timeout" -Labels "type:bug"
127git commit -m "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
@@ −1 +1 @@
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+
16 ---
2−description: Python coding standards (AgentX)
3−globs: **/*.py,**/*.pyx
4−alwaysApply: false
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+
520 ---
621
7−# Python (AgentX)
22+## Mandatory Workflow Gates (NON-SKIPPABLE)
823
9−Canonical: `.github/instructions/python.instructions.md` and
10−`.github/skills/languages/python/SKILL.md` -- read for full standards.
24+These 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.
1125
12−- PEP 8; type hints on all signatures; Black 88-col; `ruff` lint/format.
13−- Google-style docstrings; pytest (+ pytest-asyncio); name tests
14− `test_function_scenario_expected`.
15−- Catch specific exceptions, never bare `except:`.
16−- Parameterize SQL via ORM or `cursor.execute(sql, params)` -- never f-strings.
17−- Secrets via env/Key Vault, never hardcoded.
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+
40+1. **[AGENTS.md](AGENTS.md)** - Map of all resources, quick-reference rules, pointers to detailed docs. Read for ANY coding or workflow task.
41+2. **[docs/WORKFLOW.md](docs/WORKFLOW.md)** - Workflow, routing, handoff, status transitions, architecture. Read for multi-agent coordination.
42+3. **[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.
51+Always `read_file` the relevant SKILL.md, instruction file, or spec before generating code.
52+Do NOT rely on training data for project-specific patterns, conventions, or APIs.
53+If a skill, spec, or doc exists in the workspace, read it first; generate second.
54+
55+---
56+
57+## Context Loading Rules
58+
59+Load 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+
77+Read 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+
108+Every 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
115+gh issue create --title "[Story] Add /health endpoint" --label "type:story"
116+# Work...
117+git commit -m "feat: add health endpoint (#42)"
118+gh issue close 42 --reason completed
119+```
120+
121+```bash
122+# Local Mode (issues optional - commit freely)
123+git commit -m "feat: add user login"
124+
125+# Or use full issue workflow if preferred:
126+./.agentx/local-issue-manager.ps1 -Action create -Title "[Bug] Fix timeout" -Labels "type:bug"
127+git commit -m "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+```
151+type: description (#issue-number)
152+```
153+
154+Types: `feat`, `fix`, `docs`, `test`, `refactor`, `perf`, `chore`
155+
156+---
157+
158+## ASCII-Only Rule
159+
160+All 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+
169+Before 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+
180+All 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+
194+Agent 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+
225+All 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+
248+Each 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` |
18265
