Two files, one repository
jnPiyush/AgentX ships 4 formats across 17 indexed files. The question worth asking is whether the second one says anything the first does not.
| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 7 | 13 | 17 | 19% |
| Commands | 3 | 2 | 3 | 38% |
| Section tags | 5 | 1 | 1 | 71% |
What each file covers
Sections
7 shared · 13 only in A · 17 only in B- − AI Agent Guidelines
- − Quick Reference
- − Issue-First Rule
- − Local Mode (issues optional by default)
- − Quality Loop Hard Rule
- − Compound Engineering Hard Rule
- − Pipeline Phase Compliance Hard Rule
- − CLI Quick Reference
- − Agents (24 total)
- − Role Pipeline Reference
- − Deep References
- − Instruction Files (Auto-Loaded)
- − Directive Language (RFC 2119)
- + CLAUDE.md - Entry Point for Claude Code
- + Quality Loop Hard Rule (NON-SKIPPABLE)
- + Mandatory Workflow Gates (NON-SKIPPABLE)
- + Core Documents (Read Before Coding)
- + 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
- + Work...
- + Local Mode (issues optional - commit freely)
- + Or use full issue workflow if preferred:
- + Directive Language
- + Agent Definitions
- + Claude Code Commands
- + Templates
- Retrieval-Led Reasoning
- GitHub Mode
- Classification
- Commit Format
- Security Checklist
- Local Files First Rule
- ASCII-Only Rule
Commands
3 shared · 2 only in A · 3 only in B- − gh issue create --title "[Story] Add /health" --label "type:story"
- − python.instructions.md
- + gh issue create --title "[Story] Add /health endpoint" --label "type:story"
- + gh issue close 42 --reason completed
- + git commit -m "fix: resolve login timeout (#1)"
- git commit -m "feat: add health endpoint (#42)"
- git commit -m "feat: add user login"
- git reset --hard
Section tags
5 shared · 1 only in A · 1 only in B- − deployment
- + do-not
- lint-format
- code-style
- git-pr
- security
- agent-behaviour
Line diff
jnPiyush/AgentX · AGENTS.md
@@ −1 @@
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.
@@ −21 @@
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|------|-------|----------|
@@ −46 @@
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
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.
@@ +54 @@
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|------|-------|----------|
@@ +138 @@
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: 'AI Agent Guidelines - map of all resources, quick-reference rules, and pointers to detailed docs.'
3−applyTo: '**'
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+
420 ---
521
6−# AI Agent Guidelines
22+## Mandatory Workflow Gates (NON-SKIPPABLE)
723
8−> **Single source of truth for repository workflow guidance.**
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.
925
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/`.
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).
1233
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+
1336 ---
1437
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+
1548 ## Retrieval-Led Reasoning
1649
1750 **IMPORTANT**: Prefer retrieval-led reasoning over pre-training-led reasoning for ALL implementation tasks.
@@ −21 +54 @@
2154
2255 ---
2356
24−## Quick Reference
57+## Context Loading Rules
2558
26−### Issue-First Rule
59+Load context on-demand, not upfront. Match the task to the right documents:
2760
28−Every piece of work SHOULD start with an issue. See [docs/WORKFLOW.md](docs/WORKFLOW.md) for full flow.
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 |
2968
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+
30113 ```bash
31114 # GitHub Mode
32−gh issue create --title "[Story] Add /health" --label "type:story" # Creates #42
115+gh issue create --title "[Story] Add /health endpoint" --label "type:story"
116+# Work...
33117 git commit -m "feat: add health endpoint (#42)"
118+gh issue close 42 --reason completed
119+```
34120
35−# Local Mode (issues optional by default)
121+```bash
122+# Local Mode (issues optional - commit freely)
36123 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
37129 ```
38130
39−Toggle enforcement: `.agentx/agentx.ps1 config set enforceIssues true`
131+---
40132
41−### Classification
133+## Classification
42134
43135 | Type | Label | Route To |
44136 |------|-------|----------|
@@ −46 +138 @@
46138 | Research? | `type:spike` | Architect |
47139 | Docs only? | `type:docs` | Engineer |
48140 | 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 |
141+| Testing/certification? | `type:testing` | Tester |
52142 | Large/vague? | `type:epic` | Product Manager |
53143 | Single capability? | `type:feature` | Architect |
54144 | Otherwise | `type:story` | Engineer |
55145
56−### Commit Format
146+---
57147
148+## Commit Format
149+
58150 ```
59151 type: description (#issue-number)
60152 ```
61153
62154 Types: `feat`, `fix`, `docs`, `test`, `refactor`, `perf`, `chore`
63155
64−For 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.
156+---
65157
66−### Security Checklist
158+## ASCII-Only Rule
67159
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`
160+All source code, scripts, config, and documentation MUST use ASCII characters only (U+0000-U+007F).
73161
74−### Local Files First Rule
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
75164
76−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.
165+---
77166
78−### Quality Loop Hard Rule
167+## Security Checklist
79168
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.
169+Before any commit:
81170
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.
171+- [ ] No hardcoded secrets
172+- [ ] SQL parameterization (no string concatenation)
173+- [ ] Input validation on all endpoints
174+- [ ] Dependencies scanned
83175
84−### Compound Engineering Hard Rule
176+**Blocked commands**: `rm -rf /`, `git reset --hard`, `drop database`
85177
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.
178+### Local Files First Rule
92179
93−### Pipeline Phase Compliance Hard Rule
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.
94181
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−
113182 ---
114183
115−## Agents (24 total)
184+## Directive Language
116185
117−Agent 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.
186+- **MUST** / **MUST NOT** - Absolute requirement or prohibition
187+- **SHOULD** / **SHOULD NOT** - Strong recommendation (exceptions need justification)
188+- **MAY** - Truly optional
118189
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):
136−GitHub Ops, ADO Ops, AzDO PRD to WIT, Functional Reviewer, Architecture Reviewer, Prompt Engineer, Eval Specialist, Ops Monitor, RAG Specialist, Diagram Specialist, Prototype Auditor.
137−
138190 ---
139191
140−## Role Pipeline Reference
192+## Agent Definitions
141193
142−Each 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.
194+Agent role files are at `.github/agents/`. Load only the active agent's definition:
143195
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 |
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) |
159220
160221 ---
161222
162−## Deep References
223+## Claude Code Commands
163224
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 |
225+All 21 agents are available as `/project:` slash commands in Claude Code via `.claude/commands/` (invisible sub-agents do not have commands):
181226
182−### Instruction Files (Auto-Loaded)
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 |
183245
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) |
246+**Usage**: Type `/project:engineer Implement the health endpoint for issue #1` in Claude Code.
193247
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+
194250 ---
195251
196−## ASCII-Only Rule
252+## Templates
197253
198−All 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
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` |
205265
