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 for spotifai, mandated by §21.6 of OSS_SPEC.md. 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 the default branch 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 it is unclear which skill to invoke.

Do not use this skill for a targeted fix — if you know exactly which artifact is stale, call the corresponding update-* skill directly.

Tracking mechanism

.agent/skills/maintenance/.last-updated records the git commit hash of the last successful drift sweep. Empty means "never run" — fall back to the repo's initial commit (git rev-list --max-parents=0 HEAD) as the baseline. Each individual update-* skill maintains its own .last-updated independently; this file's timestamp captures the last time the whole sweep ran.

Registry

The registry is the single source of truth for which sync skills exist in this repo. Every update-* directory under .agent/skills/ must appear here exactly once. New projects start with the entries below; add rows whenever you create a new sync skill.

Skill	Fixes	Spec sections	Run order
sync-oss-spec	Repo contents vs. the latest OSS_SPEC.md fetched from GitHub (standalone — no external validator binary)	all structural §§ + §21.5	1 — run first so every downstream skill reads the freshest spec
update-docs	docs/*.md vs. source of truth	§11.1	2
update-readme	README.md vs. current public surface	§3	3
update-manpages	man/<cmd>.md vs. CLI parser and command behaviour	§12.3, §12.5	4
update-prompts	prompts/** vs. code and embedded sources	§13.5	5
update-website	website/** vs. README.md, docs/, OSS_SPEC.md	§11.2	6 — runs last so any prior README/docs/spec rewrites land in the website snapshot

Run order matters:

• sync-oss-spec runs first so every downstream skill sees the current spec — it may overwrite the local OSS_SPEC.md with the upstream copy, which downstream skills then read.
• The per-artifact skills (update-docs, update-readme, update-manpages, update-prompts, update-website, and any other skills this project adds) run afterwards in dependency order: a skill that reads files another skill rewrites must run after that other skill. update-website is intentionally last because it derives content from README.md, docs/, and OSS_SPEC.md — all of which earlier skills may have rewritten.

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, preserving 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 commit hash 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 registry order

• After all skills finish, run:

  • make fmt
  • make lint
  • make test

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

• Commit with a conventional-commit message describing the sweep

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

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

Verification

1. Every scheduled skill's verification section must pass.
2. make lint and make test must pass.
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.

Skill self-improvement

After every run, update this file:

1. Add new sync skills to the registry. Every new update-* skill must appear here, in alphabetical order, with a clear run-order slot.
2. Adjust run order if you discovered a hidden dependency.
3. Record drift signals. If a change should have triggered a skill but did not appear in any skill's mapping table, extend that skill's mapping table — not this one.
4. Commit the skill edits together with the drift sweep.