repo-agent-context-audit

# Repo Agent Context Audit

## Overview

Assess whether a repository has a small, usable agent context stack: a short top-level instruction file, task-specific skills, and behavior/implementation specs for substantial work. Default to a read-only audit and minimal recommendations; create or edit high-context files only when the user explicitly asks.

If the user asks to generate, split, or apply root/scoped `AGENTS.md` files,
handoff to `agentsmd-scaffold`. This skill may identify that scaffold as the
smallest useful change, but should not duplicate the generation workflow.

## Default Standard

Prefer this three-layer shape:

1. `AGENTS.md` or repo-equivalent: 80-150 lines, top-level routing only.
2. `.agents/skills/<task>/SKILL.md`: reusable workflows for common fragile tasks.
3. `specs/<id>/PRODUCT.md` and `specs/<id>/TECH.md`: checked-in contracts for substantial features.

Do not force this exact layout when a repo already has a coherent equivalent, such as `WARP.md`, `CLAUDE.md`, `CONTRIBUTING.md`, or framework-specific instruction files. Map existing files to the layers first, then fill only the real gaps.

## Workflow

### 1. Discover

Run the read-only scanner when possible:

```bash
# From this skill directory:
python3 scripts/scan_repo_context.py <repo-root>
```

Then inspect the important files directly. Always search before creating:

- `AGENTS.md`, `CLAUDE.md`, `WARP.md`, `.claude/instructions.md`
- `CONTRIBUTING.md`, `README.md`, `.github/copilot-instructions.md`
- `.agents/skills/*/SKILL.md`
- `specs/**/{PRODUCT,product,TECH,tech}.md`

If multiple instruction files overlap, record their scopes and precedence instead of merging them by default.

### 2. Classify

Classify the repo into one of these states:

- **Healthy**: short top-level guidance, task workflows, and specs are discoverable.
- **Missing top-level router**: useful docs exist but agents lack an entrypoint.
- **Overloaded top-level file**: one file mixes rules, workflows, architecture, and reference data.
- **Specless complex repo**: substantial work happens without PRODUCT/TECH contracts.
- **Stale or divergent**: instructions contradict code, scripts, or observed repo conventions.
- **Unsafe to modify**: high-context files are generated, externally owned, or conflict across scopes.

### 3. Score

Use the rubric in `references/standards.md` for:

- top-level routing quality
- progressive disclosure
- procedural workflows
- decision gates
- production examples
- spec quality
- validation mapping
- stale or conflicting guidance risk

### 4. Recommend

Lead with the smallest useful change. Good recommendations usually look like:

- Add a short `AGENTS.md` that points to existing docs instead of duplicating them.
- Split a long top-level file into a router plus references or skills.
- Add `.agents/skills/write-product-spec` and `.agents/skills/write-tech-spec` only if spec writing is repeated.
- Add `specs/<id>/PRODUCT.md` and `TECH.md` templates only if the repo ships substantial features.
- Remove or rewrite stale instructions only after citing the conflict.

### 5. Handoff Or Scaffold Only On Request

When the user explicitly asks to generate, split, or apply root/scoped
`AGENTS.md` files, use `agentsmd-scaffold` instead of duplicating that workflow.

When the user asks for exact PRODUCT/TECH spec templates or non-AGENTS context
scaffolding, read `references/templates.md` and adapt the templates to the repo.
Before editing:

- identify every `AGENTS.md` or equivalent whose scope covers the target path
- preserve existing high-context files unless the user asked for a rewrite
- keep generated docs small
- include actual repo commands, paths, and test gates
- leave placeholders only when the repo truly lacks the fact

## Decision Gates

| Case | Action |
|---|---|
| Small bugfix repo with README and clear tests | No spec system; maybe add a short `AGENTS.md` router |
| Repeated feature work with review churn | Add PRODUCT/TECH spec workflow |
| User asks to generate or apply root/scoped `AGENTS.md` files | Use `agentsmd-scaffold` |
| Existing `CLAUDE.md` or `WARP.md` is good | Link it from `AGENTS.md` or leave it as the repo-equivalent |
| Multiple teams or nested packages | Use scoped nested `AGENTS.md` only where rules genuinely differ |
| High-context file over 200 lines | Split into top-level router plus referenced skills/docs |
| User asks for bulk normalization | Audit first; do not batch edit until 2-3 repos have been manually validated |

## Operating Contract

Direct actions:
- Run read-only discovery, scoring, and scanner commands.
- Produce an audit report with cited files and smallest useful changes.
- Draft exact non-AGENTS scaffold content when the user asks for proposed text.
- Handoff AGENTS.md generation or application to `agentsmd-scaffold`.

Escalate before:
- Creating or editing `AGENTS.md`, `CLAUDE.md`, `WARP.md`, hooks, settings, or generated docs.
- Rewriting existing repo instructions instead of adding a short router or pointer.
- Batch-normalizing multiple repositories.

Evidence-backed pushback:
- Challenge new skill/spec scaffolding when the repo is small, has no repeated workflow, or already has a coherent equivalent.
- Challenge edits when the only evidence is style preference rather than a real agent failure, review bottleneck, or missing workflow.

Feedback loop:
- Promote repeated audit findings into the target repo's router, a task skill, or a spec template.
- Keep this skill's rubric and templates updated when multiple repos expose the same false positive or missing decision gate.

## Gotchas

- Do not treat every README as an agent instruction file. Top-level README files are usually entrypoints; nested README files are supporting evidence unless a repo explicitly routes agents there.
- Do not add `AGENTS.md` just because it is missing. If `CLAUDE.md`, `WARP.md`, or `CONTRIBUTING.md` already works as a coherent router, recommend a pointer or no change.
- Do not create PRODUCT/T