---
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. 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
4. Record observed facts first.
5. Compare doc claims against repo facts.
6. Report:
   - confirmed matches
   - must-fix drift
   - wording drift or ambiguity

## 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.