opshub
AGENTS.md2 starsChanged 5 months agoMITView on GitHub
このファイルは AI エージェント向けの共通 instructions です。 opshub: Local-first assistant agent platform — auditable operational memory for humans and AI agents. Status: Phase 1-15 complete + Phase 16 complete (epic #381, 2026-06-02) + Phase 17 complete (CLI noun-first 再編、ADR-0031、PR #414) + Phase 18 complete (Slack mention / DM demand digest、ADR-0033、epic #426 = 18-A PR #431 docs + 18-B PR #433 projection + 18-C new MCP slack.demand.list + skill 拡張 + docs 一括更新) + Phase 19 complete (Slack discovery engagement axis、ADR-0034/0035、epic #438/#448 =…
- Reads credentials
In this repository32 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- announcement-draftSkill
- catchupSkill
- decision-rationaleSkill
- external-briefSkill
- find-documentSkill
- handoff-draftSkill
- inbox-triageSkill
- meeting-followupSkill
- meeting-prepSkill
- next-actionsSkill
- personal-briefSkill
- pr-reviewSkill
- reply-draftSkill
- researchSkill
- source-extractSkill
- announcement-draftSkill
- catchupSkill
- decision-rationaleSkill
- external-briefSkill
- find-documentSkill
- handoff-draftSkill
- inbox-triageSkill
- meeting-followupSkill
- meeting-prepSkill
- next-actionsSkill
- personal-briefSkill
- pr-reviewSkill
- reply-draftSkill
- researchSkill
- source-extractSkill
The file
Files
AGENTS.md
このファイルは AI エージェント向けの共通 instructions です。
基本方針
- 日本語で応答する
- 推奨案とその理由を提示する
.envファイルは読み取り・ステージングしない- 破壊的な Git 操作を避ける
設計判断のスタンス
- 過去の決定(ADR など)やこれまでの実装量にとらわれず、「あるべき姿」を優先して提案する。既存 ADR と食い違う場合は、その ADR の見直し・転換を提案してよい。
- ただし、過去の決定や実装量をまったく無視してよいわけではない。改修にかかる手間や既存設計との兼ね合いは判断材料として示したうえで、それでも「あるべき姿」を推す。
- この方針は、opshub にまだ実ユーザーがいない現段階を前提とする。1.0 リリースや実ユーザーが付いた時点で見直す。
プロジェクト概要
opshub: Local-first assistant agent platform — auditable operational memory for humans and AI agents.
Status: Phase 1-15 complete + Phase 16 complete (epic #381, 2026-06-02) + Phase 17 complete (CLI noun-first 再編、ADR-0031、PR #414) + Phase 18 complete (Slack mention / DM demand digest、ADR-0033、epic #426 = 18-A PR #431 docs + 18-B PR #433 projection + 18-C new MCP slack.demand.list + skill 拡張 + docs 一括更新) + Phase 19 complete (Slack discovery engagement axis、ADR-0034/0035、epic #438/#448 = 19-A〜D の 4 sub-PR + 19-D で --sort=name|last_self_post|last_activity 統合 + default --format=toml 切替 + BREAKING) + Phase 20 complete (Slack thread reply ingestion + Slack sync date floor、ADR-0030 landed (revised) + ADR-0036 新規、epic #465/#457 = 20-A〜D の 4 sub-PR で conversations.replies 取り込み + 2 軸 compound cursor + thread_activity_window 30d default、20 単独 PR で sync_since / per-channel since 追加) + **Phase 21 complete (Browser read layer = Playwright 採用 + web connector + MCP browser.fetch、ADR-0037 新規 + ADR-0010 §Phase 21 改訂 (n)/(o) + ADR-0022 §決定 (g) 改訂、epic #504 = 21-A PR #510 (ADR-0037 新規 + ADR-0010 改訂) + 21-B PR #511 (src/opshub/browser/core.py = Playwright sync API、Chromium / headless default / 専用 user-data-dir / page.inner_text("body") + 500K cap / BrowserFetchError、[browser] config = headless / channel / timeout / cdp_endpoint、browser extras = playwright>=1.50、CI に --extra browser + playwright install chromium 追加、browser pytest marker) + 21-C PR #513 (connectors/web/ = web_page mapper + 抽出後本文 SHA-256 fingerprint 変更検知 + opshub web sync CLI noun-first + binary 不在 ConfigError) + 21-D PR #512 (MCP browser.fetch write-category tool = WriteCategory.BROWSER_FETCH、http / https のみ、asyncio.to_thread bridge、registry policy pin test 18 → 19 tools) + 21-E (本 docs 一括 + closeout)。read 専用 = 操作系 (click / fill / submit) は HITL 承認単位 / prompt injection 対策 / ADR-0010 §禁止事項 7 整理の 3 前提が揃う後続 Phase に defer、crawler (リンク追跡 / sitemap) も非実装、認証付きページ session 管理は connect_over_cdp escape hatch の余地のみ、14 skill 体制 / SKILL.md は不変) + **Phase 22 complete (Slack sync gap backfill = floor 引き下げ時の自動取り直し、ADR-0038 新規 + ADR-0036 §Consequences 是正 (rebuild は cursor を reset しない) + §(g) を forward 限定に精緻化、epic #516 = 22-A PR #523 (ADR-0038 新規 + 壊れた rebuild ワークアラウンド是正) + 22-B PR #525 (compound cursor 3 軸化 = backfill low-water 軸追加、backfill 欠損許容の additive migration) + 22-C PR #526 (SlackFetcher bounded-window fetch = latest_per_channel + Slack 単一 inclusive 制約への適合) + 22-D PR #527 (connector gap-backfill pass = floor 引き下げ検知 → (floor_new, low_water] だけを取得、_ingest_yield で forward/gap loop 共有、low-water lifecycle、backfill_on_floor_lower config + --no-backfill flag、相対 floor 非発火) + 22-E (opshub slack cursor show / reset / backfill サブコマンド + docs closeout)。relative floor は ts 前進で誤発火せず絶対 floor 引き下げ / 撤去時のみ 1 度発火、pre-feature channel (low-water 未記録) は復元不能のため auto backfill せず opshub slack cursor backfill --until で救済、opshub projections rebuild が Slack cursor を reset しない事実を全 docs で是正。inbox ItemEnqueued の source_ref 冪等化 (#522、旧 #339 class) は hardening dependency として別 issue 化。No DB migration (cursor schema は connector_cursors.cursor_value JSON 内で additive)、MCP 19 tools 不変、14 skill 不変) + **epic #470 closeout (Pre-userbase compat shim cleanup、PR #482-#486 の 5 PR = 1) Phase{2-9}Event 別名削除 → flat AllEvent 統合 / 2) BoxDriveConnectorSettings.exclude_globs 撤廃 → excludes.yaml paths: に SSOT 集約 / 3) OneDriveDriveConnectorSettings.exclude_globs 撤廃 / 4) expand_graph opt-in flag 撤廃 + LinkService 必須化 → graph 1-hop 拡張 を無条件 baseline 化 / 5) sources.body NOT NULL 化 + migration 0030_enforce_sources_body_not_null + mapper layer の body = summary fallback、ADR-0002 / 0017 / 0019 / 0020 / 0032 改訂、docs/upgrading.md §Pre-userbase compat shim cleanup (epic #470) で migration guide pin、本 PR で audit followup として docs drift + status header sweep を整理). Phase 15 complete 2026-06-02 (epic #338); Phase 16-A pinned distribution-channel decision via ADR-0029 + ADR-0004 §決定 (c) revision (doc + test docstring realignment), Phase 16-B (#383) landed opshub skills install / opshub skills list CLI with [tool.hatch.build.force-include] bundle of docs/skills → src/opshub/_skills, Phase 16-C (#384) wired opshub init to the install path (TTY prompt + --install-skills / --no-install-skills flag, non-interactive default = install), Phase 16-D (#385) populated in-repo .claude/skills/<assistant>/ + .agents/skills/<assistant>/ dogfood mirrors + added skills-sync-check pre-commit lefthook guard (diff -rq against SSOT). Phase 1 (foundation) + Phase 2 (coordination) + Phase 3 (connector layer + workspace ingest、MVP = framework + GitHub) + Phase 4 (semantic recall layer、MVP = Pluggable Embedder + sqlite-vec + recall + 重複検出) + Phase 5 (briefing layer、MVP = ADR-0015 + Pluggable LLM (Anthropic + OpenAI) + Briefing 自動生成 + event-driven auto-embed) + Phase 6 (action loop layer、MVP = ADR-0016 + Pluggable LLM structured output (Anthropic + OpenAI + Ollama) + Proposal domain) + Phase 7 (connectors wave 2、MVP = Slack + Microsoft 365 + Box) + Phase 8 (knowledge graph layer、MVP = ADR-0017 + links projection + 4 自動抽出 + manual link CRUD + traversal + --expand-graph) complete (2026-05-17) + Phase 9 (local-filesystem-backed connector layer、MVP = ADR-0019 + sources.fingerprint (migration 0017) + box_drive connector + core/platform.py) complete (2026-05-23) + Phase 10 (Assistant Agent Platform、MVP = ADR-0020 (full local content retention、ADR-0005 supersede) + ADR-0021 (encryption at rest、SQLCipher + keyring) + ADR-0022 (MCP server surface、stdio + policy-as-data + redact + OTel naming) + ADR-0004 改訂 (形A) + ADR-0016 改訂 (reply_draft) + ADR-0017 改訂 (reply_draft link types) + ADR-0010 改訂 (write-back 明示禁止) + 本文ベース embedding (migration 0018) + SQLite FTS5 (migration 0019) + opshub search + opshub mcp serve + アシスタント 5 Skills (Phase 12 H1 で personal-brief / next-actions / reply-draft / pr-review / find-document に rename 済) + tools/skill_scan.py) complete (2026-05-31) + Phase 11 (MS Office 深掘り、MVP = ADR-0025 (Office Document Content Extraction、markitdown 経路 + 50 MB / 500K chars cap + source_type 3 種 word_document / excel_spreadsheet / powerpoint_slide_deck + fail-safe) + ADR-0019 改訂 (content_extraction = true opt-in 例外節 + onedrive_drive パターン汎化、§決定 (b') + (j)) + ADR-0010 改訂 (Teams connector 追加 + 本文抽出契約 + delta-link cursor + 失効時 full-pass fallback + Teams User Token principal、§改訂 (a)/(b)/(c)/(d)) + src/opshub/core/document_extract.py + connectors/teams/ (Microsoft Graph chat delta + User Token) + connectors/onedrive_drive/ (FS scan、WSL2 /mnt/onedrive / macOS ~/OneDrive platform default) + connectors/box_drive の Office 抽出 hook + connectors/ms365/mapper の Outlook body deep retention、epic #233) complete (2026-05-31) + **Phase 12 (Assistant Skills 拡張、MVP = 14 skills 体制 (新規 9 = meeting-prep / research / inbox-triage / external-brief / decision-rationale / handoff-draft / announcement-draft / meeting-followup / source-extract + 既存 5 のうち rename 2 = daily-brief → personal-brief / file-lookup → find-document、read 自律 OK 10 / HITL write 4) + 4 新 MCP tools (search (FTS5、ReadCategory.SEARCH) + propose.apply (HITL idempotent、WriteCategory.PROPOSE_APPLY、destructive=false) + 既存 4 read tools の physical column ベース時間フィルタ (task.list.updated_after/before / inbox.list.created_after/before / decision.list.recorded_after/before / source.list.observed_after/before)) + 既存 5 SKILL.md を MCP 直接呼びに統一 + propose.generate の mode 引数追加 (inbox_triage / source_extract / meeting_followup) + ADR 改訂 3本 (ADR-0004 改訂 (Skills SSOT を opshub docs/skills/ に移管 + Skill catalog SSOT = docs/assistant-agent.md 独立条文化) + ADR-0022 改訂 (4 新 MCP tools 契約化) + ADR-0016 改訂 (draft 系統一方針 §決定 (l): persist 境界 = 返信元 source の有無 / mode 引数射程 / triage = reply_draft 専用 / Candidate union freeze)) + docs/assistant-agent.md を 14 skills 責務マップ SSOT に拡張 (10 § 構成: §形A 責務分担 / §アシスタントへの依頼例 / §Skill catalog / §Pair structure / §HITL boundary / §MCP tool 依存マップ / §できること・できないこと / §セットアップ / §skill security / §関連)、epic #253) complete (2026-05-31) + Phase 13 (Google Workspace コネクタ、MVP = ADR-0010 改訂 (Phase 13 改訂 (e)-(h) = Google Workspace 追加 / Drive files.watch 禁止 / Workspace export 経路の本文抽出契約 / Drive changes.list cursor + TTL fallback 義務 / Refresh Token principal = MS365 / Box pattern、Teams pattern とは別系統) + ADR-0014 改訂 (§Phase 7 Validation rotation pin リストに connector:google_workspace:refresh_token を 3 件目として追加 + env override OPSHUB_CONNECTOR_GOOGLE_WORKSPACE_REFRESH_TOKEN + Phase 7 keyring keys 一覧に Phase 13 Google Workspace を追記) + ADR-0025 改訂 (§決定 (d') 新 source_type 3 種 google_doc / google_slides / google_sheets + §決定 (j) Workspace export 経路 = Drive API files.export → MS Office mediatype → markitdown 統一) + connectors/google_workspace/ (5 module 構成 = auth.py paste-code OAuth + refresh token rotation 書き戻し / client.py Drive API v3 changes.list + httpx + rate-limit retry / cursor.py page token + TTL 失効時 full-pass fallback / mapper.py Google mimeType → source_type 分岐 + provenance / connector.py content_extraction opt-in wiring + files.export 経由 markitdown 抽出 + settings) + core/document_extract.extract_workspace_export(bytes, source_type) (G2 で API 表面拡張 = path / bytes 両方、Phase 11 path-only と backward-compat) + [connectors-google-workspace] extras (httpx)、epic #274) complete (2026-05-31) + Phase 14 (Gmail + Google Calendar コネクタ、MVP = ADR-0010 改訂 (§Phase 14 改訂 (i)-(m) = Gmail + Calendar 追加 / delta-cursor 型 connector 全般への TTL fallback 一般化 ((j) = Phase 11/13 SSOT 統合) / Outlook 流本文抽出 (text/plain 優先 → text/html 生保持 / markitdown なし / 添付 retain なし) を Gmail / Calendar に適用 / Gmail unit = message 単位 + Calendar unit = master event only + override 別 record + label / attendee は summary / body 埋め込みのみ (Outlook 流) / Google OAuth principal scope 拡張 + shared auth foundation connectors/google_auth/ 抽出方針) + ADR-0014 改訂 (§Phase 7 Validation connector:google_workspace:refresh_token slot の scope を Drive → Drive + Gmail + Calendar に拡大、shared auth foundation connectors/google_auth/auth.py への抽出方針追記、新 slot 追加なし = 1 Google account = 1 principal で 3 connector 共有) + connectors/google_auth/ (Phase 13 connectors/google_workspace/auth.py の物理移動、scope 引数化 + 3-scope 固定 list drive.readonly + gmail.readonly + calendar.readonly、token rotation pin test を shared 側に集約) + connectors/google_mail/ (5 module 構成、httpx + Gmail API v1 users.messages.list initial sync + users.history.list delta + 7 日 TTL 失効時 full-pass fallback + WARN、message 単位 mapper gmail_message = Outlook と symmetric、[Labels: ...] prepend / [gmail body truncated] tag / threadId field、添付 retain なし) + connectors/google_calendar/ (5 module 構成、httpx + Calendar API v3 events.list(syncToken=...) + 410 GONE 失効時 full-pass + timeMin/timeMax window + WARN、master event mapper google_calendar = MS365 Calendar と symmetric、summary = start_iso - end_iso (N attendees) / RRULE field / attendee body 埋め込み / override は別 record として emit) + mapper symmetry pin test (tests/unit/connectors/test_mapper_symmetry.py、Outlook ↔ Gmail / ms365_calendar ↔ google_calendar の field / summary / body フォーマット同形性を機械検証)、epic #292) complete (2026-05-31) + Phase 15 (Search 品質改善 = FTS5 日本語 tokenizer trigram 化 + 短クエリ LIKE fallback、MVP = ADR-0028 新規 (FTS5 sources_fts tokenizer choice) + migration 0028_rebuild_sources_fts_trigram (sources_fts を unicode61 remove_diacritics 2 から FTS5 built-in trigram に物理張り替え + sources.body から back-fill + trigger 3 本再作成、downgrade 経路は元 tokenizer に復元) + SearchService 短クエリ LIKE fallback (src/opshub/services/search_service.py の _MIN_FTS_QUERY_CHARS = 3 閾値で 1-2 文字 query を LOWER(body) LIKE LOWER(?) full scan に routing、NFC 正規化 + ASCII case-insensitive + LIKE wildcard escape、raw_query=True で fallback bypass) + cross-cutting fix (tests/unit/mcp/test_phase12_handlers.py::_bootstrap_fts_index() の seed tokenizer を unicode61 remove_diacritics 2 から trigram に同期、production と MCP unit boundary 再整合) + opshub search --help の --raw 説明更新 + docs/troubleshooting.md §3.6 日本語 search 節追加。日本語自然文 (boxの権限 / 進捗記入 / CDKの) は default で 3 文字以上の substring が hit、短クエリ (依頼 / PR / Q4) は LIKE fallback で hit、--raw は FTS5 boolean / prefix の power-user 契約として維持。MCP search tool (ADR-0022 §決定 (f)) は raw_query hard-coded false のためアシスタント 14 Skill (find-document / research / etc.) も透過的に恩恵を受ける。形 A + 外部書き戻しなし + immutable migration 規範 (0019 は touch せず 0028 で supersede) を継承、新規 ADR 1 本 + 改訂ゼロ (Phase 11 流の単一トピック集中パターン継承、Phase 11 = 1 新規 + 2 改訂、Phase 12 = 0 新規 + 3 改訂、Phase 13 = 0 新規 + 3 改訂、Phase 14 = 0 新規 + 2 改訂、Phase 15 = 1 新規 + 0 改訂)、epic #338) complete (2026-06-02) — event store、全 projection (tasks / inbox_items / decisions / work_sessions / agent_runs / locks / handoffs / sources (Phase 10 で body + provenance_origin + provenance_trust 追加、Phase 11 で teams_message / word_document / excel_spreadsheet / powerpoint_slide_deck source_type 追加、Phase 13 で google_doc / google_slides / google_sheets / google_workspace_file source_type 追加、Phase 14 で gmail_message / google_calendar source_type 追加) / connector_cursors / ingested_files / embeddings / briefings / proposals (Phase 10 で reply_draft candidate kind 追加) / links (Phase 10 で reply_draft_replies_to / referenced_in_reply_draft link types 追加))、CLI (init / task / inbox / decision / lock / session / agent run / handoff / connector auth set (Phase 13 で google_workspace Google OAuth paste-code flow 追加) / connector sync (Phase 13 で google_workspace) / connector list / workspace ingest / workspace generate / projections rebuild / embeddings rebuild / embeddings drain / embeddings status / embeddings find-duplicates / recall / search (Phase 10) / brief / propose generate (Phase 10 で --reply-to 対応、Phase 12 H4 で mode 対応) / propose list / propose apply / propose reject / link add / link remove / link list / graph related / graph trace / graph expand / mcp serve (Phase 10) / mcp tools (Phase 10) / db migrate)、markdown 生成、11 connector (GitHub + Slack + Microsoft 365 + Box + Box Drive (FS scan) + Teams (Phase 11、Microsoft Graph chat delta) + OneDrive Drive (Phase 11、FS scan) + Google Workspace (Phase 13、Drive API v3 changes.list + Refresh Token rotation + Workspace export 経路) + Gmail (Phase 14、Gmail API v1 users.history.list delta + message 単位 + 7 日 TTL fallback、Outlook と symmetric) + Google Calendar (Phase 14、Calendar API v3 events.list(syncToken=...) + master event only + override 別 record + 410 GONE fallback、MS365 Calendar と symmetric)、Google 3 connector は Phase 14 で connectors/google_auth/ shared auth foundation = 1 Google account principal + 3-scope 固定 list drive.readonly + gmail.readonly + calendar.readonly を共有 + Web (Phase 21、Playwright browser read 層 = headless Chromium で render 後の DOM text 抽出 + 500K cap、operator が [connectors.web] pages に明示登録した URL のみ取得 = crawler 非該当、delta API なしで抽出後本文 SHA-256 fingerprint 変更検知、ADR-0037 + ADR-0010 §Phase 21 改訂 (n)/(o)、合計 11 connector)) で source_type discriminator 別に sources projection に persist (Phase 10 で本文 + provenance 取り込みに拡張、box_drive / onedrive_drive は ADR-0019 §不変条件 (b) で default body=None、Phase 11 で content_extraction = true opt-in 時のみ markitdown 経由で Office 文書 本文取り込み、Phase 13 で Google Workspace native (google_doc / google_slides / google_sheets) も同じ content_extraction = true opt-in で Workspace export → markitdown 経路を起動、Phase 14 で Gmail / Calendar 本文は Outlook 流 = text/plain 優先 → text/html 生保持で markitdown 経路を通さない)、workspace inbox file ingest、Pluggable Embedder + sqlite-vec backed VectorStore、Pluggable LLMClient (Anthropic + OpenAI + Ollama) + structured output + Briefing 自動生成 + Proposal domain (human-in-the-loop apply、Phase 10 で reply_draft mode 追加、Phase 12 で mode 引数経由の 3 dispatch key 追加) + Knowledge graph layer + event-driven auto-embed + MCP server (stdio one transport、policy-as-data registry、Phase 10 sub C + Step 1 widening PR #231 + Phase 12 H1 で計 17 tools = read 12 + write 5、Phase 18-C で slack.demand.list 追加 → 18 tools = read 13 + write 5、Phase 21-D で browser.fetch 追加 (write-category、ADR-0037 §決定 (e) + ADR-0022 §決定 (g)) → 19 tools = read 13 + write 6) + アシスタント 14 Skill (docs/skills/<name>/SKILL.md を opshub SSOT として保持、Phase 12 H1 で確定、配信経路は Phase 16-A で opshub Python package 同梱 + opshub skills install に確定 = ADR-0029、Phase 16-B/C/D で着地済 = opshub skills install CLI / opshub init 連携 / in-repo dogfood) + 保存時暗号化 ([storage] encryption = true で opt-in、SQLCipher AES-256、Phase 10 sub A、ADR-0021) が end-to-end で動作。次の候補は Phase 16+ (形態素 tokenizer 採用 (Lindera / SudachiPy / MeCab、Phase 15 で defer、trigram で operator 体験が不足する場合に ADR-0028 改訂 + tokenizer 評価) / dual index (unicode61 + trigram、Phase 15 で却下、BM25 ranking 劣化が観測されたら再評価) / opshub search rebuild-index 専用 CLI (projection rebuild 経由で十分か、需要顕在化時に切る) / MCP search tool 契約改訂 (raw_query operator 露出、ADR-0022 改訂事項) / 検索結果の semantic re-rank (vector との hybrid score、別 ADR) / snippet() ハイライト / 検索クエリの NFKC 正規化 / 全角半角統一 / multi-machine sync / 能動性段階 1-4 = cron 委譲 / 記憶キュレーション / 通知 / filewatch / Gmail push / Calendar push 再評価 / 画像 OCR (PPT 内画像 + Office 図表、tesseract / pytesseract、Phase 13 → Phase 14 → Phase 15 から繰り越し) / Drive Comments + Suggestions (Phase 13 から繰り越し) / Gmail 添付・Calendar 添付の本文抽出 (markitdown 経路、ADR-0025 拡張) / 追加コネクタ Notion / Jira / Linear / Confluence (Phase 13 から繰り越し) / 外部書き戻し = Teams 返信送信 + Gmail send + Calendar event create + HITL / Calendar instance 展開 projection (master + RRULE → instance dynamic、ms365 / google 両 calendar 同時)、詳細は docs/principles.md §9)。
Post-Phase 15 Maintenance
Phase 15 完了 (2026-06-02) 以降の改修は Phase 化されておらず、connector-level の UX 改善 / refactor / audit followup として進行する。新 ADR / 新 projection / 新 connector category を伴う作業は新 Phase で起票、それ以外は本節に追記する。時系列順:
- Slack
channels→conversations刷新 (#366 → PR #369) —users.conversationsjoined-only default + DM/MPIM 統合 +--types/--all/ 進捗表示。docs(slack)整合 PR #371 を追随。 - Slack search title 改善 (#367 → PR #368) — bot/system message fallback + body excerpt 80 字。
- Slack
conversationstype 別固定ソート +--sinceactivity filter (#374 → PR #375) —public → private → mpim → im固定順、--since 7d/--since 2026-05-01で per-convconversations.history?limit=1+LAST_ACTIVITY列、不足*:historyscope は type 単位で skip + 1 warn (exit 0)。 - Slack 429 retry /
Retry-Afterbackoff helper 集約 (#377 → PR #378、#379 → PR #380) —opshub.connectors.slack._retry.retry_on_rate_limit1 helper に集約 (3 attempts、Retry-Afterhonoured、fallback 1s / 2s / 4s exponential)、slack コネクタ内 3 call site (SlackFetcher._call_history+conversations._call_history_oldest+conversations._call_list) が share、policy 改修が 3 箇所同期 → 1 箇所更新で済む。 - Audit followup: Slack docs drift + test coverage gap closure (PR #386) —
CLAUDE.md/docs/mcp-setup.md/AGENTS.md/docs/adr/0026-cli-progress-reporting.mdの--since関連 doc 整合 4 件 +parse_sinceOverflowError /_call_list all=Trueexhaustion /_render_jsonmixed payload /_retryheaders 防御 /_fetch_last_activity_ts防御 (ts非数値 /messages非 list) /_sort_rows未知 type fallback 計 7 件の test pin。 - Slack thread ingestion 仕様 pin (ADR-0030) — 子返信は
conversations.repliesで ingest、thread_tsfield 保持、slack_threadsource_type 作らず Gmail / Outlook と symmetric (ADR-0010 §Phase 14 改訂 (k) 不変条件 3 と対称)。当初は方針 pin のみで実装を defer したが、Phase 20 (epic #465) で 4 sub-PR (20-A fetcher 拡張 / 20-B cursor compound schema / 20-C late-reply polling + activity window / 20-D ADR §(d) revise + docs sync) として landed。ADR-0030 は Accepted + Landed (revised) に昇格、§(d) は late reply scope 外 → 2 軸 compound cursor +thread_activity_window(default 30d) prune に書き換え。
Phase 16: Assistant Skill Distribution via opshub Package Bundling
新規 architectural pattern (新 ADR + 配信経路改訂) を伴うため新 Phase で起票。epic #381。
- Phase 16-A (#382) — ADR-0029 新規 + ADR-0004 §決定 (c) 改訂 + doc 一括更新 (architecture / assistant-agent / README / README.ja / mcp-setup / upgrading / CLAUDE / AGENTS の "cp -r" 手順を pointer 化) + test docstring realignment +
_skills/payload.py不在 pin (Phase 16-B 着地前は skip)。配信経路をozzy-labs/skillsRenovate preset から opshub Python package 同梱 +opshub skills installに切り替え (SSOT 位置は opshubdocs/skills/<name>/SKILL.mdで不変)。dogfood 採用 (Phase 16-D で実行)。 - Phase 16-B (#383) —
[tool.hatch.build.force-include]でdocs/skills→src/opshub/_skills同梱 +opshub skills install/opshub skills listCLI 実装 (--scope {user,project}/--host {claude-code,codex,copilot,all}/--skip-existing/--dry-run/--print-paths)。 - Phase 16-C (#384) —
opshub init連携 (--install-skills/--no-install-skillsflag、TTY 時はrich.prompt.Confirmで確認 (default = yes)、非対話 (sys.stdin.isatty() == False) は default = install でuv tool install ozzylabs-opshub[mcp] && opshub init経路を救済 (ADR-0029 §決定 (d)))。install_commandをopshub.cli.skillsからopshub.cli.initが lazy import で呼び出す構造。 - Phase 16-D (#385、ADR-0029 §dogfood 採用) — in-repo
.claude/skills/<assistant>/populate (project scope dogfood)。
Phase 17: CLI command surface reorganization (noun-first per-noun group)
新規 ADR (新 CLI 規範) を伴うため新 Phase で起票。opshub connector <verb> group を opshub <noun> <verb> (例: opshub slack sync / opshub github sync) に再編した BREAKING CHANGE (ADR-0031)。
- Phase 17-A (PR #412) — ADR-0031 新規 + 設計 pin。
- Phase 17-B (PR #414) —
opshub connectorgroup 全廃 + per-noun group 実装 + tests +docs/upgrading.md§Phase 17 で旧 → 新コマンド対応表 (PR #415)。
Phase 18: Slack mention / DM demand digest (operator 視点の「未処理 ping」signal)
新規 ADR + 新 projection を伴うため新 Phase で起票。epic #426、根拠 ADR-0033。
- Phase 18-A (PR #431) — ADR-0033 新規 + 関連 ADR cross-reference (docs only)。
opshub slack syncが既に append しているSourceObservedevent を消費する projection 経路 + 専用 MCP read tool で出荷する方針を pin。新 fetch / 新 scope (search:read) は採用しない。 - Phase 18-B (PR #433) —
slack_demand_digestprojection 実装 + Alembic migration0029_create_slack_demand_digest+opshub projections rebuild経路へ登録 + debug CLIopshub slack mentions list(--types/--demand-kind/--format)。<@self>mention literal + DM channel id prefix (D...) で demand 信号を検出し(channel_id, demand_kind)で upsert。self user_id は constructor /OPSHUB_SLACK_SELF_USER_IDenv var /SlackAuth.test_token()cascade で解決し fail-soft。 - Phase 18-C (#430) — 新 MCP tool
slack.demand.list(ReadCategory.SLACK_DEMAND_LIST、readOnlyHint=true, openWorldHint=false、types/demand_kinds/since_ts/limit/order引数) + skill 拡張 (next-actions/personal-brief/inbox-triageの SSOT にslack.demand.list経路追記) +opshub skills install --scope projectで dogfood mirror 再生成 + docs 一括更新 (mcp-setup / assistant-agent / upgrading §Phase 18-C)。MCP tool surface は 17 → 18 (read 12 → 13)、write 5 件は不変。
Phase 19: Slack discovery engagement axis (opshub slack conversations の --since default 改訂)
新 ADR + CLI default semantics 切替を伴うため新 Phase で起票。epic #438、根拠 ADR-0034。
- Phase 19-A (#440) — ADR-0034 新規 (docs only)。
opshub slack conversations --sinceの default semantics を「any-author activity」 (Phase 17 #374) から「engagement axis = 自分が発言した channel」に切替えるための設計 pin、search.messages 経由 +search:readscope 要件、--activity=mine|anyの disjoint axes 不変条件、--all + --activity=mine非両立を確定。 - Phase 19-B (#441) — Slack adapter
_fetch_self_post_index(search.messages,query=f"from:<@{self_user_id}>", cursor + legacy paging fallback, retry 共有,_to_connector_failed_searcherror mapper) +SlackConversation.last_self_post_ts追加 +list_conversations(activity=...)引数追加 + Bot Token 拒否 (ConfigError) + indexing-lag notice +engagement_index_orphandebug counter。CLI--activityflag (minedefault、anyaccept、unknown は exit 2) +--all + --activity=mine + --since非両立 (exit 1) + tableLAST_POST/ TOMLlast post YYYY-MM-DD/ JSON disjoint axis field emit + spinner description 切替。docs 一括更新 (README / CLAUDE / AGENTS / mcp-setup §scope 表search:read追加 / troubleshooting--activity=mine失敗時セクション / upgrading §Phase 19 default semantics 切替 + JSON consumer 注意 / architecture engagement 軸段落)。 - Phase 19-C (#447) — ADR-0034 §(i)
_INDEXING_LAG_NOTICE文字列 pin + negative-path tests (Phase 19-B audit followup、docs+tests only)。 - Phase 19-D (ADR-0035, epic #448) —
--activity={mine|any}flag 完全削除 →--sort=name|last_self_post|last_activityに統合 (ADR-0035 §(c))、default--formatをtable→toml切替 (§(a))、default--sort=name固定で--sinceの有無による sort flip 廃止 (§(b))、--sort=name + --sinceで engagement 軸を implicit default に (§(d))、--sort=last_self_post|last_activity+--sinceなしで暗黙--since 90dcutoff + stderr notice (§(e))。19-D-1 (#451) で ADR-0035 新規 + ADR-0034 supersede 注記、19-D-2 (#450) で adapterSortKey型 +list_conversations(sort=...)+_emit_implicit_cutoff_notice+ Bot Token / search-scope エラー文言書き換え + CLI--sortoption +--all+ engagement-axis reject 拡張 + docs 一括更新 (README / CLAUDE / AGENTS / mcp-setup / troubleshooting / upgrading / architecture)。BREAKING CHANGE:--activity削除 / default--format変更 /--since単独でsearch:read要件発生。pre-userbase で compat shim なし。
Phase 20: opshub slack sync date floor (sync_since + per-channel since)
- Phase 20 (ADR-0036, epic #457) —
opshub slack syncに opt-in の date floor を追加し、conversations.historyのoldestを bound して初回 / 新規 channel のバックフィルを抑制する。[connectors.slack]に connector-widesync_since(相対90d/4wor ISO、defaultNone= 全件、sync 実行時点で評価) + per-channelsince(継承 /"all"全件 / 独自 floor) を追加。channelsは文字列配列と[[connectors.slack.channels]]table 形式の両方を受理する additive 変更 (conversations --format=toml出力・既存 config / env をそのまま維持)。floor 解決順 channelsince→sync_since→ なし。日付パースはopshub.core.time.parse_since(typer 非依存に core へ移設、CLI--sinceは薄い wrapper、#459) +since_to_tsに集約。floor はoldest = _max_ts(cursor, floor)で cursor を authoritative に保つ (既存 sync 済み channel は inert、再取得・削除なし、floor 下げの遡及 backfill なし)。サブ issue: #458 (ADR) / #459 (parse_since 移設) / #460 (実装)。本環境のブランチ制約により 3 sub-issue を 1 PR (claude/opshub-slack-date-filter-v5pg8) に統合実装。非破壊のためfeat(slack):(minor bump)。
Phase 20 (Slack thread reply ingestion): ADR-0030 implementation
新 ADR を伴わず (ADR-0030 を Accepted + Landed (revised) へ昇格) Slack thread reply の取り込み経路を 4 sub-PR に分割して着地させた。epic #465。
- Phase 20-A (#466 → PR #474) — fetcher 拡張 (
_iter_channelでlatest_reply持ち parent についてconversations.repliesを Phase 1 で追加 fetch、messages[0]skip、reply yield 時 cursor element = 親のts) +RawSlackMessage.thread_ts: str | Nonefield +_call_repliesを_retry.retry_on_rate_limithelper の 4 番目の share 利用者として実装 +excludeskwarg で API budget guard。unit test (thread_tsfield set / cursor element / 429 retry / excludes 該当 skip) + integration test (happy path / mixed / idempotent)。 - Phase 20-B (#467 → PR #473) —
connector_cursors.cursor_valueJSON 値を旧 flat-dict{channel_id: ts}から 2 軸 compound envelope{"channels": {...}, "threads": {...}}に張り替え。旧 schema は silent migration せずConfigErrorでopshub projections rebuildを案内 (pre-userbase posture)。DB schema (Alembic migration) は touch せず、SlackFetcher.fetch_messagessignature (cursor_per_channel=) も維持 → 20-A と並行実装可能。unit test (round-trip / 両軸 empty / legacy reject / deterministic dump) + integration test (legacy reject + monotonicity)。 - Phase 20-C (#468 → PR #476) — Phase 2 late-reply polling phase 追加 (
SlackFetcher.fetch_thread_replies(channel_id, thread_ts, oldest_reply_ts)、_call_repliesにoldestkwarg +inclusive=False) +[connectors.slack] thread_activity_window(default"30d"、parse_since経路 +"all"で prune 無効化) + CLI--thread-activity-windowflag + envOPSHUB_CONNECTORS__SLACK__THREAD_ACTIVITY_WINDOW。Phase 1 で parent ingest 時にthreads軸をlatest_reply_tsで seed、Phase 2 happy path 完了時に窓超過 entry を prune (mid-iteration crash は resume-safe)。unit test 13 件 + integration test 3 件 (late-reply ingest / prune / 429 retry)。 - Phase 20-D (#469) — ADR-0030 §(d) revise (late reply scope 外 → 2 軸 compound cursor + Phase 2 polling + activity window pruning) +
## Implementation plandeferred → landed 昇格 + 不変条件節に「2 軸 compound cursor」「thread_activity_window30d default」「cold thread reactivation = limitation」追加 + Status section Accepted → Accepted + Landed (revised)。docs 一括更新 (CLAUDE / AGENTS / assistant-agent §6.6 / architecture §2.9 / troubleshooting §3.12 / upgrading §Phase 20 thread reply)。
--max-threads-per-sync cap は本 Phase では採用せず、thread_activity_window (Phase 20-C) で rate limit budget を抑える設計に確定した (conversations.replies Tier 3 50+ /min)。
Tech Stack
- Runtime: Python 3.13+ (ADR-0001)
- Package manager: uv
- Version management: mise (
.mise.toml) - CLI: Typer
- DB: SQLite + SQLAlchemy 2.x Core + Alembic
- Validation: Pydantic v2
- Vector (Phase 4): sqlite-vec (
[vector]extras, ADR-0012)
主要コマンド
uv sync # 依存関係インストール (lockfile に従う)
uv sync --locked # CI 用、lockfile からの逸脱を許さない
uv sync --extra dev # 開発用ツール (ruff/mypy/pyright/pytest) を含める
uv run opshub --help # CLI 実行
uv run pytest # テスト実行
uv run ruff check # lint
uv run ruff format # format
uv run pyright # 高速型チェック (local)
uv run mypy src # 厳密型チェック (CI)
uv run alembic upgrade head # DB migration 適用長時間 CLI (opshub <connector> sync / opshub embeddings rebuild / opshub embeddings drain / opshub projections rebuild) は stderr が TTY のとき進捗を自動表示し、ルートの --progress / --no-progress フラグまたは OPSHUB_PROGRESS 環境変数 (truthy = 1/true/yes/on、falsy = 0/false/no/off、case-insensitive) で上書きできる (ADR-0026)。Phase 17 (ADR-0031) で旧 opshub connector <verb> group は per-noun group (opshub slack sync / opshub github sync 等) に再編済 (docs/upgrading.md §Phase 17 で旧 → 新の対応表)。
トラブルシュート用にはルートに -v / -q / --debug / --log-format / --log-file フラグと対応する OPSHUB_LOG_LEVEL / OPSHUB_LOG_FORMAT / OPSHUB_DEBUG / OPSHUB_LOG_FILE 環境変数があり、トークン / 鍵 / 既知形状の secret は全 verbosity で redaction される (ADR-0027)。手順は docs/troubleshooting.md。
検証(必須)
コード変更後、報告前に以下を通すこと:
uv run ruff check— lint 通過uv run ruff format --check— フォーマット崩れなしuv run pyright— 型チェック通過 (local 用、高速)uv run pytest— テスト通過
CI では追加で uv sync --locked と uv run mypy src を実行する。
コーディング規約
- Python: インデント 4 スペース (PEP 8)
- YAML / JSON / Markdown / TOML: インデント 2 スペース
- 改行コード: LF
- ファイル末尾: 改行あり
- 行長: 100 列 (Python
[tool.ruff] line-length = 100)
規約
言語・コミット・ブランチ・PR のルールは README.md を参照すること。
<!-- begin: @ozzylabs/skills -->Available Skills
commit— 変更をステージし、Conventional Commits でコミットする。プッシュや PR 作成は行わない。commit-conventions— Conventional Commits のメッセージ生成ルール(Type/Scope 判定表、フォーマット)。他スキルから参照される。drive— Issue または指示から実装・PR 作成・セルフレビュー・修正を自動で回し、merge-ready な PR を出す。単一/複数の Issue/PR と明示依存記法に対応。オプションでマージまで実行可能。health— リポジトリ改修中に意図せず残る状態(working tree, stash, branch, worktree, PR, issue, actions など)と skill catalog 整合性を一発で確認し、16 領域のステータス表で俯瞰しつつ各項目に固定語彙の推奨アクションを inline で付与して報告する。--deep指定時は要確認項目を read-only コマンドで追加調査し、機械判定可能な範囲でラベルを格上げする。検査と提示のみで、削除・close 等の実行は行わない。implement— Issue または指示をもとに、ブランチ作成・実装計画・コード変更を行う。Issue 番号またはテキスト指示を受け取る。lint— 全リンターを自動修正付きで実行し、結果を報告する。コード品質チェック、フォーマット、型チェック、セキュリティスキャンを含む。lint-rules— 拡張子別リンター・フォーマッターのコマンド対応表と型チェックルール。他スキルから参照される。phase-issue— Phase-N tracking issue を生成する。cross-session handoff context、決定事項表、PR ごとのタスク、DoD、Phase N+1 outlook を含む構造化された issue body を組み立てて gh issue create で起票する。引数で全項目を渡す非対話モードと、不足分を補う対話モード(Claude Code companion)に対応する。pr— コミット済みの変更をリモートにプッシュし、PR を作成・更新する。review— コード変更や PR を 11 観点(perspectives)でレビューし、JSON 構造化出力 + 人間可読レポートで報告する。quick / deep モードを切替可能。PR 番号またはワーキングツリー差分を入力に取る。ship— lint・コミット・PR 作成を一括実行する。変更に対して lint → コミット → PR 作成を順に実行する統合パイプライン。sync-consumers— skills / commons の更新を sync-targets.yaml に記載された 14 consumer リポへ並列に push し、PR auto-merge まで完結させる。drive の Phase Final 仕様(worktree drift 検出 + cleanup)を踏襲する push 型同期スキル。test— ビルド・テスト・型チェックを実行し、結果を報告する。topics— GitHub topics 候補を制約検証・人気度測定・broad+narrow / 単数複数比較・ozzy-labs 慣行ハードコードで選定し、gh repo edit --add-topicで適用する。スコープは ozzy-labs 内利用のみ。
<!-- end: @ozzylabs/skills -->Adapter Files
| Agent | Configuration |
| Claude Code | CLAUDE.md, .claude/ |
| Gemini CLI | .gemini/settings.json → AGENTS.md |
| Codex CLI | AGENTS.md + .agents/skills/ |
| GitHub Copilot | AGENTS.md + .agents/skills/ |
.agents/skills/ and .claude/skills/ are distributed from ozzy-labs/skills via the @ozzylabs/skills Renovate preset, not from commons (see ADR-0016).
アシスタント 14 Skill(Phase 12 で 5 → 14 拡張: read 自律 OK 10 = personal-brief / next-actions / pr-review / find-document / meeting-prep / research / external-brief / decision-rationale / handoff-draft / announcement-draft、HITL write 4 = reply-draft / inbox-triage / source-extract / meeting-followup)の catalog は docs/assistant-agent.md を参照(10 § 構成で責務マップ / pair structure / HITL boundary / MCP tool 依存マップを集約)。Codex / Copilot CLI も MCP 経由で同じ surface を叩ける。配信経路は Phase 16-A (ADR-0029) で opshub package 同梱 + opshub skills install に確定し、Phase 16-B (#383) で CLI (opshub skills install / opshub skills list) が着地した。@ozzylabs/skills Renovate preset 経路は ecosystem 共通 skill (drive / lint / commit 等) を引き続き担当し、アシスタント 14 skill 経路から carve out される (名前空間 disjoint、ADR-0029 §決定 (h)、test test_skills_install_only_writes_14_assistant_skills で pin)。
opshub repo 自身も Phase 16-D (ADR-0029 §dogfood、#385) で in-repo dogfood している。.claude/skills/<assistant>/ (Claude Code 用) と .agents/skills/<assistant>/ (Codex CLI / Copilot CLI 用) に 14 件分の SKILL.md が project scope で commit されているため、Codex CLI / Copilot CLI も worktree root で起動するだけでアシスタント 14 Skill を発火できる (ecosystem 共通 13 skill と名前空間 disjoint、合計 27 dir)。docs/skills/<name>/SKILL.md を編集したら uv run opshub skills install --scope project で .claude/skills/<assistant>/ + .agents/skills/<assistant>/ を再生成し、結果を commit すること。drift は skills-sync-check pre-commit lefthook hook (lefthook.yaml) が SSOT (docs/skills/<name>/) と mirror (.claude/skills/<name>/ / .agents/skills/<name>/) を diff -rq で直接比較して検知する (opshub skills CLI を経由しない理由は lefthook.yaml のコメント参照: 直接比較で uv invocation round-trip を回避し hook を fast に保つ)。
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

