{
  "schemaVersion": "1.0",
  "item": {
    "slug": "proactive-tasks",
    "name": "Proactive Tasks",
    "source": "tencent",
    "type": "skill",
    "category": "通讯协作",
    "sourceUrl": "https://clawhub.ai/ImrKhn03/proactive-tasks",
    "canonicalUrl": "https://clawhub.ai/ImrKhn03/proactive-tasks",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/proactive-tasks",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=proactive-tasks",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "CHANGELOG.md",
      "HEARTBEAT-CONFIG.md",
      "README.md",
      "SKILL.md",
      "package.json",
      "scripts/task_manager.py"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/proactive-tasks"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/proactive-tasks",
    "agentPageUrl": "https://openagent3.xyz/skills/proactive-tasks/agent",
    "manifestUrl": "https://openagent3.xyz/skills/proactive-tasks/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/proactive-tasks/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Proactive Tasks",
        "body": "A task management system that transforms reactive assistants into proactive partners who work autonomously on shared goals."
      },
      {
        "title": "Core Concept",
        "body": "Instead of waiting for your human to tell you what to do, this skill lets you:\n\nTrack goals and break them into actionable tasks\nWork on tasks during heartbeats\nMessage your human with updates and ask for input when blocked\nMake steady progress on long-term objectives"
      },
      {
        "title": "Creating Goals",
        "body": "When your human mentions a goal or project:\n\npython3 scripts/task_manager.py add-goal \"Build voice assistant hardware\" \\\n  --priority high \\\n  --context \"Replace Alexa with custom solution using local models\""
      },
      {
        "title": "Breaking Down into Tasks",
        "body": "python3 scripts/task_manager.py add-task \"Build voice assistant hardware\" \\\n  \"Research voice-to-text models\" \\\n  --priority high\n\npython3 scripts/task_manager.py add-task \"Build voice assistant hardware\" \\\n  \"Compare Raspberry Pi vs other hardware options\" \\\n  --depends-on \"Research voice-to-text models\""
      },
      {
        "title": "During Heartbeats",
        "body": "Check what to work on next:\n\npython3 scripts/task_manager.py next-task\n\nThis returns the highest-priority task you can work on (no unmet dependencies, not blocked)."
      },
      {
        "title": "Completing Tasks",
        "body": "python3 scripts/task_manager.py complete-task <task-id> \\\n  --notes \"Researched Whisper, Coqui, vosk. Whisper.cpp looks best for Pi.\""
      },
      {
        "title": "Messaging Your Human",
        "body": "When you complete something important or get blocked:\n\npython3 scripts/task_manager.py mark-needs-input <task-id> \\\n  --reason \"Need budget approval for hardware purchase\"\n\nThen message your human with the update/question."
      },
      {
        "title": "Phase 2: Production-Ready Architecture",
        "body": "Proactive Tasks v1.2.0 includes battle-tested patterns from real agent usage to prevent data loss, survive context truncation, and maintain reliability under autonomous operation."
      },
      {
        "title": "1. WAL Protocol (Write-Ahead Logging)",
        "body": "The Problem: Agents write to memory files, then context gets truncated. Changes vanish.\n\nThe Solution: Log critical changes to memory/WAL-YYYY-MM-DD.log BEFORE modifying task data.\n\nHow it works:\n\nEvery mark-progress, log-time, or status change creates a WAL entry first\nIf context gets cut mid-operation, the WAL has the details\nAfter compaction, read the WAL to recover what was happening\n\nEvents logged:\n\nPROGRESS_CHANGE: Task progress updates (0-100%)\nTIME_LOG: Actual time spent on tasks\nSTATUS_CHANGE: Task state transitions (blocked, completed, etc.)\nHEALTH_CHECK: Self-healing operations\n\nAutomatically enabled - no configuration needed. WAL files are created in memory/ directory."
      },
      {
        "title": "2. SESSION-STATE.md (Active Working Memory)",
        "body": "The Concept: Chat history is a BUFFER, not storage. SESSION-STATE.md is your \"RAM\" - the ONLY place task details are reliably preserved.\n\nAuto-updated on every task operation:\n\n## Current Task\n- **ID:** task_abc123\n- **Title:** Research voice models\n- **Status:** in_progress\n- **Progress:** 75%\n- **Time:** 45 min actual / 60 min estimate (25% faster)\n\n## Next Action\nComplete research, document findings in notes, mark complete.\n\nWhy this matters: After context compaction, you can read SESSION-STATE.md and immediately know:\n\nWhat you were working on\nHow far you got\nWhat to do next"
      },
      {
        "title": "3. Working Buffer (Danger Zone Safety)",
        "body": "The Problem: Between 60% and 100% context usage, you're in the \"danger zone\" - compaction could happen any time.\n\nThe Solution: Automatically append all task updates to working-buffer.md.\n\nHow it works:\n\n# Every progress update, time log, or status change appends:\n- PROGRESS_CHANGE (2026-02-12T10:30:00Z): task_abc123 → 75%\n- TIME_LOG (2026-02-12T10:35:00Z): task_abc123 → +15 min\n- STATUS_CHANGE (2026-02-12T10:40:00Z): task_abc123 → completed\n\nAfter compaction: Read working-buffer.md to see exactly what happened during the danger zone.\n\nManual flush: python3 scripts/task_manager.py flush-buffer to copy buffer contents to daily memory file."
      },
      {
        "title": "4. Self-Healing Health Check",
        "body": "Agents make mistakes. Task data can get corrupted over time. The health-check command detects and auto-fixes common issues:\n\npython3 scripts/task_manager.py health-check\n\nDetects 5 categories of issues:\n\nOrphaned recurring tasks - No parent goal\nImpossible states - Status=completed but progress < 100%\nMissing timestamps - Completed tasks without completed_at\nTime anomalies - Actual time >> estimate (flags for review, doesn't auto-fix)\nFuture-dated completions - Completed tasks with future timestamps\n\nAuto-fixes 4 safe categories (time anomalies just flagged for human review).\n\nWhen to run:\n\nDuring heartbeats (every few days)\nAfter recovering from context truncation\nWhen task data seems inconsistent"
      },
      {
        "title": "Production Reliability",
        "body": "These four patterns work together to create a robust system:\n\nUser request → WAL log → Update data → Update SESSION-STATE → Append to buffer\n     ↓              ↓            ↓                ↓                    ↓\nContext cut? → Read WAL → Verify data → Check SESSION-STATE → Review buffer\n\nResult: You never lose work, even during context truncation. The system self-heals and maintains consistency autonomously."
      },
      {
        "title": "5. Compaction Recovery Protocol",
        "body": "Trigger: Session starts with <summary> tag, or you're asked \"where were we?\" or \"continue\".\n\nThe Problem: Context was truncated. You don't remember what task you were working on.\n\nRecovery Steps (in order):\n\nFIRST: Read working-buffer.md - Raw danger zone exchanges\n# Check if buffer exists and has recent content\ncat working-buffer.md\n\n\n\nSECOND: Read SESSION-STATE.md - Active task state\n# Get current task context\ncat SESSION-STATE.md\n\n\n\nTHIRD: Read today's WAL log\n# See what operations happened\ncat memory/WAL-$(date +%Y-%m-%d).log | tail -20\n\n\n\nFOURTH: Check task data for the task ID from SESSION-STATE\npython3 scripts/task_manager.py list-tasks \"Goal Title\"\n\n\n\nExtract & Update: Pull important context from buffer into SESSION-STATE if needed\n\n\nPresent Recovery: \"Recovered from compaction. Last task: [title]. Progress: [%]. Next action: [what to do]. Continue?\"\n\nDo NOT ask \"what were we discussing?\" - The buffer and SESSION-STATE literally have the answer."
      },
      {
        "title": "6. Verify Before Reporting (VBR)",
        "body": "The Law: \"Code exists\" ≠ \"feature works.\" Never report task completion without end-to-end verification.\n\nTrigger: About to mark a task completed or say \"done\":\n\nSTOP - Don't mark complete yet\nTest - Actually run/verify the outcome from user perspective\nVerify - Check the result, not just the output\nDocument - Add verification details to task notes\nTHEN - Mark complete with confidence\n\nExamples:\n\n❌ Wrong: \"Added health-check command. Task complete!\"\n✅ Right: \"Added health-check. Testing... detected 4 issues, auto-fixed 3. Verified on broken test data. Task complete!\"\n\n❌ Wrong: \"Implemented SESSION-STATE updates. Done!\"\n✅ Right: \"Implemented SESSION-STATE. Tested with mark-progress, log-time, mark-blocked - all update correctly. Done!\"\n\nWhy 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."
      },
      {
        "title": "Proactive Mindset",
        "body": "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?\""
      },
      {
        "title": "Autonomous Task Work",
        "body": "During heartbeats, you have the opportunity to make real progress:\n\nCheck for next task - What's the highest priority work?\nMake progress - Work on it for 10-15 minutes autonomously\nUpdate status - Track progress, time, blockers honestly\nMessage when it matters - Completions, blockers, discoveries (not routine progress)\n\nThe transformation: From waiting for prompts → making steady autonomous progress on shared goals."
      },
      {
        "title": "When to Reach Out",
        "body": "DO message your human when:\n\n✅ Task completed (especially if it unblocks other work)\n✅ Blocked and need input/decision\n✅ Discovered something important they should know\n✅ Need clarification on requirements\n\nDON'T spam with:\n\n❌ Routine progress updates (\"now at 50%...\")\n❌ Every tiny sub-task completion\n❌ Things they didn't ask about (unless genuinely valuable)\n\nThe goal: Be a proactive partner who makes things happen, not a chatty assistant who needs constant validation."
      },
      {
        "title": "Task States",
        "body": "StateMeaningpendingReady to work on (all dependencies met)in_progressCurrently working on itblockedCan't proceed (dependencies not met)needs_inputWaiting for human input/decisioncompletedDone!cancelledNo longer relevant"
      },
      {
        "title": "Two-Mode Architecture",
        "body": "Proactive Tasks supports two distinct operational modes:\n\nModeContextTriggerBest ForRiskInteractive (systemEvent)Full main session contextUser request, manual promptsDecision-making, human-facing workFull context availableAutonomous (isolated agentTurn)No main session contextHeartbeat cron, scheduled backgroundVelocity reports, cleanup, recurring tasksMay lose context"
      },
      {
        "title": "Key Design: Avoid Interruption",
        "body": "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:\n\nUse heartbeat polling (every 30 min) for interactive checks + work\nUse isolated agentTurn (cron subprocess) for pure computation work\n\nThis ensures background tasks never interrupt your main conversation.\n\nSee HEARTBEAT-CONFIG.md for complete autonomous operation patterns, including:\n\nHeartbeat setup (recommended for most work)\nIsolated cron patterns (velocity reports, cleanup)\nWhen to use each pattern\nAnti-patterns to avoid"
      },
      {
        "title": "Heartbeat Integration",
        "body": "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.\n\nQuick setup: See HEARTBEAT-CONFIG.md for complete setup instructions and patterns.\n\nTL;DR:\n\nCreate a cron job that sends you a heartbeat message every 30 minutes\nAdd proactive-tasks checks to your HEARTBEAT.md\nYou'll automatically check for tasks and work on them without waiting for prompts"
      },
      {
        "title": "Heartbeat Message Template",
        "body": "Your cron job should send this message every 30 minutes:\n\n💓 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."
      },
      {
        "title": "Add to HEARTBEAT.md",
        "body": "Add this to your workspace HEARTBEAT.md:\n\n## Proactive Tasks (Every heartbeat) 🚀\n\nCheck if there's work to do on our goals:\n\n- [ ] Run `python3 skills/proactive-tasks/scripts/task_manager.py next-task`\n- [ ] If a task is returned, work on it for up to 10-15 minutes\n- [ ] Update task status when done, blocked, or needs input\n- [ ] Message your human with meaningful updates (completions, blockers, discoveries)\n- [ ] Don't spam - only message for significant milestones or when stuck\n\n**Goal:** Make autonomous progress on our shared objectives without waiting for prompts."
      },
      {
        "title": "What Happens",
        "body": "Every 30 minutes:\n├─ Heartbeat fires\n├─ You read HEARTBEAT.md\n├─ Check for next task\n├─ If task found → work on it, update status, message human if needed\n└─ If nothing → reply \"HEARTBEAT_OK\" (silent)\n\nThe transformation: You go from reactive (waiting for prompts) to proactive (making steady autonomous progress)."
      },
      {
        "title": "When to Create Goals",
        "body": "Long-term projects (building something, learning a topic)\nRecurring responsibilities (monitor X, maintain Y)\nExploratory work (research Z, evaluate options for W)"
      },
      {
        "title": "When to Create Tasks",
        "body": "Break goals into tasks that are:\n\nSpecific: \"Research Whisper models\" not \"Look into AI stuff\"\nAchievable in one sitting: 15-60 minutes of focused work\nClear completion criteria: You know when it's done"
      },
      {
        "title": "When to Message Your Human",
        "body": "✅ Do message when:\n\nYou complete a meaningful milestone\nYou need input/decision to proceed\nYou discover something important\nA task will take longer than expected\n\n❌ Don't spam with:\n\nEvery tiny sub-task completion\nRoutine progress updates\nThings they didn't ask about (unless relevant)"
      },
      {
        "title": "Managing Scope Creep",
        "body": "If a task turns out to be bigger than expected:\n\nMark current task as in_progress\nAdd new sub-tasks for the pieces you discovered\nUpdate dependencies\nContinue with manageable chunks"
      },
      {
        "title": "File Structure",
        "body": "All data stored in data/tasks.json:\n\n{\n  \"goals\": [\n    {\n      \"id\": \"goal_001\",\n      \"title\": \"Build voice assistant hardware\",\n      \"priority\": \"high\",\n      \"context\": \"Replace Alexa with custom solution\",\n      \"created_at\": \"2026-02-05T05:25:00Z\",\n      \"status\": \"active\"\n    }\n  ],\n  \"tasks\": [\n    {\n      \"id\": \"task_001\",\n      \"goal_id\": \"goal_001\",\n      \"title\": \"Research voice-to-text models\",\n      \"priority\": \"high\",\n      \"status\": \"completed\",\n      \"created_at\": \"2026-02-05T05:26:00Z\",\n      \"completed_at\": \"2026-02-05T06:15:00Z\",\n      \"notes\": \"Researched Whisper, Coqui, vosk. Whisper.cpp best for Pi.\"\n    }\n  ]\n}"
      },
      {
        "title": "CLI Reference",
        "body": "See CLI_REFERENCE.md for complete command documentation."
      },
      {
        "title": "Evolution & Guardrails",
        "body": "Before proposing new features, evaluate them using our VFM/ADL scoring frameworks to ensure stability and value:"
      },
      {
        "title": "VFM Protocol (Value Frequency Multiplier)",
        "body": "Score across four dimensions:\n\nHigh Frequency (3x): Will this be used daily/weekly?\nFailure Reduction (3x): Does this prevent errors or data loss?\nUser Burden (2x): Does this reduce manual work significantly?\nSelf Cost (2x): How much maintenance/complexity does this add?\n\nThreshold: Must score ≥60 points to proceed."
      },
      {
        "title": "ADL Protocol (Architecture Design Ladder)",
        "body": "Priority ordering: Stability > Explainability > Reusability > Scalability > Novelty\n\nForbidden Evolution:\n\n❌ Adding complexity to \"look smart\"\n❌ Unverifiable changes (can't test if it worked)\n❌ Sacrificing stability for novelty\n\nThe Golden Rule: \"Does this let future-me solve more problems with less cost?\" If no, skip it."
      },
      {
        "title": "Example Workflow",
        "body": "Day 1:\n\nHuman: \"Let's build a custom voice assistant to replace Alexa\"\nAgent: *Creates goal, breaks into initial research tasks*\n\nDuring heartbeat:\n\n$ python3 scripts/task_manager.py next-task\n→ task_001: Research voice-to-text models (priority: high)\n\n# Agent works on it, completes research\n$ python3 scripts/task_manager.py complete-task task_001 --notes \"...\"\n\nAgent messages human:\n\n\"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?\"\n\nDay 2:\n\nHuman: \"Yeah, compare Pi 5 vs alternatives\"\nAgent: *Adds task, works on it during next heartbeat*\n\nThis cycle continues - the agent makes steady autonomous progress while keeping the human in the loop for decisions and updates.\n\nBuilt by Toki for proactive AI partnership 🚀"
      }
    ],
    "body": "Proactive Tasks\n\nA task management system that transforms reactive assistants into proactive partners who work autonomously on shared goals.\n\nCore Concept\n\nInstead of waiting for your human to tell you what to do, this skill lets you:\n\nTrack goals and break them into actionable tasks\nWork on tasks during heartbeats\nMessage your human with updates and ask for input when blocked\nMake steady progress on long-term objectives\nQuick Start\nCreating Goals\n\nWhen your human mentions a goal or project:\n\npython3 scripts/task_manager.py add-goal \"Build voice assistant hardware\" \\\n  --priority high \\\n  --context \"Replace Alexa with custom solution using local models\"\n\nBreaking Down into Tasks\npython3 scripts/task_manager.py add-task \"Build voice assistant hardware\" \\\n  \"Research voice-to-text models\" \\\n  --priority high\n\npython3 scripts/task_manager.py add-task \"Build voice assistant hardware\" \\\n  \"Compare Raspberry Pi vs other hardware options\" \\\n  --depends-on \"Research voice-to-text models\"\n\nDuring Heartbeats\n\nCheck what to work on next:\n\npython3 scripts/task_manager.py next-task\n\n\nThis returns the highest-priority task you can work on (no unmet dependencies, not blocked).\n\nCompleting Tasks\npython3 scripts/task_manager.py complete-task <task-id> \\\n  --notes \"Researched Whisper, Coqui, vosk. Whisper.cpp looks best for Pi.\"\n\nMessaging Your Human\n\nWhen you complete something important or get blocked:\n\npython3 scripts/task_manager.py mark-needs-input <task-id> \\\n  --reason \"Need budget approval for hardware purchase\"\n\n\nThen message your human with the update/question.\n\nPhase 2: Production-Ready Architecture\n\nProactive Tasks v1.2.0 includes battle-tested patterns from real agent usage to prevent data loss, survive context truncation, and maintain reliability under autonomous operation.\n\n1. WAL Protocol (Write-Ahead Logging)\n\nThe Problem: Agents write to memory files, then context gets truncated. Changes vanish.\n\nThe Solution: Log critical changes to memory/WAL-YYYY-MM-DD.log BEFORE modifying task data.\n\nHow it works:\n\nEvery mark-progress, log-time, or status change creates a WAL entry first\nIf context gets cut mid-operation, the WAL has the details\nAfter compaction, read the WAL to recover what was happening\n\nEvents logged:\n\nPROGRESS_CHANGE: Task progress updates (0-100%)\nTIME_LOG: Actual time spent on tasks\nSTATUS_CHANGE: Task state transitions (blocked, completed, etc.)\nHEALTH_CHECK: Self-healing operations\n\nAutomatically enabled - no configuration needed. WAL files are created in memory/ directory.\n\n2. SESSION-STATE.md (Active Working Memory)\n\nThe Concept: Chat history is a BUFFER, not storage. SESSION-STATE.md is your \"RAM\" - the ONLY place task details are reliably preserved.\n\nAuto-updated on every task operation:\n\n## Current Task\n- **ID:** task_abc123\n- **Title:** Research voice models\n- **Status:** in_progress\n- **Progress:** 75%\n- **Time:** 45 min actual / 60 min estimate (25% faster)\n\n## Next Action\nComplete research, document findings in notes, mark complete.\n\n\nWhy this matters: After context compaction, you can read SESSION-STATE.md and immediately know:\n\nWhat you were working on\nHow far you got\nWhat to do next\n3. Working Buffer (Danger Zone Safety)\n\nThe Problem: Between 60% and 100% context usage, you're in the \"danger zone\" - compaction could happen any time.\n\nThe Solution: Automatically append all task updates to working-buffer.md.\n\nHow it works:\n\n# Every progress update, time log, or status change appends:\n- PROGRESS_CHANGE (2026-02-12T10:30:00Z): task_abc123 → 75%\n- TIME_LOG (2026-02-12T10:35:00Z): task_abc123 → +15 min\n- STATUS_CHANGE (2026-02-12T10:40:00Z): task_abc123 → completed\n\n\nAfter compaction: Read working-buffer.md to see exactly what happened during the danger zone.\n\nManual flush: python3 scripts/task_manager.py flush-buffer to copy buffer contents to daily memory file.\n\n4. Self-Healing Health Check\n\nAgents make mistakes. Task data can get corrupted over time. The health-check command detects and auto-fixes common issues:\n\npython3 scripts/task_manager.py health-check\n\n\nDetects 5 categories of issues:\n\nOrphaned recurring tasks - No parent goal\nImpossible states - Status=completed but progress < 100%\nMissing timestamps - Completed tasks without completed_at\nTime anomalies - Actual time >> estimate (flags for review, doesn't auto-fix)\nFuture-dated completions - Completed tasks with future timestamps\n\nAuto-fixes 4 safe categories (time anomalies just flagged for human review).\n\nWhen to run:\n\nDuring heartbeats (every few days)\nAfter recovering from context truncation\nWhen task data seems inconsistent\nProduction Reliability\n\nThese four patterns work together to create a robust system:\n\nUser request → WAL log → Update data → Update SESSION-STATE → Append to buffer\n     ↓              ↓            ↓                ↓                    ↓\nContext cut? → Read WAL → Verify data → Check SESSION-STATE → Review buffer\n\n\nResult: You never lose work, even during context truncation. The system self-heals and maintains consistency autonomously.\n\n5. Compaction Recovery Protocol\n\nTrigger: Session starts with <summary> tag, or you're asked \"where were we?\" or \"continue\".\n\nThe Problem: Context was truncated. You don't remember what task you were working on.\n\nRecovery Steps (in order):\n\nFIRST: Read working-buffer.md - Raw danger zone exchanges\n\n# Check if buffer exists and has recent content\ncat working-buffer.md\n\n\nSECOND: Read SESSION-STATE.md - Active task state\n\n# Get current task context\ncat SESSION-STATE.md\n\n\nTHIRD: Read today's WAL log\n\n# See what operations happened\ncat memory/WAL-$(date +%Y-%m-%d).log | tail -20\n\n\nFOURTH: Check task data for the task ID from SESSION-STATE\n\npython3 scripts/task_manager.py list-tasks \"Goal Title\"\n\n\nExtract & Update: Pull important context from buffer into SESSION-STATE if needed\n\nPresent Recovery: \"Recovered from compaction. Last task: [title]. Progress: [%]. Next action: [what to do]. Continue?\"\n\nDo NOT ask \"what were we discussing?\" - The buffer and SESSION-STATE literally have the answer.\n\n6. Verify Before Reporting (VBR)\n\nThe Law: \"Code exists\" ≠ \"feature works.\" Never report task completion without end-to-end verification.\n\nTrigger: About to mark a task completed or say \"done\":\n\nSTOP - Don't mark complete yet\nTest - Actually run/verify the outcome from user perspective\nVerify - Check the result, not just the output\nDocument - Add verification details to task notes\nTHEN - Mark complete with confidence\n\nExamples:\n\n❌ 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!\"\n\n❌ Wrong: \"Implemented SESSION-STATE updates. Done!\" ✅ Right: \"Implemented SESSION-STATE. Tested with mark-progress, log-time, mark-blocked - all update correctly. Done!\"\n\nWhy 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.\n\nProactive Mindset\n\nThe Core Question: Don't ask \"what should I do?\" Ask \"what would genuinely help my human that they haven't thought to ask for?\"\n\nAutonomous Task Work\n\nDuring heartbeats, you have the opportunity to make real progress:\n\nCheck for next task - What's the highest priority work?\nMake progress - Work on it for 10-15 minutes autonomously\nUpdate status - Track progress, time, blockers honestly\nMessage when it matters - Completions, blockers, discoveries (not routine progress)\n\nThe transformation: From waiting for prompts → making steady autonomous progress on shared goals.\n\nWhen to Reach Out\n\nDO message your human when:\n\n✅ Task completed (especially if it unblocks other work)\n✅ Blocked and need input/decision\n✅ Discovered something important they should know\n✅ Need clarification on requirements\n\nDON'T spam with:\n\n❌ Routine progress updates (\"now at 50%...\")\n❌ Every tiny sub-task completion\n❌ Things they didn't ask about (unless genuinely valuable)\n\nThe goal: Be a proactive partner who makes things happen, not a chatty assistant who needs constant validation.\n\nTask States\nState\tMeaning\npending\tReady to work on (all dependencies met)\nin_progress\tCurrently working on it\nblocked\tCan't proceed (dependencies not met)\nneeds_input\tWaiting for human input/decision\ncompleted\tDone!\ncancelled\tNo longer relevant\nAutonomous Operation (Phase 2)\nTwo-Mode Architecture\n\nProactive Tasks supports two distinct operational modes:\n\nMode\tContext\tTrigger\tBest For\tRisk\nInteractive (systemEvent)\tFull main session context\tUser request, manual prompts\tDecision-making, human-facing work\tFull context available\nAutonomous (isolated agentTurn)\tNo main session context\tHeartbeat cron, scheduled background\tVelocity reports, cleanup, recurring tasks\tMay lose context\nKey Design: Avoid Interruption\n\nDon'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:\n\nUse heartbeat polling (every 30 min) for interactive checks + work\nUse isolated agentTurn (cron subprocess) for pure computation work\n\nThis ensures background tasks never interrupt your main conversation.\n\nSee HEARTBEAT-CONFIG.md for complete autonomous operation patterns, including:\n\nHeartbeat setup (recommended for most work)\nIsolated cron patterns (velocity reports, cleanup)\nWhen to use each pattern\nAnti-patterns to avoid\nHeartbeat Integration\n\nTo enable autonomous proactive work, you need to set up a heartbeat system. This tells you to periodically check for tasks and work on them.\n\nQuick setup: See HEARTBEAT-CONFIG.md for complete setup instructions and patterns.\n\nTL;DR:\n\nCreate a cron job that sends you a heartbeat message every 30 minutes\nAdd proactive-tasks checks to your HEARTBEAT.md\nYou'll automatically check for tasks and work on them without waiting for prompts\nHeartbeat Message Template\n\nYour cron job should send this message every 30 minutes:\n\n💓 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.\n\nAdd to HEARTBEAT.md\n\nAdd this to your workspace HEARTBEAT.md:\n\n## Proactive Tasks (Every heartbeat) 🚀\n\nCheck if there's work to do on our goals:\n\n- [ ] Run `python3 skills/proactive-tasks/scripts/task_manager.py next-task`\n- [ ] If a task is returned, work on it for up to 10-15 minutes\n- [ ] Update task status when done, blocked, or needs input\n- [ ] Message your human with meaningful updates (completions, blockers, discoveries)\n- [ ] Don't spam - only message for significant milestones or when stuck\n\n**Goal:** Make autonomous progress on our shared objectives without waiting for prompts.\n\nWhat Happens\nEvery 30 minutes:\n├─ Heartbeat fires\n├─ You read HEARTBEAT.md\n├─ Check for next task\n├─ If task found → work on it, update status, message human if needed\n└─ If nothing → reply \"HEARTBEAT_OK\" (silent)\n\n\nThe transformation: You go from reactive (waiting for prompts) to proactive (making steady autonomous progress).\n\nBest Practices\nWhen to Create Goals\nLong-term projects (building something, learning a topic)\nRecurring responsibilities (monitor X, maintain Y)\nExploratory work (research Z, evaluate options for W)\nWhen to Create Tasks\n\nBreak goals into tasks that are:\n\nSpecific: \"Research Whisper models\" not \"Look into AI stuff\"\nAchievable in one sitting: 15-60 minutes of focused work\nClear completion criteria: You know when it's done\nWhen to Message Your Human\n\n✅ Do message when:\n\nYou complete a meaningful milestone\nYou need input/decision to proceed\nYou discover something important\nA task will take longer than expected\n\n❌ Don't spam with:\n\nEvery tiny sub-task completion\nRoutine progress updates\nThings they didn't ask about (unless relevant)\nManaging Scope Creep\n\nIf a task turns out to be bigger than expected:\n\nMark current task as in_progress\nAdd new sub-tasks for the pieces you discovered\nUpdate dependencies\nContinue with manageable chunks\nFile Structure\n\nAll data stored in data/tasks.json:\n\n{\n  \"goals\": [\n    {\n      \"id\": \"goal_001\",\n      \"title\": \"Build voice assistant hardware\",\n      \"priority\": \"high\",\n      \"context\": \"Replace Alexa with custom solution\",\n      \"created_at\": \"2026-02-05T05:25:00Z\",\n      \"status\": \"active\"\n    }\n  ],\n  \"tasks\": [\n    {\n      \"id\": \"task_001\",\n      \"goal_id\": \"goal_001\",\n      \"title\": \"Research voice-to-text models\",\n      \"priority\": \"high\",\n      \"status\": \"completed\",\n      \"created_at\": \"2026-02-05T05:26:00Z\",\n      \"completed_at\": \"2026-02-05T06:15:00Z\",\n      \"notes\": \"Researched Whisper, Coqui, vosk. Whisper.cpp best for Pi.\"\n    }\n  ]\n}\n\nCLI Reference\n\nSee CLI_REFERENCE.md for complete command documentation.\n\nEvolution & Guardrails\n\nBefore proposing new features, evaluate them using our VFM/ADL scoring frameworks to ensure stability and value:\n\nVFM Protocol (Value Frequency Multiplier)\n\nScore across four dimensions:\n\nHigh Frequency (3x): Will this be used daily/weekly?\nFailure Reduction (3x): Does this prevent errors or data loss?\nUser Burden (2x): Does this reduce manual work significantly?\nSelf Cost (2x): How much maintenance/complexity does this add?\n\nThreshold: Must score ≥60 points to proceed.\n\nADL Protocol (Architecture Design Ladder)\n\nPriority ordering: Stability > Explainability > Reusability > Scalability > Novelty\n\nForbidden Evolution:\n\n❌ Adding complexity to \"look smart\"\n❌ Unverifiable changes (can't test if it worked)\n❌ Sacrificing stability for novelty\n\nThe Golden Rule: \"Does this let future-me solve more problems with less cost?\" If no, skip it.\n\nExample Workflow\n\nDay 1:\n\nHuman: \"Let's build a custom voice assistant to replace Alexa\"\nAgent: *Creates goal, breaks into initial research tasks*\n\n\nDuring heartbeat:\n\n$ python3 scripts/task_manager.py next-task\n→ task_001: Research voice-to-text models (priority: high)\n\n# Agent works on it, completes research\n$ python3 scripts/task_manager.py complete-task task_001 --notes \"...\"\n\n\nAgent messages human:\n\n\"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?\"\n\nDay 2:\n\nHuman: \"Yeah, compare Pi 5 vs alternatives\"\nAgent: *Adds task, works on it during next heartbeat*\n\n\nThis cycle continues - the agent makes steady autonomous progress while keeping the human in the loop for decisions and updates.\n\nBuilt by Toki for proactive AI partnership 🚀"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/ImrKhn03/proactive-tasks",
    "publisherUrl": "https://clawhub.ai/ImrKhn03/proactive-tasks",
    "owner": "ImrKhn03",
    "version": "1.2.3",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/proactive-tasks",
    "downloadUrl": "https://openagent3.xyz/downloads/proactive-tasks",
    "agentUrl": "https://openagent3.xyz/skills/proactive-tasks/agent",
    "manifestUrl": "https://openagent3.xyz/skills/proactive-tasks/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/proactive-tasks/agent.md"
  }
}