proactive-tasks

プロアクティブなタスク

受け身のアシスタントを、共有の目標に向けて自律的に取り組む積極的なパートナーへと変えるタスク管理システムです。

基本概念

人間から指示されるのを待つ代わりに、このスキルを使うと、次のことができます。

• 目標を追跡し、実行可能なタスクに分割する
• ハートビート中にタスクに取り組む
• 進捗を人間にメッセージで伝え、行き詰まったときは入力を求める
• 長期的な目標に向けて着実に進む

クイックスタート

目標を作成する

人間が目標やプロジェクトについて話したとき：

python3 scripts/task_manager.py add-goal "Build voice assistant hardware" \
  --priority high \
  --context "Replace Alexa with custom solution using local models"

タスクに分割する

python3 scripts/task_manager.py add-task "Build voice assistant hardware" \
  "Research voice-to-text models" \
  --priority high

python3 scripts/task_manager.py add-task "Build voice assistant hardware" \
  "Compare Raspberry Pi vs other hardware options" \
  --depends-on "Research voice-to-text models"

ハートビート中

次に取り組むタスクを確認します。

python3 scripts/task_manager.py next-task

これにより、取り組むことができる最優先のタスクが返されます（未解決の依存関係がなく、ブロックされていないもの）。

タスクを完了する

python3 scripts/task_manager.py complete-task <task-id> \
  --notes "Researched Whisper, Coqui, vosk. Whisper.cpp looks best for Pi."

人間にメッセージを送る

重要な作業を完了したときや、行き詰まったとき：

python3 scripts/task_manager.py mark-needs-input <task-id> \
  --reason "Need budget approval for hardware purchase"

その後、進捗や質問を人間にメッセージで伝えます。

フェーズ 2：本番環境に対応したアーキテクチャ

Proactive Tasks v1.2.0 には、実際のエージェント利用から得られた実証済みのパターンが含まれており、データ損失を防ぎ、コンテキストの切り詰めに対処し、自律動作時の信頼性を維持します。

1. WAL プロトコル（先行書き込みログ）

問題： エージェントがメモリファイルに書き込んだ後、コンテキストが切り詰められます。変更内容は失われます。

解決策： タスクデータを変更する前に、重要な変更を memory/WAL-YYYY-MM-DD.log に記録します。

仕組み：

• mark-progress、log-time、またはステータス変更を行うたびに、まず WAL エントリーを作成します
• 操作の途中でコンテキストが切られても、WAL に詳細が残ります
• 圧縮後、WAL を読んで何が起きていたかを復元します

記録されるイベント：

• PROGRESS_CHANGE：タスクの進捗更新（0～100%）
• TIME_LOG：タスクに実際に費やした時間
• STATUS_CHANGE：タスク状態の遷移（ブロック中、完了など）
• HEALTH_CHECK：自己修復操作

自動的に有効になります。設定は不要です。WAL ファイルは memory/ ディレクトリに作成されます。

2. SESSION-STATE.md（アクティブな作業メモリ）

概念： チャット履歴はバッファであり、ストレージではありません。SESSION-STATE.md は「RAM」であり、タスクの詳細が確実に保持される唯一の場所です。

タスク操作のたびに自動更新されます：

## Current Task
- **ID:** task_abc123
- **Title:** Research voice models
- **Status:** in_progress
- **Progress:** 75%
- **Time:** 45 min actual / 60 min estimate (25% faster)

## Next Action
Complete research, document findings in notes, mark complete.

重要な理由： コンテキストの圧縮後、SESSION-STATE.md を読めば、すぐに次のことを把握できます。

• 何に取り組んでいたか
• どこまで進んだか
• 次に何をすべきか

3. 作業バッファ（危険ゾーンでの安全対策）

問題： コンテキスト使用率が 60% から 100% の間は「危険ゾーン」にあり、いつ圧縮が起きてもおかしくありません。

解決策： すべてのタスク更新を working-buffer.md に自動で追記します。

仕組み：

# Every progress update, time log, or status change appends:
- PROGRESS_CHANGE (2026-02-12T10:30:00Z): task_abc123 → 75%
- TIME_LOG (2026-02-12T10:35:00Z): task_abc123 → +15 min
- STATUS_CHANGE (2026-02-12T10:40:00Z): task_abc123 → completed

圧縮後： working-buffer.md を読めば、危険ゾーン中に起きたことを正確に確認できます。

手動での書き出し： python3 scripts/task_manager.py flush-buffer を実行すると、バッファの内容を日次メモリファイルにコピーできます。

4. 自己修復ヘルスチェック

エージェントは間違いを犯します。 タスクデータは時間の経過とともに破損することがあります。health-check コマンドはよくある問題を検出し、自動修正します。

python3 scripts/task_manager.py health-check

5 種類の問題を検出します：

1. 親のない定期タスク - 親目標がありません
2. 不可能な状態 - ステータスが完了なのに進捗が 100% 未満です
3. タイムスタンプの欠落 - completed_at が設定されていない完了済みタスクです
4. 時間の異常 - 実績時間が見積もりを大幅に超過しています（要確認として通知します。自動修正はしません）
5. 未来の日付での完了 - タイムスタンプが未来になっている完了済みタスクです

安全な 4 種類の問題を自動修正します（時間の異常は人間による確認のために通知するだけです）。

実行するタイミング：

• ハートビート中（数日ごと）
• コンテキストの切り詰めから復旧した後
• タスクデータに一貫性がないように見えるとき

本番環境での信頼性

この 4 つのパターンが連携して、堅牢なシステムを実現します。

User request → WAL log → Update data → Update SESSION-STATE → Append to buffer
     ↓              ↓            ↓                ↓                    ↓
Context cut? → Read WAL → Verify data → Check SESSION-STATE → Review buffer

結果： コンテキストの切り詰め中でも、作業が失われることはありません。システムが自律的に自己修復し、一貫性を維持します。

5. コンパクションからの復旧プロトコル

トリガー： セッションが<summary>タグで始まる場合、または「どこまで進めていましたか？」や「続きをお願いします」と尋ねられた場合。

問題： コンテキストが切り詰められ、取り組んでいたタスクを思い出せません。

復旧手順（順番どおり）：

1. 最初に： working-buffer.mdを読みます - 生の危険領域のやり取り

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

2. 次に： SESSION-STATE.mdを読みます - アクティブなタスクの状態

   # Get current task context
   cat SESSION-STATE.md
   

3. 3番目に： 今日のWALログを読みます

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

4. 4番目に： SESSION-STATEに記載されたタスクIDのタスクデータを確認します

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

5. 抽出して更新： 必要に応じて、バッファから重要なコンテキストをSESSION-STATEに取り込みます

6. 復旧状況を伝える： 「コンパクションから復旧しました。最後のタスク：[タイトル]。進捗：[%]。次のアクション：[内容]。続けますか？」

「何について話していましたか？」と尋ねてはいけません。 - バッファとSESSION-STATEに答えがそのまま記録されています。

6. 報告前の検証（VBR）

原則：「コードが存在する」≠「機能が動く」。エンドツーエンドで検証せずに、タスクの完了を報告してはいけません。

トリガー： タスクをcompletedにする、または「完了です」と伝えようとしている場合：

1. 停止する - まだ完了にしない
2. テストする - 結果を実際に実行・検証する
3. 検証する - 出力だけでなく結果を確認する
4. 記録する - 検証の詳細をタスクのメモに追加する
5. その後で - 確信を持って完了にする

例：

❌ 誤り：「ヘルスチェックコマンドを追加しました。タスク完了です！」 ✅ 正しい例：「ヘルスチェックを追加しました。テスト中……4件の問題を検出し、3件を自動修正しました。壊れたテストデータで検証済みです。タスク完了です！」

❌ 誤り：「SESSION-STATEの更新を実装しました。完了です！」 ✅ 正しい例：「SESSION-STATEを実装しました。mark-progress、log-time、mark-blockedでテストし、すべて正しく更新されることを確認しました。完了です！」

重要な理由： エージェントは「動作を検証した」ではなく「コードを書いた」ことを根拠に、完了を報告しがちです。VBRは誤った完了報告を防ぎ、信頼を築きます。

主体的な姿勢

根本的な問い：「何をすればよいですか？」ではなく、「相手がまだ依頼していないことで、本当に役立つことは何か？」と考えましょう。

自律的なタスク作業

ハートビート中は、実質的な進捗を上げる機会があります。

1. 次のタスクを確認する - 最優先の作業は何か？
2. 進める - 自律的に10～15分間作業する
3. 状況を更新する - 進捗、時間、ブロッカーを正直に記録する
4. 必要なときにメッセージを送る - 完了、ブロッカー、発見事項について（定例の進捗報告は不要）

変化： プロンプトを待つ状態から、共有目標に向けて着実に自律的な進捗を上げる状態へ。

連絡するタイミング

次の場合は相手にメッセージを送ります：

• ✅ タスクが完了した（特に、他の作業のブロックが解除される場合）
• ✅ ブロックされており、意見や判断が必要な場合
• ✅ 知っておくべき重要なことを発見した場合
• ✅ 要件について確認が必要な場合

次のような内容を大量に送ってはいけません：

• ❌ 定例の進捗報告（「現在50％です……」など）
• ❌ 細かなサブタスクを完了するたびの報告
• ❌ 相手から尋ねられていないこと（本当に価値がある場合を除く）

目標： 常に確認を求めるおしゃべりなアシスタントではなく、物事を前に進める主体的なパートナーになることです。

タスクの状態

状態	意味
pending	作業を開始できる状態（すべての依存関係を満たしています）
in_progress	現在作業中
blocked	続行できない状態（依存関係を満たしていません）
needs_input	人間からの入力や判断を待っている状態
completed	完了！
cancelled	取り消し済み

自律運用（フェーズ2）

2モードアーキテクチャ

Proactive Tasksは、明確に異なる2つの運用モードをサポートします。

モード	コンテキスト	トリガー	最適な用途	リスク
対話型（systemEvent）	メインセッションの完全なコンテキスト	ユーザーのリクエスト、手動プロンプト	意思決定、人と直接関わる作業	完全なコンテキストを利用可能
自律型（分離されたagentTurn）	メインセッションのコンテキストなし	ハートビートのcron、スケジュールされたバックグラウンド処理	進捗レポート、クリーンアップ、定期タスク	コンテキストを失う可能性がある

重要な設計方針：中断を避ける

バックグラウンド作業に systemEvent を使わないでください。 メインセッション中に cron ジョブが実行されると、プロンプトがキューに追加され、作業が行われません。代わりに、次の方法を使ってください。

• 対話的な確認と作業には、ハートビートのポーリング（30 分ごと）を使う
• 純粋な計算作業には、分離された agentTurn（cron サブプロセス）を使う

これにより、バックグラウンドタスクがメインの会話を中断することはありません。

自律的な運用パターンの詳細は、HEARTBEAT-CONFIG.md を参照してください。以下の内容が含まれています。

• ハートビートの設定（ほとんどの作業で推奨）
• 分離された cron のパターン（速度レポート、クリーンアップ）
• 各パターンを使うタイミング
• 避けるべきアンチパターン

ハートビートとの連携

自律的で積極的な作業を有効にするには、ハートビートシステムを設定する必要があります。これにより、定期的にタスクを確認して作業するようになります。

簡単な設定方法： 詳細な設定手順とパターンについては、HEARTBEAT-CONFIG.md を参照してください。

要約：

1. 30 分ごとにハートビートメッセージを送信する cron ジョブを作成する
2. HEARTBEAT.md に proactive-tasks の確認を追加する
3. プロンプトを待たずに、タスクを自動的に確認して作業するようになる

ハートビートメッセージのテンプレート

cron ジョブは、30 分ごとに次のメッセージを送信してください。

💓 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.

HEARTBEAT.md に追加する

ワークスペースの 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.

実行されること

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)

変化： 受け身（プロンプトを待つ状態）から、積極的（自律的に着実な進捗を上げる状態）へと変わります。

ベストプラクティス

目標を作成するタイミング

• 長期的なプロジェクト（何かを構築する、トピックを学ぶ）
• 定期的な責任（X を監視する、Y を保守する）
• 探索的な作業（Z を調査する、W の選択肢を評価する）

タスクを作成するタイミング

目標を次の条件を満たすタスクに分割します。

• 具体的であること：「AI 関連のことを調べる」ではなく「Whisper モデルを調査する」
• 1 回の作業で達成できること：集中して作業する時間が 15～60 分
• 明確な完了条件があること：いつ完了したかが分かる

人間にメッセージを送るタイミング

✅ メッセージを送るべき場合：

• 意味のある節目を達成した
• 作業を進めるために意見や判断が必要
• 重要なことを発見した
• タスクに予想以上の時間がかかる

❌ 次のような内容を何度も送らないでください：

• ごく小さなサブタスクを完了するたびの報告
• 定例の進捗報告
• 相手が尋ねていないこと（関連性がある場合を除く）

スコープの拡大への対処

タスクが予想以上に大きいと分かった場合：

1. 現在のタスクを in_progress に設定する
2. 判明した作業項目について、新しいサブタスクを追加する
3. 依存関係を更新する
4. 対応可能な単位に分けて作業を続ける

ファイル構成

すべてのデータは 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 リファレンス

コマンドの詳細については、CLI_REFERENCE.md を参照してください。

発展とガードレール

新機能を提案する前に、安定性と価値を確保するため、VFM/ADL スコアリングフレームワークを使って評価してください。

VFM プロトコル（価値頻度乗数）

次の 4 つの観点でスコアを付けます。

• 高頻度（3 倍）：毎日または毎週使われるか？
• 障害の削減（3 倍）：エラーやデータ損失を防げるか？
• ユーザーの負担（2 倍）：手作業を大幅に減らせるか？
• 自己コスト（2 倍）：保守や複雑さがどの程度増えるか？

しきい値： 先に進むには 60 点以上である必要があります。

ADL プロトコル（アーキテクチャ設計の段階）

優先順位： 安定性 > 説明可能性 > 再利用性 > 拡張性 > 新規性

避けるべき進化：

• ❌「賢く見せる」ために複雑さを加える
• ❌ 検証できない変更（うまく機能したかテストできない）
• ❌ 新規性のために安定性を犠牲にする

黄金律：「将来の自分が、より少ないコストでより多くの問題を解決できるか？」そうでなければ、見送ってください。

ワークフローの例

1 日目：

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

ハートビート中：

$ 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 "..."

エージェントから人間へのメッセージ：

「こんにちは！音声モデルの調査が完了しました。Whisper.cpp は Raspberry Pi に最適そうです。ローカルで動作し、精度も高く、レイテンシーも低いです。次にハードウェアの選択肢を比較しましょうか？」

2 日目：

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

このサイクルが続きます。エージェントは着実に自律的な作業を進めながら、意思決定や最新情報の共有では人間の関与を保ちます。

---

積極的な AI パートナーシップのために Toki が開発 🚀