bjornmelin/docs-align
skills/docs-align/SKILL.md
Align docs with code. Detect drift and update ADRs, specs, README, AGENTS. Use after implementation or for docs drift reviews. Not for code review fixes or platform architecture.
$ install --global
skillsauthnpx skillsauth add bjornmelin/dev-skills docs-alignInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Jun 11, 2026, 3:50 AM387.9s4 files scanned
SKILL.md
- name:
- docs-align
- description:
- Align docs with code. Detect drift and update ADRs, specs, README, AGENTS. Use after implementation or for docs drift reviews. Not for code review fixes or platform architecture.
Docs Align
Use this skill after implementation work or when you suspect documentation drift.
Workflow
- Read the repo
AGENTS.md. - From this skill root (directory containing
SKILL.md), run drift collection (requiresgiton PATH):python3 scripts/docs_drift.py collect --cwd <repo> --out <json>- Equivalent collect-only shortcut:
python3 scripts/check_docs_drift.py --cwd <repo> --out <json>
python3 scripts/docs_drift.py compare --input <json> --out <json>- Render the summary:
python3 scripts/docs_drift.py render --input <json> --format md
- Use Alignment policies below only for doc surfaces that the gap map says are in scope.
- Update docs only after the gap map is clear.
Path note
Commands above assume the current working directory is this skill’s root (skills/docs-align in this repository). If the working directory is elsewhere, invoke the same files with an absolute path, for example:
python3 "<skill-dir>/scripts/docs_drift.py" collect --cwd <repo> --out <json>
Alignment policies
ADR
Create or update an ADR when the implementation changed:
- architecture boundaries
- execution model
- durable workflow policy
- major dependencies or infrastructure choices
Do not create ADR churn for small local refactors.
Spec
Update product or architecture specs when the implementation changed:
- interfaces
- contracts
- verification steps
- operational behavior
Prefer deleting stale spec text over leaving contradictory guidance.
README
Update the README when the change affects:
- setup
- commands
- environment variables
- high-level architecture or usage expectations
Keep the README high signal; move deep details into docs when needed.
Use When
- The task is post-implementation doc alignment.
- The user wants README, ADR, spec, or AGENTS updates based on code changes.
Do Not Use When
- The task is only code review remediation.
- The task is only dependency planning.
Outputs
- likely impacted docs
- missing/update/delete doc tasks
- a concise docs alignment summary
Related Skills
bjornmelin/multi-model-review
development
VerifiedTrustedCommunity
Pre-PR multi-model review, parallel opus and codex exec adversarial lanes, then adversarial verification of merged findings. Read-only. Use before shipping nontrivial diffs.
3SKILL.mdUpdated Jul 23, 2026
bjornmelin/codex-review
tools
VerifiedTrustedCommunity
Independent gpt-5.6 diff review via the Codex CLI, normal or steerable adversarial with JSON findings. Use before shipping nontrivial changes.
3SKILL.mdUpdated Jul 23, 2026
bjornmelin/codex-delegate
development
VerifiedTrustedCommunity
Delegate implementation, investigation, or bulk work to gpt-5.6 codex via pinned codex exec. Use for clear-spec builds, migrations, debugging, or any task MODELS.md routes to codex.
3SKILL.mdUpdated Jul 23, 2026
bjornmelin/pre-mortem
development
VerifiedTrustedCommunity
Adversarial pre-mortem: imagine the plan failed, work backwards to surface risky assumptions + irreversible bets, then harden them. Proactively offer it (after the current request; confirm first) before a hard-to-reverse or one-way-door call (API, schema, framework, a hire), an all-upside plan, or unvalidated assumptions. Also on request.
3SKILL.mdUpdated Jul 22, 2026