MIT ライセンス・Node.js 22 以上・外部パッケージなし

テスト1件が、1マス。
Git のコミットが、セーブ。

Claude Code や Codex に任せた開発を、E2E テストと Git で1マスずつ進める、すごろく型の進行管理ツールです。

GridHub の盤面。方眼ノートの見開きに、メモアプリを作る4人のキャラクターの道が描かれ、テストに通ったマスに斜線が引かれている

例: gridhub step の出力

$ gridhub step store
歩いた: store S1 テスト 3/5
  ✔ create が memo を返す
  ✔ list は新しい順
  ✔ 作業フォルダが無くても作られ、memos.json に保存される
  ✖ 作り直したストアにも残っている
  ✖ 同時に10件作っても取りこぼさない
いちばん手前のモンスター: 作り直したストアにも残っている
--- 判定の出力（末尾） ---
…

つかう技術

名前	役目	要るか
Node.js 22 以上	GridHub 本体です（ESM。外部パッケージは0）。	必須
Git	町でのセーブです。担当のファイルだけを `git commit` し、負けたら `git stash` に退避して、町のコミットへ戻します。	必須
Claude Code（Anthropic） Codex（OpenAI）	GM（地図と E2E テストを書く）と、キャラクター（実装する）です。`gridhub quest --gm claude` か `codex`、`gridhub party --agent claude` か `codex` で選びます。それぞれのアカウントか API キーで使います。	AI と遊ぶなら必須
GitHub	入手元です（`git clone`）。`gridhub push` と「町でセーブしたら push」（`gridhub remote --auto-push on`）で、セーブを送ります（force push はしません）。`gh` があれば、つなぐ手順も案内します。	任意
MCP	`gridhub mcp` で、Claude Code・Codex などから GridHub を道具として呼べます（標準入出力）。	任意
Linear・Jira	盤面の状態を issue に映します（`LINEAR_API_KEY`。Jira は `JIRA_BASE_URL`・`JIRA_EMAIL`・`JIRA_API_TOKEN`）。Linear の CSV の書き出し・読み込みもできます。	任意
macOS 13 以上・Command Line Tools	Mac アプリ `GridHub.app` を手元で組みます（`swiftc`・アドホック署名）。	Mac アプリを使うときだけ

ゲームの言葉と、実際に起きること

マス数分: テスト1件です。判定はシェルのコマンドで、終了コード 0 が合格です。node --test や TAP などの出力から、1件ずつの成否を読みます。
ダンジョン30〜90分・2〜6マス: タスクです。エージェント1回分のコンテキストで終わる大きさにします。gridhub step は何度でも走らせられ、gridhub check は一発勝負です。
出口の判定gridhub check: 直近のセーブ以降の、自分の道のタスクの判定を、古い順にすべて走らせ直します。前にできていたことを壊していても落ちます。落ちるとレベルが1つ下がり、町のコミットからやり直します。
町タスク2〜3つごと: quest.save が "git" の冒険で、担当の glob（territory）に入るファイルだけをコミットします。フックは走りません。push は、自動で送る設定（gridhub remote --auto-push on）のときだけです。
中ボス数時間に1回: 結合 E2E（gate）です。メンバーがそろうと自動で走ります。判定が MASUME_BLAME: <id> を出せば、その担当だけを町のコミットへ戻します。
大ボス数日に1回: quest.goal です。願いが叶った一場面を外から確かめる、章の最後の E2E です。
王様の城大ボスの前に必ず1つ: 人間の承認です。gridhub stamp <マスID> --as <人間のID> か、盤面のボタンで通ります。
冒険の書.masume/log.jsonl: 追記専用で、各行が前の行の SHA-256 を持つハッシュの鎖です。gridhub verify で改ざんを見つけ、gridhub load <seq|commit> でその時点の盤面に戻ります。
判定ファイルの固定（封印）: GM が、判定ファイルの SHA-256 を記録します。書き換えると判定できなくなり、そのことが記録に残ります。
視界: エージェントに渡す指示（gridhub brief）には、レベルに応じて min(Lv−1, 4) マス先までしか出しません。
担当の範囲（縄張り）: キャラクターごとに重ならない glob です。共有ファイルは GM が持ちます。
イベント: 判定のない余白のマスです。担当どうしの会話（日誌から）・宿屋の主人・瓦版（製品の分野の話題と、通過の号外）が出ます。

例: メモアプリの地図

サンプルの冒険 examples/memo の地図です。願いは「メモを書いて一覧できる、ブラウザで動くメモアプリ」です。

倉庫番メモの保存
src/store/**・Claude Code
伝令HTTP サーバーと API
src/server/**・Claude Code
絵師ブラウザの画面
web/**・Claude Code
勇者承認と最終確認
人間（あなた）

倉庫番

伝令

絵師

勇者 S1 S2 S3 A1 A2

町 A3 U1 U2

町 U3 U4

GOAL

中ボス G1「メモが再起動後も残る」

本物のストアと本物のサーバーをつなぎます。SIGTERM で止めて起動し直しても、メモが残っていることを確かめます。

中ボス G2「画面部品が API とつながる」

本物の web/ を配るサーバーに、画面の部品（API クライアント・コントローラー・一覧の描画）から、作成・一覧・検索・更新・削除をして確かめます。

大ボス GOAL「メモを書いて一覧できる」

書く → 新しい順に並ぶ → 検索 → 編集 → 削除 → 再起動しても残る、を外から確かめます。

王様の城H1・H2

H1「画面の見た目の方針を承認」と、H2「ブラウザで触って承認」です。勇者（人間）がハンコを押します。

エージェントの1ターン

gridhub brief <ID>
いまのタスクと、テスト1件ずつの成否を読みます。
コードを直す
いちばん手前の落ちているテストだけを通します。
gridhub step <ID>
いまのタスクの判定だけを走らせます。何度でも、罰はありません。
gridhub check <ID>
全部通ったら、出口の判定を受けます。
gridhub note <ID> "次の自分への申し送り"
次の代のエージェントへ、日誌を残します。

作戦（`gridhub party --tactic`）

作戦で変わるのは、エージェントの止まる所と、1回の実行（出撃）の長さ（利用料）です。ルールは変わりません。

作戦	動き方	止まる所
`careful`	1マスずつ `gridhub step` で確かめ、全部通るまで `check` しません。	タスクを1つ抜けたら
`balanced`（既定）	小さく変えて `step` を回し、全部通ったら `check` します。	タスクを1つ抜けたら
`bold`	次の町まで、タスクを続けて進みます。	町でセーブしたら・中ボスで待つことになったら

どの作戦でも、check に2回落ちたら止まって知らせます。

主なコマンド

コマンド	すること
`gridhub quest "<願い>" --gm claude\|codex`	願いから GM の LLM が地図と判定を書き、冒険を始めます（`git init` も）。
`gridhub serve`	盤面を開きます（`http://127.0.0.1:5005/`）。
`gridhub app`	はじめの画面（フォルダを選ぶ・最近のフォルダ・チュートリアル）を開きます。Mac アプリは、これを起こします。
`gridhub party --agent claude\|codex --tactic …`	キャラクターごとにエージェントを走らせ、結合テストを指揮します。
`gridhub brief <id>`	エージェントに渡す指示（いまのタスク・テストの成否・見えている先）を出します。
`gridhub step <id>`	いまのタスクの判定だけを走らせます（何度でも・罰なし）。
`gridhub check <id\|gate>`	出口の判定です（町からの累積判定）。
`gridhub note <id> "<text>"`	日誌を書きます（強敵を倒した直後は、技になります）。
`gridhub stamp <node> --as <human>`	人間の承認（ハンコ）です。
`gridhub status`	盤面の要約を出します。
`gridhub verify`	冒険の書のハッシュの鎖を検証して、改ざんを見つけます。
`gridhub load <seq\|commit>`	過去の時点の盤面に戻ります（記録の番号か Git のコミットで指します）。
`gridhub remote`・`gridhub push`	GitHub につなぐ手順と、送っていないセーブの数を出します。`push` は、いまのブランチを GitHub に送ります（force push はしません）。
`gridhub mcp`	MCP サーバーです（標準入出力）。
`gridhub export linear`・`gridhub import linear`	Linear 形式（CSV・JSON）で書き出します。Linear の CSV から、地図の下書きを作ります。
`gridhub linear push`・`gridhub jira push`	盤面の状態を、Linear・Jira に送ります。

gridhub <command> --help で、各コマンドの説明が出ます。

はじめる

GridHub を手元に置く
```
git clone https://github.com/M2AI-jp/gridhub.git && cd gridhub
ln -s "$PWD/bin/gridhub.js" ~/.local/bin/gridhub
```
リンクは PATH の通った場所に置きます。~/.local/bin が PATH に無ければ、alias gridhub="node $PWD/bin/gridhub.js" でも使えます。
Claude Code か Codex を用意する

Claude Code は https://claude.com/claude-code、Codex は https://github.com/openai/codex の公式手順で用意します。どちらも、それぞれのアカウントか API キーでログインします。
願いから冒険を作り、盤面を開く
```
mkdir ~/memo && cd ~/memo
gridhub quest "メモを書いて一覧できるアプリを作りたい" --gm claude
gridhub serve
```
gridhub serve は動かしたままにします。続きは別のターミナルで打ちます。

エージェントを走らせる

gridhub party --agent claude --tactic careful

Mac アプリ

sh mac/build.sh で dist/GridHub.app ができます（macOS 13 以上・Command Line Tools。swiftc で組み、アドホック署名します）。

チュートリアル

エージェントなしで、手で最後まで遊べるチュートリアル（約5分）があります（quests/tutorial/README.md）。Mac アプリのはじめの画面からも遊べます。

テスト1件が、1マス。Git のコミットが、セーブ。