Operational Heartbeat
The heartbeat is the control loop that keeps Kevin's wiki, skills, automations, generated surfaces, and agent sessions current without making Kevin manage maintenance state.
Core Rule
The heartbeat has one job: keep the system alive, honest, and searchable. Every session loads identity, routes through the brain, checks live maintenance state, does the requested work, writes durable memory when facts change, regenerates retrieval surfaces, and leaves no hidden process or stale scheduler ambiguity behind. Source: AGENTS.md Session Startup; scripts/check-freshness.ts; Scheduling Operating Model
[[SOUL]] defines the agent identity. [[USER]] defines Kevin, with User Model Map owning the expanded USER companion structure. This file defines the operating loop. [[agent-operations-hub]] routes the actual task.
The heartbeat is not a ritual checklist. It is a fail-visible control system. If a task does not need maintenance work, keep moving. If maintenance state changes the task, say so concretely.
What The Heartbeat Controls
| Surface | Heartbeat responsibility |
|---|---|
| Identity | Load SOUL, USER, and HEARTBEAT before substantive work. |
| Routing | Use the operations hub, skill resolver, capability map, and repo-local instructions before improvising. |
| Live state | Treat state.json, automations/, scheduler state, raw sources, and generated artifacts as current truth. |
| Wiki writes | Shape the article with Wiki Brain Operating Model, file with Filing Decision Tree, cite sources, update links, rebuild retrieval, and log. |
| Automations | Require outputs, promotion/no-op decisions, state writes, and log entries. A spawned thread without writeback is not a completed run. |
| Agent config | Keep executable skill/config surfaces, wiki references, generated packs, and bootstrap/sync checks aligned. |
| Closeout | Verify, report residual risk, and clean up processes the agent spawned. |
Session Boot
Every substantive kevin-wiki session starts with:
- Read
wiki/SOUL.md,wiki/USER.md, andwiki/HEARTBEAT.md. - Read
wiki/meta/agent-operations-hub.md. - Run
npx tsx scripts/check-freshness.ts. - Interpret the output before selecting the task path.
If Kevin asked for maintenance, report freshness before acting. If Kevin asked for unrelated work, do the work and mention only the important maintenance deltas at the end. Startup should inform the task, not displace it.
Live State Comes First
scripts/check-freshness.ts is the maintenance source of truth. Static tables in this file describe intent; they do not override the live state in state.json, automations/, raw sources, local scheduler config, or generated artifacts.
| Source | What it answers |
|---|---|
state.json |
Last successful automation, sync, compile, maintenance, and generated-surface timestamps. |
automations/<slug>.md |
Canonical recurring task contract. |
~/.codex/automations/<id>/automation.toml or Codex scheduler DB |
Local schedule, prompt, cwd, model, and recurrence. |
outputs/<date>/<slug>/<agent>.md |
Ephemeral proof from a run. |
wiki/log.md |
Durable human operation ledger. |
wiki/_index.md, wiki/_backlinks.json, qmd |
Search and graph retrieval surfaces. |
skills/.runtime/all, skill registry, agent packs |
Generated agent capability surfaces. |
As of the 2026-07-01 freshness check, the important maintenance classes are never-run integrations and automations, stale sub-daily source compile, stale syncs, and overdue self-heal. The precise list should come from the current command output, not from this paragraph. Source: npx tsx scripts/check-freshness.ts, 2026-07-01
Task Operating Loop
Route each task through this loop:
- Brain-first - search
qmd,qmd query, orwiki/_index.mdbefore answering from memory about people, tools, concepts, projects, decisions, or Kevin preferences. - Skill-first - if a named or clearly matching skill exists, read its
SKILL.mdbefore acting. - Capability-first - before choosing a tool, CLI, MCP, or service, use Capability Routing Map and Skill Resolver when the route is non-obvious.
- Shape-first - for broad wiki work, use Wiki Brain Operating Model before Filing Decision Tree.
- Execute with proof - produce the artifact, diff, output, screenshot, test result, state write, or log entry that proves the work happened.
- Compound - update pages, skills, automations, routing, or generated surfaces when the result should help future agents.
- Close cleanly - validate, report residual risk, and clean up spawned processes.
Freshness Semantics
Separate freshness output into three buckets:
| Bucket | Meaning | Agent action |
|---|---|---|
| Needs attention | Overdue or never-run local automations, stale syncs, uncompiled raw sources, self-heal needs, scheduler drift. | Name the exact items. Run or route them when in scope. |
| Notices | Often cloud-only jobs, on-demand tasks, or informational gaps. | Mention only when relevant. Do not call them failures. |
| Up to date | State is current enough for the configured cadence. | Do not recite unless it helps the task. |
If a sync fails because auth or a local session is missing, leave the sync freshness stale. Successful automation bookkeeping and successful external collection are different facts.
Cadence Matrix
Use the live freshness output first. This cadence table is the intended rhythm:
| Cadence | Agent responsibility |
|---|---|
| Every 4 hours | Slack sync, Gmail sync, and source compile / X bookmark review. Write raw digests, promote durable facts, and use ISO timestamps for hour-level freshness. |
| Daily | Signal radar, frontend frontier radar, skill maintenance, meeting sync, project briefing, code-bugfix, content pipeline, career pipeline, and daily work summary where enabled. |
| Weekly | Calendar sync, capability harvest, cross-project learning, SEO/GEO radar, language orchestration radar, recruiter discovery, OSS license audit, and scheduling audit. |
| Monthly | Wiki-quality audit, routing/trigger eval review, wiki status/breakdown review, stale schedule review, obsolete automation review, and consolidation review. |
| On demand | Security scan, self-heal apply, capture ingest, no-sus review, doctor loops, process cleanup, and high-risk manual repairs. |
Every scheduled run must either apply a durable update or record No durable wiki update needed. A silent run leaves no durable state for future agents.
Durable Automation Contract
A recurring automation is complete only when it:
- Reads
AGENTS.md,wiki/HEARTBEAT.md,automations/<slug>.md, and directly referenced files. - Writes
outputs/<date>/<slug>/<agent>.md. - Applies
wiki_targetsonly when promotion criteria pass. - Records
No durable wiki update neededwhen nothing should be promoted. - Updates
state.jsonunder the correct automation/sync key. - Appends
wiki/log.md. - Runs generated-surface checks when wiki, skills, config, routing, or indexes changed.
See Automation Proof Contract and Scheduling Operating Model for the full run contract.
Every Wiki Write
A wiki-editing turn is not done until:
- The durable shape follows Wiki Brain Operating Model.
- The target page location follows Filing Decision Tree.
- Duplicates, aliases, redirects, and existing related pages were searched when creating or moving pages.
- New facts have sources.
- Important entities have useful wikilinks and timeline entries when evidence changed.
- Compiled truth and timeline separation is preserved.
- Generated surfaces were regenerated instead of hand-edited.
npx tsx scripts/build-index.tsran.qmd update && qmd embedran, or the failure is reported.wiki/log.mdhas an entry.- A targeted doctor/check ran when routing, schema, automation, generated packs, or broad graph behavior changed.
- For broad article/tool/skill/hub quality work,
npm run wiki-qualityran and the audit report was inspected.
For URL, repo, post, or raw captures, follow Capture Ingest Protocol end to end.
Every Agent-Config Write
When changing skills, rules, hooks, MCP config, tool rankings, Codex/Cursor/Claude instructions, agent packs, or cross-agent presets:
- Update the executable/config surface.
- Update the wiki reference page.
- Update routing pages when behavior changed.
- Regenerate skill registry, runtime links, or agent packs when relevant.
- Run bootstrap/sync/doctor checks appropriate to the surface.
- Rebuild index and qmd.
- Log the operation.
See Agent Config Write Checklist and Generated Surface Refresh.
Content Backlog Gate
If the session edits or focuses on wiki/career/content-backlog.md, end by surfacing rows not yet Posted. For rows marked Ready to post, route through social-draft, humanizer, and then kevin-voice or slack-voice depending on channel.
End-Of-Turn Hygiene
If you spawned long-running processes, dev servers, test watchers, browser sessions, or automation jobs:
- keep only what Kevin is actively using
- tear down duplicates and hung workers
- do not kill the editor, agent runtime, user shell, or shared MCP servers
- mention any server URL intentionally left running
If no long-running process was spawned, normal judgment is enough. See End Of Turn Hygiene.
Escalation
Escalate when credentials are missing, destructive action is required, production/customer data is at risk, sources conflict, a bulk operation fails its sample, the same command fails twice with the same cause, or an automation is stale because its integration has never been configured.
Escalation should name the blocker and the smallest user action that would unblock it.
Timeline
- 2026-07-14 | Removed the retired offsites and Hawaii planning jobs from the daily cadence. Source: User request, 2026-07-14
- 2026-07-01 | Rebuilt the heartbeat as the current control loop for identity boot, live freshness state, sub-daily ingest, durable automation proof, wiki/config closeout, generated-surface refresh, and process hygiene. Source: User request, 2026-07-01
- 2026-07-01 | Aligned the heartbeat wiki-write loop with the updated Agent Soul and Wiki Brain Operating Model: shape before filing, generated surfaces in closeout, and broader graph validation when routing or packs change. Source: User request, 2026-07-01
- 2026-06-30 | Added the sub-daily communications/source loop: Slack sync, Gmail sync, and source compile/X bookmark review should run every four hours with raw digests, durable wiki promotion, ISO state timestamps, and scheduler freshness checks. Source: User request, 2026-06-30;
automations/slack-sync.md;automations/email-sync.md;automations/source-compile.md - 2026-06-28 | Clarified that heartbeat means scheduled work plus durable wiki writeback, added scheduler drift to freshness semantics, and aligned the cadence matrix with the Codex/Cursor automation layer. Source: User request, 2026-06-28; Scheduling Operating Model
- 2026-06-25 | Added
npm run wiki-qualityto the heartbeat for broad read-first/router/source/skill-load audits, with reports underoutputs/audits/. Source: User request, 2026-06-25;scripts/wiki-quality-audit.ts - 2026-06-24 | Added engineering routing to the heartbeat: tool-routing-first behavior, no-sus trigger conditions, repo-local source order, invariant/interface/proof loop, and no-sus review as an on-demand cadence item. Source: User request, 2026-06-24;
tool-hierarchy.mdc; Skill Resolver; Security and Review Skills - 2026-06-24 | Reframed the heartbeat as a compact operating loop: session boot, task routing, freshness semantics, wiki-write/config-write done checks, cadence from live freshness state, and end-of-turn hygiene. Source: User request, 2026-06-24; AGENTS.md;
scripts/check-freshness.ts; Agent Operations Hub - 2026-06-18 | Expanded into an operational cadence with session startup, task routing, daily/weekly/monthly loops, wiki-write checks, config-write checks, content backlog gate, and end-of-turn hygiene. Source: User request, 2026-06-18; AGENTS.md; Agent Operations Hub
- 2026-05-31 | Prior heartbeat recorded the startup trio, freshness check, automation cadence, and wiki-write checklist. Source: AGENTS.md