Skip to content
Skills Library
DevOps & cloud · Automation

loop-pulse

/loop-pulse

Before each wake of a recurring agent loop, freeze or load a pulse charter and classify the wake (DELTA / ECHO / STALL / DONE / BUDGET-CUT / SCOPE-BREACH / HOLD) from an observation fingerprint so the agent only acts when there is a real delta and budget left. Use when babysitting CI, watching an experiment, polling a research source list, or any scheduled /loop that must stop on stall, success, or spend.

Repository
loop-pulse ↗
Licence
MIT
Last repository change
06.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
7
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 06.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Before each wake of a recurring agent loop, freeze or load a pulse charter and classify the wake (DELTA / ECHO / STALL / DONE / BUDGET-CUT / SCOPE-BREACH / HOLD) from an observation fingerprint so the agent only acts when there is a real delta and budget left. Use when babysitting CI, watching an experiment, polling a research source list, or any scheduled /loop that must stop on stall, success, or spend.

Original author description

Before each wake of a recurring agent loop, freeze or load a pulse charter and classify the wake (DELTA / ECHO / STALL / DONE / BUDGET-CUT / SCOPE-BREACH / HOLD) from an observation fingerprint so the agent only acts when there is a real delta and budget left. Use when babysitting CI, watching an experiment, polling a research source list, or any scheduled /loop that must stop on stall, success, or spend.

How it works

  1. When to use
  2. Core idea
  3. Steps
  4. Charter shape
  5. Examples
  6. Tips
  7. Helper
Original SKILL.md headings · 92 lines, 631 words
SKILL.md preview
---
name: loop-pulse
description: Before each wake of a recurring agent loop, freeze or load a pulse charter and classify the wake (DELTA / ECHO / STALL / DONE / BUDGET-CUT / SCOPE-BREACH / HOLD) from an observation fingerprint so the agent only acts when there is a real delta and budget left. Use when babysitting CI, watching an experiment, polling a research source list, or any scheduled /loop that must stop on stall, success, or spend.
---

# loop-pulse

Recurring agent loops waste tokens when they wake up, see nothing new, and still "helpfully" poke the world. **loop-pulse** turns every wake into a gated pulse: observe → fingerprint → verdict → then (and only then) act.

## When to use

- A `/loop`-style or cron-woken agent that re-checks CI, metrics, or a fixed source list
- You want **delta-only** work: no side effects when the observation is unchanged
- You need a hard stop on **stall**, **success**, or **wake/hour budget**
- You must keep the loop inside an allow-listed set of sources

Do **not** use this for one-shot tasks, for user-interruption routing, or for rehearsing trigger rules before deploy — those are different jobs.

## Core idea

1. **Pulse charter** (frozen once): mission, allowed sources, allowed verbs, stop predicates, wake budget, observation recipe.
2. **Each wake**: run the recipe, feed the text to `looppulse.py check`, obey the verdict.
3. **Persist**: write `next_charter_patch` back onto the charter and append a line to `pulses.jsonl`.

### Verdicts

| Verdict | Meaning | Agent may act? |
| --- | --- | --- |
| `DELTA` | Fingerprint changed (or first pulse) | Yes — only `allowed_verbs` |
| `ECHO` | Same fingerprint; under stall limit | No — report-only |
| `STALL` | Idle streak hit `stall_limit` | No — stop the loop |
| `DONE` | A `stop_when` predicate matched | No — stop, success |
| `BUDGET-CUT` | `max_wakes` or `max_hours` exhausted | No — stop |
| `SCOPE-BREACH` | Observation names a path outside `sources` | No — stop / escalate |
| `HOLD` | Charter invalid or observation missing | No — fix charter first |

## Steps

1. Copy `templates/charter.json` → `pulse-charter.json`.
2. Fill `mission`, `sources`, `allowed_verbs`, `stop_when`, `wake_budget`, `observation.recipe`.
3. Lint: `python3 scripts/looppulse.py lint pulse-charter.json`
4. On each scheduled wake:
   - Run the observation recipe; save stdout to `obs.txt` (must only touch `sources`).
   - `python3 scripts/looppulse.py check pulse-charter.json --file obs.txt --log pulses.jsonl --write-charter pulse-charter.json`
   - Branch on `verdict` (exit code: `0` DELTA/DONE, `2` stop-class, `3` ECHO).
5. If `DELTA`: perform the smallest action from `allowed_verbs`, then re-observe only if the action itself changes the watched surface.
6. If `ECHO`: write a one-line status; do not edit code, re-run jobs, or ping humans.
7. If `STALL` / `DONE` / `BUDGET-CUT` / `SCOPE-BREACH`: end the loop and leave the pulse log as the receipt.

## Charter shape

```json
{
  "mission": "Babysit CI for pr-42 until merged or budget ends",
  "sources": ["repo/ci/pr-42.log", "repo/status.json"],
  "allowed_verbs": ["read", "rerun-failed", "reply-bot"],
  "stop_when": [
    {"kind": "obs_contains", "needle": "status=merged"},
    {"kind": "metric_at_least", "key": "pass_rate", "threshold": 1.0}
  ],
  "wake_budget": {"max_wakes": 12, "max_hours": 6, "stall_limit": 3},
  "observation": {"recipe": "tail ci log + cat status.json"},
  "started_at": "2026-11-06T00:00:00Z",
  "wakes_used": 0,
  "idle_streak": 0,
  "last_fingerprint": null
}
```

`stop_when` kinds: `fingerprint_equals`, `obs_contains`, `metric_at_least`, `status_done`.

## Examples

**CI babysit** — see `examples/pr-ci-charter.json`. First wake with a changing log → `DELTA`. Identical log next wake → `ECHO`. `status=merged` → `DONE`.

**Experiment watchdog** — sources = metric file + status file; stop on `accuracy>=0.9` or three identical pulses → `STALL`.

**Research watch** — sources = a frozen URL/file list; observation = "new titles since last pulse"; identical list → `ECHO` until `stall_limit`, never expand the source list mid-loop (`SCOPE-BREACH` if you try).

## Tips

- Put numbers in `key=value` form so `metric_at_least` can see them.
- Keep `allowed_verbs` tiny. A loop that may "refactor" will.
- Set `stall_limit` to 2–4 for noisy CI; higher for slow experiments.
- Never widen `sources` after `started_at` is set — start a new charter instead.
- Pair with your scheduler (`/loop`, cron, queue wake). This skill gates the wake; it does not schedule it.

## Helper

```bash
python3 scripts/looppulse.py demo
python3 scripts/looppulse.py lint examples/pr-ci-charter.json
python3 scripts/looppulse.py check examples/pr-ci-charter.json --file examples/sample-obs-running.txt
python3 -m unittest discover -s tests -v
```
Files in this package (7)
  • .gitignore 1 KB
  • LICENSE 1 KB
  • README.md 2 KB
  • README.zh-CN.md 2 KB
  • SKILL.md 5 KB
  • SKILL.zh-CN.md 4 KB
  • tweet_draft.txt 1 KB

Versions

The database has no other skills named loop-pulse.

Database snapshot: 13.11.2026 · package version 7a120bf85834 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100autopilot
    Protocol for one unattended wake of a scheduled cloud run on a repository, and for a local session resuming its PRs. Use when a routine prompt says to follow docs/agents/autopilot.md or do one wake, or when the user asks to resume or verify cloud work locally.
  • 100laravel-pulse
    Use when setting up Laravel Pulse — real-time dashboard, built-in cards, custom recorders, performance insights — even when the user just says 'I need app monitoring' without naming Pulse.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.