# Checklist: Agent Configuration

Use this checklist to verify a project's GitHub Copilot configuration is complete and well-structured.

For each item, mark `[x]` (done), `[/]` (partial), or leave blank (missing).

---

## Repository Instructions

The single highest-leverage Copilot customization file.

- [ ] `.github/copilot-instructions.md` exists at the repo root.
- [ ] File is under 150 lines (ideally 80–120).
- [ ] First paragraph states what the project is in 2–4 sentences.
- [ ] Tech stack section lists language, framework, database, testing, CI.
- [ ] Build & test commands section lists install, dev, test (all + single), lint, typecheck, build — each as a copy-pasteable command.
- [ ] Architecture section names the top-level directories with one-line purpose each.
- [ ] Conventions section lists 3–7 concrete rules (naming, error handling, imports, etc.).
- [ ] Verification checklist tells Copilot what to run before suggesting a change is complete.
- [ ] Common pitfalls section lists 3+ project-specific gotchas.
- [ ] Links to deeper docs (`ARCHITECTURE.md`, `docs/specs/`, style guides) instead of duplicating them.
- [ ] No placeholder brackets remain.
- [ ] Information matches actual repository state (commands work, paths exist).

## Scoped Instructions

Pattern-scoped rules that activate via `applyTo` globs.

- [ ] At least one file exists under `.github/instructions/` if the project has distinct zones (tests vs source, migrations, generated code, frontend vs backend).
- [ ] Each `.instructions.md` file starts with valid YAML frontmatter (`applyTo`, `description`).
- [ ] `applyTo` patterns match actual file extensions and directories.
- [ ] No file uses `applyTo: "**"` — that belongs in `.github/copilot-instructions.md`.
- [ ] Each file is under 60 lines and focused on one concern.
- [ ] At minimum, a `tests.instructions.md` exists if the project has tests.

## Reusable Prompts

`.github/prompts/*.prompt.md` files invoked as slash commands.

- [ ] `.github/prompts/` exists with the 16 `harness-*.prompt.md` files installed.
- [ ] Project-specific prompts also live here (e.g., `code-review.prompt.md`, `draft-pr.prompt.md`).
- [ ] Each prompt has valid YAML frontmatter with `description` and `mode`.
- [ ] Each prompt body specifies an explicit output format.
- [ ] No prompt is over 100 lines.

## Custom Agents

`.github/agents/*.md` files for specialized Copilot agent personas.

- [ ] At least one custom agent exists (planner or reviewer is the minimum useful pair).
- [ ] Each agent has valid YAML frontmatter with `description`.
- [ ] Agents that should not edit files declare a restricted `tools` allowlist.
- [ ] Each agent body specifies what it does **and what it never does**.
- [ ] Each agent file is under 80 lines.

## Universal Agent Config

`AGENTS.md` — read by Copilot Coding Agent and most other coding agents.

- [ ] `AGENTS.md` exists at the repo root.
- [ ] File is under 120 lines (ideally ~100).
- [ ] Build & run, project structure, architecture, code style, testing, key docs, verification, agent-specific notes sections present.
- [ ] Test pattern code block adapted to the project's actual test framework.
- [ ] All file paths and commands are real and current.
- [ ] No contradictions with `.github/copilot-instructions.md`.

## MCP Wiring (Optional)

`.vscode/mcp.json` wires Model Context Protocol servers to Copilot Chat.

- [ ] If MCP servers are used, `.vscode/mcp.json` exists and is valid JSON.
- [ ] Each server entry has minimum-necessary scope (filesystem servers scoped to `${workspaceFolder}`, not `/`).
- [ ] Secrets read from `${env:NAME}`, never inlined.
- [ ] No commented-out or unused server entries.

## Consistency Checks

Verify the customization layer is internally coherent.

- [ ] `.github/copilot-instructions.md` and `AGENTS.md` do not contradict each other.
- [ ] All file paths in customization files exist (`ls` or `test -e`).
- [ ] All build/test/lint commands actually run.
- [ ] Verification checklist items map to real commands.
- [ ] Glossary terms (if any) are used consistently across customization files.

## Maintenance Signals

A project with a healthy harness shows these signs.

- [ ] `git log -- .github/copilot-instructions.md` shows commits in the last 90 days.
- [ ] Code-review PRs that change architecture also update `.github/copilot-instructions.md` / `AGENTS.md`.
- [ ] A `harness-changelog.md` (or equivalent) tracks customization updates linked to code changes.
- [ ] Instruction-rot scan (`/harness-entropy`) reports zero stale references.

## Coverage by Skill

For full coverage, each of these skills should have been run (or its work done manually) at least once:

- [ ] `/harness-copilot-instructions`
- [ ] `/harness-instructions`
- [ ] `/harness-prompts`
- [ ] `/harness-agents`
- [ ] `/harness-agents-md`
- [ ] `/harness-architecture`
- [ ] `/harness-verify`
- [ ] `/harness-hooks`
- [ ] `/harness-ci`
- [ ] `/harness-linters` (optional but valuable)
- [ ] `/harness-entropy`

## Failure Modes to Watch For

- `.github/copilot-instructions.md` exceeds 200 lines.
- Customization files were generated by an agent and adopted verbatim.
- Multiple top-level instruction files contradicting each other.
- A scoped `.instructions.md` file using `applyTo: "**"`.
- Prompts that don't specify their output format.
- Custom agents without an explicit "never" list.
- Build/test commands that no longer work.
- Architecture descriptions referencing directories that no longer exist.

If you find any of these, run `/harness-maintain` or rerun the relevant generator skill.