Loop Skill Consolidation Design¶

Status: Approved (grill-me 2026-07-21)
Date: 2026-07-21

Problem¶

loop-* APM packages duplicate domain skills (loop-refactor / refactor, docs-updater / docs-updater) or isolate small skills (loop-ci-sweeper, loop-changelog, loop-tech-debt) that fit naturally in common. Check criteria drift; detect_changes.sh exists in two divergent forks.

Goals¶

One skill per domain; loop callers pass JSON envelope + ## Constraints — no duplicate loop entry skills.
Move all maintenance skills into .apm/packages/common/.apm/skills/.
Drop loop- prefix from skill names; keep Loop Engineering platform (ci-loop-caller, on-loop-*.yaml filenames, loop-detect / loop-finalize).
Update callers (agent_implementer_skill_name, detect_script, agent_implementer_instructions) and necessary docs.

Grill decisions (locked)¶

Topic	Decision
`refactor` home	`common/.apm/skills/refactor/`; abolish `refactor` APM package
`detect_changes.sh`	`docs-updater` canonical; merge useful `docs-updater` behavior
Workflow filenames	Keep `on-loop-*.yaml`; only references change
Delivery	Single effort on `main`
Docs	Update all docs that reference old skill/package paths

Target layout¶

.apm/packages/common/.apm/skills/
  refactor/              # interactive + loop envelope; scripts/detect_refactor.sh
  docs-updater/          # hook/manual + loop findings; scripts/detect_changes.sh (unified)
  ci-sweeper/            # was loop-ci-sweeper
  changelog/             # was loop-changelog
  tech-debt/      # was loop-tech-debt

Delete packages: loop-refactor, docs-updater, loop-ci-sweeper, loop-changelog, loop-tech-debt, refactor.

Skill naming¶

Old skill	New skill
`loop-refactor`	(merged into `refactor`)
`docs-updater`	(merged into `docs-updater`)
`loop-ci-sweeper`	`ci-sweeper`
`loop-changelog`	`changelog`
`loop-tech-debt`	`tech-debt`

Non-goals¶

Renaming ci-loop-caller.yaml or loop platform actions
Changing loop_name state keys or detect envelope platform schema
Merging unrelated domains (e.g. ci-sweeper into docs-updater)

Risks¶

Risk	Mitigation
`detect_changes.sh` regression	Keep bats; run after merge
Broken `detect_script` paths in workflows	Update all five `on-loop-*.yaml` in step 3
External docs cite `loop-*` skill paths	Update architecture + loop-engineering docs