project-heartbeat

# Project Heartbeat Project heartbeat is for **controlled continuation**, not endless automation. ## Use this skill when - the project has a real home (for example `Projects/<name>/`) - the work can continue in small, concrete steps - progress should survive interruptions - some blocked actions can be deferred without stopping the whole project - you want wake-up cadence plus explicit stop conditions ## Do not use this skill when - the work is small enough for one session - there is no canonical project state - the only remaining step is a human approval or external action - the project has no clear next step ## v0 scope This version focuses on what is practical now: - fit check - cadence recommendation - continue conditions - hard stop vs soft block boundary model - pending decision backlog contract - progress logging contract - continuation integrity rules - summary + handoff contract - resume protocol More advanced ideas such as model-routing and automatic blocked-path rerouting belong in the deferred backlog until the system has more real usage evidence. A stronger strategic heartbeat mode is also valid when a project has many unfinished modules and should not fall into `waiting-human` merely because no fresh external input arrived. In that mode, each cycle should first re-evaluate the whole project against its original vision, then choose one smallest high-value move that most helps the system converge toward that vision. ## Workflow 1. **Fit check** - Confirm the project is large enough and structured enough for heartbeat. 2. **Choose cadence** - Pick a wake interval that matches the project intensity. - **30 seconds** is reasonable for active projects needing close monitoring. - **5–15 minutes** is better for normal ongoing work. - **30–60 minutes** is suitable for low-intensity sustained projects. - Prefer longer cadences for normal operation; reserve short intervals for debug/active-polish phases. 3. **Define continue conditions** - Only continue if there is a concrete next step already visible in project artifacts. 4. **Define boundaries** - Separate: - hard stop boundaries - soft block boundaries 5. **Define progress artifacts** - Every wake cycle should leave behind a durable trace. 6. **Check continuation integrity** - A cycle does not count as progress unless it produces at least one real artifact update. - No artifact, no progress. 7. **Define summary + handoff behavior** - Every cycle should leave a concise human-facing summary. - `waiting-human` and `closed` must hand work back explicitly rather than stopping silently. 8. **Define resume protocol** - Humans should be able to return and understand what moved, what blocked, and what still needs approval. ## Boundary model ### Hard stop boundaries Must stop the loop: - budget exhausted - safety boundary reached - explicit human-only action with no meaningful bypass path - repeated no-progress cycles - no clear next step for multiple wake cycles ### Soft block boundaries Do not automatically stop the whole loop if other work remains: - repository creation pending approval - publish pending confirmation - one branch of work blocked while other internal improvements remain Soft blocks should be recorded in a pending-decision backlog so they can be surfaced later. ## Continuation integrity A heartbeat loop should not be allowed to survive on continuation language alone. ### False continuation False continuation happens when the agent says it continued, started, or progressed, but the project has no real new artifact to show for that cycle. ### Minimum artifact rule A cycle should count as real progress only if it leaves at least one durable change such as: - `STATE.md` updated - task/backlog file updated - `PENDING-DECISIONS.md` updated - `HEARTBEAT-LOG.md` updated - a new project/review/decision/doc artifact created - a real tracked child task started ### No-op rule If a cycle produced no durable artifact, treat it as a no-op. Repeated no-op cycles should escalate toward stop conditions rather than being narrated as progress. ## Scripts ### `scripts/fit_check.py` Quick fit assessment for whether a project is ready for heartbeat-style continuation. ### `scripts/render_plan.py` Renders a practical heartbeat plan: cadence, continue conditions, stop boundaries, backlog location, and resume guidance. ## References - `references/boundaries.md` - `references/examples.md` - `references/pending-decisions-template.md` - `references/heartbeat-log-template.md` - `references/continuation-integrity.md` - `references/summary-handoff.md` - `references/deferred-backlog.md`