Use one canonical skill entrypoint for documentation maintenance, then choose the matching mode.
Inputs
mode=skills_readme_maintenance
Required:
--workspace
Optional:
--repo-glob
, repeatable
--exclude
,
--apply-fixes
mode=roadmap_maintenance
Required:
--project-root
,
--run-mode
Optional:
--roadmap-path
Use canonical mode names in all new prompts.
Treat
skills_readme_alignment
as compatibility-only.
Workflow
Pick the canonical
mode
from the user request.
Run the read-only variant first:
skills_readme_maintenance
audit first
roadmap_maintenance
:
--run-mode check-only
first
Review findings and keep the fix scope bounded to the selected mode.
If the user requested edits, run the corresponding bounded write path:
skills_readme_maintenance
:
--apply-fixes
roadmap_maintenance
:
--run-mode apply
Re-run the same mode to confirm remaining issues.
Return the mode-specific Markdown and JSON report shape.
skills_readme_maintenance
Script:
scripts/skills_readme_maintenance.py
Scope:
README.md
maintenance for
*-skills
repositories
References:
references/output-contract.md
references/section-schema.md
references/discoverability-rules.md
references/profile-model.md
roadmap_maintenance
Script:
scripts/roadmap_alignment_maintainer.py
Scope: checklist-style
ROADMAP.md
validation, migration, and bounded normalization
References:
references/roadmap-customization.md
references/roadmap-config-schema.md
Output Contract
skills_readme_maintenance
Return Markdown plus JSON with:
run_context
repos_scanned
profile_assignments
schema_violations
command_integrity_issues
fixes_applied
post_fix_status
errors
If there are no issues and no errors, output exactly
No findings.
roadmap_maintenance
Return Markdown plus JSON with:
run_context
findings
apply_actions
errors
If there are no findings, no apply actions, and no errors, output exactly
No findings.
Guardrails
Never auto-commit, auto-push, or open a PR.
Never edit source code, manifests, lockfiles, or CI files.
In
skills_readme_maintenance
, keep edits bounded to
README.md
and explicitly approved snippet insertions into
AGENTS.md
.
In
roadmap_maintenance
,
apply
mode may edit only the target
ROADMAP.md
.
Keep deprecated aliases out of the main path and mention them only when handling legacy prompts.
References
references/output-contract.md
references/skills-readme-maintenance-automation-prompts.md
references/roadmap-automation-prompts.md
references/profile-model.md
references/section-schema.md
references/discoverability-rules.md
references/fix-policies.md
references/roadmap-customization.md
references/roadmap-config-schema.md