Skill: daowuu/project-heartbeat (version 0.4.1)

--- name: project-heartbeat description: Design controlled continuation loops for long-running projects. Use when a task is too large for one session, benefits from periodic wake-ups, and needs explicit continue conditions, stop boundaries, pending-decision handling, progress logging, and resume rules. Ideal for workspace refactors, long skill development, research tracks, and other cumulative engineering work. metadata: openclaw: prePublishChecks: - clawhub-release-auditor homepage: https://clawhub.ai/daowuu/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`

path: references/boundaries.md
content: # Boundaries

## Hard stop boundaries
- budget exhausted
- safety boundary reached
- human-only decision with no meaningful bypass path
- repeated no-progress cycles
- no clear next step across multiple wake cycles

## Soft block boundaries
- external approval pending
- repository creation blocked
- publication blocked
- one work branch blocked while another local branch remains

## Principle
A soft block should not stop the whole project if the system can still make meaningful local progress.


path: references/continuation-integrity.md
content: # Continuation Integrity

## Core rule
No artifact, no progress.

## False continuation
False continuation means the agent claims it continued the project, but no durable project artifact changed.

## Durable artifacts
Examples:
- `STATE.md`
- `TODO.md`
- `PENDING-DECISIONS.md`
- `HEARTBEAT-LOG.md`
- new review / decision / doc artifacts
- a clearly tracked child task

## Escalation rule
If multiple cycles in a row produce no durable artifacts, treat that as evidence of stagnation, not steady progress.


path: references/deferred-backlog.md
content: # Deferred Backlog

## Future upgrades
- model-routing (strong model for design, weaker model for repetitive execution)
- blocked-path rerouting across multiple work branches
- automatic diminishing-returns detection
- multi-project scheduling
- stronger budget-aware continuation policies


path: references/examples.md
content: # Examples

## Good heartbeat candidate
- large workspace refactor
- ongoing skill development with clear project files
- long-running research or documentation project
- long-horizon system projects with many unfinished capability layers (for example a personal operating system still converging toward its original vision)

## Bad heartbeat candidate
- a tiny one-shot task
- a project with no STATE.md / TODO.md
- a project whose only next step is waiting for a human approval and nothing else can proceed

## Strategic heartbeat mode
For system projects, a heartbeat can be more than a local-next-step checker.

Use strategic mode when:
- the project still has multiple unfinished capability layers
- the original vision is clear enough to evaluate progress against
- the risk is under-building or drifting, not over-automation alone

In strategic mode, each cycle should:
1. re-evaluate the whole project state against the original vision
2. decide what capability gap matters most now
3. choose one smallest high-value improvement
4. avoid collapsing into `waiting-human` just because no new external evidence appeared

Only enter `waiting-human` when a real human-only decision, authorization, or missing external information truly blocks the next justified move.

## Cadence guide
| Interval | When to use |
|----------|-------------|
| 30s | Active projects — shorter interval detects in-progress skips faster, reducing dead air between cycles |
| 5–15 min | Normal ongoing work |
| 30–60 min | Low-intensity sustained projects |
| 2–4 h | Large long-running projects with sparse milestones |

**Why 30s often works best:** When the skip-on-in-progress rule is active, a long interval means the system waits too long after each cycle finishes. 30s keeps the loop responsive without idle gaps, even when each cycle is still in-progress.

## Cron feedback delivery
**Webchat does not support cron result delivery.** Announce-mode cron jobs (which send results after each cycle) require Telegram or another configured channel.

Before enabling announce delivery, ensure:
- Telegram is enabled in config (`channels.telegram.enabled: true`)
- The cron job has `delivery: { mode: "announce", channel: "telegram", to: "<your-chat-id>" }`
- Without this, cron runs silently with no visible feedback

Alternatively, use `delivery: none` and check `HEARTBEAT-LOG.md` manually for progress.


path: references/heartbeat-log-template.md
content: # HEARTBEAT-LOG

## Cycle entry
- Time:
- Project:
- Cadence:
- What was checked:
- What changed:
- What stayed blocked:
- Next concrete step:
- Should the loop continue? Why:


path: references/pending-decisions-template.md
content: # PENDING-DECISIONS

## Pending approvals / blocked decisions
- Date:
- Decision needed:
- Why blocked:
- What work can still continue:
- What is fully blocked:
- Who must decide:
- Resume trigger:


path: references/summary-handoff.md
content: # Summary + Handoff

## Cycle summary
Every cycle should summarize:
- current state (`running`, `waiting-human`, `closed`)
- what changed
- what stayed blocked
- next step or required human action

## Waiting-human
If the project stops because only a human decision remains, the loop should say so explicitly and point to the pending decision backlog.

## Closed
If the project is done, the loop should say so explicitly and recommend disabling the cron.

## Fallback
If live delivery is unavailable, the handoff still has to exist in local project artifacts.


path: references/todo.md
content: # TODO / Deferred Ideas

## Future upgrades
- model-routing (strong model for design, weaker model for repetitive execution)
- blocked-path rerouting across multiple work branches
- automatic diminishing-returns detection
- multi-project scheduling
- stronger budget-aware continuation policies


path: scripts/fit_check.py
content: #!/usr/bin/env python3
import argparse
import os
from pathlib import Path

REQUIRED_FILES = ['README.md', 'STATE.md', 'TODO.md']


def main():
    ap = argparse.ArgumentParser(description='Check if a project is ready for heartbeat-style continuation')
    ap.add_argument('project_dir')
    args = ap.parse_args()

    project_dir = Path(os.path.expanduser(args.project_dir)).resolve()
    print(f'Project: {project_dir}')

    missing = [f for f in REQUIRED_FILES if not (project_dir / f).exists()]
    if missing:
        print('Verdict: not-ready')
        print('Reasons:')
        print('- Missing canonical project files: ' + ', '.join(missing))
        print('Recommendation: create the missing files before using a heartbeat loop.')
        return

    state = (project_dir / 'STATE.md').read_text(encoding='utf-8')
    todo = (project_dir / 'TODO.md').read_text(encoding='utf-8')
    has_focus = 'Current focus' in state or 'Current Focus' in state
    has_next = 'Next steps' in state or '## Active' in todo

    if has_focus and has_next:
        print('Verdict: ready')
        print('Reasons:')
        print('- canonical project files exist')
        print('- state/todo contain active execution context')
        print('Recommendation: safe to design a heartbeat loop for this project.')
    else:
        print('Verdict: review-before-use')
        print('Reasons:')
        if not has_focus:
            print('- STATE.md lacks a clear current focus section')
        if not has_next:
            print('- no clear next-step section found in STATE.md or TODO.md')
        print('Recommendation: clarify the current focus and next steps before using heartbeat automation.')


if __name__ == '__main__':
    main()


path: scripts/render_plan.py
content: #!/usr/bin/env python3
import argparse
import os
from pathlib import Path


def cadence_label(minutes: int) -> str:
    if minutes <= 10:
        return 'high-intensity build'
    if minutes <= 30:
        return 'active continuation'
    if minutes <= 120:
        return 'steady maintenance'
    return 'low-frequency research'


def main():
    ap = argparse.ArgumentParser(description='Render a controlled project-heartbeat plan')
    ap.add_argument('project_dir')
    ap.add_argument('--every-min', type=int, default=30)
    args = ap.parse_args()

    project_dir = Path(os.path.expanduser(args.project_dir)).resolve()
    backlog = project_dir / 'PENDING-DECISIONS.md'
    progress = project_dir / 'HEARTBEAT-LOG.md'

    print(f'Project: {project_dir}')
    print(f'Cadence: every {args.every_min} minutes ({cadence_label(args.every_min)})')
    print('\nContinue conditions:')
    print('- a clear next concrete step exists in project artifacts')
    print('- work can continue locally without requiring an external action right now')
    print('- the last few cycles still produced meaningful progress')

    print('\nHard stop boundaries:')
    print('- budget or quota exhausted')
    print('- safety / human-only boundary reached with no meaningful bypass path')
    print('- no clear next step for repeated cycles')
    print('- repeated no-progress cycles')

    print('\nSoft block boundaries:')
    print('- external approval pending')
    print('- repository creation or publishing is blocked but internal work can continue')
    print('- one path is blocked while another concrete path remains')

    print('\nArtifacts to maintain:')
    print(f'- pending decision backlog: {backlog.name}')
    print(f'- heartbeat progress log: {progress.name}')
    print('- canonical project truth: STATE.md / TODO.md / DECISIONS.md')

    print('\nContinuation integrity:')
    print('- no artifact, no progress')
    print('- a cycle should update at least one durable artifact')
    print('- repeated no-op cycles should escalate toward stopping the loop')

    print('\nResume protocol:')
    print('1. Read STATE.md')
    print('2. Read TODO.md')
    print(f'3. Read {backlog.name}')
    print(f'4. Read {progress.name}')
    print('5. Continue from the smallest clear next step')


if __name__ == '__main__':
    main()


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)