@minimalcorp/tsunagi 0.3.3 → 0.4.2

package/dist/server/routes/onboarding.js

@@ -1,24 +1,33 @@
 import { isLocalLlmReady } from '../lib/local-llm.js';
-import { DEFAULT_CLAUDE_PROFILE, getClaudeAuthStatus, listClaudeProfiles, } from '../lib/claude-profiles.js';
-/** システム既定かいずれかの Claude プロファイルがログイン済みか */
-async function isClaudeLoggedIn() {
-    if ((await getClaudeAuthStatus(DEFAULT_CLAUDE_PROFILE)).loggedIn)
+import { AGENTS, getAgentAvailability } from '../lib/agents/index.js';
+import { DEFAULT_PROFILE, getProfileAuthStatus, listProfiles } from '../lib/agent-profiles.js';
+/** 導入済みのエージェントで、システム既定かいずれかのプロファイルがログイン済みか */
+async function isAgentLoggedIn(agent) {
+    if (!(await getAgentAvailability(agent)).installed)
+        return false;
+    if ((await getProfileAuthStatus(agent, DEFAULT_PROFILE)).loggedIn)
         return true;
-    const profiles = await listClaudeProfiles();
-    const statuses = await Promise.all(profiles.map((p) => getClaudeAuthStatus(p.slug)));
+    const profiles = await listProfiles(agent);
+    const statuses = await Promise.all(profiles.map((p) => getProfileAuthStatus(agent, p.slug)));
     return statuses.some((status) => status.loggedIn);
 }
 export async function onboardingRoutes(fastify) {
     // GET /onboarding/status
     fastify.get('/onboarding/status', async (_request, reply) => {
         try {
-            const [claudeLoggedIn, localLlmReady] = await Promise.all([
-                isClaudeLoggedIn(),
-                // 実験的機能のローカルLLM（Ollama / LM Studio）を設定済みなら、Claude にログインしていなくても claude を起動できる
+            const [loggedIn, localLlmReady] = await Promise.all([
+                Promise.all(AGENTS.map(async (agent) => [agent.id, await isAgentLoggedIn(agent)])),
+                // 実験的機能のローカルLLM（Ollama / LM Studio）を設定済みなら、ログインしていなくても claude を起動できる
                 isLocalLlmReady(),
             ]);
+            const agentLoggedIn = Object.fromEntries(loggedIn);
+            const anyLoggedIn = loggedIn.some(([, value]) => value);
             return reply.status(200).send({
-                data: { completed: claudeLoggedIn || localLlmReady, claudeLoggedIn, localLlmReady },
+                data: {
+                    completed: anyLoggedIn || localLlmReady,
+                    agentLoggedIn,
+                    localLlmReady,
+                },
             });
         }
         catch (error) {

package/dist/server/routes/tasks.js

@@ -265,8 +265,8 @@ export async function tasksRoutes(fastify) {
             if (!(await worktreeManager.worktreeExists(task.owner, task.repo, task.branch))) {
                 return reply.status(400).send({ error: 'Worktree not found' });
             }
-            const isClaudeRunning = task.tabs.some((tab) => tab.status === 'running');
-            if (isClaudeRunning) {
+            const isAgentRunning = task.tabs.some((tab) => tab.status === 'running');
+            if (isAgentRunning) {
                 return reply.status(400).send({ error: 'Cannot rebase while Claude is running' });
             }
             const result = await worktreeManager.rebaseWorktree(task.owner, task.repo, task.branch, baseBranch);
@@ -335,8 +335,8 @@ export async function tasksRoutes(fastify) {
         try {
             const { id: taskId } = request.params;
             const requested = request.body?.mode;
-            const mode = requested === 'terminal'
-                ? 'terminal'
+            const mode = requested === 'terminal' || requested === 'codex'
+                ? requested
                 : requested === 'local' || requested === 'ollama' || requested === 'lmstudio'
                     ? 'local'
                     : 'claude';

package/dist/server/routes/terminal.js

@@ -1,8 +1,8 @@
-import { ptyManager } from '../pty-manager.js';
+import { isShellForeground, ptyManager } from '../pty-manager.js';
 import { prisma } from '../lib/db.js';
-import { ensureActiveLoaded } from '../lib/local-llm.js';
-import { buildClaudeCommand, isLocalLlmMode } from '../lib/claude-command.js';
-import { PtyLaunchError, prepareClaudeConfigForSession, resolvePtyLaunch, startPtySession, } from '../lib/pty-launch.js';
+import { getAgentForMode } from '../lib/agents/index.js';
+import { LOGIN_SESSION_PREFIX } from '../lib/agent-profiles.js';
+import { PtyLaunchError, prepareAgentLaunchForSession, resolvePtyLaunch, startPtySession, } from '../lib/pty-launch.js';
 import { getEnvPending, initPtyEnvSync, respawnSessionNow } from '../lib/pty-env-sync.js';
 /**
  * 再接続時の画面復元用 scrollback から「端末への問い合わせ（クエリ）」シーケンスを除去する。
@@ -145,7 +145,7 @@ export async function terminalRoutes(fastify) {
                 if (session.respawning)
                     return;
                 io.to(room).emit('exit', { exitCode });
-                // Ctrl+C等でClaudeが強制終了した場合にclaudeStatusをidleにリセット
+                // Ctrl+C等でClaudeが強制終了した場合にagentStatusをidleにリセット
                 // todos は残す（Claude 側の Task はセッションに永続化され、--resume 後も続きから使われる）
                 io.to(room).emit('status-changed', { sessionId, status: 'idle' });
                 prisma.tab
@@ -250,7 +250,7 @@ export async function terminalRoutes(fastify) {
     });
     // POST /terminal/sessions - セッション作成（または既存セッション再利用）
     fastify.post('/terminal/sessions', async (request, reply) => {
-        const { cwd, env, sessionId: requestedSessionId, claude, command } = request.body ?? {};
+        const { cwd, env, sessionId: requestedSessionId, agent, claude, command } = request.body ?? {};
         const sessionId = requestedSessionId ?? crypto.randomUUID();
         // 既存セッションが生きていれば再利用
         const existing = ptyManager.getSession(sessionId);
@@ -258,6 +258,10 @@ export async function terminalRoutes(fastify) {
             fastify.log.info({ sessionId }, 'Reusing existing PTY session');
             return reply.status(200).send({ sessionId, reused: true });
         }
+        // ログイン用 PTY は作り直さない（無ければ終わっている。ログインコマンドの無いシェルを出さない）
+        if (sessionId.startsWith(LOGIN_SESSION_PREFIX)) {
+            return reply.status(404).send({ error: 'Login session has ended. Close and try again.' });
+        }
         const pending = pendingCreations.get(sessionId);
         const creation = pending ??
             (async () => {
@@ -265,7 +269,7 @@ export async function terminalRoutes(fastify) {
                 const launch = await resolvePtyLaunch(sessionId, launchRequest);
                 await startPtySession(sessionId, launch, {
                     request: launchRequest,
-                    launchClaude: Boolean(claude),
+                    launchAgent: Boolean(agent ?? claude),
                     command,
                 });
             })();
@@ -290,33 +294,42 @@ export async function terminalRoutes(fastify) {
             return reply.status(500).send({ error: message });
         }
     });
-    // POST /terminal/sessions/:sessionId/claude - 既存 PTY で claude を（再）起動する
-    // コマンドはタブの mode に応じてサーバーで組み立てる（ローカルLLMタブは引数が付くため）
-    fastify.post('/terminal/sessions/:sessionId/claude', async (request, reply) => {
-        const { sessionId } = request.params;
-        const session = ptyManager.getSession(sessionId);
-        if (!session) {
-            return reply.status(404).send({ error: 'Session not found' });
-        }
-        const tab = await prisma.tab.findUnique({ where: { tabId: sessionId } }).catch(() => null);
-        const mode = (tab?.mode ?? 'claude');
-        if (isLocalLlmMode(mode)) {
-            // 最初の発言を待たせないよう読み込みを始めておく（未設定等のエラーは中継口がタブに返す）
-            ensureActiveLoaded().catch(() => undefined);
-        }
-        let command;
-        try {
-            command = await buildClaudeCommand(sessionId, mode);
-        }
-        catch (err) {
-            return reply.status(400).send({ error: err instanceof Error ? err.message : String(err) });
-        }
-        // 環境変数の反映で PTY を作り直したときも claude を起動し直す
-        session.options.launchClaude = true;
-        await prepareClaudeConfigForSession(session);
-        session.pty.write(`${command}\n`);
-        return reply.status(204).send();
-    });
+    // POST /terminal/sessions/:sessionId/agent - 既存 PTY でエージェントを（再）起動する
+    // コマンドはタブの mode に応じてサーバーで組み立てる（ローカルLLMタブは引数が付くため）。
+    // /claude は旧パス（互換のため残す）
+    for (const route of [
+        '/terminal/sessions/:sessionId/agent',
+        '/terminal/sessions/:sessionId/claude',
+    ]) {
+        fastify.post(route, async (request, reply) => {
+            const { sessionId } = request.params;
+            const session = ptyManager.getSession(sessionId);
+            if (!session) {
+                return reply.status(404).send({ error: 'Session not found' });
+            }
+            // エージェントなどが動いている間に書き込むと、そのコマンドの入力欄に入ってしまう
+            if (!isShellForeground(session)) {
+                return reply.status(409).send({
+                    error: 'ターミナルで実行中のコマンド（エージェント等）を終了してから実行してください',
+                });
+            }
+            const tab = await prisma.tab.findUnique({ where: { tabId: sessionId } }).catch(() => null);
+            const mode = (tab?.mode ?? 'claude');
+            const agent = getAgentForMode(mode);
+            let command;
+            try {
+                command = await agent.buildCommand(sessionId, mode);
+            }
+            catch (err) {
+                return reply.status(400).send({ error: err instanceof Error ? err.message : String(err) });
+            }
+            // 環境変数の反映で PTY を作り直したときもエージェントを起動し直す
+            session.options.launchAgent = true;
+            await prepareAgentLaunchForSession(session, mode);
+            session.pty.write(`${command}\n`);
+            return reply.status(204).send();
+        });
+    }
     // POST /terminal/sessions/:sessionId/respawn - 環境変数の変更を今すぐ反映する（PTY を作り直す）
     fastify.post('/terminal/sessions/:sessionId/respawn', async (request, reply) => {
         const ok = await respawnSessionNow(request.params.sessionId);

package/dist/with-plugin.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process';
-import { assertClaudeSupportsPluginDirs, getPluginDir, removeLegacyPluginInstall, } from './plugin-lifecycle.js';
+import { assertAgentCliAvailable, getPluginDir, removeLegacyPluginInstall, } from './plugin-lifecycle.js';
 /**
  * Development wrapper:
  *   1. Pass the Claude Code plugin dir to the server via TSUNAGI_PLUGIN_DIR
@@ -15,8 +15,8 @@ if (mode !== 'dev' && mode !== 'start') {
     console.error('Usage: tsx src/with-plugin.ts <dev|start>');
     process.exit(1);
 }
-assertClaudeSupportsPluginDirs();
-removeLegacyPluginInstall();
+if (assertAgentCliAvailable().claude)
+    removeLegacyPluginInstall();
 // 子プロセス（concurrently → server）に継承させる
 process.env.TSUNAGI_PLUGIN_DIR = getPluginDir();
 const webCmd = mode === 'dev'

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@minimalcorp/tsunagi",
-  "version": "0.3.3",
+  "version": "0.4.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@minimalcorp/tsunagi",
-      "version": "0.3.3",
+      "version": "0.4.2",
       "license": "SEE LICENSE IN LICENSE",
       "os": [
         "darwin",
@@ -235,9 +235,9 @@
       }
     },
     "node_modules/@fastify/multipart": {
-      "version": "10.1.2",
-      "resolved": "https://registry.npmjs.org/@fastify/multipart/-/multipart-10.1.2.tgz",
-      "integrity": "sha512-WHsqW5ffDXCbXXtdBQDryxu58fQvFPVGh4E4MlCO6hwCLNm0lYTCS6GKXUw2P64REDoECUNpMVvtMMstdIyBjQ==",
+      "version": "10.1.3",
+      "resolved": "https://registry.npmjs.org/@fastify/multipart/-/multipart-10.1.3.tgz",
+      "integrity": "sha512-nLZopLYgAj+0BhcSm6upfT5x4fwKDfGlJ51U4Bkg1HknFaO6LjfCc2prqbXMNjRdM0cCVzp3L4bjkvfuuTLxJg==",
       "funding": [
         {
           "type": "github",
@@ -278,9 +278,9 @@
       }
     },
     "node_modules/@fastify/reply-from": {
-      "version": "12.6.5",
-      "resolved": "https://registry.npmjs.org/@fastify/reply-from/-/reply-from-12.6.5.tgz",
-      "integrity": "sha512-/4MP+iF6T2+UBEmVYveMU2Tbx3lR1Q7xsDo8GAGjNeQrLF/JqNRlOMhOksh8fXBA47KI8ifsIlUXYdMOUXGZNQ==",
+      "version": "12.7.1",
+      "resolved": "https://registry.npmjs.org/@fastify/reply-from/-/reply-from-12.7.1.tgz",
+      "integrity": "sha512-F26CIcy6PKqyhsTwQI7p5UwH5vrv2yz7BOqAnkHTmNVSU9J+vmRh8CNfOk/ZD8AjcKbiyRkNl6Lb3AuJdxIADQ==",
       "funding": [
         {
           "type": "github",
@@ -295,7 +295,7 @@
       "dependencies": {
         "@fastify/error": "^4.0.0",
         "end-of-stream": "^1.4.4",
-        "fast-content-type-parse": "^3.0.0",
+        "fast-content-type-parse": "^4.0.0",
         "fast-querystring": "^1.1.2",
         "fastify-plugin": "^6.0.0",
         "toad-cache": "^3.7.0",
@@ -1608,9 +1608,9 @@
       "license": "MIT"
     },
     "node_modules/content-disposition": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/content-disposition/-/content-disposition-1.1.0.tgz",
-      "integrity": "sha512-5jRCH9Z/+DRP7rkvY83B+yGIGX96OYdJmzngqnw2SBSxqCFPd0w2km3s5iawpGX8krnwSGmF0FW5Nhr0Hfai3g==",
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/content-disposition/-/content-disposition-2.0.1.tgz",
+      "integrity": "sha512-e+H0ZXHSWYrENhQzw1LPuP4oF5MzVKmDU6d3hxlvaPEYLLg62MxtQNPRx4SYSuYJSBUgnQIG4HIN2tEtNv7Dog==",
       "license": "MIT",
       "engines": {
         "node": ">=18"
@@ -2190,15 +2190,15 @@
       }
     },
     "node_modules/express": {
-      "version": "5.2.1",
-      "resolved": "https://registry.npmjs.org/express/-/express-5.2.1.tgz",
-      "integrity": "sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==",
+      "version": "5.3.0",
+      "resolved": "https://registry.npmjs.org/express/-/express-5.3.0.tgz",
+      "integrity": "sha512-qCqy1xSoaugxOD4IVHb1ZWdkvCF2W3aE2okKouWj8VwJ+ztskSiXoBnCSJqfKT+cVPJhuJqe9YLbY425+Zh00g==",
       "license": "MIT",
       "dependencies": {
         "accepts": "^2.0.0",
-        "body-parser": "^2.2.1",
-        "content-disposition": "^1.0.0",
-        "content-type": "^1.0.5",
+        "body-parser": "^2.3.0",
+        "content-disposition": "^2.0.1",
+        "content-type": "^2.0.0",
         "cookie": "^0.7.1",
         "cookie-signature": "^1.2.1",
         "debug": "^4.4.0",
@@ -2214,14 +2214,14 @@
         "on-finished": "^2.4.1",
         "once": "^1.4.0",
         "parseurl": "^1.3.3",
-        "proxy-addr": "^2.0.7",
-        "qs": "^6.14.0",
+        "proxy-addr": "^2.0.8",
+        "qs": "^6.16.0",
         "range-parser": "^1.2.1",
         "router": "^2.2.0",
         "send": "^1.1.0",
         "serve-static": "^2.2.0",
         "statuses": "^2.0.1",
-        "type-is": "^2.0.1",
+        "type-is": "^2.1.0",
         "vary": "^1.1.2"
       },
       "engines": {
@@ -2251,6 +2251,19 @@
         "express": ">= 4.11"
       }
     },
+    "node_modules/express/node_modules/content-type": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/content-type/-/content-type-2.1.0.tgz",
+      "integrity": "sha512-mj7UPXE0jaqaOsukNZRUEfEi2AcL7C/vwmwcHV0O97eO1E1pxBZuyjlZrx5seTaNBg1U6+o35wpa35Qfcc+7ag==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
+      }
+    },
     "node_modules/exsolve": {
       "version": "1.1.3",
       "resolved": "https://registry.npmjs.org/exsolve/-/exsolve-1.1.3.tgz",
@@ -2280,9 +2293,9 @@
       }
     },
     "node_modules/fast-content-type-parse": {
-      "version": "3.0.0",
-      "resolved": "https://registry.npmjs.org/fast-content-type-parse/-/fast-content-type-parse-3.0.0.tgz",
-      "integrity": "sha512-ZvLdcY8P+N8mGQJahJV5G4U88CSvT1rP8ApL6uETe88MBXrBHAkZlSEySdUlyztF7ccb+Znos3TFqaepHxdhBg==",
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/fast-content-type-parse/-/fast-content-type-parse-4.0.0.tgz",
+      "integrity": "sha512-rvu3AY9s3EsDXSDUWzFU5M9/fDpjAUwyIkDR9VrwZA3H9J5f4ymkT0J4iWw9iLaMvFVwsYTGFClUgy9VIvnabA==",
       "funding": [
         {
           "type": "github",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minimalcorp/tsunagi",
-  "version": "0.3.3",
+  "version": "0.4.2",
   "description": "Multi-repo GitHub project management with Claude AI integration, designed for visualizing and controlling AI-driven development locally.",
   "keywords": [
     "tsunagi",

package/tsunagi-marketplace/codex/tsunagi-task.md

@@ -0,0 +1,120 @@
+# tsunagi タスク管理
+
+このセッションは tsunagi（タスク管理ツール）のタスクに紐づいている。タスクの検索・詳細取得・作成・更新・削除、現在担当タスクの特定、実装計画の description への記録には tsunagi MCP の `tsunagi_*` ツールを使う。計画の対話を開始した時、実装を開始した時、実装・検証が完了した時、PR がマージされた時に、必ずこの手順でステータスを更新すること。
+
+## ステータスの自動更新（必須）
+
+作業フェーズが変わったら、**即座に** `tsunagi_update_task` でステータスを更新する。
+
+| ステータス  | 遷移タイミング                                 |
+| ----------- | ---------------------------------------------- |
+| `backlog`   | タスク作成時のデフォルト                       |
+| `planning`  | ユーザーと計画の対話を開始した時点             |
+| `coding`    | ユーザーが実装を指示、または実装を開始した時点 |
+| `reviewing` | 全ての実装・検証が完了した時点                 |
+| `done`      | PRがマージされた時点                           |
+
+遷移は必ず順方向: backlog → planning → coding → reviewing → done
+
+## 実装開始時の計画作成（必須）
+
+`coding` に遷移したら、**即座に** 組み込みの `update_plan` ツールで実装ステップを登録する。これにより tsunagi UI にプログレスバーが表示される。
+
+### 手順
+
+1. `tsunagi_update_task(status: "coding")` の直後に、`update_plan` で全ステップを登録する（各ステップの `status` は `pending`）
+2. 各ステップは完了判断が明確な作業単位にする
+   - 例: 「○○ファイルを修正」「マイグレーション作成・適用」「lint/type-check を通す」「動作確認」
+3. 着手時・完了時に `update_plan` で該当ステップの status を `in_progress` → `completed` に更新する（`update_plan` は毎回計画全体を渡す）
+4. 作業中に追加ステップが判明した場合は計画に追加し、不要になったステップは計画から外す
+
+### 語彙の使い分け（混同注意）
+
+| 対象           | 使うツール               | status 語彙                            |
+| -------------- | ------------------------ | -------------------------------------- |
+| tsunagi タスク | `tsunagi_update_task`    | backlog/planning/coding/reviewing/done |
+| 計画 (進捗)    | `update_plan` (組み込み) | pending/in_progress/completed          |
+
+tsunagi タスクの status に `in_progress` を渡してはいけない（「よくある間違い」表参照）。逆に計画の進捗管理は組み込み `update_plan` で行う。
+
+## 現在のタスクを特定する
+
+タスク操作には `id`, `session_id`, `cwd` のいずれかでタスクを指定する。
+優先順位: id > session_id > cwd
+
+- **推奨**: 環境変数 `TSUNAGI_SESSION_ID`（シェルで `echo $TSUNAGI_SESSION_ID`）を `session_id` パラメータとして渡す
+- **フォールバック**: `TSUNAGI_SESSION_ID` が未設定の場合、CWDを `cwd` パラメータとして渡す
+
+## タスク操作
+
+| 操作     | ツール              | タスク指定              | その他パラメータ                                                             |
+| -------- | ------------------- | ----------------------- | ---------------------------------------------------------------------------- |
+| 一覧取得 | tsunagi_list_tasks  | 不要                    | owner?, repo?, status?(string \| string[])                                   |
+| 詳細取得 | tsunagi_get_task    | id or session_id or cwd | -                                                                            |
+| 作成     | tsunagi_create_task | 不要                    | owner, repo, title, branch?, description?, effort?, order?, status?          |
+| 更新     | tsunagi_update_task | id or session_id or cwd | title?, description?, status?, effort?, order?, baseBranch?, pullRequestUrl? |
+| 削除     | tsunagi_delete_task | id or session_id or cwd | -                                                                            |
+
+## タスク一覧取得のガイドライン
+
+`tsunagi_list_tasks` の `status` は単一値または配列で指定可能。ユースケースに応じて適切なステータスセットを指定すること。
+
+### 並び替え・棚卸しは `tsunagi-task-curator` subagent に委譲する
+
+ユーザーから以下のような依頼があった場合、**メインセッションで直接 `tsunagi_list_tasks` を呼ばず**、`spawn_agent` で `agent_type: "tsunagi-task-curator"` の subagent を起動すること:
+
+- 「優先度を並び替えて」「順序を見直して」「priorityを変更して」
+- 「棚卸しして」「backlogを整理して」「不要なタスクを削除して」「重複を確認して」
+
+重いdescription（PRD）読み込みはsubagent内に閉じ込められ、メインセッションには圧縮された判断結果（提案 + 根拠1行 + confidence）のみが返却される。
+
+subagentの返却を受けた後、メインセッションの役割:
+
+1. `confidence: "high"` の提案は **自動的に実行**（`tsunagi_update_task` で order 更新、`tsunagi_delete_task` で削除 等）
+2. `needs_user_input` に含まれる項目のみユーザーに確認
+3. 実行結果をユーザーに簡潔に報告
+
+### subagent を使わず直接 `tsunagi_list_tasks` を呼んでよいケース
+
+以下のような軽い参照用途では直接呼び出してよい:
+
+- 特定ステータスの件数確認（例: 現在 coding 中のタスクを確認）
+- 特定リポジトリのタスク一覧表示（`owner` + `repo` 指定）
+- ユーザーが明示的に全件リストを要求した場合
+
+これらのケースでも、必要なければ `status` を指定して対象を絞ること。
+
+## ブランチ命名規則
+
+`branch`を省略するとtitleから自動生成されるが、短縮された意味不明な名前になりがちなため、**必ず`branch`を明示的に指定する**。
+
+- タスク内容が一目でわかる具体的な名前にする
+- `feat/`、`fix/`等のprefixを使用する
+- 例: `feat/task-update-socket-notification`、`fix/duplicate-toast-on-create`
+
+## 実装計画の管理
+
+実装計画はタスクの `description` にPRD（Product Requirements Document）形式のmarkdownで記載・管理する。
+ファイルシステム上に計画ファイルを作成しない。
+`planning` 完了時点で `description` は完成していること。`coding` 中に計画変更があれば随時更新する。
+
+## よくある間違い
+
+| ❌ 誤り                                   | ✅ 正しい                                               | 備考                                        |
+| ----------------------------------------- | ------------------------------------------------------- | ------------------------------------------- |
+| `taskId: "..."`                           | `id: "..."`                                             | パラメータ名は `id`（camelCase ではない）   |
+| `sessionId: "..."`                        | `session_id: "..."`                                     | snake_case                                  |
+| `status: "in_progress"`                   | `status: "coding"`                                      | 組み込み update_plan とは別語彙             |
+| `status: "completed"`                     | `status: "done"`                                        |                                             |
+| `status: "todo"`                          | `status: "backlog"`                                     |                                             |
+| 識別子なしで update / get / delete を呼ぶ | `id` / `session_id` / `cwd` のいずれか1つ以上を必ず指定 | 全て省略すると `Identifier required` エラー |
+
+### ステータス語彙の混同に注意
+
+組み込みの `update_plan` ツール（`pending` / `in_progress` / `completed`）と、tsunagi の `tsunagi_update_task`（`backlog` / `planning` / `coding` / `reviewing` / `done`）は**完全に別物**。
+
+## 注意事項
+
+- `id`, `session_id`, `cwd` は優先順位に従い最初にマッチしたものでタスクを解決する
+- 削除は論理削除（UIから復元する手段は提供されていない）
+- `tsunagi_create_task` が失敗した場合、エラー内容をユーザーに報告するだけでよい（原因の深掘り不要）