maintenance

name	maintenance
description	Use when you want to bring every drift-prone artifact in the repo back into sync. Dispatches to all individual update-* skills in the correct order, aggregates their results, and leaves a single combined PR ready to review.

Maintenance

This is the umbrella skill. It does no rewriting itself — it decides which sync skills are stale, runs each one, and reports a combined summary. Use it when you do not know which specific artifact is out of date, or when several have likely drifted at once (for example, after a large merge).

When to run

• After a big merge from main when you are not sure which surfaces moved.
• On a cadence (weekly / before a release) as a "drift sweep".
• When CI flags a staleness check but the agent is uncertain which skill to run.

Do not use this skill for a targeted fix — if you know the README is the only stale thing, call update-readme directly.

Registry

The registry is the single source of truth for which sync skills exist in this repo. Keep it in alphabetical order; every update-* directory under .agent/skills/ must appear here exactly once.

Skill	Fixes	Run order
update-spec	OSS_SPEC.md propagation into check.rs, templates, tests, docs	1 — run first so downstream skills see the new mandate
update-manpages	man/oss-spec.md vs. src/cli.rs clap definitions	2
update-docs	docs/*.md vs. source of truth	3
update-readme	README.md vs. CLI, spec, and supported languages	4
update-prompts	prompts/** vs. OSS_SPEC.md, validator, manifest enums, ai glue	5
update-website	website/ vs. README.md, docs/, and OSS_SPEC.md	6
sync-oss-spec	Repo contents vs. OSS_SPEC.md (runs oss-spec validate .)	7 — run last, it verifies that every upstream fix landed correctly

Run order matters: upstream fixes must land before downstream skills read them. A skill that depends on README text (for example, update-website) must run after update-readme.

Discovery process

For each skill in the registry, decide whether it needs to run:

1. Read the skill's .last-updated file:

   BASELINE=$(cat .agent/skills/<skill>/.last-updated)
   

   An empty or missing file means "never run" — schedule it.

2. Diff the watched paths for that skill against the baseline:

   git diff --name-only "$BASELINE"..HEAD
   

   If any file in the skill's mapping table appears in the diff, schedule the skill.

3. Build the list of skills to run. Preserve the run order from the registry.

Execution

For each scheduled skill, in order:

1. Load .agent/skills/<skill>/SKILL.md.
2. Follow its discovery process, mapping table, and update checklist exactly.
3. Verify the skill's own verification section passes.
4. Record the git rev-parse HEAD value the skill wrote to its .last-updated.

Between skills, do not commit — aggregate all edits into a single working tree so the final commit covers the whole sync sweep.

Update checklist

• Read every skill's .last-updated and build the schedule

• Run each scheduled skill in the order above

• After all skills finish, run:

  • make fmt
  • make lint
  • make test
  • oss-spec validate .

• Stage every touched file (including each updated .last-updated)

• Commit with a conventional-commit message:

  docs: drift sweep — sync readme, docs, manpages, website
  

  Scopes may be comma-separated if multiple artifacts moved.

• Update .agent/skills/maintenance/.last-updated:

  git rev-parse HEAD > .agent/skills/maintenance/.last-updated
  

• Hand off to the commit skill to push and open / update the PR

Verification

1. Every scheduled skill's verification section must pass.
2. oss-spec validate . must report zero violations.
3. The final diff should touch only documentation files, skill .last-updated files, and (rarely) small code adjustments that the skills flagged.
4. Every skill that ran must have its .last-updated rewritten with the same commit hash — this is what tells the next run of maintenance that the sweep completed.

Skill self-improvement

After every run, update this file:

1. Add new sync skills to the registry. Every new update-* skill must appear in the registry table, in alphabetical order, with a clear "run order" slot.
2. Adjust run order if you discovered a hidden dependency (e.g. skill A reads files that skill B rewrites).
3. Record drift signals. If you found a change that should have triggered a skill but did not appear in any skill's mapping table, extend the offending skill's mapping table — not this one.
4. Commit the skill edits together with the drift sweep so the orchestration knowledge compounds.