hermes-pilot 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. package/LICENSE +21 -0
  2. package/README.ja.md +390 -0
  3. package/README.md +398 -2
  4. package/__init__.py +15 -0
  5. package/apps/bridge/src/api-errors.js +165 -0
  6. package/apps/bridge/src/architect.js +1298 -0
  7. package/apps/bridge/src/auth.js +202 -0
  8. package/apps/bridge/src/capabilities.js +256 -0
  9. package/apps/bridge/src/capture.js +145 -0
  10. package/apps/bridge/src/chat-profile.js +95 -0
  11. package/apps/bridge/src/config.js +73 -0
  12. package/apps/bridge/src/discord.js +89 -0
  13. package/apps/bridge/src/gitinfo.js +211 -0
  14. package/apps/bridge/src/hermes.js +97 -0
  15. package/apps/bridge/src/inbox.js +347 -0
  16. package/apps/bridge/src/kanban.js +361 -0
  17. package/apps/bridge/src/lang.js +60 -0
  18. package/apps/bridge/src/live.js +285 -0
  19. package/apps/bridge/src/memos.js +150 -0
  20. package/apps/bridge/src/ops.js +201 -0
  21. package/apps/bridge/src/pair-codes.js +125 -0
  22. package/apps/bridge/src/pipeline-optimizer.js +358 -0
  23. package/apps/bridge/src/pipeline-watcher.js +1018 -0
  24. package/apps/bridge/src/qr.js +808 -0
  25. package/apps/bridge/src/repos.js +544 -0
  26. package/apps/bridge/src/review-watcher.js +271 -0
  27. package/apps/bridge/src/review.js +1749 -0
  28. package/apps/bridge/src/search.js +162 -0
  29. package/apps/bridge/src/server.js +1738 -0
  30. package/apps/bridge/src/snippets.js +373 -0
  31. package/apps/bridge/src/specs.js +734 -0
  32. package/apps/bridge/src/tail.js +28 -0
  33. package/apps/bridge/src/telemetry.js +667 -0
  34. package/apps/bridge/src/term-snippets.js +228 -0
  35. package/apps/bridge/src/transcript.js +231 -0
  36. package/apps/bridge/src/usage.js +294 -0
  37. package/apps/bridge/src/workerFeed.js +72 -0
  38. package/apps/dashboard/index.js +2014 -0
  39. package/apps/dashboard/manifest.json +14 -0
  40. package/apps/dashboard/pilot_dashboard.py +1466 -0
  41. package/apps/dashboard/plugin_api.py +237 -0
  42. package/apps/dashboard/plugin_init.py +15 -0
  43. package/apps/dashboard/style.css +928 -0
  44. package/apps/web/dist/assets/TermPane-DYP7pi_n.css +32 -0
  45. package/apps/web/dist/assets/TermPane-U500JD2P.js +12 -0
  46. package/apps/web/dist/assets/index-6iFDsB0G.css +1 -0
  47. package/apps/web/dist/assets/index-X4Bi2FWB.js +94 -0
  48. package/apps/web/dist/favicon.ico +0 -0
  49. package/apps/web/dist/icon-180-v6.png +0 -0
  50. package/apps/web/dist/icon-192-v6.png +0 -0
  51. package/apps/web/dist/icon-512-v6.png +0 -0
  52. package/apps/web/dist/icon-maskable-192-v6.png +0 -0
  53. package/apps/web/dist/icon-maskable-512-v6.png +0 -0
  54. package/apps/web/dist/icon-v6.svg +15 -0
  55. package/apps/web/dist/index.html +21 -0
  56. package/apps/web/dist/manifest.webmanifest +49 -0
  57. package/apps/web/dist/sw.js +69 -0
  58. package/bin/hermes-pilot.mjs +964 -0
  59. package/dashboard/dist/index.js +2014 -0
  60. package/dashboard/dist/style.css +928 -0
  61. package/dashboard/manifest.json +14 -0
  62. package/dashboard/pilot_dashboard.py +1466 -0
  63. package/dashboard/plugin_api.py +237 -0
  64. package/package.json +75 -4
  65. package/plugin.json +70 -0
  66. package/plugin.yaml +4 -0
  67. package/scripts/deploy.mjs +58 -0
  68. package/scripts/migrate-to-hermes-pilot.mjs +472 -0
  69. package/scripts/postinstall.mjs +32 -0
  70. package/scripts/sync-dashboard.mjs +98 -0
  71. package/skills/annotation/SKILL.md +103 -0
  72. package/skills/quick-review/SKILL.md +170 -0
  73. package/skills/quick-review/assets/sheet-template.html +175 -0
  74. package/skills/spec-architect/SKILL.md +175 -0
@@ -0,0 +1,103 @@
1
+ ---
2
+ name: annotation
3
+ description: "Fix UI from a hand-drawn red-mark screenshot: file an [review] annotation task, read marks/note, apply the change."
4
+ version: 1.0.0
5
+ license: MIT
6
+ metadata:
7
+ hermes:
8
+ tags: [review, annotation, screenshot, ui, human-in-the-loop]
9
+ category: workflow
10
+ phase: fix
11
+ role: author
12
+ quality_tier: evidence-based
13
+ ---
14
+
15
+ # Annotation(スクショの赤入れで修正点を受け取る)
16
+
17
+ 実装後の UI 確認を「文章の指摘」ではなく**画像の赤入れ**で受け取る。
18
+ 人はスクショに線・矩形・矢印とひとことを書き、アプリが座標付きの
19
+ `.annotation.json`(`marks` + `note`)に落とす。エージェントはそれを読み、
20
+ **指摘された場所を特定して直す**。
21
+
22
+ このスキルは **`hermes-pilot` プラグイン同梱**。データの置き場は
23
+ `~/.hermes/plugin-data/hermes-pilot/review/`(環境変数 `HP_DATA_DIR` で上書き可)。
24
+
25
+ ## いつ使うか
26
+
27
+ - 実装後の見た目(間隔・折返し・色・重なり)を人の目で確定したい
28
+ - 文章で説明すると長くなる・言葉が食い違う(「ここ」が通じない)
29
+ - PWA のスクショに赤を入れるのが最短(`390x844` の撮影が済んでいる)
30
+
31
+ 使わない: 一意に決まる不具合(テスト失敗、例外、型エラー)は自分で直す。
32
+
33
+ ## 手順 A: 自分で注釈タスクを起票する(スクショを撮った側)
34
+
35
+ ### 1. 撮る(UI が変わる変更のときだけ)
36
+
37
+ - `npm run deploy` を**先に**実行(ブリッジは `apps/web/dist` を配信する。ビルドしないと古い画面が写る)
38
+ - 撮影: PWA は `390x844`(タブレット確認は `820x1180`)
39
+ - 置き場: `~/.hermes/plugin-data/hermes-pilot/review/shots/<label>-<round>.png`
40
+ - 変更前と後を比べるなら `.before.png` / `.after.png` を両方残す
41
+
42
+ ### 2. 起票して `blocked` にする
43
+
44
+ 本文の機械可読行:
45
+
46
+ ```text
47
+ [review] label=<label> round=<round> mode=annotation image=shots/<label>-<round>.png target=<repo_path> chat=<session_id>
48
+ ```
49
+
50
+ ```bash
51
+ hermes kanban create "注釈: <何を見てほしいか>" --body "$(cat <<'BODY'
52
+ 見てほしい点(1〜3 個)。どの画面の、どの状態か。
53
+
54
+ [review] label=tasks-strip round=1 mode=annotation image=shots/tasks-strip-1.png target=~/Projects/your-repo chat=<session_id>
55
+ BODY
56
+ )" --assignee <profile>
57
+
58
+ hermes kanban block <task_id> "注釈待ち(赤入れ)" --kind needs_input
59
+ ```
60
+
61
+ - `image=` は `review/` からの相対(`shots/...`)。`..` と絶対パスは拒否される
62
+ - `assignee` は必須(無いと dispatcher が拾わない)
63
+ - PWA から起票する場合: レビュータブ →[+ 注釈]→ 画像を選ぶ → 送信
64
+ (`POST /api/review/annotation/new`。本文と `chat=` はブリッジが組み立てる)
65
+
66
+ ### 3. 待つ
67
+
68
+ 回答(赤入れ)が来るまで別のタスクを進める。赤を自分で捏造しない。
69
+
70
+ ## 手順 B: 赤入れを受け取って直す
71
+
72
+ 保存物(`review/shots/` 配下):
73
+
74
+ | ファイル | 中身 |
75
+ |---|---|
76
+ | `<label>-<r>.png` | 下地(元のスクショ) |
77
+ | `<label>-<r>.annotated.png` | 赤入れ合成済み(**人が何を指したかはこれで見る**) |
78
+ | `<label>-<r>.annotation.json` | `{ note, marks: [{tool, points}], base_image, annotated_image, base_sha256, image_sha256, annotated_at }` |
79
+
80
+ `marks[].points` は **元画像の幅・高さに対する % (0〜1)**。`tool` は `pen` / `rect` / `arrow`。
81
+ ので、座標 → 実画面の位置は `x * width`, `y * height` で戻す。
82
+
83
+ 1. `.annotation.json` の `note` を読む(ひとこと。ここに意図が書いてある)
84
+ 2. `annotated.png` を開いて赤の位置を確認する(画像が無く `marks` だけでも座標で読める)
85
+ 3. 赤の領域 → どのコンポーネントかを特定する(DOM なら `document.elementFromPoint`、
86
+ React なら該当 CSS/JSX を `rg` で引く)
87
+ 4. **指摘された場所だけ**直す。周辺の「ついで改善」は混ぜない(差分が読めなくなる)
88
+ 5. `npm run deploy` → 撮り直して after を残す
89
+ 6. `hermes kanban comment <task_id> "反映: <どのファイルの何をどう直したか>"` を残す
90
+
91
+ 赤入れは `POST /api/review/<task_id>/annotation`
92
+ (`{annotated_image: "data:image/png;base64,…", marks, note}`)で保存され、
93
+ 同時に `comment` + `unblock` される。同じ画像の再送は冪等(`image_sha256`)。
94
+
95
+ ## 落とし穴
96
+
97
+ - **回答は `blocked` のときだけ**受け付ける。`ready` / `running` / `done` に送ると 409 `NOT_WAITING`
98
+ - 画像は 12MB まで(data URL)。超えるなら縮小してから送る
99
+ - `marks` は 200 件、`points` は 1 ストローク 400 点までに丸められる(それ以上は捨てられる)
100
+ - `.annotation.json` の `annotated_image` は**相対パス**。解決はブリッジが `review/` 配下で行う
101
+ - 座標は「元画像」基準。合成済み画像を縮小して見ても比率は変わらないが、
102
+ スクショを撮り直して下地が変わったら**古い marks は使えない**(round を上げて起票し直す)
103
+ - 画像をコピーするときは `preserveTimestamps: true`(一覧は `mtime` の新しい順に並ぶ)
@@ -0,0 +1,170 @@
1
+ ---
2
+ name: quick-review
3
+ description: "Ask a human to decide between options: build a Quick Review sheet, file a blocked [review] task, then apply the answer."
4
+ version: 1.0.0
5
+ license: MIT
6
+ metadata:
7
+ hermes:
8
+ tags: [review, human-in-the-loop, kanban, sheet]
9
+ category: workflow
10
+ phase: decide
11
+ role: author
12
+ quality_tier: decision-ready
13
+ ---
14
+
15
+ # Quick Review(設問シートで判断を仰ぐ)
16
+
17
+ エージェントが実装・調査の分岐点で**人に決めてほしい**とき、長文チャットで質問せず
18
+ 「選択肢+推奨案」のシートを 1 枚出し、スマホから 1 タップで答えてもらう。
19
+ 答えはカンバンの `comment` と `unblock` として戻り、ワーカーが自走を再開する。
20
+
21
+ このスキルは **`hermes-pilot` プラグイン同梱**。データの置き場は
22
+ `~/.hermes/plugin-data/hermes-pilot/review/`(環境変数 `HP_DATA_DIR` で上書き可)。
23
+
24
+ ## いつ使うか / 使わないか
25
+
26
+ 使う:
27
+ - 見た目・配置・文言など、**正解が一意でない**判断
28
+ - 2 つ以上の実装方針があり、どちらも成立する
29
+ - 破壊的・不可逆な操作の直前に、人の意思を確定させたい
30
+
31
+ 使わない(自分で決めて進む):
32
+ - 正解が一意(テストが通る/通らない、型エラー、排他 1 択)
33
+ - 事実確認だけで決まること(`file:line` を読めば分かる)
34
+ - 多数の項目の一括検収(1 枚に詰め込むと答えられない)
35
+
36
+ ## 手順
37
+
38
+ ### 1. 問いを 3±1 に絞る
39
+
40
+ 各問は「人が決めること 1 つ」。**事実(`file:line` か実行結果)は本文に書き、人には決定だけを残す**。
41
+ 選択肢は 2〜3。推奨を 1 つ決め、理由(利点 / 代償)を必ず書く。
42
+
43
+ ### 2. 絵にする(任意・見た目の論点だけ)
44
+
45
+ 見た目・配置・情報密度・配色の**比較そのものが論点**のときだけ、両方の案を絵にする。
46
+ 現行 UI に加える変更なら、まず現行画面の忠実な再現を撮る(現物と乖離したモックを描かない)。
47
+ 絵の無い論点(命名、保存形式、API、ロジック)には付けない — 付けない方が速く、判断もぶれない。
48
+ スクショが必要なときだけヘッドレスブラウザ(`browser_exec`)を使う。
49
+
50
+ ### 3. シートを作る(JSON が主・HTML は任意)
51
+
52
+ **第一推奨は構造化 JSON 1 枚(`mode=standard`)**。PWA はこれでネイティブフォームを描く。
53
+ `.html` は複数タブ比較・図解・スクショ並べが不可欠なときだけの**任意拡張**。
54
+
55
+ 置き場: `~/.hermes/plugin-data/hermes-pilot/review/sheets/<label>-<round>.json`
56
+ (`mkdir -p` してから書く。`<label>` は `^[a-z0-9][a-z0-9._-]{0,40}$`)
57
+
58
+ ```json
59
+ {
60
+ "label": "cockpit-03",
61
+ "round": 1,
62
+ "mode": "standard",
63
+ "title": "シートの表題(タスク名と同じでよい)",
64
+ "topic": "何を決めるのか 1〜2 文",
65
+ "target": "~/Projects/your-repo",
66
+ "questions": [
67
+ {
68
+ "id": "q1",
69
+ "text": "問いの本文",
70
+ "options": [
71
+ { "id": "A", "label": "選択肢", "detail": "利点: … / 代償: …", "recommended": true, "thumb": "thumbs/cockpit-03-1/q1-A.png" },
72
+ { "id": "B", "label": "選択肢", "detail": "利点: … / 代償: …" }
73
+ ]
74
+ }
75
+ ],
76
+ "has_global_note": true,
77
+ "sheet": "sheets/cockpit-03-1.json",
78
+ "created_at": "2026-11-13"
79
+ }
80
+ ```
81
+
82
+ 挿絵を付けるなら `review/thumbs/<label>-<round>/q1-A.png` に置き、`thumb` は `thumbs/...` の相対パスにする。
83
+
84
+ `.html` を併用する場合だけ、このスキルの `assets/sheet-template.html` をコピーして中身を差し替える。
85
+ ブリッジが読むのはこの 3 点なので**構造は変えない**(`.json` だけで起票するときは不要):
86
+
87
+ - `#akForm` … 設問フォームのルート
88
+ - `#out` … 回答テキストの出力先(`textarea`)
89
+ - `#genBtn` … 回答テキストを組み立てるボタン(アプリ内では「回答を送信」に化ける)
90
+
91
+ HTML を書くときの設問のマークアップ(ブリッジの注入スクリプトが `#akForm .q h3` を装飾する):
92
+
93
+ ```html
94
+ <section class="q" data-q="q1">
95
+ <h3>Q1. 帯の形は、流す・静止・今のまま、どれにするか</h3>
96
+ <label data-opt="A"><input type="radio" name="q1" value="A"> A. 流れるティッカー <span class="rec">推奨</span>
97
+ <span class="d">利点: 件名が長くても最後まで読める / 代償: 動く文字を追い続ける負担</span></label>
98
+ <label data-opt="B"><input type="radio" name="q1" value="B"> B. 静止 1 行
99
+ <span class="d">利点: 疲れない / 代償: 2 件目以降は省略</span></label>
100
+ <textarea name="note-q1" placeholder="補足(任意)"></textarea>
101
+ </section>
102
+ ```
103
+
104
+ > 旧手順(`.html` を主・`mode=sheet`)は**レガシー/カスタム HTML 拡張**として残る。
105
+ > どちらの `mode` でも、`.json` さえあれば PWA は `<StandardForm>` で回答でき、
106
+ > `.html` が無ければブリッジが `.json` から安全な HTML を動的生成する。
107
+
108
+ ### 4. カンバンに起票して `blocked` にする
109
+
110
+ 本文の**機械可読行**(この 1 行がブリッジの唯一の手掛かり):
111
+
112
+ ```text
113
+ [review] label=<label> round=<round> mode=standard sheet=sheets/<label>-<round>.json target=<repo_path> chat=<session_id>
114
+ ```
115
+
116
+ ```bash
117
+ hermes kanban create "Q1〜Q3: <表題>" --body "$(cat <<'BODY'
118
+ <人向けの要約。何が決まれば進めるか、いま何が止まっているか>
119
+
120
+ [review] label=cockpit-03 round=1 mode=standard sheet=sheets/cockpit-03-1.json target=~/Projects/your-repo chat=<session_id>
121
+ BODY
122
+ )" --assignee <profile>
123
+
124
+ hermes kanban block <task_id> "レビュー待ち(Q1〜Q3)" --kind needs_input
125
+ ```
126
+
127
+ - `target=` は `~` 展開後の絶対パスでも `~/...` でもよい(ブリッジが実パスに直す)
128
+ - `chat=<session_id>` を書くと、完了報告がその会話に戻る(書かないとフィードだけ)
129
+ - **`assignee` を必ず付ける**(無いと dispatcher が拾わない)
130
+ - 起票後は**待つ**。回答が来るまで別のタスクを進める(自分で回答を捏造しない)
131
+
132
+ ### 5. 回答を受けて反映する
133
+
134
+ 回答は次のどちらかで届く:
135
+
136
+ 1. PWA のレビュー画面 → `POST /api/review/<task_id>/answer`
137
+ → `review/sheets/<label>-<round>.answer.json` と `.answer.txt` が書かれ、タスクが `comment` + `unblock` される
138
+ 2. タスクのコメントに貼られた回答テキスト(`【レビュー回答】` 形式)
139
+
140
+ `.answer.txt`(またはコメント)を読み、**選ばれた選択肢どおりに実装**する。
141
+ `(未選択 = お任せ)` は推奨案で確定してよい。`全体へのコメント:` の指示は最優先。
142
+
143
+ 反映したら `hermes kanban comment <task_id> "反映: <何をどう変えたか>"` を残して完了へ進む。
144
+ 反映が回答と違うと判断したら `POST /api/review/<task_id>/reopen`(`request-changes`)で再質問する。
145
+
146
+ ## 回答フォーマット(壊さない)
147
+
148
+ シートが生成するテキストはこの形。ブリッジの `parseReplyText` は
149
+ `【レビュー回答】` と `全体へのコメント:` を読み、旧 `【赤ペン回答】` / `全体への赤ペン:` も受理する。
150
+
151
+ ```text
152
+ 【レビュー回答】cockpit-03
153
+ Q1. 帯の形は、流す・静止・今のまま、どれにするか: A — 流れるティッカー / 補足: 3 件までなら可
154
+ Q2. 既存バーは置き換えるか: (未選択 = お任せ)
155
+ 全体へのコメント: 色は現行のまま
156
+ ---
157
+ 上の回答を反映して作業を続けてください。お任せの項目は推奨案で確定してください。
158
+ ```
159
+
160
+ ## 落とし穴
161
+
162
+ - **`sheet=` のパスは `review/` からの相対**(`sheets/x-1.json`)。`..`・絶対パスは拒否される
163
+ - 機械可読行は **`mode=standard sheet=sheets/<label>-<round>.json`** を第一推奨にする
164
+ (`.html` を併用したときだけ `mode=sheet sheet=sheets/x-1.html`)。`image=` に `.html` を書いても
165
+ `sheet` として救済されるが、`sheet=` を正しく書く
166
+ - **見た目の比較が論点でないときに `.html` を手書きしたり `browser_exec` で撮ったりしない**。
167
+ JSON 1 枚で足りる論点に絵を付けると、シート 1 枚に数分かかり回答も遅れる
168
+ - 同じ回答の再送は冪等(`.answer.json` の `sha256` で判定)。二重に `comment` は付かない
169
+ - 回答は **`blocked` のときだけ**受け付ける。`ready` / `running` / `done` に送ると 409 `NOT_WAITING`
170
+ - 2 ラウンド目は `round=2` で**新しいファイル**(`<label>-2.json` / `.html`)を作る(1 を上書きしない)
@@ -0,0 +1,175 @@
1
+ <!DOCTYPE html>
2
+ <html lang="ja">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1">
6
+ <title>Quick Review テンプレート</title>
7
+ <!--
8
+ hermes-pilot / skills/quick-review/assets/sheet-template.html
9
+
10
+ 使い方:
11
+ 1. このファイルをコピーして
12
+ ~/.hermes/plugin-data/hermes-pilot/review/sheets/<label>-<round>.html に置く
13
+ 2. タイトル・事実・設問(.q セクション)を差し替える
14
+ 3. 同じディレクトリに <label>-<round>.json を書く(PWA のネイティブフォーム用)
15
+
16
+ ブリッジが依存する構造(消さない):
17
+ #akForm … 設問フォームのルート(注入スクリプトが .q h3 を装飾する)
18
+ #out … 回答テキストの出力先(textarea)
19
+ #genBtn … 回答テキストを組み立てるボタン(アプリ内では「回答を送信」に化ける)
20
+ .q[data-q], h3, label[data-opt], input[type=radio][name=qN]
21
+ file:// で開いても、アプリ内(/api/review/:id/sheet)で開いても動く。
22
+ -->
23
+ <style>
24
+ :root{--ink:#212529;--muted:#64707C;--line:#DEE2E6;--paper:#fff;--dim:#F6F8FA;--accent:#2563EB;--red:#DC2626}
25
+ *{box-sizing:border-box}
26
+ body{background:var(--paper);color:var(--ink);margin:0;padding:0 16px 40px;border-top:3px solid var(--red);
27
+ font-family:'IBM Plex Sans JP','Hiragino Kaku Gothic ProN','Hiragino Sans',-apple-system,sans-serif;
28
+ font-size:14.5px;line-height:1.9;-webkit-text-size-adjust:100%}
29
+ main{max-width:760px;margin:0 auto}
30
+ .kicker{font-family:'IBM Plex Mono',Menlo,monospace;font-size:12.5px;letter-spacing:.08em;color:var(--red);
31
+ font-weight:600;padding-top:14px}
32
+ h1{font-size:23px;line-height:1.45;margin:8px 0 12px}
33
+ h2{font-size:18px;line-height:1.45;margin:28px 0 8px;padding-bottom:4px;border-bottom:1px solid var(--line)}
34
+ h3{font-size:15px;line-height:1.5;margin:0 0 8px}
35
+ p{margin:8px 0}
36
+ .m{color:var(--muted);font-size:12.5px;line-height:1.7}
37
+ .concl{border:1px solid var(--line);border-left:3px solid var(--red);border-radius:10px;padding:12px 16px}
38
+ code{font-family:'IBM Plex Mono',Menlo,monospace;font-size:12.5px;background:var(--dim);border:1px solid var(--line);
39
+ border-radius:4px;padding:0 4px}
40
+ #akForm{margin-top:28px}
41
+ .q{border:1px solid var(--line);border-radius:10px;padding:14px 16px;margin:12px 0;background:var(--paper)}
42
+ .q label{display:block;border:1px solid var(--line);border-radius:8px;padding:10px 12px;margin:8px 0;cursor:pointer}
43
+ .q label:has(input:checked){border-color:var(--red);background:#FFF7F7}
44
+ .q input[type=radio]{margin-right:6px}
45
+ .rec{font-family:'IBM Plex Mono',Menlo,monospace;font-size:11px;color:var(--red);border:1px solid var(--red);
46
+ border-radius:4px;padding:0 5px;margin-left:4px;white-space:nowrap}
47
+ .d{display:block;color:var(--muted);font-size:12.5px;line-height:1.7;margin-top:2px}
48
+ textarea{width:100%;font:inherit;font-size:13px;border:1px solid var(--line);border-radius:8px;padding:8px 10px;
49
+ background:var(--paper);color:var(--ink);min-height:56px}
50
+ #out{min-height:140px;display:none}
51
+ .actions{display:flex;gap:8px;flex-wrap:wrap;margin:16px 0 8px}
52
+ button{font:inherit;font-size:14px;padding:10px 16px;border-radius:10px;border:1px solid var(--red);
53
+ background:var(--red);color:#fff;cursor:pointer}
54
+ button.ghost{background:var(--paper);color:var(--red)}
55
+ .status{font-size:13px;min-height:1.6em;margin:6px 0}
56
+ .status.ok{color:#0b5f45}.status.err{color:#8a1f17}
57
+ footer{margin-top:24px;border-top:1px solid var(--line);padding-top:10px}
58
+ @media (prefers-color-scheme: dark){
59
+ :root{--ink:#e8f4f6;--muted:#84a5ad;--line:rgba(120,190,205,.2);--paper:#0a2029;--dim:#0e2a35}
60
+ }
61
+ </style>
62
+ </head>
63
+ <body>
64
+ <main>
65
+ <div class="kicker">QUICK REVIEW / label=<span id="labelSlot">example-01</span> round=1</div>
66
+ <h1>ここに表題(タスク名と同じでよい)</h1>
67
+
68
+ <div class="concl">
69
+ <p><strong>決めてほしいこと:</strong> 何が決まれば作業を再開できるかを 1〜2 文で。</p>
70
+ <p class="m">判断に必要な事実はここに書く(<code>file:line</code> や実測値)。人は決定だけを返す。</p>
71
+ </div>
72
+
73
+ <h2>設問</h2>
74
+
75
+ <form id="akForm">
76
+ <section class="q" data-q="q1">
77
+ <h3>Q1. 問いを 1 つだけ書く</h3>
78
+ <label data-opt="A"><input type="radio" name="q1" value="A"> A. 選択肢 A のラベル <span class="rec">推奨</span>
79
+ <span class="d">利点: … / 代償: …</span></label>
80
+ <label data-opt="B"><input type="radio" name="q1" value="B"> B. 選択肢 B のラベル
81
+ <span class="d">利点: … / 代償: …</span></label>
82
+ <textarea name="note-q1" placeholder="補足(任意)"></textarea>
83
+ </section>
84
+
85
+ <section class="q" data-q="q2">
86
+ <h3>Q2. 問いを 1 つだけ書く</h3>
87
+ <label data-opt="A"><input type="radio" name="q2" value="A"> A. 選択肢 A のラベル <span class="rec">推奨</span>
88
+ <span class="d">利点: … / 代償: …</span></label>
89
+ <label data-opt="B"><input type="radio" name="q2" value="B"> B. 選択肢 B のラベル
90
+ <span class="d">利点: … / 代償: …</span></label>
91
+ <textarea name="note-q2" placeholder="補足(任意)"></textarea>
92
+ </section>
93
+
94
+ <h2>全体へのコメント</h2>
95
+ <textarea name="global_note" placeholder="複数の問いをまたぐ指示(任意)"></textarea>
96
+
97
+ <div class="actions">
98
+ <button type="button" id="genBtn">回答テキストを作る</button>
99
+ <button type="button" class="ghost" id="copyBtn">コピー</button>
100
+ </div>
101
+ <p class="m">選んで[回答テキストを作る]を押すと、下に貼り付け用のテキストが出ます(未選択は「お任せ」)。
102
+ アプリから開いた場合はボタンが[回答を送信]に変わり、そのままレビューへ返ります。</p>
103
+ <div id="status" class="status"></div>
104
+ <textarea id="out" readonly></textarea>
105
+ </form>
106
+
107
+ <footer class="m">
108
+ <p>反映先: <code id="targetSlot">~/Projects/your-repo</code></p>
109
+ </footer>
110
+ </main>
111
+ <script>
112
+ (function () {
113
+ var QUESTIONS = [
114
+ { id: 'q1', text: 'Q1. 問いを 1 つだけ書く' },
115
+ { id: 'q2', text: 'Q2. 問いを 1 つだけ書く' }
116
+ ];
117
+ var LABEL = 'example-01';
118
+
119
+ function oneLine(s) { return String(s || '').replace(/\s+/g, ' ').trim(); }
120
+
121
+ function buildReply() {
122
+ var lines = ['【レビュー回答】' + LABEL];
123
+ QUESTIONS.forEach(function (q) {
124
+ var el = document.querySelector('input[name="' + q.id + '"]:checked');
125
+ var noteEl = document.querySelector('textarea[name="note-' + q.id + '"]');
126
+ var note = oneLine(noteEl ? noteEl.value : '');
127
+ var line = q.text + ': ';
128
+ if (el) {
129
+ var lab = el.closest('label');
130
+ var lbl = lab ? oneLine(lab.textContent).replace(/^(A|B|C)\.\s*/, '') : '';
131
+ line += el.value + ' — ' + lbl;
132
+ } else {
133
+ line += '(未選択 = お任せ)';
134
+ }
135
+ if (note) line += ' / 補足: ' + note;
136
+ lines.push(line);
137
+ });
138
+ var g = document.querySelector('textarea[name="global_note"]');
139
+ var gv = oneLine(g ? g.value : '');
140
+ lines.push('全体へのコメント: ' + (gv || '(なし)'));
141
+ lines.push('---');
142
+ lines.push('上の回答を反映して作業を続けてください。お任せの項目は推奨案で確定してください。');
143
+ return lines.join('\n');
144
+ }
145
+
146
+ function setStatus(msg, cls) {
147
+ var el = document.getElementById('status');
148
+ if (!el) return;
149
+ el.textContent = msg || '';
150
+ el.className = 'status' + (cls ? ' ' + cls : '');
151
+ }
152
+
153
+ document.getElementById('genBtn').addEventListener('click', function () {
154
+ var out = document.getElementById('out');
155
+ out.style.display = 'block';
156
+ out.value = buildReply();
157
+ setStatus('回答テキストを作りました。貼り付けるか[回答を送信]してください。', 'ok');
158
+ });
159
+
160
+ document.getElementById('copyBtn').addEventListener('click', function () {
161
+ var out = document.getElementById('out');
162
+ var text = out.value || buildReply();
163
+ var done = function (ok) {
164
+ setStatus(ok ? '✓ コピーしました' : 'テキストを選択してコピーしてください', ok ? 'ok' : 'err');
165
+ };
166
+ if (navigator.clipboard && navigator.clipboard.writeText) {
167
+ navigator.clipboard.writeText(text).then(function () { done(true); }, function () { done(false); });
168
+ } else {
169
+ try { out.select(); done(document.execCommand('copy')); } catch (e) { done(false); }
170
+ }
171
+ });
172
+ })();
173
+ </script>
174
+ </body>
175
+ </html>
@@ -0,0 +1,175 @@
1
+ ---
2
+ name: spec-architect
3
+ description: "Turn a one-line seed into a SPEC the batch runner can execute: sheet-driven interview, then docs/SPEC-<SLUG>.md with Execution Mode per batch."
4
+ version: 1.0.0
5
+ license: MIT
6
+ metadata:
7
+ hermes:
8
+ tags: [architect, spec, interview, quick-review, a2b-pipeline, kanban]
9
+ category: workflow
10
+ phase: design
11
+ role: architect
12
+ quality_tier: decision-ready
13
+ ---
14
+
15
+ # Spec Architect(1 行の種から自走できる仕様書を作る)
16
+
17
+ Architect の仕事は「仕様書を書くこと」ではなく、**Builder(カンバン自走ワーカー)が
18
+ 追加の質問をせずに完走できる仕様書を 2 ラウンドで作ること**。長文の質問をチャットへ
19
+ 並べない。判断は設問シートに載せ、人が 1 タップで答える形にする。
20
+
21
+ このスキルは **`hermes-pilot` プラグイン同梱**。`hermes-pilot init` が
22
+ `~/.hermes/skills/spec-architect/` へ配置する。
23
+
24
+ ## いつ使うか
25
+
26
+ 使う:
27
+ - 1 行メモ / 音声ディクテーション(`Spec Seed`)から実装計画を作るとき
28
+ - 既存リポジトリに新しい機能群(複数バッチ)を足すとき
29
+ - 人が「何を作るか」は言えるが「どう作るか」は決めていないとき
30
+
31
+ 使わない:
32
+ - 変更が 1 ファイルで正解が一意(そのまま実装して `npm run verify` を通す)
33
+ - すでに `docs/SPEC-*.md` があり、`hermes-pilot` の仕様ランチャーで起票するだけのとき
34
+
35
+ ## 2 ラウンド・プロトコル
36
+
37
+ ### Round 1 — Quick Review 直結インタビュー
38
+
39
+ チャットに箇条書きの質問を並べる代わりに、**設問シートを 1 枚だけ**作る。
40
+ **第一推奨は構造化 JSON(`mode=standard`)**。手書き HTML とヘッドレスブラウザ撮影は
41
+ 「見た目の比較そのものが論点」のときだけの任意拡張。
42
+
43
+ 1. 質問は **3±1 問**。各問は「人が決めること 1 つ」。事実(`file:line`・実行結果)は
44
+ 本文に書き、人には決定だけを残す。根拠は**該当箇所の最小確認だけ**で足りる
45
+ (リポジトリ全体の作り込みやモック構築をしない。決まったら即シート)。
46
+ **Round 1 では `npm test` / `npm run verify` を走らせない**。探索は `rg` / `grep` で
47
+ 該当シンボルだけを引き、依存関係の全量確認やビルドで時間を使わない。テストとビルドは
48
+ Round 2 で SPEC(各バッチの Verify)に書けばよい。シートを書いたら**即ブロック**する。
49
+ 2. 各問に選択肢 2〜3・`recommended: true` を 1 つ。理由(利点 / 代償)を必ず添える。
50
+ 3. 見た目の論点(配置・情報密度・配色の比較そのもの)**だけ**両案を絵にする。
51
+ それ以外(仕様・ロジック・文言・API・データ設計)は `.json` のみで起票して即ブロックする
52
+ — `browser_exec` での撮影も 300 行級の HTML 生成も行わない。
53
+ 既存画面への追加で絵が要るときは、現行 UI の忠実な再現を先に撮る。
54
+ 4. 出力先は `quick-review` スキルと同じ場所・同じ形式。**主成果物は `.json`**:
55
+
56
+ ```text
57
+ ~/.hermes/plugin-data/hermes-pilot/review/sheets/spec-<slug>-1.json ← これが主(mode=standard)
58
+ ~/.hermes/plugin-data/hermes-pilot/review/sheets/spec-<slug>-1.html ← 見た目の論点のときだけ任意
59
+ ```
60
+
61
+ 5. カンバンへ起票して **blocked** にする(回答が来るまで実装しない):
62
+
63
+ ```bash
64
+ hermes kanban create "Q1〜Q3: <プロジェクト名>の設計方針" --assignee <profile> --body "$(cat <<'BODY'
65
+ <何が決まれば仕様書を書き始められるか。いま何が止まっているか。>
66
+
67
+ [review] label=spec-<slug> round=1 mode=standard sheet=sheets/spec-<slug>-1.json target=<repo_path> chat=<session_id>
68
+ BODY
69
+ )"
70
+ hermes kanban block <task_id> "仕様インタビュー待ち(Q1〜Q3)" --kind needs_input
71
+ ```
72
+
73
+ `.json` だけで PWA のネイティブフォーム(`<StandardForm>`)と「シート全体を開く ↗」の
74
+ 両方が動く(`.html` が無ければブリッジが `.json` から安全な HTML を動的生成する)。
75
+
76
+ 待つ間は別のタスクを進める。**自分で回答を捏造しない。**
77
+
78
+ ### Round 2 — SPEC 生成
79
+
80
+ 回答(`.answer.json` / `.answer.txt` / コメントの `【レビュー回答】`)を読み、
81
+ `docs/SPEC-<SLUG>.md` を書く。`(未選択 = お任せ)` は推奨案で確定してよい。
82
+
83
+ 必須フォーマット(`apps/bridge/src/specs.js` が機械的に読む。**形を変えない**):
84
+
85
+ ```markdown
86
+ # SPEC: <プロジェクト名> (`SPEC-<SLUG>`)
87
+
88
+ 状態: 仕様確定(<日付>・インタビュー Q1〜Q3 合意済み)
89
+ 前提仕様: <前バージョンの SPEC があればリンク>
90
+
91
+ ## 1. コンセプト
92
+
93
+ <3〜6 行。何を、誰のために、どこまで作るか。>
94
+
95
+ ## 2. 合意決定表(インタビュー結果)
96
+
97
+ | # | 論点 | 決定内容 | 根拠・背景 |
98
+ |---|---|---|---|
99
+ | **D1** | <問い> | <決めたこと> | <なぜ> |
100
+
101
+ ## 3. 詳細技術仕様
102
+
103
+ ### 3.1 <領域>
104
+
105
+ 対象: <file>, <file>
106
+
107
+ 1. **<機能>**: <仕様。関数名・保存キー・エンドポイント名まで書く>
108
+
109
+ ## 4. カンバンタスク分割(Batch <SLUG>-1 〜 <SLUG>-N)
110
+
111
+ ### Batch <SLUG>-1: <バッチ名>
112
+
113
+ - **Execution Mode**: `[Mode: Zero-Stop]`
114
+ - **目的**: <1〜3 行。何をどのファイルに実装するか>
115
+ - **変更・新規ファイル**:
116
+ - 新規: `<path>`
117
+ - 変更: `<path>`
118
+ - **受入条件(Verify)**:
119
+ - <観測可能な条件。テストファイル名まで書く>
120
+ - `npm run verify` が全件パスすること。
121
+
122
+ ---
123
+ ```
124
+
125
+ ## バッチ見出しの規約(守らないと起票が壊れる)
126
+
127
+ - バッチ見出しは **`### Batch <ID>: <Title>`** のみ。`<ID>` は英字始まり 16 文字まで
128
+ (`V5-1` / `P2` / `T3` は可、`1.1` は不可)。
129
+ - バッチ以外の `###` 見出しは**必ず数字で始める**(`### 3.1 …`)。数字で始めないと
130
+ 仕様ランチャーがバッチと誤認して起票する。
131
+ - 各バッチに必ず次の 3 行を置く: `- **Execution Mode**: ...` / `- **目的**: ...` /
132
+ `- **受入条件(Verify)**: ...`。`Execution Mode` が無いバッチは起票時に
133
+ 行動契約(`[Hermes Pilot Execution Contract]`)が注入されず、自走が保証されない。
134
+
135
+ ## Execution Mode の選び方
136
+
137
+ | Mode | 使うとき | ワーカーに注入される契約 |
138
+ |---|---|---|
139
+ | `Zero-Stop` | 正解が一意(テスト・ビルド・機械的リファクタ) | 質問せず `npm run verify` が通るまで自律修復して `done` |
140
+ | `Fast-Track Review` | 実装方針が 1 つに決まらず、途中で分岐しうる | 分岐が出たら実装前に `quick-review` シートを起票して 1 タップ承認を待つ |
141
+ | `Visual Gate` | 見た目が変わる(UI・CSS・文言・レイアウト) | `npm run deploy` → 実画面 390×844 / 820×1180 を検証・撮影 → 必要なら `annotation` レビュー |
142
+
143
+ 迷ったら `Visual Gate`。見た目が変わらないと断言できないなら視覚検収を挟む。
144
+
145
+ ## バッチ分割の目安
146
+
147
+ - 1 バッチ = **1 回の `npm run verify` で閉じる**変更量(おおむね 200〜600 行)。
148
+ - 依存は前から後ろへの一方向。`V5-2` が `V5-1` の API を使うなら `V5-1` を先に置く。
149
+ - 「基盤 → 機能 → 演出 → 総合検証」の順にし、最後のバッチは結合検証と実画面監査にする。
150
+ - 6 バッチを超えるなら、独立した SPEC に割る(1 SPEC = 1 つの目的)。
151
+
152
+ ## 仕上げ(A2B ハンドオフ)
153
+
154
+ SPEC を書いたら、次を 1 つだけ出す:
155
+
156
+ ```text
157
+ 仕様書: docs/SPEC-<SLUG>.md(Batch <SLUG>-1 〜 <SLUG>-N / n バッチ)
158
+ 起票: hermes-pilot の Tasks → 仕様ランチャー、または scripts から specs.launchSpec(dryRun: true で確認 → 実行)
159
+ ```
160
+
161
+ `autoStart=true` のタグ付きで依頼されていた場合は、未起票バッチを **1 回だけ**
162
+ 起票する(`dryRun: true` → `dryRun: false`。二重起票を絶対に作らない)。
163
+
164
+ ## 落とし穴
165
+
166
+ - **Round 1 に手書き HTML を作らない/`browser_exec` で撮らない**。見た目の比較そのものが
167
+ 論点でなければ `.json` 1 枚で起票して即ブロックする(HTML とモック画像で数分失うだけで
168
+ 判断は変わらない)。絵が要るのは配置・情報密度・配色の比較が主題のときだけ。
169
+ - **`docs/SPEC-*.md` のファイル名は大文字 `SPEC` で始める**。`spec-*.md` は走査対象外。
170
+ - `BATCH_ID_RE` は 16 文字まで。長い ID(`V5-1-optimizer`)は切り落とされる。
171
+ - 本文中の `### ` 見出しは起票時のバッチ境界になる。**バッチ内の小見出しは `####` 以下**にする。
172
+ - `- **実行モード**` / `[Mode: ...]` の表記は `specs.js` の正規表現に合う形
173
+ (`- **Execution Mode**: \`[Mode: Zero-Stop]\``)を厳守する。バックティックの有無は許容。
174
+ - 仕様書に **認証情報・トークン・個人情報を書かない**。パスは `~` か相対パスで書く。
175
+ - インタビュー回答を待たずに SPEC を書き始めない。待つ間は別タスクを進める。