autonomous-common

Autonomous Common Infrastructure

autonomous-dev、autonomous-review、autonomous-dispatcher が使用する、ワークフローを強制する共通フックと、エージェントから呼び出せるユーティリティスクリプトです。他の autonomous-* スキルはここにあるスクリプトとフックを参照します。参照パスが壊れた場合は、通常このスキルを確認してください。

開発／レビュー時の任意の学習内容の記録、スコープを指定した事実の改訂、ローカル環境への参照、またはマージ後のドキュメントへの書き戻しについては、 references/session-knowledge.md を参照してください。評価の結果、更新不要と報告される場合があります。有用なドキュメント差分がある場合にのみ、コミット／PR が作成されます。

npx skills add ユーザー向けのセットアップ

npx skills add の実行後、プロジェクトのルートからコーディングエージェント用インストーラーを一度実行してください。

エージェント	インストーラー	書き込み先
Claude Code	bash .claude/skills/autonomous-common/scripts/install-claude-hooks.sh	.claude/settings.json
Qoder	bash .claude/skills/autonomous-common/scripts/install-qoder-hooks.sh	.qoder/settings.json
Antigravity	bash .claude/skills/autonomous-common/scripts/install-antigravity-hooks.sh	.antigravity/hooks.json
Cursor	bash .claude/skills/autonomous-common/scripts/install-cursor-hooks.sh	.cursor/hooks.json
Kiro CLI	bash .claude/skills/autonomous-common/scripts/install-kiro-hooks.sh [--agent <name>]	.kiro/agents/<name>.json（デフォルト：default）
Gemini CLI	bash .claude/skills/autonomous-common/scripts/install-gemini-hooks.sh	.gemini/settings.json
Codex CLI	bash .claude/skills/autonomous-common/scripts/install-codex-hooks.sh（Python 3.11+）	.codex/hooks.json + .codex/config.toml
Windsurf	bash .claude/skills/autonomous-common/scripts/install-windsurf-hooks.sh	.windsurf/hooks.json
Kimi CLI	bash .claude/skills/autonomous-common/scripts/install-kimi-hooks.sh [--project]	~/.kimi/config.toml（デフォルト。--project を指定すると .kimi/config.toml に書き込みます）

各インストーラーは、プロジェクトスコープでワークフローフックを設定します。そのため、autonomous-* スキルが明示的に読み込まれている場合だけでなく、リポジトリ内のすべてのシェルコマンドでフックが実行されます。これを設定しない場合、スキルのフロントマターで宣言されたフックコマンドは、会話内でスキルが有効な間しか実行されません。これは #68 で修正されたリグレッションです。

エージェントごとのスキーママッピングについては、docs/cross-agent-hooks.md を参照してください。

プロジェクト側の scripts/ と hooks/ のシンボリックリンク

上記の IDE インストーラーが書き込むのは、IDE の設定ファイル（例：.claude/settings.json）だけです。プロジェクト側の <project>/scripts/ シンボリックリンク（dispatcher-tick.sh が autonomous-dev.sh、lib-agent.sh などを見つけられるようにするもの）と、<project>/hooks ディレクトリのシンボリックリンクは、IDE に依存しない別のブートストラップスクリプトで管理します。これは、プロジェクトの scripts/ にすでにプロジェクト固有のファイルがある場合の標準的なパターンです。

# From your project root, after `npx skills add`:
bash .agents/skills/autonomous-common/scripts/install-project-hooks.sh

このスクリプトの処理：

• インストール済みの autonomous-dispatcher/scripts/ にあるすべての *.sh を <project>/scripts/ にシンボリックリンクします。autonomous.conf やプロジェクトごとのデプロイ用ヘルパーなど、実体のある（シンボリックリンクではない）プロジェクト固有のファイルは上書きしません。
• アップストリームでファイルが削除された場合、リンク先のないシンボリックリンクを削除します。
• <project>/hooks → autonomous-common/hooks のシンボリックリンクを作成します（既存の実ディレクトリを隠すことはありません）。
• ワークツリーごとの git pre-push フックをインストールします（#65）。--no-git-hook でスキップできます。

冪等性があるため、npx skills update のたびに再実行してください。新たに追加されたアップストリームのファイル（このスキルセットに新しい lib-*.sh が追加された場合など）が自動的に反映されます。これにより、ファイルごとに ln -s を実行する方法をそのまま真似たプロジェクトが新しいファイルを見落とし、レビュー処理が始まる前に、存在しないファイルを source しようとして autonomous-review.sh が停止するという、#153 の背後にあった気づきにくい差異の発生を防ぎます。

レガシーなディレクトリ単位のフォールバック（非推奨）

以前のドキュメントでは、プロジェクトの scripts/ ディレクトリを単一のシンボリックリンクに置き換える方法が提案されていました。

ln -sf .claude/skills/autonomous-dispatcher/scripts scripts   # DEPRECATED

この方法では、scripts/ にあるプロジェクト固有のファイルが失われます。代わりに install-project-hooks.sh を使用してください。プロジェクト固有の内容がすでにあるディレクトリでも適切に処理され、再実行すると上流の変更を取り込みます。

必須の Claude Code プラグイン

Claude Code のみが対象です。インストーラーがこれらの追加を促します。手動でインストールする場合は、.claude/settings.json の enabledPlugins に追加してください。

{
  "enabledPlugins": {
    "code-simplifier@claude-plugins-official": true,
    "pr-review-toolkit@claude-plugins-official": true
  }
}

フックに対応していない IDE（Cursor、Windsurf）では、インストーラーとシンボリックリンクの両方をスキップします。スキルはフックなしでも動作しますが、ワークフローの手順は手動で実行する必要があります。

内容

• hooks/ — ワークフロー強制用フック（block-push-to-main、block-commit-outside-worktree、check-pr-review、check-shellcheck、verify-completion、…）。正式な一覧と各フックの動作については、hooks/README.md を参照してください。
• scripts/ — 開発・レビュー用スキルで使用する、エージェントから呼び出し可能なユーティリティ：
  • session-knowledge.sh / session-knowledge.py — 非公開の共有タスク記録、任意の検証済み候補、ローカルナレッジ、および分離されたドキュメントのコミット（Python 標準ライブラリ）
  • install-project-hooks.sh — IDE に依存しないプロジェクト側のブートストラップ：ディスパッチャーの *.sh を <project>/scripts/ にシンボリックリンクし（プロジェクト固有のファイルは上書きしません）、<project>/hooks をシンボリックリンクし、リンク切れを削除し、git の pre-push フックをインストールします。npx skills update のたびに再実行してください（#153 を解決）
  • lib-installer.sh — 各エージェント用インストーラーが使用する、共有のマージ／書き込みヘルパー
  • lib-installer-translate.sh — 類似実装のエージェント向けスキーマ変換ヘルパー（イベント名マップ、ツール名マップ、タイムアウト単位変換）
  • install-claude-hooks.sh — Claude Code インストーラー（.claude/settings.json に書き込みます）
  • install-qoder-hooks.sh — Qoder インストーラー（.qoder/settings.json に書き込みます。スキーマは Claude Code と同じです）
  • install-antigravity-hooks.sh — Antigravity インストーラー（.antigravity/hooks.json に書き込みます。フック専用ファイルです。仕様はコミュニティの観察に基づくもので、Google によるドキュメントはありません）
  • install-cursor-hooks.sh — Cursor インストーラー（.cursor/hooks.json に書き込みます。version: 1 のエンベロープ、キャメルケースのイベント、Shell マッチャーを使用します）
  • install-kiro-hooks.sh — Kiro CLI／Amazon Q インストーラー（.kiro/agents/<name>.json に書き込みます。キャメルケースのイベント、execute_bash／fs_write マッチャー、ミリ秒単位の timeout_ms を含むエージェント定義です）
  • install-gemini-hooks.sh — Gemini CLI インストーラー（.gemini/settings.json に書き込みます。BeforeTool／AfterTool イベント、run_shell_command／write_file／replace マッチャーを使用します）
  • install-codex-hooks.sh — Codex CLI インストーラー（Python 3.11 以降の tomllib が必要です。ワークツリーのルートから解決可能な .codex/hooks.json を生成し、正式な [features] hooks = true を設定し、非推奨の codex_hooks エイリアスを安全に移行します）
  • install-windsurf-hooks.sh — Windsurf インストーラー（.windsurf/hooks.json に書き込みます。スネークケースのイベントにマッチャー情報を統合し、ツールごとのマッチャーフィールドはありません）
  • install-kimi-hooks.sh — Kimi CLI インストーラー（デフォルトではユーザーレベルの ~/.kimi/config.toml に書き込みます。--project を指定すると .kimi/config.toml に書き込みます。TOML の [[hooks]] ブロックを出力します）
  • claude-settings.template.json — すべてのエージェント用インストーラーが適用する正式なフック一覧
  • gh-as-user.sh — 実ユーザーとして gh を実行します（/q review などでボットのレビューを再実行する際に必要です）
  • mark-issue-checkbox.sh — エージェントから GitHub イシュー本文のチェックボックスを切り替えます
  • reply-to-comments.sh — PR のレビューコメントに返信します
  • resolve-threads.sh — PR のレビュースレッドを一括で解決します

フックとスクリプトの詳細は、それぞれの README／ソースファイルに記載されています。この SKILL.md では、編集するファイルを見つけやすいように、利用可能なものを一覧にしています。