git:20260915.f17c505 to git:20260923.ff2190a

22 added, 230 removed. Audit A to A.

# CLAUDE.md - Entry Point for Claude Code

- > This file is the equivalent of `.github/copilot-instructions.md` for Claude Code.

- > It loads once at session start. Keep it small -- point to detailed docs, don't duplicate them.

- ---

- ## Quality Loop Hard Rule (NON-SKIPPABLE)

- > **HARD RULE**: Before editing, creating, or deleting any file for a code or docs change, run `.agentx/frontier.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/frontier.ps1 loop complete -s "<summary>"` succeeds, and the subagent review pass must be recorded as a structured verdict on the FINAL iteration (`loop iterate ... --verdict approved --reviewer <id> --high 0 --medium 0`). `loop complete` fails on a non-approved verdict, on non-zero HIGH/MEDIUM, or when iterations were recorded after the approval. The pre-commit hook blocks commits when these conditions are unmet.

- >

- > **Honesty rule**: If asked whether the loop ran, run `.agentx/frontier.ps1 loop status` and report the actual state. Do not claim completion unless `loop complete` succeeded in the current session.

- >

- > **Risk-based iterations**: The CLI enforces minimums of standard `1`, auto-fix `2`, complex/Frontier `3`, and high-risk `5`. A structured independent reviewer verdict is still required on the final iteration. Report each iteration with `loop iterate -s "..."`, then summarize before completing.

- >

- > **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.

- >

- > Frontmatter-only enforcement is insufficient -- this rule lives here in body prose because models routinely skip rules placed only in deeper docs.

- ---

- ## Mandatory Workflow Gates (NON-SKIPPABLE)

- 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.

- > **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).

- >

- > **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).

- >

- > **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).

- >

- > **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).

- **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.

- ---

- ## Core Documents (Read Before Coding)

- 1. **[AGENTS.md](AGENTS.md)** - Map of all resources, quick-reference rules, pointers to detailed docs. Read for ANY coding or workflow task.

- 2. **[docs/WORKFLOW.md](docs/WORKFLOW.md)** - Workflow, routing, handoff, status transitions, architecture. Read for multi-agent coordination.

- 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.

- **When to skip AGENTS.md**: Answering questions, research, debugging only.

- ---

- ## Retrieval-Led Reasoning

- **IMPORTANT**: Prefer retrieval-led reasoning over pre-training-led reasoning for ALL implementation tasks.

- Always `read_file` the relevant SKILL.md, instruction file, or spec before generating code.

- Do NOT rely on training data for project-specific patterns, conventions, or APIs.

- If a skill, spec, or doc exists in the workspace, read it first; generate second.

- ---

- ## Context Loading Rules

- Load context on-demand, not upfront. Match the task to the right documents:

- | Task | Load | Skip |

- |------|------|------|

- | Writing/editing code | AGENTS.md + matching instruction file + relevant skills | Skills not matching task |

- | Creating new files, features, issues | AGENTS.md (workflow + classification) | Unrelated skills |

- | Multi-agent coordination, handoffs | AGENTS.md + [docs/WORKFLOW.md](docs/WORKFLOW.md) | Unrelated skills |

- | Answering questions, research | Nothing extra | AGENTS.md, Skills.md |

- | Debugging | Matching instruction file + error handling skill | AGENTS.md |

- **Token budget**: Load only the skills relevant to the task and active phase. Prefer progressive disclosure over broad context loading.

- ---

- ## Context Loading

- ### Session-Persistent Instructions (load at session start)

- Read these two files at the start of EVERY session -- they apply to all tasks:

- - [.github/instructions/memory.instructions.md](.github/instructions/memory.instructions.md) -- memory read/write protocol

- - [.github/instructions/project-conventions.instructions.md](.github/instructions/project-conventions.instructions.md) -- learned project conventions

- ### Instruction Files (5 remaining -- load on demand)

- | File Pattern | Read This |

- |--------------|-----------|

- | `*agent*`, `*llm*`, `*workflow*` | [.github/instructions/ai.instructions.md](.github/instructions/ai.instructions.md) |

- | `*.py`, `*.pyx` | [.github/instructions/python.instructions.md](.github/instructions/python.instructions.md) |

- | `*.cs`, `*.csx` | [.github/instructions/csharp.instructions.md](.github/instructions/csharp.instructions.md) |

- | `*.ts` (backend) | [.github/instructions/typescript.instructions.md](.github/instructions/typescript.instructions.md) |

- | `*.tsx`, `*.jsx`, `components/`, `hooks/` | [.github/instructions/react.instructions.md](.github/instructions/react.instructions.md) |

- ### Skills (load directly for domains without instructions)

- | File Pattern | Load Skill |

- |--------------|------------|

- | `*.tf`, `*.tfvars` | [.github/skills/infrastructure/terraform/SKILL.md](.github/skills/infrastructure/terraform/SKILL.md) |

- | `*.bicep`, `*.bicepparam` | [.github/skills/infrastructure/bicep/SKILL.md](.github/skills/infrastructure/bicep/SKILL.md) |

- | `*.razor`, `*.razor.cs` | [.github/skills/languages/blazor/SKILL.md](.github/skills/languages/blazor/SKILL.md) |

- | `*.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) |

- | `*.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) |

- | `Controllers/`, `api/`, `endpoints/` | [.github/skills/architecture/api-design/SKILL.md](.github/skills/architecture/api-design/SKILL.md) |

- | `**/ux/**`, `**/prototypes/**` | [.github/skills/design/ux-ui-design/SKILL.md](.github/skills/design/ux-ui-design/SKILL.md) |

- ---

- ## Issue-First Workflow

- Every piece of work SHOULD start with an issue. Issue enforcement depends on mode:

- - **GitHub Mode**: Issue references in commits are **required** (teams need traceability)

- - **Local Mode**: Issue references are **optional** by default (solo developers can commit freely)

- - Toggle: `.agentx/frontier.ps1 config set enforceIssues true` (or `false`)

- ```bash

- # GitHub Mode

- gh issue create --title "[Story] Add /health endpoint" --label "type:story"

- # Work...

- git commit -m "feat: add health endpoint (#42)"

- gh issue close 42 --reason completed

- ```

- ```bash

- # Local Mode (issues optional - commit freely)

- git commit -m "feat: add user login"

- # Or use full issue workflow if preferred:

- ./.agentx/local-issue-manager.ps1 -Action create -Title "[Bug] Fix timeout" -Labels "type:bug"

- git commit -m "fix: resolve login timeout (#1)"

- ./.agentx/local-issue-manager.ps1 -Action close -IssueNumber 1

- ```

- ---

- ## Classification

- | Type | Label | Route To |

- |------|-------|----------|

- | Broken? | `type:bug` | Engineer |

- | Research? | `type:spike` | Architect |

- | Docs only? | `type:docs` | Engineer |

- | Pipeline/deploy? | `type:devops` | DevOps Engineer |

- | Testing/certification? | `type:testing` | Tester |

- | Fabric data platform? | `type:fabric` | Fabric Engineer |

- | Power Platform solution? | `type:lowcode` | Power Platform Builder |

- | Large/vague? | `type:epic` | Product Manager |

- | Single capability? | `type:feature` | Architect |

- | Otherwise | `type:story` | Engineer |

- ---

- ## Commit Format

- ```

- type: description (#issue-number)

- ```

- Types: `feat`, `fix`, `docs`, `test`, `refactor`, `perf`, `chore`

- ---

- ## ASCII-Only Rule

- All source code, scripts, config, and documentation MUST use ASCII characters only (U+0000-U+007F).

- - MUST NOT use emoji, Unicode symbols, box-drawing characters, smart quotes

- - MUST use ASCII equivalents: `[PASS]` not checkmarks, `[FAIL]` not cross marks, `->` not arrows, `-` not em-dashes

- ---

- ## Security Checklist

- Before any commit:

- - [ ] No hardcoded secrets

- - [ ] SQL parameterization (no string concatenation)

- - [ ] Input validation on all endpoints

- - [ ] Dependencies scanned

- **Blocked commands**: `rm -rf /`, `git reset --hard`, `drop database`

+ Claude Code loads this file at session start. The shared Frontier contract

+ (quality loop, gates, classification, commits, security) lives in `AGENTS.md`

+ and is imported below instead of being copied, so both stay in sync.

- ### Local Files First Rule

+ @AGENTS.md

+ @.github/instructions/project-conventions.instructions.md

+ @.github/instructions/memory.instructions.md

- 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.

+ Honesty rule: report loop and gate state from `.agentx/frontier.ps1 loop status`

+ and the staged artifacts; never claim a check or review happened without evidence.

---

- ## Directive Language

- - **MUST** / **MUST NOT** - Absolute requirement or prohibition

- - **SHOULD** / **SHOULD NOT** - Strong recommendation (exceptions need justification)

- - **MAY** - Truly optional

- ---

+ ## Loading Rules For Claude Code

- ## Agent Definitions

+ Claude Code does not apply `applyTo` patterns, so read the matching file when you

+ edit these paths:

- Agent role files are at `.github/agents/`. Load only the active agent's definition:

+ | File pattern | Read |

+ |--------------|------|

+ | `*agent*`, `*llm*`, `*workflow*` | `.github/instructions/ai.instructions.md` |

+ | `*.py`, `*.pyx` | `.github/instructions/python.instructions.md` |

+ | `*.cs`, `*.csx` | `.github/instructions/csharp.instructions.md` |

+ | `*.ts` (backend) | `.github/instructions/typescript.instructions.md` |

+ | `*.tsx`, `*.jsx`, `components/`, `hooks/` | `.github/instructions/react.instructions.md` |

+ | `*.tf`, `*.bicep`, `*.razor`, `*.sql`, `*.yml`, `api/`, `**/ux/**` | the matching skill listed in `Skills.md` |

- | Agent | Definition |

- |-------|-----------|

- | Frontier (Hub) | [.github/agents/frontier.agent.md](.github/agents/frontier.agent.md) |

- | Product Manager | [.github/agents/product-manager.agent.md](.github/agents/product-manager.agent.md) |

- | UX Designer | [.github/agents/ux-designer.agent.md](.github/agents/ux-designer.agent.md) |

- | Architect | [.github/agents/architect.agent.md](.github/agents/architect.agent.md) |

- | Engineer | [.github/agents/engineer.agent.md](.github/agents/engineer.agent.md) |

- | Reviewer | [.github/agents/reviewer.agent.md](.github/agents/reviewer.agent.md) |

- | Auto-Fix Reviewer | [.github/agents/reviewer-auto.agent.md](.github/agents/reviewer-auto.agent.md) |

- | DevOps Engineer | [.github/agents/devops.agent.md](.github/agents/devops.agent.md) |

- | Data Scientist | [.github/agents/data-scientist.agent.md](.github/agents/data-scientist.agent.md) |

- | Tester | [.github/agents/tester.agent.md](.github/agents/tester.agent.md) |

- | Fabric Engineer | [.github/agents/fabric-engineer.agent.md](.github/agents/fabric-engineer.agent.md) |

- | Power Platform Builder | [.github/agents/power-platform-builder.agent.md](.github/agents/power-platform-builder.agent.md) |

- | Power BI Analyst | [.github/agents/powerbi-analyst.agent.md](.github/agents/powerbi-analyst.agent.md) |

- | Consulting Research | [.github/agents/consulting-research.agent.md](.github/agents/consulting-research.agent.md) |

- | GitHub Ops | [.github/agents/internal/github-ops.agent.md](.github/agents/internal/github-ops.agent.md) |

- | ADO Ops | [.github/agents/internal/ado-ops.agent.md](.github/agents/internal/ado-ops.agent.md) |

- | AzDO PRD to WIT | [.github/agents/internal/ado-prd-to-wit.agent.md](.github/agents/internal/ado-prd-to-wit.agent.md) |

- | Functional Reviewer | [.github/agents/internal/functional-reviewer.agent.md](.github/agents/internal/functional-reviewer.agent.md) |

- | Architecture Reviewer | [.github/agents/internal/architecture-reviewer.agent.md](.github/agents/internal/architecture-reviewer.agent.md) |

- | Prompt Engineer | [.github/agents/internal/prompt-engineer.agent.md](.github/agents/internal/prompt-engineer.agent.md) |

- | Eval Specialist | [.github/agents/internal/eval-specialist.agent.md](.github/agents/internal/eval-specialist.agent.md) |

- | Ops Monitor | [.github/agents/internal/ops-monitor.agent.md](.github/agents/internal/ops-monitor.agent.md) |

- | RAG Specialist | [.github/agents/internal/rag-specialist.agent.md](.github/agents/internal/rag-specialist.agent.md) |

- | Agile Coach | [.github/agents/agile-coach.agent.md](.github/agents/agile-coach.agent.md) |

+ Agent definitions live in `.github/agents/` and templates in `.github/templates/`;

+ load only the active agent's file.

---

## Claude Code Commands

All 18 command-backed agents are available as `/project:` slash commands in Claude Code via `.claude/commands/` (other internal sub-agents remain invisible):

| Command | Agent | Purpose |

|---------|-------|---------|

- | `/project:agent-x` | Frontier (Hub) | Route work to specialist agents based on type and complexity |

+ | `/project:frontier` | Frontier (Hub) | Route work to specialist agents based on type and complexity |

| `/project:product-manager` | Product Manager | Create PRD, break Epics into Features and Stories |

| `/project:ux-designer` | UX Designer | Wireframes, HTML/CSS prototypes, WCAG 2.1 AA |

| `/project:architect` | Architect | ADR with 3+ options, Tech Spec with diagrams |

| `/project:engineer` | Engineer | Implement code, tests (80% coverage), quality loop |

| `/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 |

| `/project:reviewer-auto` | Auto-Fix Reviewer | Review + auto-apply safe fixes |

| `/project:devops` | DevOps Engineer | GitHub Actions pipelines, deployment automation |

| `/project:data-scientist` | Data Scientist | ML pipelines, evaluations, drift monitoring |

| `/project:tester` | Tester | Automated testing, certification reports |

| `/project:fabric-engineer` | Fabric Engineer | Fabric Lakehouse, Warehouse, notebooks, pipelines, and data quality |

| `/project:power-platform-builder` | Power Platform Builder | Unpacked Power Platform solution source and package validation |

| `/project:powerbi-analyst` | Power BI Analyst | Power BI reports, DAX measures, semantic models |

| `/project:consulting-research` | Consulting Research | Domain-expert consulting research, client-ready materials |

| `/project:github-ops` | GitHub Ops | GitHub issue triage, sprint planning, backlog management |

| `/project:ado-ops` | ADO Ops | Azure DevOps work items, sprint planning, PRD decomposition |

| `/project:ado-prd-to-wit` | AzDO PRD to WIT | Analyze PRDs and plan ADO work item hierarchies for execution |

| `/project:agile-coach` | Agile Coach | Story creation, refinement, INVEST compliance |

**Usage**: Type `/project:engineer Implement the health endpoint for issue #1` in Claude Code.

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.

- ---

- ## Templates

- | Template | Location |

- |----------|----------|

- | PRD | `.github/templates/PRD-TEMPLATE.md` |

- | ADR | `.github/templates/ADR-TEMPLATE.md` |

- | Tech Spec | `.github/templates/SPEC-TEMPLATE.md` |

- | UX Design | `.github/templates/UX-TEMPLATE.md` |

- | Code Review | `.github/templates/REVIEW-TEMPLATE.md` |

- | Architecture Review | `.github/templates/ARCH-REVIEW-TEMPLATE.md` |

- | Security Plan | `.github/templates/SECURITY-PLAN-TEMPLATE.md` |

- | Progress Log | `.github/templates/PROGRESS-TEMPLATE.md` |

- | Roadmap | `.github/templates/ROADMAP-TEMPLATE.md` |