feat(agents): gen-repo-instructions — generate repo-specific .instructions.md from a codebase

### Custom Agent Name

gen-repo-instructions

### Type

Custom Agent

## Purpose

Engineering teams repeatedly hit the same friction: GitHub Copilot produces code that doesn't match a repository's established conventions, so engineers hand-write ad-hoc guardrail instructions on every project. This was a consistent theme across recent internal HVE engagements, where practitioners reported:

- "Copilot had a tendency to do something wrong — I would add some kind of repo tool or Copilot instructions to fix that."
- Repo-specific guardrail instruction files were described as "really mission critical."

hve-core today ships excellent *static, language-level* instructions (csharp, python, bash, terraform, etc.), but there is no agent that **generates repository-specific** `.instructions.md` files from an existing codebase's actual patterns. (Verified: no existing agent under `.github/agents/` covers this; it is a genuine gap, not a duplicate of the research/discovery/indexing/planning categories.)

This is a **generator** agent: it inspects a repo only to gather evidence, and its sole deliverable is repo-specific `.github/instructions/**/*.instructions.md` files — codifying observed conventions (dependency injection, error handling, data access, API contracts, auth helpers, test structure) so Copilot follows the project's patterns by default.

## Requirements

Behaviors the agent should enable:

- **Three phases:** (1) **Repository Scan** — detect stacks, tooling config, existing guidance, and monorepo package boundaries; exclude generated/vendored output. (2) **Instruction Generation** — sample representative files, derive evidence-backed rules, emit one focused file per cluster with a narrow `applyTo` glob, RFC 2119 keywords, and inline evidence citations. (3) **Validation & Generation Summary** — verify globs match real files, scan snippets for secrets, dedupe against existing instructions, and report a confidence distribution.
- **Repo-specific deltas only** — never restate generic language rules already covered by `copilot-instructions.md` or the static `coding-standards` instructions.
- **Evidence-graded keywords** — config-enforced / 4+ examples → MUST; 2–3 examples → SHOULD; single occurrence → omitted and flagged for human review. Clusters with no stable convention are skipped rather than fabricated.
- **Idempotent re-runs** — generated content lives between managed markers so human edits are preserved; conflicts are flagged, not silently overwritten.
- **Safe** — writes only under `.github/instructions/`; never modifies source; never inlines secrets (Phase-3 secret scan with concrete patterns).

**Proposed home:** the `coding-standards` collection (complements the static language instructions). Targets latest Anthropic/OpenAI models only; `model` omitted so the primary agent inherits the session model.

A working implementation plus a standalone validator, a frontmatter JSON schema, and a runnable mock-repo fixture are already prototyped and validate clean — happy to open the PR on a thumbs-up.

**Questions for maintainers:**
1. Is `coding-standards` the right collection for this agent?
2. Should the per-stack detection playbook and topic taxonomy live in the agent body, or be moved to a referenced docs page to keep the agent lean?

Start by reviewing the existing .github/agents/ content and the coding-standards collection, then compare the proposed agent with copilot-instructions.md and static coding-standards instructions. Validate the prototyped agent, standalone validator, frontmatter JSON schema, and mock-repo fixture against the three required phases; done means safe, evidence-backed files under .github/instructions/**/*.instructions.md with idempotent markers and a generation summary.

Written by the indexing model from the issue text.