memory-continuity/skills/project-heartbeat/SKILL.md

name, description

name	description
project-heartbeat	Keep active delegated projects from going silent by arming a 10-minute heartbeat timer after main reports progress, checking worker status when the timer expires, and pushing a fresh user-visible update until the project is done, paused, failed, or cancelled. Use when a project has active workers or outstanding milestones and the main agent needs anti-silence discipline.

Project Heartbeat

Use this skill to stop active projects from disappearing into silence.

This skill exists because delegated projects can look alive while no user-visible update is happening:

• main says work is in progress, then goes quiet
• workers stall or launch-fail without being surfaced upward
• the user has to ask "how is it going?" to get a status refresh

Purpose

Create a simple project-level heartbeat loop:

1. main gives a user-visible project update
2. a 10-minute timer is armed
3. if another meaningful update happens before timeout, reset the timer
4. if timeout is reached, check active workers / project state
5. send a fresh user-visible update
6. repeat until the project is closed

States

Use these states only:

• idle
• armed
• checking
• closed

Meaning

• idle: no active heartbeat-monitored project
• armed: project is active and the 10-minute silence timer is running
• checking: timer expired; main is actively collecting status from workers / project state
• closed: project is done, paused, failed, or cancelled; heartbeat stops

Trigger to arm

Arm the heartbeat when:

• main tells the user a project has started
• main dispatches work and communicates that the project is active
• main says it will continue work and more updates are expected

Do not arm for:

• one-shot answers
• tiny tasks that are already done
• passive discussion with no active project

Reset rule

Reset the 10-minute timer when any of these happen:

• main sends a meaningful project update to the user
• a worker milestone/blocker/completion is forwarded to the user
• the user sends a project-touching follow-up and main replies with real status

A "meaningful update" must contain actual status, not filler.

Timeout rule

If 10 minutes pass with no meaningful update while the project is active:

1. switch to checking
2. inspect active workers / project state
3. determine whether the project is:
   • still progressing
   • blocked
   • launch-failed
   • stalled
   • done
4. send a user-visible update
5. return to armed if still active, else closed

Hard anti-silence rule

This is stricter than a reminder.

If the timeout window expires and there is still no fresh execution evidence, main must still send a user-visible update.

Allowed timeout updates when there is no new evidence:

• blocked
• launch failure
• no change
• still waiting on <specific blocker>

Disallowed timeout behavior:

• saying nothing
• waiting for a "more complete" answer before updating Tao
• reusing old optimistic wording like in_progress without fresh evidence

Silence after timeout is itself a process failure.

Worker check order

When timeout fires, check in this order:

1. worker session history / visible traces
2. subagent/session visibility
3. task state in CURRENT_STATE.md
4. known blockers (model, auth, tool, path, review, external)

If a worker was supposedly active but has no trace, prefer blocked (launch failure) over vague waiting language.

User update format

Use the normal 4-line update format:

• who
• status
• output
• next

Close conditions

Close the heartbeat when the project becomes:

• done
• paused
• failed
• cancelled

If multiple sub-tasks belong to the same project, keep the heartbeat open until the overall project is closed.

Guardrails

• Do not spam on a fixed timer if there is nothing meaningful to say; timeout should trigger a real status check first.
• Do not keep the heartbeat alive after project closure.
• Do not claim progress without evidence.
• Silence is a process problem, not a neutral state.
• If the latest check finds no new evidence since the previous user-visible update, do not dress that up as in_progress; report blocked, launch failure, or no change plainly.
• Do not keep re-broadcasting stale CURRENT_STATE text as if it were fresh execution progress.

References

• For task-state rules and evidence gates: read ../agent-workflow/references/state-machine.md
• For reporting format: read ../agent-workflow/references/reporting.md
• For continuity workbench use: read ../memory-continuity/references/template.md