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