Customization Layer (`.github/`)¶

This page is the docs-side index of the agent customization that lives under .github/. The single source of truth — including invocation syntax — is the human-facing guide .github/AGENT_CUSTOMIZATION.md. This page summarises what exists and why, with direct links to each artifact.

Status: Operational. All artifacts listed below are wired and in use.

Layout¶

.github/
├── copilot-instructions.md   # always-on project rules
├── AGENT_CUSTOMIZATION.md    # human-facing guide
├── agents/                   # *.agent.md — specialised subagents
├── instructions/             # *.instructions.md — scoped rules (applyTo)
├── prompts/                  # *.prompt.md — single focused tasks
├── skills/                   # SKILL.md folders — multi-step workflows + assets
└── hooks/                    # *.json + scripts — deterministic lifecycle checks

Activation tiers¶

The four tiers map to when the agent sees a rule. Memorise the tier, not the file.

Tier	Triggered by	Developer action	Artifact type
Always-on	Every request	Nothing	`copilot-instructions.md`
Auto-attached	Editing a matching file	Nothing — just edit	`*.instructions.md` (`applyTo` glob)
On-demand	`/` picker or agent switch	Pick from picker	prompts, skills, agents
Deterministic	Tool lifecycle event	Nothing	hooks

This separation keeps the always-on context small (cheap tokens, fast latency) while still covering specialised paths when they become relevant.

Always-on rules¶

Artifact	Purpose
`copilot-instructions.md`	Project-wide rules: boundaries, reproducibility, ML guardrails, conflict resolution order, hard prohibitions. Loaded on every request.

Scoped instruction files (auto-attached)¶

Each file declares an applyTo glob. The matching file in the editor pulls the rule set into context automatically — no manual invocation.

File	Scope	What it enforces
`python.instructions.md`	`*/.py`	Style, type hints, exceptions, logging, no opportunistic refactor
`api.instructions.md`	`src/app/**`	FastAPI router/service/task boundaries, DI, idempotency, schemas
`ml-features.instructions.md`	`src/features/**`	Purity, determinism, leakage prevention
`mlflow.instructions.md`	training / tuning / register / loader paths	Tracking, registry, no ad-hoc model loading
`dvc-pipelines.instructions.md`	`dvc.yaml`, `params.yaml`, `src/pipelines/**`	Stage contracts, parameter rules, reproducibility
`airflow.instructions.md`	`airflow/dags/**`	DAG purity, idempotency, scheduling, DAG↔pipeline boundary
`tests.instructions.md`	`tests/**`	Determinism, offline-by-default, contract tests, what to protect
`docs.instructions.md`	`docs/**`	Status semantics, ADR template, structure
`agent-customization.instructions.md`	`.github/**`	How to add or modify customization safely

Subagents¶

Each agent is a narrow, read-only role — separate from the default chat agent so that context stays focused.

Agent	Role	Source
SoccerPredictAI Code Reviewer	Reviews a diff/file/PR against project boundaries, contracts, reproducibility, and ML guardrails. Read-only.	`agents/code-reviewer.agent.md`
SoccerPredictAI Docs Agent	Answers architecture/design/status questions via filesystem MCP access to `docs/`.	`agents/soccer-doc-agent.agent.md`

Prompts (on-demand, single task)¶

Each prompt is the standard procedure for one recurring task — invoked from the / picker.

Prompt	When to use
`new-feature`	Add a new feature engineering function in `src/features/`
`add-pipeline-stage`	Add or modify a DVC stage
`add-api-endpoint`	Add a FastAPI endpoint with router/service/schema split
`register-model`	Register a trained model in MLflow with the project's promotion rules
`debug-failing-test`	Diagnose a single failing or red-on-collect test
`release-checklist`	Pre-release checks (status, tests, contracts)
`sync-docs-with-code`	Reconcile a `docs/` page with current code reality

Skills (on-demand, multi-step workflows with bundled assets)¶

A skill is a folder: SKILL.md + scripts/templates the procedure relies on. Skills exist when a task is repeatable enough that the procedure itself is worth versioning.

Skill	What it does	Output
`audit-system`	Runs a numbered audit cycle (00–11+) covering data, features, training, registry, serving, orchestration, UI, ops/security, docs/testing	Reports under `docs/validation/<YYYYMMDD>/`
`plan-test-coverage`	Inventories `src/` ↔ `tests/`, builds gap matrix, prioritises (P0–P3), generates phased remediation plan	Plan under `docs/planning/<YYYYMMDD>_test.md`

The artifacts these skills produce are documented in Continuous System Audits and Iteration Plans.

Hooks (deterministic lifecycle)¶

Hooks fire on tool lifecycle events without developer action. They enforce checks the agent cannot skip.

Hook config	Purpose
`hooks/pre-tool-checks.json`	Pre-tool-call validation; backed by scripts in `hooks/scripts/`

External MCP servers¶

Server	Purpose	Wired in
`awesome-copilot-main`	Read-only catalogue of customization examples; consulted when designing new artifacts	`instructions/agent-customization.instructions.md`
`soccer-docs`	Read-only filesystem access to `docs/` for the docs subagent	`agents/soccer-doc-agent.agent.md`

Conflict resolution order¶

When rules conflict, the agent follows this order (defined in copilot-instructions.md):

Explicit user task
Correctness and safety
Reproducibility and boundary integrity
Documented contracts and intended architecture
Existing code conventions
Minimal patch size

Customization Layer (.github/)¶