global-heartbeat
Skill1 starsChanged 3 months agoMITView on GitHub
Fast consistency check across the whole setup: the notes heartbeat plus every project's folder and document structure against what code-standards defines. Reports, fixes only what is mechanical, and names the rest. Cheap enough to run often. Invoked by name.
In this repository12 other files it gives its agents.
- AGENTS.mdAGENTS.md
- add-sourceSkill
- analyze-videoSkill
- archive-projectSkill
- clean-projectSkill
- code-standardsSkill
- map-projectSkill
- notes-heartbeatSkill
- researchSkill
- resolve-projectSkill
- sleepSkill
- test-projectSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 60
No HTML. If the output is long enough to want a page, the finding is that something drifted badly and sleep should run.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
global-heartbeat
Two deterministic scripts and a short read of what they print. No subagents, no synthesis, no vault reshaping. sleep is the expensive pass; this is the one you can run any time without thinking about cost.
python3 $VAULT/.scripts/relink.py
python3 $VAULT/.scripts/health.py
python3 $VAULT/.claude/skills/global-heartbeat/scripts/config-health.pyrelink.py runs first so a renamed skill or a new docs/technical-spec.md is mirrored before anything reads the vault.
What each answers
| Script | Covers |
health.py | the vault: dangling links, unlinked mentions, fences, frontmatter, dead paths, graph shape |
config-health.py | everything else: dead paths and skill names in this config, script syntax and shebangs, settings.json hooks, symlink farms, project-to-document pairing, project structure |
notes-heartbeat covers the first script's output in full, including what each report means. Load it rather than restating those rules here.
Structure findings, and what they mean
config-health.py structure reads each project against code-standards and against the documents its own priority calls for.
| Finding | Read it as |
no src / no docs / no tests | a project not laid out the standard way. Fine for a scratch repo, a gap for anything tracked. |
no runner | tests/ with no run-tests.sh, so nothing runs the suite the standard way |
no doc | the document that priority owes: P3 wants a market analysis and a masterdoc, P0 owes almost nothing |
versioned | a docs/ file scoped to a version, which contradicts the version-agnostic rule |
no document / no project | a live project with no Notes entry, or an entry naming a directory that is gone |
A missing document is a proposal, never a write. priority and status are owner-set, so a new project document gets drafted with those left blank and raised in chat.
Fix, and where to stop
Fix what is mechanical and provable: a dead path that clearly moved, a stale symlink, a skill name that was renamed, a broken shebang. Each is a one-line edit against something a script already proved.
Everything else is a line in the report:
- Anything about note content. A stale claim, a duplicate, a missing edge:
sleepowns those and it decides with agents, not greps. - Anything that creates a project document or a
docs/file.resolve-projectwrites those, per project, with its own audit. - Anything structural. Adding
src/ortests/to a project is a refactor, not a heartbeat fix.
Report
In chat, nothing else:
- one line per script with its finding count
- what was fixed, as a list
- what was left, grouped by which skill owns it
- the vault's graph numbers, so a trend is visible run to run
No HTML. If the output is long enough to want a page, the finding is that something drifted badly and sleep should run.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

