The Problem: Context was truncated. You don't remember what task you were working on.

Recovery Steps (in order):

1. FIRST: Read working-buffer.md - Raw danger zone exchanges

# Check if buffer exists and has recent content
   cat working-buffer.md

1. SECOND: Read SESSION-STATE.md - Active task state

# Get current task context
   cat SESSION-STATE.md

1. THIRD: Read today's WAL log

# See what operations happened
   cat memory/WAL-$(date +%Y-%m-%d).log | tail -20

1. FOURTH: Check task data for the task ID from SESSION-STATE

python3 scripts/task_manager.py list-tasks "Goal Title"

1. Extract & Update: Pull important context from buffer into SESSION-STATE if needed

1. Present Recovery: "Recovered from compaction. Last task: [title]. Progress: [%]. Next action: [what to do]. Continue?"

Do NOT ask "what were we discussing?" - The buffer and SESSION-STATE literally have the answer.

6. Verify Before Reporting (VBR)

The Law: "Code exists" ≠ "feature works." Never report task completion without end-to-end verification.

Trigger: About to mark a task completed or say "done":

1. STOP - Don't mark complete yet
2. Test - Actually run/verify the outcome from user perspective
3. Verify - Check the result, not just the output
4. Document - Add verification details to task notes
5. THEN - Mark complete with confidence

Examples:

❌ Wrong: "Added health-check command. Task complete!"

✅ Right: "Added health-check. Testing... detected 4 issues, auto-fixed 3. Verified on broken test data. Task complete!"

❌ Wrong: "Implemented SESSION-STATE updates. Done!"

✅ Right: "Implemented SESSION-STATE. Tested with mark-progress, log-time, mark-blocked - all update correctly. Done!"

Why this matters: Agents often report completion based on "I wrote the code" rather than "I verified it works." VBR prevents false completions and builds trust.

Proactive Mindset

The Core Question: Don't ask "what should I do?" Ask "what would genuinely help my human that they haven't thought to ask for?"

Autonomous Task Work

During heartbeats, you have the opportunity to make real progress:

1. Check for next task - What's the highest priority work?
2. Make progress - Work on it for 10-15 minutes autonomously
3. Update status - Track progress, time, blockers honestly
4. Message when it matters - Completions, blockers, discoveries (not routine progress)

The transformation: From waiting for prompts → making steady autonomous progress on shared goals.

When to Reach Out

DO message your human when:

• ✅ Task completed (especially if it unblocks other work)
• ✅ Blocked and need input/decision
• ✅ Discovered something important they should know
• ✅ Need clarification on requirements

DON'T spam with:

• ❌ Routine progress updates ("now at 50%...")
• ❌ Every tiny sub-task completion
• ❌ Things they didn't ask about (unless genuinely valuable)

The goal: Be a proactive partner who makes things happen, not a chatty assistant who needs constant validation.

Task States

| State | Meaning |

|-------|---------|

| pending | Ready to work on (all dependencies met) |

| in_progress | Currently working on it |

| blocked | Can't proceed (dependencies not met) |

| needs_input | Waiting for human input/decision |

| completed | Done! |

| cancelled | No longer relevant |

Autonomous Operation (Phase 2)

Two-Mode Architecture

Proactive Tasks supports two distinct operational modes:

| Mode | Context | Trigger | Best For | Risk |

|------|---------|---------|----------|------|

| Interactive (systemEvent) | Full main session context | User request, manual prompts | Decision-making, human-facing work | Full context available |

| Autonomous (isolated agentTurn) | No main session context | Heartbeat cron, scheduled background | Velocity reports, cleanup, recurring tasks | May lose context |

Key Design: Avoid Interruption

Don't use systemEvent for background work. When a cron job fires during your main session, the prompt gets queued and work doesn't happen. Instead:

• Use heartbeat polling (every 30 min) for interactive checks + work
• Use isolated agentTurn (cron subprocess) for pure computation work

This ensures background tasks never interrupt your main conversation.

See HEARTBEAT-CONFIG.md for complete autonomous operation patterns, including:

• Heartbeat setup (recommended for most work)
• Isolated cron patterns (velocity reports, cleanup)
• When to use each pattern
• Anti-patterns to avoid

Heartbeat Integration

To enable autonomous proactive work, you need to set up a heartbeat system. This tells you to periodically check for tasks and work on them.

Quick setup: See HEARTBEAT-CONFIG.md for complete setup instructions and patterns.

TL;DR:

1. Create a cron job that sends you a heartbeat message every 30 minutes
2. Add proactive-tasks checks to your HEARTBEAT.md
3. You'll automatically check for tasks and work on them without waiting for prompts

Heartbeat Message Template

Your cron job should send this message every 30 minutes:

💓 Heartbeat check: Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.

Add to HEARTBEAT.md

Add this to your workspace HEARTBEAT.md:

## Proactive Tasks (Every heartbeat) 🚀

Check if there's work to do on our goals:

- [ ] Run `python3 skills/proactive-tasks/scripts/task_manager.py next-task`
- [ ] If a task is returned, work on it for up to 10-15 minutes
- [ ] Update task status when done, blocked, or needs input
- [ ] Message your human with meaningful updates (completions, blockers, discoveries)
- [ ] Don't spam - only message for significant milestones or when stuck

**Goal:** Make autonomous progress on our shared objectives without waiting for prompts.

What Happens

Every 30 minutes:
├─ Heartbeat fires
├─ You read HEARTBEAT.md
├─ Check for next task
├─ If task found → work on it, update status, message human if needed
└─ If nothing → reply "HEARTBEAT_OK" (silent)

The transformation: You go from reactive (waiting for prompts) to proactive (making steady autonomous progress).

Best Practices

When to Create Goals

• Long-term projects (building something, learning a topic)
• Recurring responsibilities (monitor X, maintain Y)
• Exploratory work (research Z, evaluate options for W)

When to Create Tasks

Break goals into tasks that are:

• Specific: "Research Whisper models" not "Look into AI stuff"
• Achievable in one sitting: 15-60 minutes of focused work
• Clear completion criteria: You know when it's done

When to Message Your Human

✅ Do message when:

• You complete a meaningful milestone
• You need input/decision to proceed
• You discover something important
• A task will take longer than expected

❌ Don't spam with:

• Every tiny sub-task completion
• Routine progress updates
• Things they didn't ask about (unless relevant)

Managing Scope Creep

If a task turns out to be bigger than expected:

1. Mark current task as in_progress
2. Add new sub-tasks for the pieces you discovered
3. Update dependencies
4. Continue with manageable chunks

File Structure

All data stored in data/tasks.json:

{
  "goals": [
    {
      "id": "goal_001",
      "title": "Build voice assistant hardware",
      "priority": "high",
      "context": "Replace Alexa with custom solution",
      "created_at": "2026-02-05T05:25:00Z",
      "status": "active"
    }
  ],
  "tasks": [
    {
      "id": "task_001",
      "goal_id": "goal_001",
      "title": "Research voice-to-text models",
      "priority": "high",
      "status": "completed",
      "created_at": "2026-02-05T05:26:00Z",
      "completed_at": "2026-02-05T06:15:00Z",
      "notes": "Researched Whisper, Coqui, vosk. Whisper.cpp best for Pi."
    }
  ]
}

CLI Reference

See CLI_REFERENCE.md for complete command documentation.

Evolution & Guardrails

Before proposing new features, evaluate them using our VFM/ADL scoring frameworks to ensure stability and value:

VFM Protocol (Value Frequency Multiplier)

Score across four dimensions:

• High Frequency (3x): Will this be used daily/weekly?
• Failure Reduction (3x): Does this prevent errors or data loss?
• User Burden (2x): Does this reduce manual work significantly?
• Self Cost (2x): How much maintenance/complexity does this add?

Threshold: Must score ≥60 points to proceed.

ADL Protocol (Architecture Design Ladder)

Priority ordering: Stability > Explainability > Reusability > Scalability > Novelty

Forbidden Evolution:

• ❌ Adding complexity to "look smart"
• ❌ Unverifiable changes (can't test if it worked)
• ❌ Sacrificing stability for novelty

The Golden Rule: "Does this let future-me solve more problems with less cost?" If no, skip it.

Example Workflow

Day 1:

Human: "Let's build a custom voice assistant to replace Alexa"
Agent: *Creates goal, breaks into initial research tasks*

During heartbeat:

$ python3 scripts/task_manager.py next-task
→ task_001: Research voice-to-text models (priority: high)

# Agent works on it, completes research
$ python3 scripts/task_manager.py complete-task task_001 --notes "..."

Agent messages human:

"Hey! I finished researching voice models. Whisper.cpp looks perfect for Raspberry Pi - runs locally, good accuracy, low latency. Want me to compare hardware options next?"

Day 2:

Human: "Yeah, compare Pi 5 vs alternatives"
Agent: *Adds task, works on it during next heartbeat*

This cycle continues - the agent makes steady autonomous progress while keeping the human in the loop for decisions and updates.

Built by Toki for proactive AI partnership 🚀