# Harness-ready repository template

A GitHub **template repository** that drops a new repo into the org's AI-coding
harness from day one. Click **"Use this template"** to create a repo that already
has the standard instruction files, agents, workflows, and branch protection.

> QRefAI *AI Coding Field Guide*, Part 4 (Q4.1). This is the "golden repo" half of
> the distribution story; `bootstrap-repo.sh` is the "retrofit an existing repo" half.

## What you get

```
.
├── AGENTS.md                              # cross-vendor canonical context (open standard)
├── CLAUDE.md                              # thin Claude wrapper (@imports AGENTS.md)
├── .github/
│   ├── copilot-instructions.md            # Copilot repo-wide layer (4,000-char rule noted)
│   ├── instructions/
│   │   └── payments.instructions.md       # path-scoped rules (applyTo glob)
│   ├── agents/
│   │   └── security-scout.agent.md        # shared security reviewer persona
│   ├── workflows/
│   │   ├── security-guard.md              # gh-aw: per-PR security pass
│   │   └── agents-md-maintainer.md        # gh-aw: keeps AGENTS.md honest
│   └── rulesets/
│       └── main-protection.json           # auto Copilot review + required human review
└── .claude/
    └── settings.json                      # hooks seed (post-edit lint)
```

## After creating a repo from this template

1. Replace every `<PLACEHOLDER>` in `AGENTS.md`, `CLAUDE.md`, and
   `.github/copilot-instructions.md`.
2. Rename/extend `payments.instructions.md` to your real areas (auth, frontend…).
3. Compile the agentic workflows: `gh aw compile --strict`.
4. Import the ruleset (Settings → Rules → Rulesets → Import) if your org doesn't
   apply it automatically.
5. Add a real `CODEOWNERS` so `require_code_owner_review` has owners to request.

## Keeping repos in sync

This template is the **source of truth**. When you improve a golden file here,
propagate it to existing repos by re-running `bootstrap-repo.sh` (with
`OVERWRITE=1` for the files you intend to refresh). Author once, distribute many —
the same principle the guide applies to the harness itself.

_Mid-2026 snapshot. Re-verify vendor specifics before relying on them._