---
name: agent-docs-repo-alignment
description: Use when checking whether AGENTS.md and agent-docs still match repository facts such as scripts, ports, directory structure, contract ownership, runtime behavior, or verification commands.
---

# Agent Docs Repo Alignment

## Overview

Use this skill to compare AGENTS and `agent-docs` against the real repository. It detects drift between documentation and code, config, scripts, tests, and folder structure.

## When to Use

- The user asks whether docs still match the repository
- A doc mentions commands, ports, packages, stack choices, routes, DTO ownership, or runtime behavior
- A previous audit found wording that might be stale
- A refactor changed scripts or layout and the docs may need follow-up updates

## Workflow

1. Read the docs in scope.
2. Read `../agent-docs/references/repo-alignment-checklist.md`.
3. Read `../agent-docs/references/severity-model.md`.
4. Read `../agent-docs/references/report-format.md`.
5. Inspect the repository facts relevant to the claim:
   - scripts and `package.json`
   - ports and proxy config
   - directory and package structure
   - shared contracts and DTO ownership
   - tests or verification commands
   - runtime and thread-sync code paths when relevant
6. Record observed facts first.
7. Compare doc claims against repo facts.
8. For each finding or confirmation, report it in this order:
   - doc claim
   - observed repo fact
   - result: `confirmed` / `must-fix drift` / `wording drift`
   - severity when the item is not `confirmed`
9. Use the repo-alignment shape from `report-format.md`.
10. Keep `must-fix drift` for statements that currently misstate repository facts, commands, ownership, or behavior. Use `wording drift` for stale or imprecise wording that should still be cleaned up.

## Boundary

- This skill checks docs against repo facts.
- It does not replace structural graph checks from `agent-docs-consistency`.
- It does not perform the actual doc rewrite; use `agent-docs-refactor` for that.