Project Docs Maintainer

Use one canonical skill entrypoint for documentation maintenance, then choose the matching mode.

Inputs

• mode=skills_readme_maintenance
  • Required: --workspace <path>
  • Optional: --repo-glob <glob>, repeatable --exclude <path>, --apply-fixes
• mode=roadmap_maintenance
  • Required: --project-root <path>, --run-mode <check-only|apply>
  • Optional: --roadmap-path <path>
• Use canonical mode names in all new prompts.
• Treat skills_readme_alignment as compatibility-only.

Workflow

1. Pick the canonical mode from the user request.
2. Run the read-only variant first:
   • skills_readme_maintenance: audit first
   • roadmap_maintenance: --run-mode check-only first
3. Review findings and keep the fix scope bounded to the selected mode.
4. If the user requested edits, run the corresponding bounded write path:
   • skills_readme_maintenance: --apply-fixes
   • roadmap_maintenance: --run-mode apply
5. Re-run the same mode to confirm remaining issues.
6. 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