@ozzylabs/suasor 0.1.0

package/docs/skills/README.md

@@ -0,0 +1,54 @@
+# Assistant Skills
+
+[ADR-0008](../adr/0008-assistant-skills.md)。自然文トリガのアシスタント skill 群。SSOT は `docs/skills/<name>/SKILL.md`、`suasor skills install` で `.claude/skills/` `.agents/skills/` に展開する。read 系はエージェント自律 OK、write 系は HITL（auto-apply なし、[ADR-0004](../adr/0004-mcp-agent-boundary-and-hitl.md)）。
+
+> 本ファイルは catalog（責務と発火条件の一覧）。各 skill の本体は `<name>/SKILL.md`（下表の skill 名からリンク）。frontmatter（`name` / 自然文トリガの `description`）+ 駆動する MCP tool flow を持つ。
+
+## Read 系（自律 OK・11）
+
+| skill | 発火例 | 主な MCP tool |
+|---|---|---|
+| [`personal-brief`](personal-brief/SKILL.md) | 「今日のまとめ」「最近どう」 | brief / recall.search / task.list / decision.list |
+| [`next-actions`](next-actions/SKILL.md) | 「次に何やる」「優先度高いのは」 | task.list / recall.search |
+| [`catchup`](catchup/SKILL.md) | 「前回以降の差分」「久しぶりに確認」 | (seen-marker ベースの差分要約) |
+| [`find-document`](find-document/SKILL.md) | 「あの資料」「<語>含むファイル」 | search (FTS) |
+| [`research`](research/SKILL.md) | 「`<X>`について調べて」「網羅的に」 | recall.search + search + graph.related + brief |
+| [`meeting-prep`](meeting-prep/SKILL.md) | 「次の会議準備」「明日のMTG前確認」 | source.list(calendar) / recall.search / graph.related |
+| [`decision-rationale`](decision-rationale/SKILL.md) | 「あの決定はなぜ」「Xを選んだ理由」 | decision.list / graph.related / recall.search |
+| [`external-brief`](external-brief/SKILL.md) | 「上司向け週次」「クライアント向け進捗」 | task.list(completed) / decision.list / brief |
+| [`pr-review`](pr-review/SKILL.md) | 「PR #N レビューして」 | recall.search (+ gh diff) |
+| [`handoff-draft`](handoff-draft/SKILL.md) | 「引き継ぎ書作って」 | task.list / decision.list / recall.search（text-only・persist なし） |
+| [`announcement-draft`](announcement-draft/SKILL.md) | 「リリース告知文」 | recall.search / decision.list / brief（text-only・persist なし） |
+
+> **MCP tool 注記:** 上表の `brief` / `graph.related` は計画中で未提供（[mcp-surface.md](../design/mcp-surface.md) の「後続 Issue」）。該当 skill は当面、提供済みの read tool（`recall.search` / `search` / `*.list`）を組み合わせて動作する。
+
+## HITL write 系（人の承認で適用・4）
+
+| skill | 発火例 | 主な MCP tool |
+|---|---|---|
+| [`reply-draft`](reply-draft/SKILL.md) | 「返信案考えて」「下書き作って」 | propose.generate(reply_draft) → propose.apply |
+| [`inbox-triage`](inbox-triage/SKILL.md) | 「受信箱整理して」「未処理捌いて」 | inbox.list → propose.generate(inbox_triage) → task.create / propose.apply |
+| [`source-extract`](source-extract/SKILL.md) | 「この資料からタスク抽出」 | source.get → propose.generate(source_extract) → propose.apply |
+| [`meeting-followup`](meeting-followup/SKILL.md) | 「会議後のaction items」「議事録からタスク」 | source.list(calendar) → propose.generate(meeting_followup) → propose.apply |
+
+エコシステム共通 dev skill（drive / lint / commit / ship / pr / review 等）は `@ozzylabs/skills` 経由で別供給（名前空間 disjoint）。
+
+## インストール
+
+SSOT（本ディレクトリ）はパッケージに同梱され、`suasor skills install` でエージェントの skill ディレクトリに展開する（[ADR-0008](../adr/0008-assistant-skills.md)・[docs/design/cli.md](../design/cli.md)）。
+
+```bash
+suasor skills install                 # カレントプロジェクトの .claude/skills/ + .agents/skills/ へ展開
+suasor skills install --scope claude  # Claude Code（.claude/skills/）のみ
+suasor skills install --scope agents  # Codex / Copilot / Gemini（.agents/skills/）のみ
+suasor skills install --host /path/to/project   # 展開先プロジェクトを指定
+suasor skills install --dry-run       # 書き込まず差分だけ確認
+suasor skills list                    # 各 skill の状態（installed / missing / modified）
+suasor skills list --json             # 機械可読（SkillStatus[]）
+```
+
+展開は冪等で、内容一致は `unchanged`・欠落は `created`・差分は SSOT 内容で `updated` に上書きする。`suasor init` は本コマンドを案内するのみで自動展開はしない。
+
+### in-repo dogfood
+
+本リポジトリは展開結果（`.claude/skills/` / `.agents/skills/`）を commit して dogfood する。SSOT を編集したら `suasor skills install` を再実行して mirror を更新し、両方を commit する。pre-commit の `skills-drift` フック（`scripts/skills-drift.sh`）が SSOT ↔ mirror の同期を検査し、ずれていれば commit を止める。

package/docs/skills/announcement-draft/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: announcement-draft
+description: 「リリース告知文書いて」「announcement 作って」「アナウンス文章まとめて」「release notes 草案」「お知らせ案ほしい」と頼まれたら、Suasor MCP の recall.search（関連 release / change context）+ decision.list（recorded_after=last_release）+ brief（告知 tone）を読み取り系で組み立て、ホスト LLM が告知文 text を構成して返す。persist しない（text-only）。propose 経路を持たず、ユーザーが手で SaaS に投稿する。
+---
+
+# announcement-draft
+
+リリース告知文 / お知らせの text を組み立てる。read-only・text-only。
+
+## いつ発火するか
+
+- 「リリース告知文書いて」「announcement 作って」「アナウンス文章まとめて」
+- 「release notes 草案」「お知らせ案ほしい」
+
+## 何をするか（MCP tool flow）
+
+read tool のみ（[ADR-0004](../../adr/0004-mcp-agent-boundary-and-hitl.md)）。
+
+1. `recall.search` で関連 release / change context を引く（embedding 無効時は `signal: embedding_disabled` を見て `search`（FTS）へフォールバック、[ADR-0005](../../adr/0005-fts-first-retrieval-embedding-sidecar.md)）
+2. `decision.list`（`recordedAfter=last_release`）で前回リリース以降に記録された決定・変更を引く
+3. `brief` で告知 tone のまとめ素材を作る（LLM 要約。委譲先で生成、[ADR-0006](../../adr/0006-ml-delegation.md)）
+4. ホスト LLM が告知文 text（ハイライト / 変更点 / 影響 / 次のステップ）を構成して返す
+
+## 制約
+
+- read-only。persist しない（text-only）
+- `propose.generate` を経由せず候補保存 / apply 経路を持たない
+- ユーザーが受け取った text を手で SaaS（Slack / Notion / GitHub release / メール 等）に投稿する
+- 本 skill は手順書のみで実処理を持たない

package/docs/skills/catchup/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: catchup
+description: 「前回以降の差分」「久しぶりに確認」「最後に見てから何が変わった」「不在中の動き」と頼まれたら、ホスト側で保持する seen-marker（最終確認時刻）を since として、Suasor MCP の source.list / task.list / decision.list / inbox.list を時間フィルタで合成し、前回以降の差分だけを要約する。専用 MCP tool は使わない。
+---
+
+# catchup
+
+「前回確認した時点からの差分」を組み立てる。15 skill のうち本 skill だけ専用 MCP tool を持たず、既存 read tool + host 側 seen-marker で合成する（mcp-surface レビュー D1 確定）。
+
+## いつ発火するか
+
+- 「前回以降の差分」「久しぶりに確認」「最後に見てから何が変わった」「不在中の動き」
+
+## 何をするか（MCP tool flow）
+
+read tool のみ（[ADR-0004](../../adr/0004-mcp-agent-boundary-and-hitl.md)）。**専用 tool は追加しない**（[mcp-surface.md](../../design/mcp-surface.md) の D1 方針）。
+
+1. seen-marker（最終確認時刻）を `since` として取る。marker は **host（Claude Code 等）側で保持**する。server は永続 marker を持たない（local-first / stateless read surface）
+2. `since` を各 read tool の下限 inclusive 時間フィルタに渡して差分を集める:
+   - `source.list`（`observedAfter=since`）— 新規・更新ソース
+   - `task.list`（`updatedAfter=since`）— 動いた task
+   - `decision.list`（`recordedAfter=since`）— 記録された決定
+   - `inbox.list`（`updatedAfter=since`）— 仕分けの変化
+3. ホスト LLM が「前回以降に何が変わったか」として要約して返す
+4. 応答後、host 側で seen-marker を現在時刻に更新する（次回 catchup の `since`）
+
+## 制約
+
+- read-only。persist しない。server 側に marker を残さない
+- 時間フィルタは下限 inclusive（`>=`）/ 上限 exclusive（`<`）。`since = last_seen` を各 `*After` に渡す
+- server 側 marker が必要と判断された場合に限り、別 Issue で専用 `catchup` read tool を検討する（本 skill の scope 外）

package/docs/skills/decision-rationale/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: decision-rationale
+description: 「あの決定はなぜ」「X を選んだ理由」「Y の決定経緯」「なんで A じゃなくて B にしたんだっけ」「この方針の根拠は?」と聞かれたら、Suasor MCP の decision.list（期間 / トピック絞り）+ graph.related（decision から関連 source / 先行 decision へ provenance を辿る）+ recall.search（関連 context の補強）を組み合わせ、決定 + 経緯 + 関連 source + 関連 prior decisions のサマリを返す。read-only。
+---
+
+# decision-rationale
+
+過去の決定の「なぜ」を provenance を辿って組み立てる。read-only。
+
+## いつ発火するか
+
+- 「あの決定はなぜ」「X を選んだ理由」「Y の決定経緯」
+- 「なんで A じゃなくて B にしたんだっけ」「この方針の根拠は?」
+
+## 何をするか（MCP tool flow）
+
+read tool のみ（[ADR-0004](../../adr/0004-mcp-agent-boundary-and-hitl.md)）。`decisions` projection は `rationale` + provenance（`links`）を保持する（[data-model.md](../../design/data-model.md)）。
+
+1. `decision.list`（`recordedAfter` / `recordedBefore` で期間絞り）で対象決定を引く。各 decision は `title` / `rationale` / `recorded_at`
+2. `graph.related` で当該 decision を起点に、関連 source（根拠になったやりとり）/ 先行 decision（先立つ判断）へ `links` を辿る
+3. `recall.search` で関連 context を補強する（embedding 無効時は `signal: embedding_disabled` を見て `search`（FTS）へフォールバック、[ADR-0005](../../adr/0005-fts-first-retrieval-embedding-sidecar.md)）
+4. 決定 + 経緯（rationale）+ 関連 source + 関連 prior decisions のサマリを組み立てて返す
+
+## 制約
+
+- read-only。persist しない
+- 本 skill は手順書のみで実処理を持たない

package/docs/skills/external-brief/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: external-brief
+description: 「上司向け週次報告」「クライアント向け進捗まとめ」「外向きステータス」「マネージャーに送る report」「お客さんに見せる進捗」と頼まれたら、Suasor MCP の task.list（state=completed, updated_after=対象期間開始）と decision.list（recorded_after=対象期間開始）を組み合わせて完了タスク + 意思決定を引き、brief で外向き tone のまとめを返す。persist なし。
+---
+
+# external-brief
+
+外向き（上司 / クライアント）の進捗レポートを組み立てる。read-only。pair: 自分向けは [personal-brief](../personal-brief/SKILL.md)。
+
+## いつ発火するか
+
+- 「上司向け週次報告」「クライアント向け進捗まとめ」「外向きステータス」
+- 「マネージャーに送る report」「お客さんに見せる進捗」
+
+## 何をするか（MCP tool flow）
+
+read tool のみ（[ADR-0004](../../adr/0004-mcp-agent-boundary-and-hitl.md)）。
+
+1. 対象期間の開始を ISO 8601 で決める（既定は直近 1 週間）
+2. `task.list`（`state=completed`、`updatedAfter=対象期間開始`）で完了 task を引く
+3. `decision.list`（`recordedAfter=対象期間開始`）で記録された意思決定を引く
+4. `brief` で外向き tone のまとめを生成する（LLM 要約。委譲先で生成、[ADR-0006](../../adr/0006-ml-delegation.md)）。内部のみの未確定事項・生本文は外向きから落とす
+5. 外向きレポート text を返す
+
+## 制約
+
+- read-only。persist しない（text-only）
+- 外部 SaaS への送信はしない。ユーザーが受け取った text を手で送る
+- 本 skill は手順書のみで実処理を持たない

package/docs/skills/find-document/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: find-document
+description: 「あの資料どこ」「先週共有された PDF」「<キーワード>含むファイル」「あの議事録」「あの Doc」と頼まれたら、Suasor MCP の search（FTS5 全文検索）で本文ベースに横断検索し、connector 取り込み済みの source を返す。意味検索が要るときは recall.search を補助的に併用する。外部 SaaS を直接叩かない。
+---
+
+# find-document
+
+取り込み済み source を本文ベースで横断検索して「あの資料」を見つける。FTS-first（[ADR-0005](../../adr/0005-fts-first-retrieval-embedding-sidecar.md)）。
+
+## いつ発火するか
+
+- 「あの資料どこ」「先週共有された PDF」「<キーワード>含むファイル」「あの議事録」「あの Doc」「あのメール」
+
+## 何をするか（MCP tool flow）
+
+read tool のみ（[ADR-0004](../../adr/0004-mcp-agent-boundary-and-hitl.md)）。外部 SaaS は直接叩かず、local projection の保持本文（[ADR-0003](../../adr/0003-local-first-and-content-minimization.md)）だけを検索する。
+
+1. `search`（FTS5、[retrieval.md](../../design/retrieval.md)）で query を本文全文検索する。返り値 `hits[]` は `externalId` / `sourceType` / `observedAt` / `score`（bm25 昇順=より関連）/ `body`、および `strategy`（`fts` | `like-fallback`）
+2. 必要なら `source.list`（`sourceType` 絞り / `observedAfter` / `observedBefore`）で source 種別・期間を絞り込む
+3. 本文全体が要れば `source.get`（`externalId`）で取得する
+4. 意味検索ハイブリッドが要る場合のみ `recall.search` を補助的に併用する（embedding 無効時は `signal: embedding_disabled` を見て `search` に寄せる）
+5. 該当 source を提示して返す
+
+## 制約
+
+- read-only。本文取得は read 経路のみ。外部 SaaS API を直接呼ばない
+- 短クエリは `search` が `like-fallback` に切り替わる（[retrieval.md](../../design/retrieval.md)）
+- 本 skill は手順書のみで実処理を持たない

package/docs/skills/handoff-draft/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: handoff-draft
+description: 「引き継ぎ書作って」「handoff 書く」「後任向け資料まとめて」「業務引継メモほしい」と頼まれたら、Suasor MCP の task.list（state=in_progress）+ decision.list + recall.search + graph.related を読み取り系で組み立て、ホスト LLM が引き継ぎ書 text を構成して返す。persist しない（text-only）。propose 経路を持たず、ユーザーが手で SaaS に貼り付ける。
+---
+
+# handoff-draft
+
+後任向けの引き継ぎ書 text を組み立てる。read-only・text-only。
+
+## いつ発火するか
+
+- 「引き継ぎ書作って」「handoff 書く」「後任向け資料まとめて」「業務引継メモほしい」
+
+## 何をするか（MCP tool flow）
+
+read tool のみ（[ADR-0004](../../adr/0004-mcp-agent-boundary-and-hitl.md)）。
+
+1. `task.list`（`state=in_progress`）で進行中 task を引く（＝引き継ぐべき作業）
+2. `decision.list` で関連する決定・方針を引く（後任が背景を理解できるよう）
+3. `recall.search` で各 task の関連やりとりを補強する（embedding 無効時は `signal: embedding_disabled` を見て `search`（FTS）へフォールバック、[ADR-0005](../../adr/0005-fts-first-retrieval-embedding-sidecar.md)）
+4. `graph.related` で task / decision に紐づく source を辿り、参照先をまとめる
+5. ホスト LLM が引き継ぎ書 text（進行中作業 / 背景決定 / 関連資料 / 次の一手）を構成して返す
+
+## 制約
+
+- read-only。persist しない（text-only）
+- `propose.generate` を経由せず候補保存 / apply 経路を持たない
+- ユーザーが受け取った text を手で SaaS（Notion / Confluence / docs / Slack 等）に貼り付ける
+- 本 skill は手順書のみで実処理を持たない

package/docs/skills/inbox-triage/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: inbox-triage
+description: 「受信箱整理して」「inbox 仕分けて」「未処理アイテム捌いて」「pending を片付けて」と頼まれたら、Suasor MCP の inbox.list（state=open）で未処理アイテムを集め、propose.generate（mode=inbox_triage）で各アイテムへの action 候補（task 化 / decision 記録）を生成し、ユーザー確認後に propose.apply で承認分のみ保存する。auto-apply 経路は存在しない。
+---
+
+# inbox-triage
+
+未処理 inbox を仕分ける HITL write skill。各アイテムを task 化 / decision 記録 / dismiss する action 候補を提案し、承認分のみ適用する（[ADR-0004](../../adr/0004-mcp-agent-boundary-and-hitl.md)）。
+
+## いつ発火するか
+
+- 「受信箱整理して」「inbox 仕分けて」「未処理アイテム捌いて」「pending を片付けて」
+
+## 何をするか（MCP tool flow）
+
+read で集めて、write は HITL。**auto-apply 経路は存在しない**（[ADR-0004](../../adr/0004-mcp-agent-boundary-and-hitl.md)）。
+
+1. `inbox.list`（`state=open`）で未処理アイテムを集める。各 item は `source_external_id` / `state` / `updated_at`
+2. `propose.generate`（mode=`inbox_triage`）で各アイテムへの action 候補を生成する。候補は次のいずれか:
+   - **task 化** — `task.create`（write tool）に渡す task 候補。`TaskProposed` event に対応
+   - **decision 記録** — `DecisionRecorded` に対応する候補
+   - **仕分け** — `InboxItemTriaged`（state: snoozed / done / dismissed）に対応する候補
+3. **生成した action 候補一式をユーザーに提示して確認を取る**（native framing: ホスト側で人の承認を促す）
+4. ユーザーが承認した候補のみ `propose.apply` で保存する（idempotent）。task 化を含む場合も承認後に適用する
+
+## 制約
+
+- HITL。人の承認なしに `propose.apply` / `task.create` を呼ばない。auto-apply しない
+- `inbox.state` の語彙: `open` / `snoozed` / `done` / `dismissed`（[data-model.md](../../design/data-model.md)）
+- 本 skill は手順書のみで実処理を持たない

package/docs/skills/meeting-followup/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: meeting-followup
+description: 「会議後の action items」「ミーティングのフォローアップ」「議事録から task 抽出」「打ち合わせのフォロー」と頼まれたら、Suasor MCP の source.list（calendar source）で直近の会議を集め、source.get で議事録を読み recall.search で関連やりとりを引いた上で、propose.generate（mode=meeting_followup）で task / decision 候補を生成し、ユーザー確認後に propose.apply で承認分のみ保存する。auto-apply 経路は存在しない。
+---
+
+# meeting-followup
+
+会議後に action items を抽出する HITL write skill（[ADR-0004](../../adr/0004-mcp-agent-boundary-and-hitl.md)）。pair: 会議前は [meeting-prep](../meeting-prep/SKILL.md)。
+
+## いつ発火するか
+
+- 「会議後の action items」「ミーティングのフォローアップ」「議事録から task 抽出」
+- 「昨日の会議どうだった」「打ち合わせのフォロー」
+
+## 何をするか（MCP tool flow）
+
+read で集め、write は HITL。**auto-apply 経路は存在しない**（[ADR-0004](../../adr/0004-mcp-agent-boundary-and-hitl.md)）。
+
+1. `source.list`（calendar の `sourceType`、`observedBefore=now` で直近）で対象会議を集める
+2. `source.get`（`externalId`）で議事録 / 関連やりとりを読む
+3. `recall.search` で会議トピックの関連 context を引く（embedding 無効時は `signal: embedding_disabled` を見て `search`（FTS）へフォールバック、[ADR-0005](../../adr/0005-fts-first-retrieval-embedding-sidecar.md)）
+4. `propose.generate`（mode=`meeting_followup`）で task / decision 候補を生成する（`TaskProposed` / `DecisionRecorded` 候補に対応、[data-model.md](../../design/data-model.md)）
+5. **生成した候補一式をユーザーに提示して確認を取る**（native framing: ホスト側で人の承認を促す）
+6. ユーザーが承認した候補のみ `propose.apply` で保存する（idempotent）
+
+## 制約
+
+- HITL。人の承認なしに `propose.apply` を呼ばない。auto-apply しない
+- 本 skill は手順書のみで実処理を持たない

package/docs/skills/meeting-prep/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: meeting-prep
+description: 「来週の会議準備」「明日のミーティング前確認」「次の会議の context」「<会議名> の準備して」「打ち合わせ前に状況教えて」と頼まれたら、Suasor MCP の source.list（calendar source）で該当 event を引き、recall.search で過去の関連やりとり、graph.related で関連 decisions / sources を辿り、会議準備サマリ（目的 / 過去文脈 / 関連 decisions / 参考 sources）を組み立てる。read-only、persist なし。
+---
+
+# meeting-prep
+
+次の会議に向けた context を組み立てる。read-only。pair: 会議後は [meeting-followup](../meeting-followup/SKILL.md)。
+
+## いつ発火するか
+
+- 「来週の会議準備」「明日のミーティング前確認」「次の会議の context」
+- 「<会議名> の準備して」「打ち合わせ前に状況教えて」
+
+## 何をするか（MCP tool flow）
+
+read tool のみ（[ADR-0004](../../adr/0004-mcp-agent-boundary-and-hitl.md)）。
+
+1. `source.list`（calendar の `sourceType`、`observedAfter` / `observedBefore` で対象期間）で該当 calendar event を引く
+2. `source.get`（`externalId`）で event 本文・議題を取る
+3. `recall.search` で過去の関連やりとりを引く（embedding 無効時は `signal: embedding_disabled` を見て `search`（FTS）へフォールバック、[ADR-0005](../../adr/0005-fts-first-retrieval-embedding-sidecar.md)）
+4. `graph.related` で関連 decisions / sources を辿る
+5. 会議準備サマリ（目的 / 過去文脈 / 関連 decisions / 参考 sources）を組み立てて返す
+
+## 制約
+
+- read-only。persist しない
+- 本 skill は手順書のみで実処理を持たない

package/docs/skills/next-actions/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: next-actions
+description: 「次に何をする?」「やること教えて」「タスク何が残ってる?」「今日やること」「優先度高いのは?」と聞かれたら、Suasor MCP の task.list と recall.search を使って優先度順の next-actions を組み立てる。新規 task 作成は write tool（task.create）のためホスト側で人確認を促す。
+---
+
+# next-actions
+
+未処理 task を優先度順に並べて「次にやること」を返す。
+
+## いつ発火するか
+
+- 「次に何をする?」「やること教えて」「タスク何が残ってる?」
+- 「今日やること」「今週やること」「来週やること」「優先度高いのは?」
+
+## 何をするか（MCP tool flow）
+
+read tool のみ（[ADR-0004](../../adr/0004-mcp-agent-boundary-and-hitl.md)）。
+
+1. `task.list`（`state=open` / `state=in_progress`）で未完 task を取る。期間指定があれば `updatedAfter` / `updatedBefore`（ISO 8601、`tasks.updated_at` ベース）でフィルタする
+2. `recall.search` で各 task に関連する context を補強する（embedding 無効時は `signal: embedding_disabled` を見て `search`（FTS）へフォールバック、[ADR-0005](../../adr/0005-fts-first-retrieval-embedding-sidecar.md)）
+3. ホスト LLM が緊急度・依存・期日から優先度順に並べて next-actions を組み立てて返す
+
+## 制約
+
+- read-only。task の状態を変えない
+- **新規 task の作成は `task.create`（write tool）のため、ここでは行わず、ホスト側で人の確認を促す**（HITL、auto-apply なし、[ADR-0004](../../adr/0004-mcp-agent-boundary-and-hitl.md)）
+- 本 skill は手順書のみで実処理を持たない

package/docs/skills/personal-brief/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: personal-brief
+description: 「今日のまとめ」「今週どうなってる」「最近どう」「自分の状況」「先週の振り返り」と聞かれたら、指定期間（既定は直近 24h）の主要な動きを自分向けにまとめる。Suasor MCP の brief / recall.search / task.list / decision.list / inbox.list を読み取り系で組み合わせて要約する。
+---
+
+# personal-brief
+
+自分向けの状況サマリ。「最近どうなってる」を read-only で組み立てる。pair: 外向きは [external-brief](../external-brief/SKILL.md)。
+
+## いつ発火するか
+
+- 「今日のまとめ」「今週どうなってる」「今月の動き」「先週の状況」「先月の振り返り」
+- 「最近どうなってる」「状況教えて」「自分の状況」
+
+## 何をするか（MCP tool flow）
+
+すべて read tool（[ADR-0004](../../adr/0004-mcp-agent-boundary-and-hitl.md)）。副作用なし・エージェント自律 OK。
+
+1. 期間を決める。明示がなければ直近 24h。ISO 8601（offset 付き）の `since` を作る
+2. `brief` で期間サマリを取る（LLM 要約。委譲先で生成、[ADR-0006](../../adr/0006-ml-delegation.md)）
+3. 補強が要れば次を時間フィルタ付きで叩く（下限 inclusive `*After` / 上限 exclusive `*Before`）:
+   - `task.list`（`updatedAfter=since`）— 動いた task
+   - `decision.list`（`recordedAfter=since`）— 記録された決定
+   - `inbox.list`（`state=open`）— 未処理シグナル
+   - `recall.search` — トピックの関連 context（embedding 無効時は `signal: embedding_disabled` を見て `search`（FTS）へフォールバック、[ADR-0005](../../adr/0005-fts-first-retrieval-embedding-sidecar.md)）
+4. 集めた結果をホスト LLM が「主要な動き」として要約して返す
+
+## 制約
+
+- read-only。persist しない（イベントを書かない）
+- LLM 推論ループは外部ホスト（Claude Code 等）側。本 skill は手順書のみで実処理を持たない
+- 時間窓は各 projection の自然な timestamp 列が対象（task/inbox=`updated_at`、decision=`recorded_at`）

package/docs/skills/pr-review/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: pr-review
+description: 「この PR レビューして」「#123 確認して」「PR どう思う」と頼まれたら、Suasor MCP の recall.search で関連 source / decision / 過去 review を引き、必要に応じて gh pr diff の出力を組み合わせてレビュー観点を提示する。read 系のみで構成し、PR への comment 投稿は外部送信扱いのため本 skill では行わない。
+---
+
+# pr-review
+
+PR に対し、過去の決定・関連やりとりを踏まえたレビュー観点を提示する。read-only。
+
+## いつ発火するか
+
+- 「この PR レビューして」「#123 確認して」「PR どう思う」
+
+## 何をするか（MCP tool flow）
+
+Suasor MCP は read tool のみ（[ADR-0004](../../adr/0004-mcp-agent-boundary-and-hitl.md)）。diff は host の `gh` CLI から取る。
+
+1. `recall.search` で PR のトピックに関連する source / decision / 過去 review を引く（embedding 無効時は `signal: embedding_disabled` を見て `search`（FTS）へフォールバック、[ADR-0005](../../adr/0005-fts-first-retrieval-embedding-sidecar.md)）
+2. `decision.list` で当該領域の既存方針・決定を引き、PR がそれに沿っているか照合する
+3. 必要なら host 側で `gh pr diff <N>` の出力を組み合わせて差分を読む
+4. レビュー観点（過去決定との整合 / 関連やりとりとの矛盾 / 抜け）を提示して返す
+
+## 制約
+
+- read-only。Suasor から PR を変更しない
+- **PR への comment 投稿は外部送信扱いのため本 skill では行わない**（HITL、[ADR-0004](../../adr/0004-mcp-agent-boundary-and-hitl.md)）。観点を提示し、投稿はユーザー / dev skill 側に委ねる
+- 本 skill は手順書のみで実処理を持たない

package/docs/skills/reply-draft/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: reply-draft
+description: 「返信案を考えて」「下書き作って」「これに返信したい」と頼まれたら、Suasor MCP の propose.generate（reply_draft mode、reply_to_source_id 指定）で返信下書きを生成し、ユーザー確認後に propose.apply で承認分のみ保存する。外部 SaaS への送信はせず、ユーザーが下書きを確認して手で送る。HITL（auto-apply なし）。
+---
+
+# reply-draft
+
+返信下書きを生成する HITL write skill。生成だけでは送信も保存もしない（[ADR-0004](../../adr/0004-mcp-agent-boundary-and-hitl.md)）。
+
+## いつ発火するか
+
+- 「返信案を考えて」「下書き作って」「これに返信したい」
+
+## 何をするか（MCP tool flow）
+
+write tool は HITL。**auto-apply 経路は存在しない**（[ADR-0004](../../adr/0004-mcp-agent-boundary-and-hitl.md)）。
+
+1. 返信元 source を特定する（必要なら `source.get` / `search` で `externalId` を確定）
+2. `propose.generate`（mode=`reply_draft`、`reply_to_source_id=<externalId>`）で返信下書き候補を生成する。これは `ReplyDraftProposed` event（HITL・未適用、[data-model.md](../../design/data-model.md)）に対応する候補で、まだ確定・送信されない
+3. **生成した下書きをユーザーに提示して確認を取る**（native framing: ホスト側で人の承認を促す）
+4. ユーザーが承認した候補のみ `propose.apply` で保存する（idempotent）
+
+## 制約
+
+- HITL。人の承認なしに `propose.apply` を呼ばない。auto-apply しない
+- 外部 SaaS への送信は行わない。ユーザーが下書きを確認して手で送る
+- 本 skill は手順書のみで実処理を持たない

package/docs/skills/research/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: research
+description: 「<X> について調べて」「<Y> の経緯」「<Z> に関するすべての情報」「<トピック> を網羅的に教えて」と頼まれたら、Suasor MCP の recall.search（意味検索）+ search（FTS5 全文）+ graph.related（関連 entity 拡張）+ brief（統合要約）を順に叩き、sources 一覧 / 関連 entities / 経緯サマリを組み立てて返す。read-only、persist なし。
+---
+
+# research
+
+トピックを横断調査して「関連するすべて」を組み立てる。FTS-first（[ADR-0005](../../adr/0005-fts-first-retrieval-embedding-sidecar.md)）に意味検索とグラフ拡張を重ねる。
+
+## いつ発火するか
+
+- 「`<X>` について調べて」「`<Y>` の経緯」「`<Z>` に関するすべての情報」
+- 「`<トピック>` を網羅的に教えて」「`<キーワード>` 周りの状況」
+
+## 何をするか（MCP tool flow）
+
+read tool のみ（[ADR-0004](../../adr/0004-mcp-agent-boundary-and-hitl.md)）。
+
+1. `recall.search` で意味的に関連する source を引く（embedding 無効時は `signal: embedding_disabled` を見て次の `search` に寄せる）
+2. `search`（FTS5）で本文全文検索を重ね、語の一致を取りこぼさないようにする
+3. `graph.related` でヒットした entity（source / decision / task）を起点に関連 entity を辿る
+4. `brief` で集めた context を統合要約する（LLM 要約。委譲先で生成、[ADR-0006](../../adr/0006-ml-delegation.md)）
+5. sources 一覧 / 関連 entities / 経緯サマリを組み立てて返す
+
+## 制約
+
+- read-only。persist しない
+- 本 skill は手順書のみで実処理を持たない

package/docs/skills/source-extract/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: source-extract
+description: 「この資料から task 抽出」「これに含まれる decisions 教えて」「<source_id> から候補を」「このドキュメントから ToDo 拾って」と頼まれたら、Suasor MCP の source.get で対象 source の本文を読み、propose.generate（mode=source_extract）で task / decision / reply_draft 候補を生成し、ユーザー確認後に propose.apply で承認分のみ保存する。auto-apply 経路は存在しない。
+---
+
+# source-extract
+
+特定 source の本文から task / decision / reply_draft 候補を抽出する HITL write skill（[ADR-0004](../../adr/0004-mcp-agent-boundary-and-hitl.md)）。
+
+## いつ発火するか
+
+- 「この資料から task 抽出」「これに含まれる decisions 教えて」
+- 「`<source_id>` から候補を」「このドキュメントから ToDo 拾って」
+
+## 何をするか（MCP tool flow）
+
+read で本文を取り、write は HITL。**auto-apply 経路は存在しない**（[ADR-0004](../../adr/0004-mcp-agent-boundary-and-hitl.md)）。
+
+1. 対象 source を特定する（`externalId` 不明なら `search` / `find-document` で確定）
+2. `source.get`（`externalId`）で対象 source の本文を読む
+3. `propose.generate`（mode=`source_extract`）で task / decision / reply_draft 候補を生成する（それぞれ `TaskProposed` / `DecisionRecorded` / `ReplyDraftProposed` 候補に対応、[data-model.md](../../design/data-model.md)）
+4. **生成した候補一式をユーザーに提示して確認を取る**（native framing: ホスト側で人の承認を促す）
+5. ユーザーが承認した候補のみ `propose.apply` で保存する（idempotent）
+
+## 制約
+
+- HITL。人の承認なしに `propose.apply` を呼ばない。auto-apply しない
+- 本 skill は手順書のみで実処理を持たない

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@ozzylabs/suasor",
+  "version": "0.1.0",
+  "description": "A local-first AI secretary that gathers your scattered work context into private memory you and your AI agents can query over MCP. It advises you, and proposes replies, tasks, and decisions, with nothing sent or saved without your approval.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "suasor": "dist/index.js"
+  },
+  "files": [
+    "dist/index.js",
+    "docs/skills"
+  ],
+  "engines": {
+    "bun": ">=1.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.14",
+    "@types/bun": "^1.1.0",
+    "drizzle-kit": "^0.31.10",
+    "markdownlint-cli2": "0.21.0",
+    "typescript": "^5.6.0"
+  },
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "build": "bun build ./src/index.ts --target=bun --outdir=dist --external @slack/web-api --external @microsoft/microsoft-graph-client --external @azure/msal-node --external googleapis --external box-typescript-sdk-gen --external playwright-core --external @napi-rs/keyring",
+    "compile": "bun build ./src/index.ts --compile --outfile=dist/suasor --external @slack/web-api --external @microsoft/microsoft-graph-client --external @azure/msal-node --external googleapis --external box-typescript-sdk-gen --external playwright-core --external @napi-rs/keyring",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "lint": "biome check .",
+    "lint:md": "markdownlint-cli2 \"**/*.md\"",
+    "format": "biome format --write .",
+    "db:generate": "drizzle-kit generate"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ozzy-labs/suasor.git"
+  },
+  "homepage": "https://github.com/ozzy-labs/suasor",
+  "mcpName": "io.github.ozzy-labs/suasor",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@azure/msal-node": "5.2.4",
+    "@microsoft/microsoft-graph-client": "3.0.7",
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "@napi-rs/keyring": "1.3.0",
+    "@slack/web-api": "7.17.0",
+    "box-typescript-sdk-gen": "1.19.1",
+    "clipanion": "4.0.0-rc.4",
+    "drizzle-orm": "^0.45.2",
+    "googleapis": "173.0.0",
+    "octokit": "5.0.5",
+    "playwright-core": "1.60.0",
+    "sqlite-vec": "^0.1.9",
+    "zod": "^4.4.3"
+  },
+  "overrides": {
+    "uuid": "^11.1.1"
+  }
+}