Listspace

コーディングエージェント向け Listspace

エージェントが Listspace のボードをプロジェクトメモリとして使うための要素です。このフォルダーは github.com/listspace/agent で公開されており、CLI は npm の listspace で公開されています。次のコマンドでインストールしてサインインします。

npx listspace login     # paste a personal token from Listspace: Settings > Your AI > API tokens
npx listspace boards

パス	内容
skills/listspace/	スキルです。作業の流れを記した SKILL.md と、必要なときだけ読み込まれる reference/（ツール、エージェントアクセス、CLI）で構成されています。Agent Skills 形式に準拠しているため、npx skills add でインストールできます。これはソースコピーです。
cli/	MCP サーバーを使わないエージェント向けの小さな Node CLI、listspace です。REST API（https://api.listspace.app/v1）経由の短いコマンドと、MCP サーバー（https://mcp.listspace.app）経由ですべての MCP ツールを呼び出す call を提供します。TypeScript を単一の ESM ファイルにバンドルしており、実行時の依存関係はありません。Node 20 以降が必要です。
claude-code-plugin/	Claude Code プラグインです。スキル（コピーされたファイル一式）と、リモート MCP サーバー https://mcp.listspace.app を登録する .mcp.json が含まれています。
.claude-plugin/marketplace.json	プラグインを登録するマーケットプレイスファイルです。このフォルダーを今はローカルマーケットプレイスとして、後で GitHub マーケットプレイスとして追加できます。
AGENTS.md.snippet	エージェントに適切なボードを参照させるため、ユーザーがリポジトリの AGENTS.md または CLAUDE.md に貼り付ける行です。
scripts/	sync-skill.mjs はスキルをプラグインにコピーします。check-agent.mjs（CI で実行）はコピー、フロントマター、バージョン、MCP エントリーを確認します。

MCP サーバーは MCP Registry に app.listspace/listspace として、また Smithery にも登録されています。

スキルの編集

skills/listspace/ だけを編集し、その後次を実行します。

node agent/scripts/sync-skill.mjs
node agent/scripts/check-agent.mjs

プラグインにはシンボリックリンクではなく実際のコピーが配置されるため、プラグインフォルダーを単独でコピーまたはダウンロードしても動作します。2つの内容が異なると CI は失敗します。SKILL.md は短く保ち、手順とルールを記載してください。詳細は reference/ に記載します。

バージョンは cli/package.json、cli/src/version.ts、plugin.json、スキルの metadata.version で管理されています。これらが異なるとチェックに失敗します。

ローカルで試す

CLI

cd agent/cli
npm ci
npm run build
node dist/listspace.mjs login            # paste a token from Listspace: Settings > Your AI > API tokens
node dist/listspace.mjs whoami
node dist/listspace.mjs session "<board title or id>"
node dist/listspace.mjs add "<board>" ideas "Try dark mode" --description "Seen in **settings**"

agent/cli で npm link を実行すると、listspace が PATH に追加されます。LISTSPACE_TOKEN は1回の実行に限り保存済みトークンを上書きし、LISTSPACE_API_URL と LISTSPACE_MCP_URL は CLI の接続先サーバーを変更します。すべてのコマンドで --json を指定できます。トークンは OS の設定ディレクトリ（Windows では %APPDATA%\listspace、macOS では ~/Library/Application Support/listspace、その他では ~/.config/listspace）に credentials.json として、モード 600 で保存されます。

テスト：npm test（偽の fetch を使う node:test。ネットワーク接続は不要です）。npm run typecheck は厳格な型チェックを実行します。

スキル単体での利用

Agent Skills を読み込める任意のエージェントでは、次を実行します。

npx skills add ./agent -s listspace     # the skills CLI reads skills/ in a local folder

または、agent/skills/listspace を ~/.claude/skills/listspace にコピーして Claude Code で使用します。MCP サーバーには別途接続するか（claude mcp add --transport http listspace https://mcp.listspace.app）、上記の CLI を使用してください。

Claude Code プラグイン

1回のセッションで使用する場合：

claude --plugin-dir ./agent/claude-code-plugin

インストール状態を維持するローカルマーケットプレイスとして使用する場合：

claude plugin marketplace add ./agent
claude plugin install listspace@listspace

次に /mcp を実行し、listspace サーバーを選んでサインインします（Listspace 経由の OAuth）。スキルは /listspace:listspace として表示され、プロジェクトにボードがある場合、Claude が自動で読み込みます。claude plugin validate ./agent/claude-code-plugin でマニフェストを検証できます。

すでに Listspace MCP サーバーを自分で追加している場合、Claude Code に両方が表示されることがあります。その場合は、どちらか一方を削除してください。

意思決定チェック

このプラグインには、Claude の各ターンの終了時に実行される小さなチェックもあります（hooks/hooks.json、hooks/decision-check.mjs）。ユーザーが選択肢を選ぶ、提案に同意する、または事実を訂正したにもかかわらず、Claude がそのターンで意思決定を記録していない場合、Claude に一度だけ次の一文が送られます。今後の作業に影響する意思決定であれば、record_decision を使って Proposed として記録してください。それ以外の場合は、何もコメントせずにターンを終了してください。

ルールは、何もしない方向に傾いています。作業の申し出への同意（「コミットしましょうか？」「はい」）、迷っている回答、バグ報告やコード内の箇所についての指摘（「いいえ、まだ失敗しています」「バグはパーサーにあります」）は、意思決定ではありません。同意が意思決定としてカウントされるのは、Claude の直前のメッセージで選択肢を提示したか、提案をした場合のみです（推奨する、提案する、選択肢、どれにするか、アルファベット付きのリストなど）。

• Listspace ツールを一度も使っていないセッションでは何もせず、1 ターン内で二度ブロックすることもないため（stop_hook_active）、ループすることはありません。
• ユーザーの言葉に対する単純なルールであり、モデル呼び出しもネットワーク通信も行わないため、費用はかからず、数ミリ秒で応答します（タイムアウトは 5 秒です）。
• コンピューター（Windows、macOS、Linux）に Node.js 18 以降が必要です。各コマンドの末尾には ; exit 0 が付いているため、Node.js がない場合、チェックは何もせず、Claude Code にフックエラーは表示されません（sh、Git Bash、PowerShell）。
• プラグインのデータフォルダー（CLAUDE_PLUGIN_DATA、ユーザーのみが読み取り可能）に、セッションごとに小さなファイルをいくつか保持し、1 週間後に削除します。通常のプロンプトでは何も書き込みません。意思決定のように見えるプロンプトでは、その先頭行を 80 文字で切り詰めて、そのターンの間だけ保持します。Claude の直前のメッセージについては、選択肢を提示したかどうかだけを保持します。データフォルダーがない場合、チェックは何も行いません。
• テスト：node --test agent/scripts/decision-check.test.mjs。check-agent.mjs は hooks.json をチェックします。

進捗チェック

ターン終了時に実行される 2 つ目のチェック（hooks/progress-check.mjs）は、作業の進捗をボードに反映します。ターン中にファイルが変更された場合（Edit、Write、MultiEdit、NotebookEdit）、git でコミット、プッシュ、マージした場合、gh でプルリクエストを作成またはマージした場合、あるいはデプロイした場合に、その作業の後に Claude が Listspace への書き込みを行っていなければ、Claude に一度だけ次の一文が送られます。「Listspace ボードを更新してください。このターンで何を開始または完了しましたか？項目を移動し、短いコメントを追加してください。」

• Listspace ツールを一度も使っていないセッションでは何もせず、連続して二度ブロックすることもないため（stop_hook_active）、ループすることはありません。
• リマインド後は、次のリマインドまでに最低 3 ターン待ちます。また、新しい作業がある場合にのみ再度リマインドするため、しつこく通知することはありません。
• Listspace への書き込みはどれも更新としてカウントされます（move_item、add_comment、complete_item、record_decision、capture など）。読み取りはカウントされません。
• 作業の内容、ボードの更新、最後にリマインドしたターンなどの事実だけをプラグインのデータフォルダーに保持します。コマンドやファイル名は保持せず、1 週間後に削除します。Node.js と ; exit 0 のルールは意思決定チェックと同じです。
• テスト：node --test agent/scripts/progress-check.test.mjs。

ボードのコンテキスト

ボードのルールは、セッション開始時に Listspace サーバーの指示とともに届きます。長いセッション、とりわけ会話が圧縮されたセッションでは、ルールが失われることがあります。hooks/board-hooks.mjs は、重要なタイミングで Claude のコンテキストにルールを追加します。コンテキストを追加するだけで、何かをブロックしたり、コマンドやその出力を変更したりすることはありません。

• セッション開始時（SessionStart: startup、resume、clear）：プロジェクトのボード名を示し、まず get_account と start_session を実行し、最初に unfinished_from_last_sessions の項目を更新して、ボードを最新の状態に保つよう伝える一文を追加します。
• 圧縮後（source が compact の SessionStart）：ボードのルールと、先に進む前に get_account（または start_session）を呼び出すよう伝えます。これは、claimed_by_you と started_by_you に Claude が作業中だった項目が一覧表示されるためです。
• プルリクエストまたはデプロイ後（Bash と PowerShell の PostToolUse）：gh pr create、gh pr merge、またはデプロイコマンドが成功した後、該当する項目を移動し（新しいプルリクエストなら Doing、マージまたはデプロイ後なら Done）、短いコメントを追加するよう伝える一文を表示します。
• これは、プロジェクトの CLAUDE.md または AGENTS.md に Listspace board: の行がある場合（フォルダー内、またはリポジトリのルートまでの上位フォルダー）、あるいは Listspace ツールを使用したセッション（進捗チェックのメモがあるセッション）でのみ実行されます。ファイルから取得するのは Listspace ボードへのリンクのみで、ほかのテキストは取得しません。
• ファイルへの書き込みは行わず、ネットワーク呼び出しもしません。判断チェックと同じ Node.js および ; exit 0 のルールに従います。
• テスト：node --test agent/scripts/board-hooks.test.mjs。

対象外のものと、その理由

• login のデバイスペアリング：API（POST /auth/device）にはありますが、CLI ではまだ使用していません。login では、トークンの取得方法と保存方法がすでに分離されており、ペアリングを追加する場所には cli/src/cli.ts 内の TODO が記されています。スクリプト用に --token とパイプ入力のトークンは残しています。
• プラグイン内のトークン：.mcp.json にヘッダーを設定していないのは意図的です。トークンを設定すると、すべてのユーザーに配布されてしまいます。/mcp 経由のサインインはユーザーごとに行われます。チェック用スクリプトは、ここにヘッダーがあると拒否します。
• プラグイン内の CLI（bin/）：claude.ai と Cowork は最上位の bin/ を含むプラグインをインストールしないため、また MCP サーバーが Claude Code をカバーするため、対象外です。

公開

1. npx skills add によるスキル：公開済みです。公開リポジトリ listspace/agent のルートにこのフォルダーがあるため、npx skills add listspace/agent が使えます。
2. npm の CLI：スコープなしの listspace（0.5.0）として公開済みです。新しいバージョンをリリースするには、バージョンを 1 か所で更新し（「スキルの編集」を参照）、npm pack --dry-run でパッケージの内容を確認してから、2FA を有効にした npm アカウントで agent/cli から npm publish を実行します。prepublishOnly によって型チェック、テスト、ビルドが実行されます。
3. Claude Code プラグイン：公開リポジトリはマーケットプレイス（.claude-plugin/marketplace.json）も兼ねているため、ユーザーは /plugin marketplace add listspace/agent と /plugin install listspace@listspace を実行します。Anthropic のプラグインディレクトリへの掲載には別途申請が必要です。掲載に関する判断はオーナーが行い、その掲載用のプライバシーポリシー URL と利用規約 URL が必要です。

参考資料：Claude Code プラグインマニフェストのリファレンス（https://code.claude.com/docs/en/plugins-reference）、プラグインの読み込みと --plugin-dir（https://code.claude.com/docs/en/plugins/loading）、マーケットプレイスのリファレンス（https://code.claude.com/docs/en/plugins/marketplace-reference）、スキル（https://code.claude.com/docs/en/skills）、Agent Skills 仕様（https://agentskills.io/specification）、skills CLI（https://github.com/vercel-labs/skills）、モデルとして参照した Postiz のエージェントリポジトリ（https://github.com/gitroomhq/postiz-agent）。