Loop Engineering¶
Understanding-oriented design docs for autonomous CI and documentation loops in this repository.
Documents sit in one folder on disk. Read them by layer, not as a flat list. Per-loop callers already live under workflows/; platform and cross-cutting contracts do not.
Layer A Nesting (shared job graph)
on-loop-* → ci-loop-caller → ci-loop-agent (L1 | L2/L3)
Layer B Per-loop workflow
one on-loop-<name>.yaml + workflows/loop-<name>-workflow-design.md
Layer C Cross-cutting contracts
PR body, notify, detect I/O, report shapes — not a fourth pipeline stage
Layer A — Nesting (shared platform)¶
Job graph, phases, and which workflow / action files own them. Optional jobs such as ack-trigger are caller UX on this graph, not a new phase.
| Read | Owns | Target files |
|---|---|---|
| Ubiquitous Language | Phase names (detect / execute / verify / finalize) | — |
| Loop Engineering Design | Invariants, L1/L2/L3, retry, full-stack diagram (draw once) | .github/actions/loop-*, detect script envelope |
| Loop Caller Workflows Design | Shared on-loop-*.yaml shell: detect → execute → record-skip |
on-loop-*.yaml, ci-loop-caller.yaml, ci-loop-agent.yaml |
| Loop Caller Reusable Workflow Design | ci-loop-caller jobs, optional ack-trigger, with: vs env: |
ci-loop-caller.yaml, ci-loop-agent.yaml |
| Multi-Branch Loops Design | Targets, matrix, state, caller input map | state files, loop-detect handoff |
| Loop-Capable Skills | Skill family bound to loops | .apm/packages/**/skills/ |
Layer B — Per-loop workflow¶
Each loop is a thin on-loop-<name>.yaml plus a design page. Input key lookup is not a platform design doc; it is the shared reference for those callers.
| Loop | Design | Caller file |
|---|---|---|
| (all) | Caller Inputs Reference | ci-loop-caller.yaml with: keys |
| changelog | Changelog | on-loop-changelog.yaml |
| ci-sweeper | CI Sweeper | on-loop-ci-sweeper.yaml |
| docs-updater | Docs Updater | on-loop-docs-updater.yaml |
| refactor | Refactor | on-loop-refactor.yaml |
| tech-debt | Report Tech Debt | on-loop-tech-debt.yaml |
| github-issue-triage | Issue Triage | on-loop-github-issue-triage.yaml |
| github-issue-autofix | Issue Autofix | on-loop-github-issue-autofix.yaml |
| github-pr-revise | PR Revise | on-loop-github-pr-revise.yaml |
Also listed from Multi-Branch Loops Design — Workflow Design Documents.
Layer C — Cross-cutting contracts¶
Shared shapes that apply to many loops. They are not nested jobs.
| Topic | Document | Target files |
|---|---|---|
| Action / detect I/O | Specification | .github/actions/loop-*, detect_*.sh |
| PR body (templates, Created By, validate) | Loop PR Body Skill Contract | render_pr_body.sh, skill assets/pr-body-template*.md |
| Survey/apply report shape | Loop Automation Report Format | skill output comments |
| PR comment notify | loop-notify-pr Specification | .github/actions/loop-notify-pr/ |
| New-loop author checklist | Loop Engineering Checklist | — |
| Canonical map / when to edit docs | Documentation Maintenance | this docs/explanation/loop-engineering/ tree |
Out of the reading path¶
Dated Superpowers specs and plans under docs/superpowers/ are implementation history. Do not treat them as the live platform map.
Reading order (first time)¶
- Layer A: Design → Reusable caller
- Layer B: the loop you are changing
- Layer C: only the contract that matches the files you touch