Docs Alignment Maintainer
Run a deterministic two-pass docs alignment workflow across repositories under a provided workspace root. Detect drift first, then apply only bounded high-confidence fixes when requested.
Inputs
Pass runtime inputs from the calling prompt:
--workspace <path>--exclude <path>(repeatable)- Optional
--exclude-file <path>with one path per line
Defaults are intentionally not hardcoded in the skill body so automation can control scope per run.
Workflow
- Run pass 1 discovery and checks with
scripts/docs_alignment_maintainer.py. - Review unaligned repos and issue categories.
- If safe remediation is desired, run pass 2 with
--apply-fixes. - Re-check touched repos (handled by the script) and inspect remaining issues.
- Report results from Markdown and JSON outputs.
Commands
Audit only:
python3 scripts/docs_alignment_maintainer.py \
--workspace ~/Workspace \
--exclude ~/Workspace/services \
--print-md \
--print-jsonAudit and safe fixes:
python3 scripts/docs_alignment_maintainer.py \
--workspace ~/Workspace \
--exclude ~/Workspace/services \
--apply-fixes \
--md-out /tmp/docs-alignment-report.md \
--json-out /tmp/docs-alignment-report.jsonFail the run when unresolved issues remain:
python3 scripts/docs_alignment_maintainer.py \
--workspace ~/Workspace \
--exclude ~/Workspace/services \
--apply-fixes \
--fail-on-issuesSafety Rules
- Never commit changes automatically.
- Edit docs only (for example
README.md,CONTRIBUTING.md,ROADMAP.md,docs/*.md). AGENTS.mdis out-of-scope for this skill and is owned by a dedicated AGENTS maintainer workflow.- Never edit source code, lockfiles, or manifests.
- Apply only bounded replacements and concise quickstart insertion when evidence is explicit.
- Keep diffs minimal and preserve existing formatting style.
Output Contract
The script emits:
- Markdown summary with run context, discovery summary, unaligned repos, fixes applied, remaining issues, modified files, and errors.
- JSON report containing:
- run_context - repos_scanned - unaligned_repos - fixes_applied - post_fix_status - errors
Use JSON for automation pipelines and Markdown for operator review.
Automation Templates
Use $docs-alignment-maintainer inside automation prompts so Codex reliably loads this skill context.
For ready-to-fill Codex App and Codex CLI (codex exec) templates, including guardrails, placeholders, and customization knobs, use:
references/automation-prompts.md
References
- Common checks and discovery rules:
references/checks-common.md - Swift guidance:
references/checks-swift.md - JS/TS guidance:
references/checks-js-ts.md - Python guidance:
references/checks-python.md - Rust guidance:
references/checks-rust.md - Safe-fix policy boundaries:
references/fix-policies.md - Report schema and section contract:
references/output-contract.md - Automation prompt templates:
references/automation-prompts.md