hermes-pilot 0.0.0-stage → 0.2.2
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.
- package/LICENSE +21 -0
- package/README.ja.md +419 -0
- package/README.md +428 -2
- package/__init__.py +15 -0
- package/apps/bridge/src/api-errors.js +165 -0
- package/apps/bridge/src/architect.js +1298 -0
- package/apps/bridge/src/auth.js +202 -0
- package/apps/bridge/src/capabilities.js +256 -0
- package/apps/bridge/src/capture.js +145 -0
- package/apps/bridge/src/chat-profile.js +95 -0
- package/apps/bridge/src/config.js +73 -0
- package/apps/bridge/src/discord.js +89 -0
- package/apps/bridge/src/gitinfo.js +211 -0
- package/apps/bridge/src/hermes.js +97 -0
- package/apps/bridge/src/inbox.js +347 -0
- package/apps/bridge/src/kanban.js +361 -0
- package/apps/bridge/src/lang.js +60 -0
- package/apps/bridge/src/live.js +285 -0
- package/apps/bridge/src/memos.js +150 -0
- package/apps/bridge/src/ops.js +201 -0
- package/apps/bridge/src/pair-codes.js +125 -0
- package/apps/bridge/src/pipeline-optimizer.js +513 -0
- package/apps/bridge/src/pipeline-watcher.js +1022 -0
- package/apps/bridge/src/qr.js +808 -0
- package/apps/bridge/src/repos.js +544 -0
- package/apps/bridge/src/review-watcher.js +271 -0
- package/apps/bridge/src/review.js +1749 -0
- package/apps/bridge/src/search.js +162 -0
- package/apps/bridge/src/server.js +1745 -0
- package/apps/bridge/src/snippets.js +373 -0
- package/apps/bridge/src/specs.js +806 -0
- package/apps/bridge/src/tail.js +28 -0
- package/apps/bridge/src/telemetry.js +667 -0
- package/apps/bridge/src/term-snippets.js +228 -0
- package/apps/bridge/src/transcript.js +231 -0
- package/apps/bridge/src/usage.js +294 -0
- package/apps/bridge/src/workerFeed.js +72 -0
- package/apps/dashboard/index.js +2014 -0
- package/apps/dashboard/manifest.json +14 -0
- package/apps/dashboard/pilot_dashboard.py +1466 -0
- package/apps/dashboard/plugin_api.py +237 -0
- package/apps/dashboard/plugin_init.py +15 -0
- package/apps/dashboard/style.css +928 -0
- package/apps/web/dist/assets/TermPane-DYP7pi_n.css +32 -0
- package/apps/web/dist/assets/TermPane-q4f5Zu0I.js +12 -0
- package/apps/web/dist/assets/index-BzUof8lw.js +94 -0
- package/apps/web/dist/assets/index-DwZdbPU7.css +1 -0
- package/apps/web/dist/favicon.ico +0 -0
- package/apps/web/dist/icon-180-v6.png +0 -0
- package/apps/web/dist/icon-192-v6.png +0 -0
- package/apps/web/dist/icon-512-v6.png +0 -0
- package/apps/web/dist/icon-maskable-192-v6.png +0 -0
- package/apps/web/dist/icon-maskable-512-v6.png +0 -0
- package/apps/web/dist/icon-v6.svg +15 -0
- package/apps/web/dist/index.html +21 -0
- package/apps/web/dist/manifest.webmanifest +49 -0
- package/apps/web/dist/sw.js +69 -0
- package/bin/hermes-pilot.mjs +964 -0
- package/dashboard/dist/index.js +2014 -0
- package/dashboard/dist/style.css +928 -0
- package/dashboard/manifest.json +14 -0
- package/dashboard/pilot_dashboard.py +1466 -0
- package/dashboard/plugin_api.py +237 -0
- package/package.json +75 -4
- package/plugin.json +70 -0
- package/plugin.yaml +4 -0
- package/scripts/deploy.mjs +58 -0
- package/scripts/migrate-to-hermes-pilot.mjs +472 -0
- package/scripts/postinstall.mjs +32 -0
- package/scripts/sync-dashboard.mjs +98 -0
- package/skills/annotation/SKILL.md +138 -0
- package/skills/quick-review/SKILL.md +200 -0
- package/skills/quick-review/assets/sheet-template.html +175 -0
- package/skills/spec-architect/SKILL.md +226 -0
|
@@ -0,0 +1,226 @@
|
|
|
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
|
+
abstract_roles: [role:planner, role:builder, role:visual-reviewer, role:decision-framer]
|
|
13
|
+
recommended_role: role:planner
|
|
14
|
+
quality_tier: decision-ready
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
# Spec Architect(1 行の種から自走できる仕様書を作る)
|
|
18
|
+
|
|
19
|
+
Architect の仕事は「仕様書を書くこと」ではなく、**Builder(カンバン自走ワーカー)が
|
|
20
|
+
追加の質問をせずに完走できる仕様書を 2 ラウンドで作ること**。長文の質問をチャットへ
|
|
21
|
+
並べない。判断は設問シートに載せ、人が 1 タップで答える形にする。
|
|
22
|
+
|
|
23
|
+
このスキルは **`hermes-pilot` プラグイン同梱**。`hermes-pilot init` が
|
|
24
|
+
`~/.hermes/skills/spec-architect/` へ配置する。
|
|
25
|
+
|
|
26
|
+
## いつ使うか
|
|
27
|
+
|
|
28
|
+
使う:
|
|
29
|
+
- 1 行メモ / 音声ディクテーション(`Spec Seed`)から実装計画を作るとき
|
|
30
|
+
- 既存リポジトリに新しい機能群(複数バッチ)を足すとき
|
|
31
|
+
- 人が「何を作るか」は言えるが「どう作るか」は決めていないとき
|
|
32
|
+
|
|
33
|
+
使わない:
|
|
34
|
+
- 変更が 1 ファイルで正解が一意(そのまま実装して `npm run verify` を通す)
|
|
35
|
+
- すでに `docs/SPEC-*.md` があり、`hermes-pilot` の仕様ランチャーで起票するだけのとき
|
|
36
|
+
|
|
37
|
+
## 2 ラウンド・プロトコル
|
|
38
|
+
|
|
39
|
+
### Round 1 — Quick Review 直結インタビュー
|
|
40
|
+
|
|
41
|
+
チャットに箇条書きの質問を並べる代わりに、**設問シートを 1 枚だけ**作る。
|
|
42
|
+
**第一推奨は構造化 JSON(`mode=standard`)**。手書き HTML とヘッドレスブラウザ撮影は
|
|
43
|
+
「見た目の比較そのものが論点」のときだけの任意拡張。
|
|
44
|
+
|
|
45
|
+
1. 質問は **3±1 問**。各問は「人が決めること 1 つ」。事実(`file:line`・実行結果)は
|
|
46
|
+
本文に書き、人には決定だけを残す。根拠は**該当箇所の最小確認だけ**で足りる
|
|
47
|
+
(リポジトリ全体の作り込みやモック構築をしない。決まったら即シート)。
|
|
48
|
+
**Round 1 では `npm test` / `npm run verify` を走らせない**。探索は `rg` / `grep` で
|
|
49
|
+
該当シンボルだけを引き、依存関係の全量確認やビルドで時間を使わない。テストとビルドは
|
|
50
|
+
Round 2 で SPEC(各バッチの Verify)に書けばよい。シートを書いたら**即ブロック**する。
|
|
51
|
+
2. 各問に選択肢 2〜3・`recommended: true` を 1 つ。理由(利点 / 代償)を必ず添える。
|
|
52
|
+
3. 見た目の論点(配置・情報密度・配色の比較そのもの)**だけ**両案を絵にする。
|
|
53
|
+
それ以外(仕様・ロジック・文言・API・データ設計)は `.json` のみで起票して即ブロックする
|
|
54
|
+
— `browser_exec` での撮影も 300 行級の HTML 生成も行わない。
|
|
55
|
+
既存画面への追加で絵が要るときは、現行 UI の忠実な再現を先に撮る。
|
|
56
|
+
4. 出力先は `quick-review` スキルと同じ場所・同じ形式。**主成果物は `.json`**:
|
|
57
|
+
|
|
58
|
+
```text
|
|
59
|
+
~/.hermes/plugin-data/hermes-pilot/review/sheets/spec-<slug>-1.json ← これが主(mode=standard)
|
|
60
|
+
~/.hermes/plugin-data/hermes-pilot/review/sheets/spec-<slug>-1.html ← 見た目の論点のときだけ任意
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
5. カンバンへ起票して **blocked** にする(回答が来るまで実装しない):
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
hermes kanban create "Q1〜Q3: <プロジェクト名>の設計方針" --assignee <profile> --body "$(cat <<'BODY'
|
|
67
|
+
<何が決まれば仕様書を書き始められるか。いま何が止まっているか。>
|
|
68
|
+
|
|
69
|
+
[review] label=spec-<slug> round=1 mode=standard sheet=sheets/spec-<slug>-1.json target=<repo_path> chat=<session_id>
|
|
70
|
+
BODY
|
|
71
|
+
)"
|
|
72
|
+
hermes kanban block <task_id> "仕様インタビュー待ち(Q1〜Q3)" --kind needs_input
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
`.json` だけで PWA のネイティブフォーム(`<StandardForm>`)と「シート全体を開く ↗」の
|
|
76
|
+
両方が動く(`.html` が無ければブリッジが `.json` から安全な HTML を動的生成する)。
|
|
77
|
+
|
|
78
|
+
待つ間は別のタスクを進める。**自分で回答を捏造しない。**
|
|
79
|
+
|
|
80
|
+
### Round 2 — SPEC 生成
|
|
81
|
+
|
|
82
|
+
回答(`.answer.json` / `.answer.txt` / コメントの `【レビュー回答】`)を読み、
|
|
83
|
+
`docs/SPEC-<SLUG>.md` を書く。`(未選択 = お任せ)` は推奨案で確定してよい。
|
|
84
|
+
|
|
85
|
+
必須フォーマット(`apps/bridge/src/specs.js` が機械的に読む。**形を変えない**):
|
|
86
|
+
|
|
87
|
+
```markdown
|
|
88
|
+
# SPEC: <プロジェクト名> (`SPEC-<SLUG>`)
|
|
89
|
+
|
|
90
|
+
状態: 仕様確定(<日付>・インタビュー Q1〜Q3 合意済み)
|
|
91
|
+
前提仕様: <前バージョンの SPEC があればリンク>
|
|
92
|
+
|
|
93
|
+
## 1. コンセプト
|
|
94
|
+
|
|
95
|
+
<3〜6 行。何を、誰のために、どこまで作るか。>
|
|
96
|
+
|
|
97
|
+
## 2. 合意決定表(インタビュー結果)
|
|
98
|
+
|
|
99
|
+
| # | 論点 | 決定内容 | 根拠・背景 |
|
|
100
|
+
|---|---|---|---|
|
|
101
|
+
| **D1** | <問い> | <決めたこと> | <なぜ> |
|
|
102
|
+
|
|
103
|
+
## 3. 詳細技術仕様
|
|
104
|
+
|
|
105
|
+
### 3.1 <領域>
|
|
106
|
+
|
|
107
|
+
対象: <file>, <file>
|
|
108
|
+
|
|
109
|
+
1. **<機能>**: <仕様。関数名・保存キー・エンドポイント名まで書く>
|
|
110
|
+
|
|
111
|
+
## 4. カンバンタスク分割(Batch <SLUG>-1 〜 <SLUG>-N)
|
|
112
|
+
|
|
113
|
+
### Batch <SLUG>-1: <バッチ名>
|
|
114
|
+
|
|
115
|
+
- **Execution Mode**: `[Mode: Zero-Stop]`
|
|
116
|
+
- **Recommended Role**: `role:builder`
|
|
117
|
+
- **目的**: <1〜3 行。何をどのファイルに実装するか>
|
|
118
|
+
- **変更・新規ファイル**:
|
|
119
|
+
- 新規: `<path>`
|
|
120
|
+
- 変更: `<path>`
|
|
121
|
+
- **受入条件(Verify)**:
|
|
122
|
+
- <観測可能な条件。テストファイル名まで書く>
|
|
123
|
+
- `npm run verify` が全件パスすること。
|
|
124
|
+
|
|
125
|
+
---
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
## バッチ見出しの規約(守らないと起票が壊れる)
|
|
129
|
+
|
|
130
|
+
- バッチ見出しは **`### Batch <ID>: <Title>`** のみ。`<ID>` は英字始まり 16 文字まで
|
|
131
|
+
(`V5-1` / `P2` / `T3` は可、`1.1` は不可)。
|
|
132
|
+
- バッチ以外の `###` 見出しは**必ず数字で始める**(`### 3.1 …`)。数字で始めないと
|
|
133
|
+
仕様ランチャーがバッチと誤認して起票する。
|
|
134
|
+
- 各バッチに必ず次の 3 行を置く: `- **Execution Mode**: ...` / `- **目的**: ...` /
|
|
135
|
+
`- **受入条件(Verify)**: ...`。`Execution Mode` が無いバッチは起票時に
|
|
136
|
+
行動契約(`[Hermes Pilot Execution Contract]`)が注入されず、自走が保証されない。
|
|
137
|
+
- 任意行 `- **Recommended Role**: role:planner | role:builder | role:visual-reviewer`
|
|
138
|
+
を `Execution Mode` の直後に置ける(設計寄りは `role:planner`、実装・検証は `role:builder`、
|
|
139
|
+
見た目の検収を含むなら `role:visual-reviewer`)。未宣言でも起票は壊れない。
|
|
140
|
+
|
|
141
|
+
## Execution Mode の選び方
|
|
142
|
+
|
|
143
|
+
| Mode | 使うとき | ワーカーに注入される契約 |
|
|
144
|
+
|---|---|---|
|
|
145
|
+
| `Zero-Stop` | 正解が一意(テスト・ビルド・機械的リファクタ) | 質問せず `npm run verify` が通るまで自律修復して `done` |
|
|
146
|
+
| `Fast-Track Review` | 実装方針が 1 つに決まらず、途中で分岐しうる | 分岐が出たら実装前に `quick-review` シートを起票して 1 タップ承認を待つ |
|
|
147
|
+
| `Visual Gate` | 見た目が変わる(UI・CSS・文言・レイアウト) | `npm run deploy` → 実画面 390×844 / 820×1180 を検証・撮影 → 必要なら `annotation` レビュー |
|
|
148
|
+
|
|
149
|
+
迷ったら `Visual Gate`。見た目が変わらないと断言できないなら視覚検収を挟む。
|
|
150
|
+
|
|
151
|
+
## 抽象ロールと委譲・フォールバック(Model-Agnostic Delegation)
|
|
152
|
+
|
|
153
|
+
このスキルは**モデル非依存**。特定モデル名・プロバイダ名・課金プラン・個人環境のパスをここに書かない。
|
|
154
|
+
「どの抽象ロールをどの実モデルへ割り当て、失敗時にどこへ落とすか」は**実機プロファイル側**
|
|
155
|
+
(プロファイルメモリ / `SOUL.md` の割当表)が持つ。仕様書とスキルは抽象ロール名だけを扱う。
|
|
156
|
+
|
|
157
|
+
### 4 つの抽象ロール
|
|
158
|
+
|
|
159
|
+
- `role:planner` — 高度推論・設計・仕様策定・複雑な原因究明。Round 1 の問い設計、
|
|
160
|
+
Round 2 の影響分析・バッチ分割がここ。
|
|
161
|
+
- `role:builder` — 通常実装・テスト修正・ビルド・定型作業。SPEC に沿った実装と
|
|
162
|
+
`npm test` / `npm run verify` の修復がここ。
|
|
163
|
+
- `role:visual-reviewer` — スクショ差分・赤入れ画像(`.annotated.png`)の読解・
|
|
164
|
+
`390x844` / `820x1180` の視覚検収。**見た目の比較が論点のときだけ**使う。
|
|
165
|
+
- `role:decision-framer` — 設問設計・トレードオフ整理。3±1 問への切り出しと
|
|
166
|
+
選択肢・推奨理由の構成がここ。
|
|
167
|
+
|
|
168
|
+
推奨の当て方:
|
|
169
|
+
|
|
170
|
+
- Round 1 / Round 2 の設計推論・影響分析・バッチ分割は **`role:planner`**。
|
|
171
|
+
- 絵(モック・スクショ)を検証する場合のみ **`role:visual-reviewer` を併用**する。
|
|
172
|
+
絵の無い論点(API・保存形式・命名・ロジック)には付けない。
|
|
173
|
+
- 各バッチ定義に任意行 `- **Recommended Role**: role:builder` を書ける
|
|
174
|
+
(`role:planner` / `role:visual-reviewer` / `role:decision-framer` も同様)。
|
|
175
|
+
未宣言なら Execution Mode から推定される。
|
|
176
|
+
|
|
177
|
+
### ネイティブ委譲とフォールバック
|
|
178
|
+
|
|
179
|
+
委譲は Hermes Agent 標準の **`delegate_task`** だけを使う。
|
|
180
|
+
|
|
181
|
+
1. 親がロール条件に合うサブタスクを切り出し、`goal` / `context` にロール名を明記して 1 回だけ委譲する。
|
|
182
|
+
2. 子は**読み取り専用の助言者**。ファイル編集・commit・install・`npm run verify` は親が行う。
|
|
183
|
+
3. 委譲が失敗した(エラー / レート制限 / タイムアウト / 未対応モデル / 委譲ツール未搭載)
|
|
184
|
+
場合は**停止しない**。プロファイルの割当表どおりのフォールバック順(次点 → 主モデル)へ
|
|
185
|
+
切り替え、自分でそのまま完走する。
|
|
186
|
+
4. フォールバックした事実は完了報告か comment に 1 行残す(黙って検証を落とさない)。
|
|
187
|
+
5. 同じロールで 2 回失敗したら 3 回目を投げない。自分で完走する。
|
|
188
|
+
|
|
189
|
+
### 外部 AI CLI の禁止境界
|
|
190
|
+
|
|
191
|
+
`gemini` CLI(`gemini -p` 等)・`agy -p` のような**外部 AI CLI をサブプロセスで起動して
|
|
192
|
+
推論させる経路は使わない**。`spawn` / `execFile` / `exec` での起動も、シェルからのパイプも対象。
|
|
193
|
+
ランタイムコード側は `npm run check:oauth` が機械検査する。委譲は Hermes のネイティブ API
|
|
194
|
+
プロバイダ+`delegate_task` のみ。
|
|
195
|
+
|
|
196
|
+
## バッチ分割の目安
|
|
197
|
+
|
|
198
|
+
- 1 バッチ = **1 回の `npm run verify` で閉じる**変更量(おおむね 200〜600 行)。
|
|
199
|
+
- 依存は前から後ろへの一方向。`V5-2` が `V5-1` の API を使うなら `V5-1` を先に置く。
|
|
200
|
+
- 「基盤 → 機能 → 演出 → 総合検証」の順にし、最後のバッチは結合検証と実画面監査にする。
|
|
201
|
+
- 6 バッチを超えるなら、独立した SPEC に割る(1 SPEC = 1 つの目的)。
|
|
202
|
+
|
|
203
|
+
## 仕上げ(A2B ハンドオフ)
|
|
204
|
+
|
|
205
|
+
SPEC を書いたら、次を 1 つだけ出す:
|
|
206
|
+
|
|
207
|
+
```text
|
|
208
|
+
仕様書: docs/SPEC-<SLUG>.md(Batch <SLUG>-1 〜 <SLUG>-N / n バッチ)
|
|
209
|
+
起票: hermes-pilot の Tasks → 仕様ランチャー、または scripts から specs.launchSpec(dryRun: true で確認 → 実行)
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
`autoStart=true` のタグ付きで依頼されていた場合は、未起票バッチを **1 回だけ**
|
|
213
|
+
起票する(`dryRun: true` → `dryRun: false`。二重起票を絶対に作らない)。
|
|
214
|
+
|
|
215
|
+
## 落とし穴
|
|
216
|
+
|
|
217
|
+
- **Round 1 に手書き HTML を作らない/`browser_exec` で撮らない**。見た目の比較そのものが
|
|
218
|
+
論点でなければ `.json` 1 枚で起票して即ブロックする(HTML とモック画像で数分失うだけで
|
|
219
|
+
判断は変わらない)。絵が要るのは配置・情報密度・配色の比較が主題のときだけ。
|
|
220
|
+
- **`docs/SPEC-*.md` のファイル名は大文字 `SPEC` で始める**。`spec-*.md` は走査対象外。
|
|
221
|
+
- `BATCH_ID_RE` は 16 文字まで。長い ID(`V5-1-optimizer`)は切り落とされる。
|
|
222
|
+
- 本文中の `### ` 見出しは起票時のバッチ境界になる。**バッチ内の小見出しは `####` 以下**にする。
|
|
223
|
+
- `- **実行モード**` / `[Mode: ...]` の表記は `specs.js` の正規表現に合う形
|
|
224
|
+
(`- **Execution Mode**: \`[Mode: Zero-Stop]\``)を厳守する。バックティックの有無は許容。
|
|
225
|
+
- 仕様書に **認証情報・トークン・個人情報を書かない**。パスは `~` か相対パスで書く。
|
|
226
|
+
- インタビュー回答を待たずに SPEC を書き始めない。待つ間は別タスクを進める。
|