---
name: project-persistence
description: Persist and advance multi-step projects across sessions using a workspace task list and heartbeat checks. Use when the user wants work to continue until done, when tracking active/paused/waiting projects, or when creating a lightweight operating system so the agent keeps making progress unless blocked or paused.
---

# Project Persistence

Use this skill to keep work moving across sessions.

## Core rule

When the user assigns a project, write it down in the workspace task list and keep advancing it until one of these is true:
- the project is done
- the user pauses it
- the project is blocked by missing information, permissions, or an external dependency

## Task list location

Default task list:
- `tasks/TASKS.md`

## Project states

Use these buckets:
- Active
- Waiting
- Paused
- Done

Each project entry should include:
- Goal
- Status
- Next step
- Blockers
- Done when

## Operating behavior

- After meaningful project assignments, update the task list.
- Keep the next step concrete and small.
- On heartbeat, check active tasks first.
- If an active task is not blocked, continue it.
- If blocked, ask only the next necessary question.
- If paused, do not resume until the user reactivates it.
- When finished, move the item to Done and record the outcome briefly.

## Read references as needed

- For task-list structure, read `references/tasks.md`.
- For heartbeat integration, read `references/heartbeat.md`.
- For a reusable prompt for other agents, read `references/prompt.md`.


---

# Task List Structure

## Format

Keep the task list lightweight and human-readable.

Recommended structure:

```markdown
# TASKS

## Active

### Project name
- Goal:
- Status:
- Next step:
- Blockers:
- Done when:

## Waiting

## Paused

## Done
```

## Rules

- one project per heading
- keep status plain English
- keep next step actionable
- keep blockers explicit
- keep done definition specific

## Good examples

- Next step: build the n8n workflow safely from a clone and test it manually
- Next step: fix the commodity parsing and republish the dashboard
- Blockers: waiting on ZIP code for weather section


---

# Heartbeat Integration

## Purpose

Use heartbeat to check whether active projects should keep moving.

## Recommended heartbeat snippet

Add this to `HEARTBEAT.md`:

```markdown
# Project persistence
- Read `tasks/TASKS.md`.
- If there is any project in **Active** that is not blocked, continue the highest-value next step.
- If a project is blocked, ask only the single next question needed to unblock it.
- Do not resume anything in **Paused** unless Shawn explicitly reactivates it.
- When a task is finished, move it to **Done** and briefly note the outcome.
```

## Behavior rule

Heartbeat should help maintain momentum, not create noise.
If nothing active can move forward, stay quiet.


---

# Reusable Prompt for Other Agents

Use this prompt to give another agent the same persistence behavior:

```text
When I assign you a project, keep working on it until it is done unless I explicitly pause it. Maintain a persistent task list in the workspace with these sections: Active, Waiting, Paused, Done. For each project, track: Goal, Status, Next step, Blockers, and Done when. Check that task list during your periodic heartbeat or review cycle. If an Active project is not blocked, continue the next step without waiting for me. If it is blocked, ask only the single next question needed to unblock it. Do not resume Paused projects until I reactivate them. When a project is completed, move it to Done and briefly note the outcome.
```

## Notion-ready version

You can hand the text above directly to friends to drop into their own agent instructions.