# Agents � AI-First Development System

> **Dynatrace Scorecards** uses a multi-agent AI development system: 14 specialist agents, 12 reusable skills, and 13 orchestration prompts that together cover the full development lifecycle — from requirements through implementation, testing, and review.
>
> Every agent is defined in `.github/agents/`, every skill in `.github/skills/`, every prompt in `.github/prompts/`, and every master definition in `.github/base/`. This file is the entry point.

---

## Table of Contents

| # | Section |
|---|---|
| 1 | [Quick Start � Which prompt to use?](#1-quick-start--which-prompt-to-use) |
| 2 | [System Architecture](#2-system-architecture) |
| 3 | [Universal Session Start Protocol](#3-universal-session-start-protocol) |
| 4 | [Agent Catalogue](#4-agent-catalogue) |
| 5 | [Skills Catalogue](#5-skills-catalogue) |
| 6 | [Prompt Catalogue](#6-prompt-catalogue) |
| 7 | [Development Workflow](#7-development-workflow) |
| 8 | [Artefacts](#8-artefacts) |
| 9 | [Anti-Patterns](#9-anti-patterns) |
| 10 | [Key Files Reference](#10-key-files-reference) |
| 11 | [CI Integration � AI Gate in GitHub Actions](#11-ci-integration--ai-gate-in-github-actions) |

---

## 1. Quick Start � Which prompt to use?

| I want to… | Use this prompt | Delegates to |
|---|---|---|
| Build a feature end-to-end | `full-cycle.prompt.md` | All agents in sequence |
| Refine requirements for a ticket | `problem-refinement.prompt.md` | Requirements Refinement Agent |
| Implement an approved spec | `implementation.prompt.md` | Coding → Smith FAST → [human verifies] → Smith FULL → Testing → Execution |
| Implement step-by-step with human approval per step | `pair-programming.prompt.md` | Coding Agent (step-locked, one commit per approved step) |
| Review a changelist | `review.prompt.md` | 5 review agents in parallel |
| Run Agent Smith FAST (pre-commit) | `pre-commit-check.prompt.md` | Agent Smith (FAST mode) |
| Write a DQL query | `query-development.prompt.md` | DQL Query → Unit Testing → Security |
| Run a security audit | `security-audit.prompt.md` | Security Review Agent |
| Write unit tests for a file | `write-unit-tests.prompt.md` | Unit Testing Agent |
| Write component tests | `write-component-tests.prompt.md` | Component Testing Agent |
| Write E2E tests | `write-e2e-tests.prompt.md` | E2E Testing Agent |
| Write DQL sandbox tests | `write-dql-tests.prompt.md` | DQL Test Writer Agent |
| Discuss / challenge a topic or proposal | `discussion.prompt.md` | Discussion skill (no dedicated agent) |
| Improve agents/prompts/skills | `refine-system.prompt.md` | System Refinement skill |

---

## 2. System Architecture

### Layered Knowledge

```
Layer 1: .github/base/instructions.md          ? Operational rules (highest authority)
Layer 2: .github/copilot-instructions.md       ? Coding standards
Layer 3: .github/skills/*.skill.md             ? Reusable capabilities
Layer 4: .github/agents/*.agent.md             ? Agent-specific domain knowledge
Layer 5: .github/prompts/*.prompt.md           ? Workflow orchestration
Layer 6: .github/findings/*.md                 ? Accumulated institutional memory
```

When layers conflict, higher layers win.

### Agent Categories

```
+-----------------+    +----------------------+    +----------------------+
�   Development   �    �      Testing          �    �       Review         �
�                 �    �                       �    �                       �
�  Coding         �    �  Unit Testing         �    �  Code Review         �
�  DQL Query      �    �  Component Testing    �    �  Security Review     �
�                 �    �  E2E Testing          �    �  Architect Review    �
+-----------------+    �  DQL Test Writer      �    �  Accessibility       �
                        �  Test Execution       �    �  UX Review           �
+-----------------+    +----------------------+    �  Documentation       �
�    Process      �                                 +----------------------+
�                 �    +----------------------+
�  Requirements   �    �    Quality Gates      �
�  Refinement     �    �                       �
�  Integration    �    �  Agent Smith          �
+-----------------+    +----------------------+
```

### Development Loop

> Full per-phase operational reference: [.github/base/workflow.md](.github/base/workflow.md)

```mermaid
flowchart TD
    REFINE["🔍 Phase 1: Refinement\nrequirements.agent"] --> RG{"Human approves\nrequirements.md?"}
    RG -->|"No — iterate"| REFINE
    RG -->|"Yes"| CODE["⚙️ Phase 2a: Coding\ncoding.agent"]
    CODE --> VAL{"typecheck + lint"}
    VAL -->|"Ambiguous error"| PAUSE["⏸ Pause & Ask\nhuman for direction"]
    PAUSE --> CODE
    VAL -->|"Fail ≤3×, retry"| CODE
    VAL -->|"Fail, retries exhausted"| ESC["⚠️ Escalate to human"]
    VAL -->|"Pass"| FAST["🔬 Agent Smith FAST\n6 structural checks\nauto-triggered"]
    FAST -->|"BLOCK, fix loop ≤3×"| CODE
    FAST -->|"BLOCK, loop exhausted"| ESC
    FAST -->|"PASS"| HV["👁️ Human Verify\nin browser"]
    HV -->|"Needs revision"| CODE
    HV -->|"Approved"| FULL["🔬 Agent Smith FULL\nall 17 checks"]
    FULL -->|"BLOCK, fix loop ≤3×"| CODE
    FULL -->|"BLOCK, loop exhausted"| ESC
    FULL -->|"PASS"| PAR["🧪 Phase 3: Tests\nparallel trigger"]
    PAR --> UT["unit-testing-agent"]
    PAR --> CT["component-testing-agent"]
    UT --> EXEC["test-execution-skill"]
    CT --> EXEC
    EXEC -->|"Same error ×2"| PAUSE
    EXEC -->|"Fail ≤5×, fix"| CODE
    EXEC -->|"All pass + coverage ≥90%"| DONE["✅ Complete → Review"]
```

| Phase | Gate condition | Max loops |
|---|---|---|
| Refinement → Code | Human approves `requirements.md` | ∞ |
| Code → Smith FAST | `typecheck` + `lint` exit 0 | 3 |
| Smith FAST → Human Verify | Smith FAST PASS (6 structural checks) | 3 |
| Human Verify → Smith FULL | Human explicitly approves ("OK", "looks good", etc.) | ∞ |
| Smith FULL → Tests | Smith FULL PASS (all 17 checks) | 3 |
| Tests → Review | All tests pass, coverage ≥90%, typecheck/lint clean | 5 |
| Review → Complete | Zero 🔴 findings across all review agents | 3 |
| Any → Escalate | Max loops exceeded | ∞ |

---

## 3. Universal Session Start Protocol

**Every agent and every prompt must follow this at the start of every invocation:**

```
1. Read .github/findings/cache.md
   ? current task state, phase, key decisions from all prior sessions
   → current task state, phase, key decisions from all prior sessions

2. Read .github/findings/<agent-name>-findings.md (if exists)
   ? own prior findings, patterns discovered, known pitfalls
   → own prior findings, patterns discovered, known pitfalls

3. Read .github/base/instructions.md
   ? command lookup table, anti-patterns, import boundary rules
   → command lookup table, anti-patterns, import boundary rules

4. Read package.json scripts section
   ? (agents that run terminal commands only)
4. Read relevant knowledge files (prevents MCP storms and import hallucination):
   - .github/base/knowledge/codebase.md  — all agents
   - .github/base/knowledge/strato.md    — agents with strato_* MCP access
   - .github/base/knowledge/dql-patterns.md — agents with dql_search MCP access
   → Check Last verified date in each. If > 7 days old, refresh before relying on content.

5. Read package.json scripts section
   → (agents that run terminal commands only)
```

**After every significant step, write back:**

```
? Append to .github/findings/<agent-name>-findings.md
? Update .github/findings/cache.md with:
   - Current task and phase
   - Decisions made
   - Files created or modified
   - Any blockers
```

This ensures context survives context-window resets and cross-agent handoffs lose no information.

---

## 4. Agent Catalogue

### Testing Agents

| Agent | File | Trigger | Key output |
|---|---|---|---|
| **Unit Testing** | `unit-testing.agent.md` | After new/changed source files | `*.spec.ts` co-located, ≥90% coverage |
| **Component Testing** | `component-testing.agent.md` | After new/changed components | `component/tests/**/*.spec.tsx` + Page Objects |
| **E2E Testing** | `e2e-testing.agent.md` | After new/changed pages or flows | `e2e/tests/**/*.spec.ts` + Page Objects + Assertions |
| **DQL Test Writer** | `dql-test-writer.agent.md` | After new/changed DQL queries | `dql/tests/*.spec.ts` with `BaseRecord` + `changes` arrays |

### Review Agents

| Agent | File | Focus | Severity model |
|---|---|---|---|
| **Code Review** | `code-review.agent.md` | TypeScript, patterns, quality, documentation | 🔴 Error / 🟡 Warning / 🔵 Suggestion |
| **Security Review** | `security-review.agent.md` | CVEs, DQL injection, scopes, secrets | 🔴 Critical / 🟡 Warning / 🔵 Info |
| **Architect Review** | `architect.agent.md` | Layering, coupling, platform compliance | 🟢/🟡/🔴 per area + top-5 priorities |
| **Accessibility** | `accessibility.agent.md` | WCAG 2.2 AA | 🔴 Violation / 🟡 Risk / 🔵 Enhancement |
| **UX Review** | `ux-review.agent.md` | Strato correctness, experience standards | 🔴 Flaw / 🟡 Concern / 🔵 Enhancement |

### Development Agents

| Agent | File | Trigger | Key output |
|---|---|---|---|
| **Coding** | `coding.agent.md` | After requirements approved | Production code in `src/`, updated tests |
| **DQL Query** | `dql-query.agent.md` | When Grail data is needed | `QUERY_*` constant + typed fetch function |

### Process Agents

| Agent | File | Trigger | Key output |
|---|---|---|---|
| **Requirements Refinement** | `requirements.agent.md` | Ticket or ad-hoc topic | `.github/tickets/<TICKET_ID>/requirements.md` |

### Quality Gate Agents

| Agent | File | Trigger | Key output |
|---|---|---|---|
| **Agent Smith** | `agent-smith.agent.md` | FAST: after typecheck+lint; FULL: after human verify | `AgentSmithReport` + `PASS`/`BLOCK` verdict |

### Agent Detail: Quality Gates

| Agent | Must satisfy before handing off |
|---|---|
| Unit Testing | All 4 coverage metrics ≥90% per file; zero `test.only`/`any` |
| Component Testing | All tests pass `npm run test:ct`; every test uses Page Objects |
| E2E Testing | All tests pass `npm run test:e2e`; import boundary rules respected |
| DQL Test Writer | All tests pass `npm run test:dql`; every `filter` clause has positive + negative test |
| Coding | `npm run typecheck` exits 0; `npm run lint` exits 0; Agent Smith FAST PASS; consumers traced |
| Agent Smith FAST | Zero 🔴 findings (6 structural checks) before presenting to human |
| Agent Smith FULL | Zero 🔴 findings (all 17 checks) before test writing |
| DQL Query | `dql_search` confirms syntax; `scanLimitGBytes: -1`; results bounded |
| All review agents | Zero 🔴 findings before declaring clean |

### MCP Tool Access Matrix

| Agent | `strato_*` | `sdk_*` | `dql_search` | `validate_cves` | `get_exp_standard` | `playwright_*` |
|---|---|---|---|---|---|---|
| Coding | ✓ | ✓ | — | — | ✓ | ✓ |
| DQL Query | — | — | ✓ | — | — | — |
| DQL Test Writer | — | — | — | — | — | — |
| Security Review | — | ✓ | — | ✓ | — | — |
| Architect Review | ✓ | ✓ | ✓ | — | ✓ | — |
| Accessibility | ✓ | — | — | — | ✓ | ✓ |
| UX Review | ✓ | ✓ | — | — | ✓ | ✓ |
| Requirements | ✓ | ✓ | ✓ | — | ✓ | — |
| E2E Testing | — | — | — | — | — | ✓ |
| Component Testing | — | — | — | — | — | ✓ |
| Agent Smith | — | — | — | — | — | — |
| Other agents | — | — | — | — | — | — |

---

## 5. Skills Catalogue

Skills are composable, reusable capabilities that agents declare and apply. All skills live in `.github/skills/`.
The full catalogue with agent-skill matrix and composition model is in `.github/base/skills-definition.md`.

| # | Skill | File | Purpose | Used by |
|---|---|---|---|---|
| 1 | **Validation Pipeline** | `validation-pipeline.skill.md` | typecheck → lint → test → coverage in the right order | All code-writing agents |
| 2 | **Consumer Impact Tracing** | `consumer-tracing.skill.md` | Find every file that imports a changed type | Coding, Requirements, Architect, Code Review, DQL |
| 3 | **Pattern Matching** | `pattern-matching.skill.md` | Read 2-3 existing examples before writing new code | Coding, all testing agents, DQL |
| 4 | **Error Recovery** | `error-recovery.skill.md` | Decision tree + Pause-and-Ask for typecheck/lint/test failures | Coding, testing agents |
| 5 | **MCP Tool Usage** | `mcp-tools.skill.md` | Ground Strato/SDK/DQL recommendations in live docs | Agents with MCP access |
| 6 | **Agent Smith Checks** | `agent-smith-checks.skill.md` | 17-check LLM hallucination detection (FAST: 6, FULL: all 17) | Agent Smith |
| 7 | **Playwright Browser Inspection** | `playwright-browser.skill.md` | Inspect the running app in a real browser — locators, ARIA, UI | E2E Testing, Component Testing, UX Review, Accessibility, Coding |
| 8 | **Context Triage** | `context-triage.skill.md` | Priority-ordered file reading for limited context window budgets | All agents — universal |
| 9 | **Critical Discussion** | `discussion.skill.md` | Research SOAT, challenge proposals, surface flaws, record decisions | Discussion prompt — standalone |
| 10 | **Test Execution** | `test-execution.skill.md` | Run test suites, produce coverage tables, report full logs | Unit Testing, Component Testing, Implementation |
| 11 | **Changelist Planning** | `changelist.skill.md` | Multi-CL mode: ≥5 files or ≥3 layers triggers CL breakdown | Coding, Implementation |
| 12 | **System Refinement** | `system-refinement.skill.md` | Structured agent system improvement with overengineering gate | Refine System prompt |

### Skill Composition Examples

```
Coding Agent = {
  skills: [ValidationPipeline, ConsumerTracing, PatternMatching,
           ErrorRecovery, MCPToolUsage, PlaywrightBrowser, ChangelistPlanning, ContextTriage],
  gates:  [typecheck=0, lint=0, Smith FAST PASS]
}

Agent Smith = {
  skills: [AgentSmithChecks, ContextTriage],
  gates:  [zero_red_findings → PASS]
}

E2E Testing Agent = {
  skills: [ValidationPipeline, PatternMatching, ErrorRecovery, PlaywrightBrowser, TestExecution, ContextTriage],
  gates:  [typecheck=0, all_e2e_tests_pass]
}
```

---

## 6. Prompt Catalogue

### Workflow Prompts (multi-agent orchestration)

| Prompt | File | Agents invoked | Gate |
|---|---|---|---|
| **Full Cycle** | `full-cycle.prompt.md` | All agents (Phases 1–3) | Human approval → tests pass → zero 🔴 |
| **Problem Refinement** | `problem-refinement.prompt.md` | Requirements Refinement | Human approves spec |
| **Implementation** | `implementation.prompt.md` | Coding → Smith FAST → [human] → Smith FULL → Unit+Component → Execution | Tests pass, coverage ≥90% |
| **Pair Programming** | `pair-programming.prompt.md` | Coding Agent (step-locked) | Explicit approval per step; one commit per step |
| **Review** | `review.prompt.md` | 5 review agents | Zero 🔴 findings |
| **Pre-Commit Check** | `pre-commit-check.prompt.md` | Agent Smith (FAST mode only) | Zero 🔴 structural findings |
| **Query Development** | `query-development.prompt.md` | DQL → Unit → Execution → Security → Architect | Syntax valid, zero injection risks |
| **Security Audit** | `security-audit.prompt.md` | Security Review | Zero critical CVEs, zero secrets |
| **Discussion** | `discussion.prompt.md` | Discussion skill (ticket-based or ad-hoc) | Human closes or all OQs resolved |
| **Distill Findings** | `distill-findings.prompt.md` | Human-gated pattern promotion | Human approves each proposed change |
| **Refine System** | `refine-system.prompt.md` | System Refinement skill | Human approves; overengineering gate passes |

### Test Writer Prompts (single-agent, file as input)

| Prompt | File | Input | Output | Run with |
|---|---|---|---|---|
| **Write Unit Tests** | `write-unit-tests.prompt.md` | Source file path | `*.spec.ts` co-located | `npm run test:app` |
| **Write Component Tests** | `write-component-tests.prompt.md` | Component file path (+ `--a11y` flag) | `component/tests/**/*.spec.tsx` | `npm run test:ct` |
| **Write E2E Tests** | `write-e2e-tests.prompt.md` | Page/flow description | `e2e/tests/**/*.spec.ts` | `npm run test:e2e` |
| **Write DQL Tests** | `write-dql-tests.prompt.md` | Query file path | `dql/tests/*.spec.ts` | `npm run test:dql` |

---

## 7. Development Workflow

### Full Cycle (via `full-cycle.prompt.md`)

```
Phase 0: Session Start
  → Read cache.md, all findings files, instructions.md
  → Resume if ticket is already in progress

Phase 1: Refinement
  → requirements-agent reads context.md (or ad-hoc description)
  → Asks clarifying questions, self-challenges draft (Step 9.5)
  → Writes requirements.md incrementally (resilient to context resets)
  → GATE: human explicitly approves

Phase 2: Implementation (7 sub-phases — see implementation.prompt.md)
  → coding-agent implements production code
  → GATE: typecheck + lint + Smith FAST PASS
  → Human verifies in browser (4-item checklist)
  → Smith FULL (all 17 checks) — GATE: PASS
  → unit-testing-agent + component-testing-agent (parallel)
  → test-execution-skill reports coverage
  → GATE: all tests pass, coverage ≥90%
  → Final human check — GATE: explicit "yes"
  → Agent-written summary.md

Phase 3: Review
  → code-review-agent → security-review-agent → architect-agent
  → accessibility-agent → ux-review-agent
  → GATE: zero 🔴 findings across all agents
  → On failure: collect all 🔴 findings → coding-agent (max 3 loops)
  → Only re-run agents that reported 🔴 findings in fix loops
```

### Fix Loop: Context Propagation

Every fix loop must pass:
- Which gate failed (typecheck / lint / Smith FAST / Smith FULL / test / coverage)
- Exact error messages or uncovered lines
- Which files were involved
- What was already tried

Without full context, the agent repeats the same mistakes.

### Escalation

When maximum loop count is exceeded, the Integration Agent reports:

```markdown
### ?? Escalation Required

**Phase**: <phase name>
**Iteration**: <N>/<max>
**Unresolved issues**: <list>
**Attempted fixes**: <list>
**Recommendation**: <next step for human>
```

---

## 8. Artefacts

### Ticket-Scoped Artefacts (`.github/tickets/<TICKET_ID>/`)

| Artefact | Owner | Created when | Content |
|---|---|---|---|
| `context.md` | Human | Before refinement starts (ticket mode) | Problem description, constraints, known context |
| `requirements.md` | Requirements agent | Start of refinement (updated incrementally) | Full spec: criteria, data model, UX, impl plan, test plan |
| `implementation-plan.md` | Requirements agent | After requirements approved | Approved spec snapshot + running log of all agent decisions |
| `summary.md` | Requirements agent | At requirements approval | Human-readable feature summary: description, commit message proposal, what changed, ACs |

`requirements.md` is created at the **start** of refinement and updated after every Q&A round — never only at the end. This makes it resilient to context-window resets.

### Institutional Memory (`.github/findings/`)

| File | Written by | Content |
|---|---|---|
| `cache.md` | **All agents** | Current task state, phase, key decisions — cross-agent, cross-session |
| `coding-agent-findings.md` | Coding Agent | Files changed, implementation decisions, issues |
| `agent-smith-findings.md` | Agent Smith | Verdicts, loop counts, finding summaries per ticket |
| `unit-testing-agent-findings.md` | Unit Testing Agent | Coverage numbers, mocking patterns, edge cases |
| `component-testing-agent-findings.md` | Component Testing Agent | POs created, Grail mock patterns, flaky scenarios |
| `e2e-testing-agent-findings.md` | E2E Testing Agent | Grail interception patterns, import boundary issues |
| `code-review-agent-findings.md` | Code Review Agent | Recurring patterns, false positive learnings |
| `security-review-agent-findings.md` | Security Review Agent | CVE trends, recurring injection vectors |
| `architect-agent-findings.md` | Architect Agent | Architecture debt register, patterns |
| `accessibility-agent-findings.md` | Accessibility Agent | Strato a11y confirmations, recurring gaps |
| `ux-review-agent-findings.md` | UX Review Agent | Experience standard violations, Strato misuse |
| `dql-query-agent-findings.md` | DQL Query Agent | Validated patterns, performance lessons |
| `dql-test-writer-agent-findings.md` | DQL Test Writer Agent | Test coverage, position-index issues, BaseRecord patterns |

`cache.md` is the single most important file — it is the cross-agent shared context. Every agent reads it first and writes to it after every step.

---

## 9. Anti-Patterns

These are the most common failure modes this system is designed to prevent:

| Anti-pattern | Why it fails | What to do instead |
|---|---|---|
| Agent skips `cache.md` on start | Loses cross-session context, re-asks answered questions | Always read `cache.md` first (Session Start Protocol) |
| Agent validates after every micro-edit | Wastes context window, types reference each other | Create all files ? validate once ? fix all ? validate once |
| Agent fixes lint manually | Misses auto-fixable issues, introduces new errors | `npx eslint --fix <file>` first, then address remainders |
| E2E test imports from `src/` | `SyntaxError: Unexpected token '.'` at runtime (Strato CSS-in-JS) | Only import from `e2e/src/`, `dql/`, `src/app/models/` (pure TS) |
| Interface changed, consumers not traced | Cascading type errors across codebase | Search all imports of the changed type before changing it |
| Mock data missing fields | `undefined` at runtime in component tests | Mock must include **all** fields from the interface |
| Fix loop runs > 3 times on same error | Context window waste, no new information | Escalate to human with full error context after 3 attempts |
| Review agent flags Strato internals | False positives � Strato handles a11y/UX internally | Use `strato_get_component` to verify before flagging |
| Agent truncates terminal output | Loses exact error messages needed to fix failures | Always show full logs � never summarise terminal output |
| Agent writes findings only at session end | Context lost if window fills mid-session | Append findings incrementally after each step |
| Page-specific utils placed in `src/app/utils/` | Pollutes global namespace with logic no other page needs | Place in `src/app/pages/<Page>/utils/<name>Utils.ts` |
| Page-specific component placed in `src/app/components/` | Implies false reusability; misleads future readers | Place in `src/app/pages/<Page>/components/<Name>.tsx` |
| New global utils file for logic already in an existing one | Duplicates domain knowledge, splits related functions | Check all files in `src/app/utils/` first; extend the matching one |
| Agent adds unprompted fields/parameters to an interface | YAGNI violation � "future use" additions break spec compliance | Implement exactly what requirements.md specifies |
| Agent extracts a shared abstraction for single-use logic | Premature DRY � creates false reusability promise | Wait for 3+ consumers before extracting; tolerate mild duplication |
| Agent reads every file in a directory "just in case" | Burns context budget on low-value files | Apply Context Triage skill � read in priority order, stop at budget |

---

## 10. Key Files Reference

### Agent Files

| File | Purpose |
|---|---|
| `.github/agents/coding.agent.md` | Production code implementation |
| `.github/agents/agent-smith.agent.md` | LLM self-review — FAST (6 checks) + FULL (17 checks) |
| `.github/agents/unit-testing.agent.md` | Jest unit test generation |
| `.github/agents/component-testing.agent.md` | Playwright component test generation |
| `.github/agents/e2e-testing.agent.md` | Playwright E2E test generation |
| `.github/agents/code-review.agent.md` | Code quality + documentation review |
| `.github/agents/security-review.agent.md` | Security audit |
| `.github/agents/architect.agent.md` | Architecture review |
| `.github/agents/accessibility.agent.md` | WCAG 2.2 AA review |
| `.github/agents/ux-review.agent.md` | UX / Strato correctness review |
| `.github/agents/dql-query.agent.md` | DQL query development |
| `.github/agents/dql-test-writer.agent.md` | DQL sandbox test authoring |
| `.github/agents/requirements.agent.md` | Ticket-scoped + ad-hoc requirements refinement |

### Skill Files

| File | Purpose |
|---|---|
| `.github/skills/validation-pipeline.skill.md` | typecheck + lint + test + coverage sequence |
| `.github/skills/consumer-tracing.skill.md` | Trace all consumers of changed types |
| `.github/skills/pattern-matching.skill.md` | Read examples before writing (5-step procedure) |
| `.github/skills/error-recovery.skill.md` | Decision tree + Pause-and-Ask paths |
| `.github/skills/mcp-tools.skill.md` | Cached knowledge-first MCP usage |
| `.github/skills/agent-smith-checks.skill.md` | 17 hallucination check definitions |
| `.github/skills/playwright-browser.skill.md` | Browser inspection + ARIA verification |
| `.github/skills/context-triage.skill.md` | Priority-ordered file reading |
| `.github/skills/discussion.skill.md` | Research, challenge, OQ, decision recording |
| `.github/skills/test-execution.skill.md` | Test runner + coverage reporter |
| `.github/skills/changelist.skill.md` | Multi-CL mode definition and per-CL gates |
| `.github/skills/system-refinement.skill.md` | Agent system improvement + overengineering gate |

### Base Files

| File | Purpose |
|---|---|
| `.github/base/instructions.md` | **Highest authority** — command lookup table, anti-patterns, import boundary rules |
| `.github/base/workflow.md` | Canonical workflow reference — Mermaid diagram, per-phase gates, loop limits |
| `.github/base/human-testing-guidelines.md` | State-of-the-art human review and manual testing guide — browser verify checklist, code reading, exploratory testing, cognitive bias traps |
| `.github/base/state-of-the-art.md` | Best practices knowledge base |
| `.github/base/agents-definition.md` | Master catalogue of all agents |
| `.github/base/prompts-definition.md` | Prompt orchestration catalogue |
| `.github/base/skills-definition.md` | Master catalogue of all skills |
| `.github/base/knowledge/codebase.md` | Domain types, utils, API functions, canonical patterns |
| `.github/base/knowledge/strato.md` | Strato import map and component APIs |
| `.github/base/knowledge/dql-patterns.md` | Validated DQL patterns and field name reference |
| `.github/base/knowledge/testing-patterns.md` | CT and E2E boilerplate examples |
| `.github/base/knowledge/software-principles.md` | KISS, YAGNI, DRY, SRP, SoC, Fail Fast |
| `.github/copilot-instructions.md` | Coding standards — TypeScript, components, testing, naming |

### Command Lookup (from `instructions.md`)

| Task | Command |
|---|---|
| TypeScript check | `npm run typecheck` |
| Lint | `npm run lint` |
| Lint autofix | `npx eslint --fix <file>` |
| Unit tests | `npm run test:app -- --testPathPattern="<pattern>"` |
| Unit tests + coverage | `npm run test:app -- --testPathPattern="<pattern>" --coverage --collectCoverageFrom="<source>"` |
| Component tests | `npm run test:ct -- --grep "<name>"` |
| E2E tests | `npm run test:e2e` |
| DQL tests | `npm run test:dql` |
| A11y tests | `npm run test:a11y` |
| Integration tests | `npm run test:it` |
| Refresh codebase knowledge | `npm run knowledge:refresh` |

> Always use `npm run` scripts — never raw `jest`, `tsc`, or `eslint` with custom flags. Every script is pre-configured in `package.json`.

---

## 11. CI Integration � AI Gate in GitHub Actions

This repository runs a **dynamic AI code review agent** on every pull request as a required status check. Unlike static linters, it reviews intent and patterns � not just syntax.

### How it works

```
PR opened / commit pushed
        �
        ?
.github/workflows/ai-pr-review.yml
        �
        +-- git diff origin/<base>...HEAD ? pr.diff + changed-files.txt
        �
        +-- .github/scripts/ai-pr-review.mjs
        �     +-- Loads .github/agents/code-review.agent.md   (Review Checklist section)
        �     +-- Loads .github/agents/security-review.agent.md (Security Checklist section)
        �     +-- Calls GitHub Models API / OpenAI with diff + checklists
        �     +-- Parses structured JSON response (errorCount, findings per file)
        �     +-- Upserts a single PR comment (updates in place on every push)
        �
        +-- Enforce gate step
              +-- verdict = REQUEST_CHANGES ? exit 1 (?? breaks the pipeline)
              +-- verdict = APPROVE         ? exit 0 (? passes)
```

### Key properties

| Property | Behaviour |
|---|---|
| **Dynamic** | Review checklist is read live from agent files � update the agent, the CI check updates automatically |
| **Non-blocking on failure** | If the AI API is unavailable, the check passes (never blocks PRs due to infra issues) |
| **Single comment** | Upserts one comment per PR � no comment spam on every push |
| **Draft skip** | Skips draft PRs entirely |
| **Concurrency** | Cancels in-progress reviews when a new push arrives |
| **Two-model support** | Uses GitHub Models by default (no secrets needed); set `OPENAI_API_KEY` repo secret to use OpenAI directly |

### Severity gate

| Finding | Symbol | Blocks pipeline? |
|---|---|---|
| Error | ?? | ? Yes � `verdict = REQUEST_CHANGES`, enforce gate exits 1 |
| Warning | ?? | No � reported but does not block |
| Suggestion | ?? | No � reported as informational |

### Setup: make it a required check

1. Go to **Settings ? Branches ? Add rule** on `main`
2. Enable **Require status checks to pass before merging**
3. Search for and add: **`Agent Review`** (the job name in `ai-pr-review.yml`)
4. Enable **Require branches to be up to date before merging**

### Files

| File | Purpose |
|---|---|
| `.github/workflows/ai-pr-review.yml` | Workflow � triggers, permissions, enforce gate |
| `.github/scripts/ai-pr-review.mjs` | Script � diff loading, prompt building, API call, comment upsert |

### Optional: use OpenAI instead of GitHub Models

Add a repository secret `OPENAI_API_KEY`. The script auto-detects it and switches to `https://api.openai.com/v1/chat/completions`. No workflow changes needed.


