handoff-bridge 0.1.1 → 0.1.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.
Files changed (3) hide show
  1. package/README.md +11 -11
  2. package/docs/theory.md +39 -39
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -2,9 +2,9 @@
2
2
 
3
3
  [English](README.en.md) | 日本語
4
4
 
5
- `handoff-bridge` は、コーディングエージェントの元セッションから、次のセッションが迷わず再開できる必要十分な引き継ぎ Markdown を作る skill です。
5
+ `handoff-bridge` は、コーディングエージェントが把握している作業状況を、次のセッションが迷わず再開できる引き継ぎ文書にまとめるスキルです。
6
6
 
7
- 全文ログを複製するのではなく、目的、現在地、採用済みの判断、次の行動、未解決事項、正本への参照を選びます。引き継ぎは生成時点の派生物として扱い、常に参照先の正本を優先します。
7
+ 全文ログを複製するのではなく、目的、現在地、決定事項、次の行動、未解決事項と、確認すべきコードや仕様などへの参照を選んでまとめます。引き継ぎは作成時点の記録であり、内容が食い違う場合は参照先のコードや仕様などを優先します。
8
8
 
9
9
  ## インストール
10
10
 
@@ -28,7 +28,7 @@ npx handoff-bridge@latest --codex /path/to/project
28
28
  | Codex | `.agents/skills/handoff-bridge/` |
29
29
  | Claude | `.claude/skills/handoff-bridge/` |
30
30
 
31
- このインストーラーはモデルを実行せず、API key や Claude Subscription の認証も使いません。`npx` が npm package を取得する通信だけが発生し得ます。
31
+ このインストーラーはモデルを実行せず、API キーや Claude Subscription の認証も使いません。`npx` が npm パッケージを取得する通信だけが発生する場合があります。
32
32
 
33
33
  ## 使い方
34
34
 
@@ -38,23 +38,23 @@ npx handoff-bridge@latest --codex /path/to/project
38
38
  handoff-bridgeで次のセッションへの引き継ぎを作って。
39
39
  ```
40
40
 
41
- 保存先を明示しなければ、検証済みの Markdown を会話へ返すだけです。ファイルへ保存したい場合は、依頼の中で完全な保存先を指定してください。
41
+ 保存先を明示しなければ、検証済みの Markdown を会話へ返すだけです。ファイルへ保存したい場合は、依頼の中で保存先のパスを省略せず指定してください。
42
42
 
43
43
  ## ファイル保護
44
44
 
45
- インストール前に全対象を確認します。
45
+ インストール前に、すべての配置先を確認します。
46
46
 
47
- - 対象が無ければ新規作成します。
47
+ - 対象のファイルがなければ新規作成します。
48
48
  - 同じ内容の通常ファイルは変更せずスキップします。
49
- - 内容が異なる既存ファイルが1つでもあれば、書き込み前に全体を中止します。
50
- - 配置経路に symbolic link や通常ディレクトリ以外があれば中止します。
49
+ - 内容が異なる既存ファイルが1つでもあれば、何も書き込まずにインストールを中止します。
50
+ - 配置先までの途中にシンボリックリンクがある場合や、ディレクトリではないものが含まれる場合は中止します。
51
51
  - 既存ファイルは上書きしません。
52
52
 
53
- 書き込み開始後に I/O error やプロセス停止が起きた場合、自動 rollback は行わず、新規ファイルの一部が残ることがあります。同じ内容は再実行時にスキップされるため、原因を直して再実行できます。
53
+ 書き込み開始後に I/O エラーやプロセス停止が起きた場合、自動で元の状態には戻さないため、新規ファイルの一部が残ることがあります。同じ内容のファイルは再実行時にスキップされるため、原因を直して再実行できます。
54
54
 
55
55
  ## 設計
56
56
 
57
- 詳しい考え方は [理論的背景](docs/theory.md) を参照してください。skill の実行契約は [SKILL.md](skills/handoff-bridge/SKILL.md) にあります。
57
+ 詳しい考え方は [理論的背景](docs/theory.md) を参照してください。スキルを実行するときの規則は [SKILL.md](skills/handoff-bridge/SKILL.md) にあります。
58
58
 
59
59
  ## 開発と公開
60
60
 
@@ -65,6 +65,6 @@ npm run check:package
65
65
 
66
66
  公開手順は [scripts/PUBLISHING.md](scripts/PUBLISHING.md) にあります。
67
67
 
68
- ## License
68
+ ## ライセンス
69
69
 
70
70
  MIT
package/docs/theory.md CHANGED
@@ -2,93 +2,93 @@
2
2
 
3
3
  [English](theory.en.md) | 日本語
4
4
 
5
- `handoff-bridge` は、コーディングエージェントのセッション間で作業を継続するための、小さな情報圧縮と検証の仕組みです。
5
+ `handoff-bridge` は、コーディングエージェントの作業を別のセッションへ引き継ぐために、必要な情報を絞り込んで検証する仕組みです。
6
6
 
7
7
  **この文書を読まなくても使えます。** 導入と利用方法は [README](../README.md)、実行上の規則は [SKILL.md](../skills/handoff-bridge/SKILL.md) にあります。
8
8
 
9
- ## 問題 — セッションの境界で作業の意味が失われる
9
+ ## 問題 — セッションをまたぐと作業の意味が失われる
10
10
 
11
- 新しいセッションは、前のセッションの会話や一時的な判断を完全には持ちません。一方、リポジトリの全ファイルや会話全文を渡すと、重要な差分が大量の情報に埋もれます。必要なのは全文保存ではなく、次の担当が最初の判断と行動を再現できるだけの情報です。
11
+ 新しいセッションには、前のセッションの会話や、その場で下した判断が完全には引き継がれません。一方、リポジトリの全ファイルや会話全文を渡すと、重要な情報が大量の文章に埋もれます。必要なのは全文の保存ではなく、次の担当が最初に何を判断し、何をすればよいか分かるだけの情報です。
12
12
 
13
13
  handoff-bridge は、引き継ぐ情報を次へ絞ります。
14
14
 
15
15
  - 何を達成しようとしているか。
16
16
  - どこまで終わり、何が作業中か。
17
- - 正本だけからは復元できない判断と理由。
17
+ - コードや仕様など、参照先の資料だけからは分からない判断と理由。
18
18
  - 次に行う具体的な行動と成功の確認方法。
19
19
  - 既知の未解決事項、リスク、例外時の対応。
20
- - 読み直すべき正本と、その資料から何を確認するか。
20
+ - 読み直すべきコードや仕様などと、そこで何を確認するか。
21
21
 
22
- これは可逆圧縮ではありません。受け手の再開に必要な意味を残し、正本から再取得できる詳細を参照へ置き換える、目的に合わせた損失のある圧縮です。
22
+ これは、元の情報を完全に戻せる圧縮ではありません。作業の再開に必要な意味を残し、コードや仕様などから再確認できる詳細は参照先だけを示すことで、目的に合わせて情報を絞り込みます。
23
23
 
24
- ## 引き継ぎは正本ではない
24
+ ## 引き継ぎだけで現在の事実を決めない
25
25
 
26
- 引き継ぎは生成した時点の観測です。コード、仕様、issue、設計文書などが後から更新されれば、引き継ぎの記述は古くなります。そのため出力には生成時点と参照を持たせ、受け手が最初に正本を照合できる形にします。
26
+ 引き継ぎは、作成した時点の状況を記録したものです。コード、仕様、課題管理の記録、設計文書などが後から更新されれば、引き継ぎの記述は古くなります。そのため、出力には作成日時と参照先を含め、次の担当が最初に最新の情報を確認できる形にします。
27
27
 
28
28
  ```text
29
- 現在の可視文脈 ──> 選別 ──> 検証済みhandoff ──> 次セッション
30
- │ │
31
- └── 正本への参照 ──┘
29
+ 現在わかっていること ──> 選別 ──> 検証済みの引き継ぎ ──> 次のセッション
30
+ │ │
31
+ └── コードや仕様などへの参照 ──┘
32
32
  ```
33
33
 
34
- handoff は「前の担当がそう理解していた」という証拠にはなりますが、現在の事実を決める権限は持ちません。
34
+ 引き継ぎは「前の担当がそう理解していた」という記録にはなりますが、現在の事実は参照先のコードや仕様などで確認します。
35
35
 
36
- ## なぜ skill が文章を構成し、script が検証するのか
36
+ ## なぜスキルが文章を組み立て、スクリプトが検証するのか
37
37
 
38
- 目的や判断理由を選ぶには文脈の理解が必要です。これは固定的な抽出プログラムだけでは扱いにくい仕事です。一方、必須項目、出力形式、秘密らしい値、保存時の上書き禁止は、同じ入力へ同じ判定を返す program で確認できます。
38
+ 目的や判断理由を選ぶには、文脈を理解する必要があります。これは、あらかじめ決めた規則で情報を抜き出すプログラムだけでは扱いにくい仕事です。一方、必須項目や出力形式を満たしているか、秘密情報と思われる値を含んでいないか、保存時に既存ファイルを上書きしないかは、決まった規則で動くプログラムで確認できます。
39
39
 
40
40
  そこで責務を分けます。
41
41
 
42
- - **宿主エージェント**は、すでに見えている文脈から必要な意味を選び、内部 model を構成する。
43
- - **決定的な script**は、内部 model と Markdown の契約を検証し、同じ形式で描画する。
44
- - **利用者**は、handoff を作るか、どこへ保存するかを明示する。
42
+ - **スキルを実行するエージェント**は、すでに把握している情報から引き継ぎに必要な内容を選び、内部データを組み立てる。
43
+ - **検証用スクリプト**は、内部データと Markdown が決められた形式を満たすか確認し、常に同じ形式で出力する。
44
+ - **利用者**は、引き継ぎを作るかどうかと、保存する場合はその保存先を明示する。
45
45
 
46
- 自然言語の判断を完全自動化せず、機械的に確認できる境界だけを program へ渡す設計です。
46
+ 自然言語による判断を完全に自動化せず、機械的に確認できる部分だけをプログラムに任せる設計です。
47
47
 
48
- ## 可視文脈だけを使う理由
48
+ ## 現在のセッションで確認できる情報だけを使う理由
49
49
 
50
- handoff 作成を理由に repository、network、hidden transcript を追加探索すると、「いま引き継ぐ」作業が新しい調査へ変わります。さらに、読めることと送信・保存してよいことを混同する危険があります。
50
+ 引き継ぎの作成を理由にリポジトリ、ネットワーク、表示されていない会話履歴を追加で調べ始めると、引き継ぎ作業が新しい調査に変わってしまいます。さらに、情報を読めることと、その情報を送信・保存してよいことを混同する危険があります。
51
51
 
52
- そのため skill は、現在の model context にすでに見えている情報だけを使います。参照先は意味付きの locator として渡しますが、その場で読み戻しません。知識が不足している場合も、新しい答えを作らず、既知の未解決事項として運びます。
52
+ そのためスキルは、実行するエージェントにすでに与えられている情報だけを使います。参照先と、そこで確認すべき内容は引き継ぎに記録しますが、その場で参照先を読み直しません。情報が不足していても推測で補わず、未解決事項として残します。
53
53
 
54
- ## 必要十分な情報量
54
+ ## 作業再開に必要な情報量
55
55
 
56
- 短すぎる引き継ぎは「続けてください」だけになり、受け手へ再調査を押し付けます。長すぎる引き継ぎは会話全文の複製になり、何を信頼し何から始めるかを曖昧にします。
56
+ 短すぎる引き継ぎは「続けてください」だけになり、次の担当に調査のやり直しを強います。長すぎる引き継ぎは会話全文の複製になり、何を信頼し、どこから始めればよいかを分かりにくくします。
57
57
 
58
- handoff-bridge が目指す十分性は文字数ではなく、受け手が次を説明できることです。
58
+ 十分かどうかは文字数では決まりません。次の担当が以下の点を説明できることが基準です。
59
59
 
60
60
  1. 目的は何か。
61
61
  2. 現在地はどこか。
62
- 3. 最初にどの正本を何のために読むか。
62
+ 3. 最初にどの参照先を、何のために読むか。
63
63
  4. 最初の行動は何か。
64
64
  5. 何を確認できれば前進したと言えるか。
65
65
 
66
- この再開可能性を保ったまま、正本と重複する説明を減らします。
66
+ これらを判断できる情報を残しつつ、コードや仕様などから再確認できる説明は重ねて書かないようにします。
67
67
 
68
- ## 秘密と外部由来テキスト
68
+ ## 秘密情報と外部から届いた文章
69
69
 
70
- 入力に見えている情報であっても、credential、secret、個人を直接特定する生値は出力しません。必要なら「再取得が必要」という状態だけを残します。
70
+ 現在のセッションで確認できる情報でも、認証情報、秘密情報、個人を直接特定できる値は出力しません。必要な場合は「再取得が必要」という状態だけを残します。
71
71
 
72
- また、貼り付けられた文書や参照内容に命令文が含まれていても、それは引き継ぎ対象の data です。handoff 作成中に実行すべき命令として扱いません。これは、情報を読む責務と行動を許可する責務を分けるためです。
72
+ また、貼り付けられた文書や参照内容に命令文が含まれていても、それは引き継ぐ情報の一部です。引き継ぎの作成中に実行すべき命令としては扱いません。これは、情報を読むことと、その情報に従って行動する権限を分けるためです。
73
73
 
74
- ## 保存を明示操作にする理由
74
+ ## 保存先を明示してもらう理由
75
75
 
76
- 保存先が指定されていない場合、結果は会話へ返すだけです。既定のファイル名を推測すると、利用者が意図しない永続状態を作り、既存文書を正本のように見せる可能性があるからです。
76
+ 保存先が指定されていない場合、結果は会話へ返すだけです。既定のファイル名を推測すると、利用者が意図しないファイルを作り、補助的な文書を正式な記録のように見せる可能性があるからです。
77
77
 
78
- 保存先が明示された場合も、既存ファイルは確認なしに上書きしません。描画と検証が成功した Markdown だけを保存対象にし、保存に失敗しても会話上の結果と区別して報告します。
78
+ 保存先が明示された場合も、既存ファイルは確認なしに上書きしません。生成と検証に成功した Markdown だけを保存対象にし、保存に失敗した場合は、会話に返した結果とは分けて報告します。
79
79
 
80
80
  ## 配布を小さく保つ
81
81
 
82
- npm package は canonical な skill と、その決定的 script、日英の説明、最小の installer だけを含みます。installer は agent の project-local skill directory へ同じ bytes を配置するだけで、モデル実行、API client、自動更新、管理 manifest、backup、複数ファイル rollback を持ちません。
82
+ npm パッケージに含めるのは、配布元となるスキル、機械的な検証用スクリプト、日英の説明文書、最小限のインストーラーだけです。インストーラーは、各エージェント向けのプロジェクト内スキルディレクトリへ同じ内容のファイルを配置します。モデルの実行、API クライアント、自動更新、管理用ファイル、バックアップ、複数ファイルをまとめて元に戻す機能は持ちません。
83
83
 
84
- 既存ファイルの保護は、全対象の事前確認、同一 bytes の skip、差異がある場合の書き込み前中止、symbolic link の拒否で行います。書き込み中の OS 障害まで transaction 化しないことは明示的な境界です。複雑な復旧機構を増やす代わりに、既存ファイルを上書きせず、再実行を安全にします。
84
+ 既存ファイルを守るため、すべての配置先を事前に確認し、内容が同じファイルは変更せず、異なるファイルがあれば書き込み前に中止し、シンボリックリンクは拒否します。書き込み中に OS の障害が起きた場合まで、すべて元に戻せるとは保証しません。複雑な復旧機能を増やす代わりに、既存ファイルを上書きせず、安全に再実行できるようにします。
85
85
 
86
86
  ## 限界
87
87
 
88
- - handoff の意味的な完全性は、宿主モデルが見えている文脈と選別品質に依存します。
88
+ - 引き継ぐ内容が十分かどうかは、スキルを実行するモデルに与えられた情報と、そのモデルによる情報の選び方に左右されます。
89
89
  - 見えていない情報は復元できません。
90
- - 参照先の正しさや最新性は生成時には検証しません。
91
- - 秘密らしい表現の機械検査は、すべての機密情報を識別できる保証ではありません。
92
- - 出力の検証は形式と既知の禁止条件を確認するもので、将来の受け手が必ず成功することを証明しません。
90
+ - 参照先の正しさや最新性は、引き継ぎの作成時には検証しません。
91
+ - 秘密情報らしい文字列を機械的に検査しても、すべての機密情報を識別できるとは限りません。
92
+ - 出力の検証で確認できるのは、形式とあらかじめ定めた禁止事項です。次の担当が必ず作業を再開できることまでは証明できません。
93
93
 
94
- これらの限界があるため、handoff を正本へ昇格させず、受け手による最初の照合を契約の一部にしています。
94
+ これらの限界があるため、引き継ぎだけで現在の事実を決めず、次の担当が最初に参照先を確認することを利用手順に含めています。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "handoff-bridge",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "description": "Create compact, verifiable handoffs between coding-agent sessions.",
5
5
  "private": false,
6
6
  "type": "module",