bluecraft/skills/agent-docs-repo-alignment/SKILL.md

name, description

name	description
agent-docs-repo-alignment	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.