opshub
CLAUDE.md2 starsChanged 5 months agoMITView on GitHub
共通方針は AGENTS.md を参照(Phase 1-21 + epic #470 closeout 状態の記載含む)。以下は Claude Code 固有の設定。 Phase 21 (epic #504、ADR-0037) で *Playwright ベースの browser read 層*を新設した: (1) src/opshub/browser/core.py browser core (Chromium / headless default / opshub 専用 user-data-dir / render 後の page.inner_text("body") を 500K char cap で抽出、[browser] config = headless / channel / timeout / cdp_endpoint、browser extras = playwright>=1.50、binary は playwright install chromium が operator 手順で不在時 ConfigError)、(2) connectors/web/ web connector (web_page source_type、operator が [connectors.web] pages に明示登録した URL のみ取得 = crawler 非該当、delta API なしのため抽出後本文 SHA-256…
In this repository32 other files it gives its agents.
- AGENTS.mdAGENTS.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
CLAUDE.md
共通方針は AGENTS.md を参照(Phase 1-21 + epic #470 closeout 状態の記載含む)。以下は Claude Code 固有の設定。
Phase 21 (epic #504、ADR-0037) で Playwright ベースの browser read 層を新設した: (1) src/opshub/browser/core.py browser core (Chromium / headless default / opshub 専用 user-data-dir / render 後の page.inner_text("body") を 500K char cap で抽出、[browser] config = headless / channel / timeout / cdp_endpoint、browser extras = playwright>=1.50、binary は playwright install chromium が operator 手順で不在時 ConfigError)、(2) connectors/web/ web connector (web_page source_type、operator が [connectors.web] pages に明示登録した URL のみ取得 = crawler 非該当、delta API なしのため抽出後本文 SHA-256 fingerprint 変更検知、opshub web sync CLI、connector 数 10 → 11)、(3) MCP browser.fetch tool (ad-hoc Web ページ read、ネットワークに egress するため write-category = HITL per call、asyncio.to_thread bridge、MCP surface 18 → 19 tools = read 13 + write 6)。read 専用 — 操作系 (click / fill / submit) は ADR-0037 §決定 (f) で後続 Phase に defer。詳細は docs/upgrading.md §Phase 21 / docs/troubleshooting.md §3.13 (chromium 未 install / headless 切替 / timeout) を参照。
基本ルール
- ユーザーへの確認には
AskUserQuestionを使用する
Available Skills
スキル配信経路は 2 系統に分かれる:
- アシスタント 15 Skill (
personal-brief/next-actions/ ... /meeting-followup/catchup) は opshub Python package に 同梱 され、opshub skills installまたはopshub init経由で.claude/skills/(Claude Code 用) と.agents/skills/(Codex CLI / Copilot CLI 用) に展開される(Phase 16-A〜D、ADR-0029)。SSOT はdocs/skills/<name>/SKILL.md(ADR-0004 §決定 (c))。 - ecosystem 共通スキル (drive / lint / commit / ship / pr / review / health / implement / phase-issue / topics / commit-conventions / lint-rules / test) は
ozzy-labs/skillsに置かれ、@ozzylabs/skillsの Renovate preset 経由で配布される(handbook ADR-0016)。両系統は名前空間 disjoint で、opshub skills installはアシスタント 15 skill のみを書き込み、ecosystem 共通 skill には触れない (testtest_skills_install_only_writes_15_assistant_skillsで pin)。
開発作業用スキル
/implement— Issue または指示をもとに、ブランチ作成・実装/lint— 全リンターを自動修正付きで実行/test— ビルド・テスト・型チェックを実行/commit— 変更をステージし、Conventional Commits でコミット/pr— 変更を push し、PR を作成・更新/review— コード変更や PR をレビュー/ship— lint・コミット・PR 作成を一括実行/drive— implement + ship + review loop(Issue から merge-ready な PR まで自律駆動)
アシスタントエージェント Skills (Phase 10 で 5 Skill 開始、Phase 12 で 14 Skill 体制に拡張、Phase 25-E で catchup を加えて 15 Skill、opshub MCP 経由)
opshub は形A (ADR-0004) に基づきアシスタント 15 Skill を提供する。SKILL.md の SSOT は docs/skills/<name>/SKILL.md に置く (Phase 12 H1 で opshub を SSOT に確定、ADR-0004 §決定 (c))。配信経路は Phase 16-A (ADR-0029) で opshub package 同梱 + opshub skills install に確定し、Phase 16-B (#383) で CLI が着地した (opshub skills install / opshub skills list、--host / --scope / --skip-existing / --dry-run / --print-paths flag、詳細は docs/assistant-agent.md §8)。ecosystem 共通 skill (drive / lint / commit 等) は引き続き @ozzylabs/skills Renovate preset 経由で配布される (アシスタント 15 skill 経路と名前空間 disjoint、test test_skills_install_only_writes_15_assistant_skills で pin)。発火条件は自然文 (skill description) で表現されており、自分で叩く必要はない。
opshub repo 自身も Phase 16-D (ADR-0029 §dogfood、#385) で in-repo dogfood している。.claude/skills/<assistant>/ (Claude Code 用) と .agents/skills/<assistant>/ (Codex CLI / Copilot CLI 用) に 15 件分の SKILL.md が project scope で commit されており、opshub maintainer は worktree root で Claude Code / Codex CLI / Copilot CLI を起動するだけでアシスタント 15 Skill を発火できる (ecosystem 共通 skill 13 件 = commit / commit-conventions / drive / health / implement / lint / lint-rules / phase-issue / pr / review / ship / test / topics と名前空間 disjoint、合計 28 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 に保つ)。
read 自律 OK (11 件):
personal-brief— 「今日のまとめ」「今週どうなってる」「先月の振り返り」「最近どうなってる」「状況教えて」next-actions— 「次に何やる?」「やること教えて」「今週やること」「優先度高いのは?」pr-review— 「PR #N レビューして」「この差分どう?」find-document— 「Box にあったあの資料」「<キーワード>含むファイル」 (Phase 12 H1 でsearchFTS5 MCP tool 直接利用)meeting-prep(Phase 12 H2) — 「来週の会議準備」「明日のミーティング前確認」research(Phase 12 H2) — 「<X>について調べて」「<トピック>網羅的に教えて」external-brief(Phase 12 H3) — 「上司向け週次報告」「クライアント向け進捗まとめ」 (pair = personal-brief)decision-rationale(Phase 12 H3) — 「あの決定はなぜ」「X を選んだ理由」handoff-draft(Phase 12 H5) — 「引き継ぎ書作って」「handoff 書く」 (text-only、persist なし)announcement-draft(Phase 12 H5) — 「リリース告知文書いて」「announcement 作って」 (text-only、persist なし)catchup(Phase 25-E) — 「前回見て以降どうなった」「久しぶりに状況確認」「差分だけ教えて」 (seen-marker を前進させる、pair = personal-brief)
HITL write (4 件) (外送信なし、apply は HITL):
reply-draft— 「これに返信案考えて」「下書き作って」 (idempotent apply)inbox-triage(Phase 12 H4) — 「受信箱整理して」「inbox 仕分けて」 (pair = source-extract)source-extract(Phase 12 H4) — 「この資料から task 抽出」「<source_id> から候補を」meeting-followup(Phase 12 H4) — 「会議後の action items」「議事録から task 抽出」 (pair = meeting-prep)
詳細 (責務マップ / pair structure / MCP tool 依存マップ / HITL boundary) は docs/assistant-agent.md を参照。MCP セットアップは docs/mcp-setup.md。
Skills の共通ルール
- スキル完了時のネクストアクション提案には
AskUserQuestionを使用する - ネクストアクションはユーザーの確認なく実行しない
長時間 CLI の進捗表示
長時間 CLI (opshub <connector> sync / opshub slack conversations / opshub embeddings rebuild / opshub embeddings drain / opshub projections rebuild) は TTY 時に進捗を自動表示し、--progress / --no-progress フラグまたは OPSHUB_PROGRESS 環境変数 (truthy = 1/true/yes/on、falsy = 0/false/no/off、case-insensitive) で上書きできる (ADR-0026)。opshub slack conversations は Phase 19-D (ADR-0035) で --activity={mine|any} flag を廃止し --sort=name|last_self_post|last_activity に統合した。default は --sort=name (display_name 昇順) + --format=toml ([connectors.slack] channels に直接貼れる)。--sort=last_self_post は engagement 軸 (search.messages 経由、search:read User Token 必須)、--sort=last_activity は any-author 軸 (conversations.history per-row、*:history scope 必須) を起動する。Phase 23-G (#537) で sort 軸を直交化した: 活動軸は --sort 明示でのみ選択され、--since は「選んだ軸の ts で絞る純粋 filter」(scope/token を追加要求しない)。旧 --sort=name + --since の暗黙 engagement default (ADR-0035 §(d)) は撤去され、--sort=name + --since は ConfigError exit 1 で activity 軸 (--sort=last_self_post / --sort=last_activity) の明示を誘導する。spinner 説明文は engagement 軸経路で "listing conversations + engagement"、any 軸経路で "listing conversations + activity"、probe なしで "listing conversations"。table の追加列は engagement 軸で LAST_POST (YYYY-MM-DD UTC、last_self_post_ts)、any 軸で LAST_ACTIVITY (last_activity_ts); TOML コメントは engagement 軸で "last post YYYY-MM-DD"、any 軸で "last YYYY-MM-DD"。engagement 軸経路では 1 度だけ stderr に notice: search.messages may lag by minutes; use --sort=last_activity for live activity. が出る (indexing lag advisory、ADR-0034 §(i) 継承、-q / OPSHUB_LOG_LEVEL の影響を受けない、完全 suppress したい場合は --sort=last_activity を明示)。--sort=last_self_post|last_activity を --since なしで指定すると暗黙 --since 90d cutoff が当たり、stderr に notice: --sort=<sort> defaulted to --since 90d to cap probe cost; pass --since explicitly to override. が 1 度出る (ADR-0035 §(e))。Phase 23-G でこの解決済み cutoff 日付を出力にも刻む (TOML/table の # activity window: since YYYY-MM-DD (90d default; pass --since to widen)、stderr notice だけでなく artifact 内で可視化)。engagement 軸経路 (--sort=last_self_post) は Bot Token で ConfigError (--sort=last_activity への切替を誘導する)。--all + engagement 軸経路は非両立 (engagement 軸は self-member channel しか index しないため) で ConfigError exit 1 する; --all + --sort=last_activity は workspace-wide any-author 軸として受理される。JSON 出力は populated 軸の field のみ emit する (どちらの軸でも他方の field は drop される)。opshub connector group は Phase 17 で全廃止 (ADR-0031、docs/upgrading.md §Phase 17 / §Phase 19-D で旧 → 新コマンドの対応表を参照)。opshub slack sync は Phase 20 (ADR-0036) で date floor を追加した: [connectors.slack] sync_since (相対 90d/4w or ISO 2026-01-01、default None = 全件、相対は sync 実行時点で評価) が connector-wide 既定 floor、per-channel [[connectors.slack.channels]] since が上書き (since = "all" で当該 channel だけ全件)。channels は従来の文字列配列 ["C0123"] と新 table 形式 [[connectors.slack.channels]] id=... の両方を受理する (additive、conversations --format=toml 出力もそのまま有効)。floor は oldest = _max_ts(cursor, floor) で cursor を authoritative に保つため、既存 sync 済み channel に後から sync_since を効かせても再取得・削除は起きない。floor を下げたときの過去取り直しは Phase 22 (ADR-0038) の 自動 gap backfill (compound cursor の per-channel low-water backfill 軸 + bounded fetch、feature 着地後に sync された channel で発火・相対 floor は ts 前進のため非発火) + 明示 opshub slack cursor backfill --channel <id> --since <new> [--until <old>] が担う。opshub projections rebuild は Slack cursor をリセットしない (replay で ConnectorSyncCompleted を流し直し同値復元するため、ADR-0038 §Context で旧記述を是正)。
opshub slack sync は Phase 20 (ADR-0030 revised + landed) で thread reply (late reply 含む) も含む message 単位の全量取得 に拡張された (Gmail / Outlook と symmetric)。1 回の sync は Phase 1 (conversations.history で親 + latest_reply 持ち親について conversations.replies 即時 fetch、messages[0] は親自身なので skip) と Phase 2 (threads 軸 cursor を持つ既知 thread について conversations.replies(oldest=threads_cursor, inclusive=False) で late reply のみ追加 fetch) の 2 phase 構成。cursor schema は Phase 20-B で {"channels": {...}, "threads": {...}} の 2 軸 compound に拡張され、旧 flat-dict は silent migration せず ConfigError で reject する (pre-userbase posture)。Phase 23-A (#531) でこの reject メッセージの誘導先を opshub projections rebuild (flat-dict event payload を replay して同形に戻す dead-end) から opshub slack cursor reset --all (cursor を parse せず空 compound で hard-drop = 唯一の working 回復経路) に是正した。late reply polling 対象を絞るため [connectors.slack] thread_activity_window (default "30d"、CLI --thread-activity-window / env OPSHUB_CONNECTORS__SLACK__THREAD_ACTIVITY_WINDOW で上書き、"all" で prune 無効化) を設け、Phase 2 happy path 完了時に窓を超えた threads 軸 entry を prune する (mid-iteration crash は resume-safe のため prune しない)。窓経過後の cold thread に late reply が来ても本経路では追従せず (意図された limitation)。opshub projections rebuild は cursor をリセットしない (replay で同値復元するため) ので取り直しには使えず、実際に機能する cursor 操作は Phase 22-E (ADR-0038 §(f)) で着地し、Phase 23-F (#536) で 日常 = opshub slack status(読み取り) / 復旧 = opshub slack cursor(書き換え) の二層に整理された。opshub slack status が 3 軸 cursor を人間語で表示 (前進取得済み=high-water / 過去取得下限=low-water(無記録なら「先頭まで」) / 追跡中スレッド数 + 「次回 sync で過去取り直し予定」=実効 floor < low-water。cursor は再開点であって被覆台帳ではないため high/low water を別事実として出し連続被覆は主張しない)、opshub slack status --verbose が生 3 軸 + raw ts の pretty-print (旧 opshub slack cursor show を昇格・置換)。opshub slack cursor reset [--channel C1,C2 | --all] が working cursor reset、opshub slack cursor backfill --channel <id> --since <new> [--until <old>] が明示 bounded backfill (pre-feature channel の救済主経路)。cursor group は help から隠さない (障害時の命綱、flat-dict エラーが cursor reset --all を案内する整合性)。Phase 23-H (#538、ADR-0039) で single-workspace を non-goal に pin し team_id bind guard を入れたが、Phase 24 (epic #552、ADR-0041、ADR-0039 を supersede) で 1 install = N Slack workspace を first-class 化した。workspace は operator が付ける alias (操作層 = config / CLI / keyring) と Slack の team_id (データ層 = 不変 id) の二層 identity で識別する: (1) config は flat [connectors.slack] channels を廃し [connectors.slack.workspaces.<alias>] table 必須 (旧 flat 形式は ConfigError、単一構成でも table 必須・暗黙 default なし。alias 文法 ^[a-z0-9][a-z0-9_]*$、- 不許可。floor 解決 3 段 = per-channel since → per-workspace sync_since → connector-wide sync_since、thread_activity_window も per-workspace override 可。env は OPSHUB_CONNECTORS__SLACK__WORKSPACES__<ALIAS>__CHANNELS)、(2) keyring は install-wide connector:slack:token 固定を廃し per-alias slot connector:slack:<alias>:token (env override OPSHUB_CONNECTOR_SLACK_<ALIAS>_TOKEN)、(3) external_id を f"{channel_id}:{ts}" から f"{team_id}:{channel_id}:{ts}" の 3-token に re-key (workspace 跨ぎの channel id 衝突を team_id prefix で名前空間分離)、(4) cursor は 4 軸 shape (channels/backfill/threads/team_id) ごと per-alias nest {"workspaces": {"<alias>": {...}}} に移す (旧 23-H top-level shape は silent migration せず ConfigError で opshub slack cursor reset --all を案内)、(5) bind guard を per-alias 一般化 (各 alias cursor が自分の team_id を bind、token 差し替え mismatch / 2 alias が同一 team_id に解決 → ConfigError loud)、(6) per-workspace self-id: digest の self user id を install-wide 単一から {team_id: self_user_id} map に置換 (per-alias SlackAuth(alias).test_token() 解決、env override は team-qualified OPSHUB_SLACK_SELF_USER_ID__<ALIAS>=T...:U...。旧 install-wide OPSHUB_SLACK_SELF_USER_ID は廃止)。connector instance は name = "slack" 単一のまま (multi-instance 化は不採用)。opshub slack sync (flag なし) は 全 workspace を直列 sync (per-workspace error isolation: 1 workspace 失敗が他の進捗を巻き込まず checkpoint で前進保存、失敗 alias を stderr 列挙して非ゼロ exit); --workspace <alias> で絞り込み。auth set/auth test/conversations/cursor backfill/cursor reset --channel は --workspace を受理し default 解決 (1 workspace → 省略可 / 0・複数 → 必須)。opshub slack status は per-workspace block で全 alias の bound workspace を表示。conversations --format=toml は [connectors.slack.workspaces.<alias>] block を emit。MCP connector.sync は常に全 workspace、MCP slack.demand.list 出力に workspace field ({team_id, alias}) を追加。既存 install の upgrade path は DB 再 init + 全 connector re-sync (external_id re-key で旧行と重複するため、re-key migration は作らず pre-userbase hard flip。Slack 以外の connector データも再取得になる、ADR-0041 §(e) / docs/upgrading.md §Phase 24)。複数 workspace の詳細手順は docs/slack-setup.md §9、ConfigError 集は docs/troubleshooting.md §3.14。Phase 23-I (#539、ADR-0040) で feature→scope 対応表の SSOT を src/opshub/connectors/slack/scopes.py (FEATURE_SCOPES const) に一本化した (旧 auth.py docstring / conversations.py:_HISTORY_SCOPE_FOR_TYPE / ADR 散文の 6+ 箇所散在を解消、ADR は data を二重に持たず参照のみ)。opshub slack auth test は granted scope + principal から導出した features: readiness ブロック (READY / MISSING <scope> / N/A (User Token only)、追加 API コール 0) を stdout に表示する。readiness は scope レイヤ限定の capability model で config も channel membership も読まない (membership = not_in_channel は別レイヤとして footnote で 1 度明示)。listing は readiness 対象外 (conversations が per-type missing_scope を self-report 済)。conversations.py:_HISTORY_SCOPE_FOR_TYPE は scopes.py 由来に repoint (挙動不変)。
トラブルシュート用オプション
全サブコマンドに共通の -v / -q / --debug / --log-format / --log-file フラグと OPSHUB_LOG_LEVEL / OPSHUB_LOG_FORMAT / OPSHUB_DEBUG / OPSHUB_LOG_FILE 環境変数で verbosity を制御できる。トークン / 鍵 / 既知形状の secret は全 verbosity で redaction される (ADR-0027)。手順は docs/troubleshooting.md。
opshub search の日本語クエリ
Phase 15 (ADR-0028、epic #338) で sources_fts の tokenizer を FTS5 built-in trigram に張り替え + SearchService に短クエリ LIKE fallback を入れたため、日本語自然文 (boxの権限 / 進捗記入 / CDKの) は default mode で 3 文字以上の substring を hit する。1-2 文字の短クエリ (依頼 / PR / Q4) は LOWER(body) LIKE LOWER(?) 経路 (full scan、raw_query=False 時のみ) で hit する。--raw は FTS5 boolean / phrase / prefix を直接書きたい power-user 向けに維持 (例: box* AND 権限*)、短クエリ fallback は無効化される。MCP search tool (ADR-0022 §決定 (f)) は raw_query hard-coded false のためアシスタント 15 Skill (find-document / research / etc.) も透過的に恩恵を受ける。発火しないときの調査は docs/troubleshooting.md §3.6 を参照。
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.

