Agent プロトコル

概要

このドキュメントは、外部 Agent（AI CLI ツール、カスタムスクリプト等）が Mutsumi の mutsumi.json を読み書きする方法を定義します。

後方互換性: Mutsumi はフォールバックとして tasks.json も受け付けます。ただし、mutsumi.json が今後の正式なファイル名です。

核心原則: Mutsumi は特定の Agent に縛られません。JSON を正しく読み書きできるあらゆるプログラムが正当な Controller です。

Agent Skills（推奨）

Mutsumi は Agent Skills オープン標準 に準拠した 5 つのバンドルスキルを同梱しています。インストール後、Agent が自動的にスキルを検出するため、手動でプロンプトをペーストする必要はありません。

インストール

mutsumi setup --agent claude-code   # または codex-cli、gemini-cli、opencode

これで ~/.mutsumi/skills/（SSOT）から Agent のスキルディレクトリにシンボリックリンクが作成されます。

スキル一覧

スキル	説明	トリガー
mutsumi-manage	タスク CRUD — CLI または直接 JSON 操作で追加・編集・完了・削除	ユーザーがタスク管理を依頼した時
mutsumi-track	作業中にタスク進捗を自動更新	自動トリガー（user-invocable: false）
mutsumi-plan	複雑な目標を parent + サブタスクに分解	ユーザーが計画や分解を依頼した時
mutsumi-report	スコープ別のステータスサマリーを生成	ユーザーがレポートを依頼した時（disable-model-invocation: true）
mutsumi-context	セッション開始時にタスクボードの状態を読み込み、優先順位を把握	自動トリガー（user-invocable: false）

SKILL.md の構造

各スキルは SKILL.md ファイルを含むディレクトリです：

mutsumi-manage/
  SKILL.md          ← YAML frontmatter + Markdown 指示

frontmatter は agentskills.io 仕様 に準拠：

---
name: mutsumi-manage
description: >
  Add, edit, complete, or remove tasks in mutsumi.json.
---

主要な frontmatter フィールド：

• name — 小文字 + ハイフン、最大 64 文字
• description — Agent がこのスキルを有効化すべきタイミング
• user-invocable: false — Agent が自動トリガー、ユーザーは直接呼び出し不可
• disable-model-invocation: true — ユーザーが明示的に依頼した時のみ有効化

アーキテクチャ

pip パッケージに同梱              SSOT（単一コピー）            Agent スキルディレクトリ
mutsumi/skills/              →    ~/.mutsumi/skills/      →    ~/.claude/skills/
  mutsumi-manage/                   mutsumi-manage/              mutsumi-manage/ (symlink)
  mutsumi-track/                    mutsumi-track/               mutsumi-track/  (symlink)
  mutsumi-plan/                     mutsumi-plan/                ...
  mutsumi-report/                   mutsumi-report/
  mutsumi-context/                  mutsumi-context/
  references/                       references/

ステップ 1: ensure_ssot() がバンドルスキルを ~/.mutsumi/skills/ にコピー。 ステップ 2: install_for_agent() が SSOT から Agent ディレクトリにシンボリックリンクを作成。

この SSOT アーキテクチャにより、すべての Agent が同一のスキル定義を共有します。Mutsumi のアップグレード（pip install --upgrade）後、次回 mutsumi setup を実行すると SSOT が自動的に更新されます。

ヒント

Skills は推奨される統合方法です。下記の手動プロンプトテンプレートは、Agent Skills 標準をサポートしないツール向けのフォールバックです。

書き込みプロトコル（Agent → Mutsumi）

ワークフロー

1. 現在の mutsumi.json を読み取り（全内容）
2. JSON としてパース
3. tasks 配列を変更（追加/更新/削除）
4. ファイル全体を書き戻し（部分書き込み禁止）
5. Mutsumi の watchdog が変更を検知 → TUI を再描画

ルール

ルール	説明
未知フィールドの保持	認識しないフィールドを削除しない。そのまま保持する
アトミック書き込み	推奨: 一時ファイルに書いてから os.replace() でリネーム。Mutsumi が半分書かれた状態を読むのを防ぐ
有効な JSON	書き込み後のファイルは有効な JSON でなければならない
有効な ID の生成	新しいタスクの ID には UUIDv7 を使用。最低限、一意性を保証すること
必須フィールド	すべてのタスクに id, title, status が必要
列挙型の遵守	status は "pending" / "done" のみ

タスクの追加（Python 例）

import json, uuid, datetime, tempfile, os

# 読み取り
with open("mutsumi.json") as f:
    data = json.load(f)

# 追加
new_task = {
    "id": str(uuid.uuid7()),
    "title": "ログインバグを修正",
    "status": "pending",
    "scope": "day",
    "priority": "high",
    "tags": ["bugfix"],
    "created_at": datetime.datetime.now(datetime.UTC).isoformat(),
    "children": []
}
data["tasks"].append(new_task)

# アトミック書き込み
tmp = tempfile.NamedTemporaryFile(
    mode='w', dir='.', suffix='.tmp', delete=False
)
json.dump(data, tmp, ensure_ascii=False, indent=2)
tmp.close()
os.replace(tmp.name, "mutsumi.json")

タスクの完了

for task in data["tasks"]:
    if task["id"] == target_id:
        task["status"] = "done"
        task["completed_at"] = datetime.datetime.now(datetime.UTC).isoformat()
        break

読み取りプロトコル（Mutsumi → Agent）

イベントログ

ユーザーが TUI で操作を行うと、Mutsumi はオプションで events.jsonl にイベントを追記します：

{"ts":"2026-03-21T10:00:00Z","event":"task_completed","task_id":"01JQ...","title":"キャッシュバグを修正","source":"tui"}
{"ts":"2026-03-21T10:01:22Z","event":"task_created","task_id":"01JQ...","title":"ユニットテストを書く","source":"tui"}
{"ts":"2026-03-21T10:05:00Z","event":"task_deleted","task_id":"01JQ...","title":"古いタスク","source":"tui"}
{"ts":"2026-03-21T10:06:30Z","event":"task_updated","task_id":"01JQ...","changes":{"priority":"high→low"},"source":"tui"}

イベントタイプ

イベント	フィールド	説明
task_created	task_id, title	新しいタスクが作成された
task_completed	task_id, title	タスクが完了にマークされた
task_deleted	task_id, title	タスクが削除された
task_updated	task_id, changes (dict)	タスクのフィールドが変更された
schema_error	file, message	JSON バリデーションが失敗した

Agent による消費

# シェルでリアルタイム監視
tail -f events.jsonl | jq .

# Agent プロンプトでの参照
"タスクに関する最近のユーザー操作を events.jsonl で確認してください"

スキーマディスカバリ

Agent は CLI を使って現在の JSON Schema を取得できます：

mutsumi schema
# JSON Schema を stdout に出力

mutsumi schema --format markdown
# Markdown 形式でフィールド説明を出力

エラーハンドリング

Agent が不正なデータを書いた場合

Agent が無効な JSON を書き込む
       │
       v
Mutsumi の watchdog が変更を検知
       │
       v
パース失敗 → TUI にエラーバナー表示
       │       "mutsumi.json にエラーがあります。最後の有効な状態を表示中"
       │
       v
エラーを stderr + error.log に記録
       │
       v
イベント発行: {"event":"schema_error","file":"mutsumi.json","message":"..."}
       │
       v
Agent が error.log または events.jsonl を読んで自己修正可能

自己修復プロンプト

Agent のプロンプトに以下を含めることを推奨：

mutsumi.json に書き込んだ後、~/.local/share/mutsumi/error.log を確認してください。
スキーマバリデーションエラーがあれば、修正して再書き込みしてください。

マルチ Agent 協調

複数の Agent が同じ mutsumi.json を同時に操作する場合：

推奨事項

1. 書き込み前に読み込む — 常に最新バージョンを読んでから書く
2. 書き込みスコープの最小化 — 自分のタスクだけを変更。他のタスクの順序は変えない
3. 冪等操作 — 完了マークなどの操作は冪等であるべき（繰り返してもエラーにならない）
4. 一意な ID を使用 — UUIDv7 で異なる Agent の ID が衝突しないことを保証

コンフリクト解決

Mutsumi はロック機構を提供しません。コンフリクト戦略: Last Write Wins。

ノート

実際には、Agent の書き込みは離散的（通常は数秒〜数分間隔）であるため、コンフリクトの確率は極めて低いです。