Add loop skill

README.md

@@ -200,6 +200,11 @@ If a skill needs reusable instructions that are not a runnable skill:
   - Use when: scope is locked and the main job is execution.
   - Do not use when: the task still needs discovery or approval shaping.
 
+- `skills/loop`
+  - What it is: generic agent-agnostic loop router for bounded repeated task cycles with state baton, one-cycle executors, progress reporting, and explicit stop rules.
+  - Use when: a task should run through repeated independent cycles, such as bug hunts, docs cleanup passes, PR comment handling, or quality-gated review/fix loops.
+  - Do not use when: the task only needs a one-shot answer, continuation criteria are missing, or another cycle would bypass required approval, safety, or external-action gates.
+
 - `skills/code-review-orchestrator`
   - What it is: one entrypoint for multi-role code review with merged findings.
   - Use when: the user wants a repo, diff, branch, or PR reviewed from one or more specialist angles.

skills/loop/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Affaan Mustafa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

skills/loop/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: loop
+description: "Generic agent-agnostic loop router for repeated task cycles with explicit state, worker handoff, progress reporting, and safe stop conditions."
+origin: ECC-adapted
+---
+
+# Loop Skill
+
+Run a bounded, stateful agent loop for tasks that benefit from repeated independent cycles, for example: `Loop: find bugs in project X`.
+
+This skill is agent-agnostic. It does not require Claude, CI, PRs, or any specific implementation runner. Use the executor/subagent mechanism available in the current environment.
+
+## Source note
+
+Adapted from the MIT-licensed ECC autonomous loop material. The upstream catalog informed the stability mechanisms here: bounded iterations, persistent state/baton, separate worker contexts, retry context, verification gates, saturation stops, and approval boundaries. The upstream Claude-specific command catalog is intentionally not the operational path for this skill.
+
+## Triggers
+
+Use when the request asks for a repeated autonomous cycle, or starts with forms like:
+
+- `Loop: <task>`
+- `Run a loop to <task>`
+- `Keep iterating on <task> until <condition>`
+- `Find more bugs in <project>`
+- `Repeat cleanup/review passes until no progress`
+
+Do not use when a one-shot answer is enough, when safe continuation criteria are missing and cannot be inferred, or when the next action requires approval that has not been granted.
+
+## Inputs
+
+Collect or infer:
+
+- `task`: the work objective for each cycle.
+- `maxIterations`: default `3` unless the user gives another bound.
+- `successCriteria`: what counts as done or good enough.
+- `stopConditions`: max iterations, no progress, blocker, user stop, approval boundary, risk threshold, or success signal.
+- `verificationRequirements`: optional checks/review/tests that must run before considering a cycle successful.
+- `executorConstraints`: allowed tools, write permissions, external actions, target paths/repos, and reporting format.
+
+If the task is risky, destructive, external-writing, financial, privacy-sensitive, or under-specified in a way that changes safety, ask for approval or clarification before starting.
+
+## State Baton
+
+Keep a compact baton after every iteration and pass it to the next executor.
+
+```yaml
+task: "..."
+maxIterations: 3
+iteration: 1
+successCriteria:
+  - "..."
+stopConditions:
+  - "..."
+verificationRequirements:
+  - "..."
+lastResult: "none yet"
+nextAction: "start first cycle"
+noProgressCount: 0
+blocker: null
+artifacts:
+  files: []
+  prs: []
+  issues: []
+  notes: []
+retryContext: null
+approvalBoundaries:
+  - "..."
+```
+
+Minimum per-iteration state:
+
+- iteration number
+- last result
+- next action
+- no-progress count
+- blocker, if any
+- artifacts/PRs/issues/files, if any
+- verification result, if any
+- retry context for failures
+
+## Loop Lifecycle
+
+1. Initialize the state baton from the inputs.
+2. Start exactly one executor/subagent for the current iteration.
+3. Executor performs one focused cycle, reports result, then stops.
+4. Main/orchestrator reports progress to the user.
+5. Main/orchestrator updates the state baton.
+6. Main/orchestrator decides: continue, retry with context, pause for approval, or stop.
+7. If continuing, start the next executor with the updated baton.
+8. Do not give a final answer until either the next iteration has been started or the loop has explicitly stopped.
+
+## Executor Protocol
+
+Each executor gets one iteration only.
+
+Executor instructions must include:
+
+- the task and current baton
+- the exact iteration number
+- what to inspect/change/run in this cycle
+- verification/review requirements for this cycle
+- approval and safety boundaries
+- required report fields: result, evidence, artifacts, verification, blocker, next recommended action
+
+Executor must:
+
+- run only its assigned cycle
+- preserve exact paths, commands, IDs, errors, and artifacts in the report
+- stop after reporting
+- not launch its own loop or next iteration unless explicitly assigned
+- not bypass approval, external-action, destructive-action, or privacy boundaries
+
+## Orchestrator Contract
+
+The main/orchestrator owns continuity.
+
+After each executor result:
+
+- summarize progress to the user before continuing when the environment supports visible progress updates
+- update the baton
+- increment `iteration`
+- update `noProgressCount`
+- capture failures as `retryContext`
+- decide whether continuation criteria still allow another cycle
+- start the next executor if continuing
+- explicitly stop if done, saturated, blocked, unsafe, out of iterations, or waiting for approval
+
+Final report must include:
+
+- why the loop stopped
+- iterations completed
+- results found or changes made
+- verification performed
+- open blockers/risks
+- artifacts/PRs/issues/files touched, if any
+- recommended next step
+
+## Continuation and Stop Rules
+
+Continue only when all are true:
+
+- `iteration < maxIterations`
+- no stop condition has fired
+- there is a concrete next action
+- the last cycle made progress, or the retry context changes the next attempt materially
+- no new approval boundary is required before the next action
+
+Stop when any are true:
+
+- success criteria are met
+- max iterations reached
+- `noProgressCount >= 2` by default
+- the same blocker repeats without new information
+- verification proves the approach is failing
+- continuation would require unapproved external, destructive, risky, or privacy-sensitive action
+- user asks to stop
+
+## Stability Mechanisms
+
+- **Bounded loop:** default `maxIterations: 3`; never infinite by default.
+- **State baton:** durable, compact handoff between independent contexts.
+- **One-cycle executors:** workers cannot silently self-loop.
+- **Progress reporting:** user sees cycle results before the next cycle decision.
+- **Saturation stop:** repeated no-progress cycles stop instead of burning time.
+- **Retry context:** failures carry exact logs/errors/diffs into the next attempt.
+- **Verification gates:** checks/reviews are explicit, not assumed.
+- **Approval boundaries:** external writes, destructive operations, secrets, finance, security-sensitive changes, and remote pushes still need the surrounding environment's approval rules.
+- **Resume behavior:** if interrupted, reload the last baton/artifacts, verify repo/task state, then continue only from the next safe iteration.
+- **Separate contexts:** author/reviewer or search/fix phases can be separate executors when bias or complexity matters.
+
+## Generic Examples
+
+### Bughunt loop
+
+Input: `Loop: find bugs in project X, max 3 iterations, verify with targeted tests when possible.`
+
+Cycle shape:
+
+1. Executor audits one area and reports a concrete bug or no finding.
+2. Orchestrator records evidence and chooses the next area.
+3. Stop on two no-finding cycles, max iterations, or unapproved write boundary.
+
+### Docs cleanup loop
+
+Input: `Loop: improve onboarding docs until the quickstart is coherent.`
+
+Cycle shape:
+
+1. Executor reviews one doc path or user journey and edits only approved files.
+2. Executor reports changed files and remaining gaps.
+3. Orchestrator runs/requests verification if configured, then continues or stops.
+
+### PR comment loop
+
+Input: `Loop: address unresolved review comments, max 5, stop before pushing.`
+
+Cycle shape:
+
+1. Executor handles one coherent group of comments.
+2. Executor reports comment IDs, files changed, and checks run.
+3. Orchestrator continues while comments remain and local changes are safe; stops before any unapproved push/merge.
+
+## Reference Protocol
+
+For a copyable baton schema and worker/orchestrator report templates, see `references/protocol.md`.

skills/loop/references/protocol.md

@@ -0,0 +1,86 @@
+# Generic Loop Protocol
+
+This reference is the copyable protocol for `skills/loop`. It is intentionally agent-agnostic: replace "executor" with the current runtime's worker, subagent, script, or human-assisted pass.
+
+## Iteration Baton
+
+```yaml
+loopId: "short human-readable id"
+task: "original user task"
+maxIterations: 3
+iteration: 1
+successCriteria:
+  - "observable done condition"
+stopConditions:
+  - "max iterations"
+  - "success criteria met"
+  - "noProgressCount >= 2"
+  - "unapproved approval boundary"
+verificationRequirements:
+  - "tests/checks/review to run when relevant"
+lastResult:
+  summary: "none yet"
+  evidence: []
+  artifacts: []
+  verification: []
+nextAction: "specific next cycle objective"
+noProgressCount: 0
+blocker: null
+retryContext: null
+approvalBoundaries:
+  - "no remote push without approval"
+  - "no destructive command without approval"
+```
+
+## Executor Prompt Template
+
+```markdown
+You are the executor for loop iteration {iteration}/{maxIterations}.
+
+Task: {task}
+Current baton:
+{baton}
+
+Do exactly one cycle:
+1. Work only on `nextAction` unless a small prerequisite lookup is required.
+2. Respect approval/safety boundaries.
+3. Run configured verification when applicable and safe.
+4. Report compactly, then stop. Do not start the next iteration.
+
+Return:
+- status: completed | partial | blocked | no-progress
+- result:
+- evidence: exact paths/commands/IDs/errors/findings
+- artifacts: files/PRs/issues/notes created or changed
+- verification: checks run and outcomes, or why not run
+- blocker:
+- next: recommended next action
+```
+
+## Orchestrator Update Template
+
+```markdown
+Iteration {n} result: {one-line summary}
+Evidence: {key evidence}
+Verification: {check status}
+Decision: continue | retry-with-context | stop | pause-for-approval
+Reason: {continuation/stop rule}
+Next action: {specific next cycle objective, if continuing}
+```
+
+## Progress Accounting
+
+Update `noProgressCount` as follows:
+
+- Reset to `0` when the executor finds a new useful result, lands an approved change, removes a blocker, or produces new evidence that changes the next action.
+- Increment by `1` when the executor repeats known information, cannot act for the same reason, or produces no actionable evidence.
+- Stop at `noProgressCount >= 2` unless the user explicitly requested a larger saturation window.
+
+## Resume Checklist
+
+Before resuming an interrupted loop:
+
+1. Read the last baton and final executor report.
+2. Inspect current artifacts/state; do not trust stale baton entries blindly.
+3. Re-run only cheap, relevant verification if state may have changed.
+4. Continue from the next safe iteration, or stop/pause if an approval boundary is now active.