セットアップ
このスキルは、採用側プロジェクトがコミットする唯一のフレームワーク成果物です。
他のすべての Apache Magpie スキル（セキュリティ、PR管理、課題管理）は、このスキルが管理するgitignoredなスナップショット <snapshot-dir> へのシンボリックリンクです。
採用モデルは スナップショット + エージェントオーバーライド + ドリフト認識更新 です（サブモジュール、マーケットプレイス、ベンダーコピーではありません）。
- フレームワークは
<snapshot-dir>にダウンロードされ、採用側リポジトリでは gitignored になります。スナップショットはビルド成果物であり、ソースコードではありません。 - 3つのインストール方法がサポートされています（詳細は
docs/setup/install-recipes.mdのコピー＆ペースト可能なレシピを参照）:- svn-zip — ASF配布サイトからダウンロードするリリース版の署名付きzip（リリースが出たら本番環境で推奨）。
- git-tag — 特定のgitタグに固定。
- git-branch — ブランチの先端を追跡（デフォルトは
main、開発中ブランチ）。
- 2つのロックファイルがフレームワークのバージョンを記録します。コミットされたロックファイルはプロジェクトが固定するバージョンを宣言し、ローカルロックファイルは各マシンが実際に取得したものを記録します。両者のドリフトは
/magpie-setup upgradeによって検出され、修正されます。 - シンボリックリンクにより、フレームワークのスキルが採用側リポジトリにあるかのように呼び出せるようになります。各シンボリックリンクの名前は
magpie-<framework-skill>です。すべてのフレームワークスキルはmagpie-プレフィックスでインストールされるため、名前空間が分離され、採用側のスキルと衝突することはありません（例：スナップショットのskills/pr-management-triage/はmagpie-pr-management-triageとなり、/magpie-pr-management-triageとして呼び出されます）。.agents/skills/が唯一の正規の設置場所です。その中にあるmagpie-*エントリは<snapshot-dir>/skills/<framework-skill>/へのリンクです。他のすべてのエージェントターゲット（.claude/skills/、.github/skills/など）には、スキルごとに正規エントリを指すリレーシンボリックリンクが張られます（.claude/skills/magpie-<n>→../../.agents/skills/magpie-<n>）。採用側プロジェクトが以前どのようなレイアウトを使っていたかは関係ありません（agents.md参照）。シンボリックリンクは gitignored です。新しいクローンでは/magpie-setupが実行されるまでリンク先が存在しないからです。 - フレームワークワークフローに対する採用側固有の変更は、
.apache-magpie-overrides/<skill-name>.mdにエージェントが読み取れる指示として保存されます（コミットされます）。これらはフレームワークのスキルが実行するはずの手順を無効化または変更します。契約についてはoverrides.mdを、設計根拠についてはdocs/setup/agentic-overrides.mdを参照してください。
ローカルセルフアドプション（フレームワークチェックアウトのみ）。 Apache Magpie フレームワークのチェックアウト自体は、スナップショット機構で採用できません。フレームワークのリモートスナップショットを自分自身に取り込むのは循環参照になるからです。代わりに method:local でセルフアドプションします。.agents/skills/ 内の各正規の magpie-<skill> は、リポジトリ内の ../../skills/<skill>/ ソースへの コミットされた シンボリックリンクであり、他のすべてのアクティブなエージェントターゲット（agents.md）— .claude/skills/（Claude Code）、.github/skills/（GitHubのスキルローダー）、およびその他の存在するターゲット — には、コミットされた リレー シンボリックリンク（magpie-<skill> → ../../.agents/skills/magpie-<skill>）が張られます。スナップショットもリモートフェッチもコピーもありません。これにより、フレームワーク開発中にフレームワーク自身のスキルを呼び出せ、すべてのコントリビューターがセットアップ不要で新しいクローンでスキルを有効にできます。adopt はフレームワークチェックアウトを構造的に検出し、自動的にそのルートにルーティングします（adopt.md → ローカルセルフアドプション 参照）。
2つのロックファイル
フレームワークのロックファイルモデルは、プロジェクトが固定するもの（コミット済み）とこのマシンが実際に取得したもの（ローカル）を分離します。この分離がドリフト検出とマルチインストーラサポートの基盤です。
<committed-lock> — .apache-magpie.lock
採用側リポジトリのルートにコミットされます。プロジェクトの固定バージョンです。/magpie-setup 以外で編集しないでください。手動で変更してはいけません。
# .apache-magpie.lock — コミット済み。プロジェクトの固定バージョン。
method: <git-branch | git-tag | svn-zip>
url: <各メソッドの形式については以下を参照>
# method=git-branch の場合:
ref: main
# method=git-tag の場合:
ref: v1.0.0 # タグ名
commit: <SHA> # コミット時にタグが指していたコミット
# method=svn-zip の場合:
ref: 1.0.0 # バージョン番号
sha512: <hash> # リリースzipのSHA-512（再取得検証用）
次に /magpie-setup adopt を実行する採用者はこのファイルを読み込み、プロジェクトが宣言した同じバージョンを再インストールします。これが「一度採用すれば、後続のすべてのユーザーが同じものを得る」という約束の核心です。
<local-lock> — .apache-magpie.local.lock
採用側リポジトリのルートにgitignoredで配置されます。ローカルスナップショットのフィンガープリントです。このマシンが何をいつ取得したかを記録します。
# .apache-magpie.local.lock — gitignored。マシンごとの設定。
source_method: <git-branch | git-tag | svn-zip>
source_url: <スナップショットが実際に取得されたURL>
source_ref: <実際に取得されたブランチ / タグ / バージョン>
fetched_commit: <現在ディスク上にあるコミットSHA>
fetched_at: <ISO-8601タイムスタンプ>
すべてのフレームワークスキルの呼び出し時に、このファイルと <committed-lock> を比較し、不一致があれば /magpie-setup upgrade の提案としてドリフトを通知します。
このディレクトリの詳細ファイル
| ファイル | 目的 |
|---|---|
adopt.md | 初回採用の手順 — 既存スナップショットかブートストラップ必要かを認識、2つのロックファイルの書き込み、ユーザーにどのスキルファミリーを配線するか質問、gitignoredなシンボリックリンクの作成、.apache-magpie-overrides/ のスキャフォールディング、ポストチェックアウトフックのインストール、プロジェクトドキュメントの更新。デフォルトのサブアクション。 |
upgrade.md | コミットされたロックに従ってgitignoredなスナップショットをリフレッシュ、エージェントオーバーライドとシンボリックリンクを新しいフレームワーク構造に合わせて調整、競合を表面化。ドリフト修正フローを駆動。 |
verify.md | 読み取り専用のヘルスチェック — スナップショットが存在し無傷、両方のロックファイルが同期、シンボリックリンクが有効なターゲットを指している、.gitignore が正しい、.apache-magpie-overrides/ が存在する、ドリフト状態（コミット済み vs ローカル）、setup スキル自体が最新。 |
agents.md | エージェントターゲットのレジストリ — フレームワークスキルのシンボリックリンクがベンダー間でどのディレクトリに配置されるか、および正規＋リレーモデル：.agents/skills/ が唯一の正規設置場所（スナップショット/ソースへのリンク）。他のすべてのターゲット（claude-code、github、Windsurf / Goose などのホールドアウト）には、スキルごとに .agents/skills/ へのリレーシンボリックリンクが張られる。アクティブターゲットの選択、SKILL.md 形式の移植性、Claude Code 専用レイヤー（サンドボックス/フック）を定義。すべてのサブアクションがターゲットセットを参照するための信頼できる情報源。 |
overrides.md | エージェントオーバーライドファイルの管理 — フレームワークスキル用のオーバーライドを開く/スキャフォールドする、既存のオーバーライドを一覧表示する、アップグレード時にフレームワークが基盤となるスキルの構造を変更した場合の調整を支援する。 |
unadopt.md | 採用の解除 — スナップショット、ロック、シンボリックリンク、ポストチェックアウトフック、.gitignore エントリ、README.md / AGENTS.md / CONTRIBUTING.md の採用セクション、およびコミットされた setup スキル自体を削除。デフォルトでは .apache-magpie-overrides/ を保持。--purge-overrides でそれも削除。書き込み前に完全な削除計画を表示。 |
黄金のルール
黄金のルール 1 — スナップショットを決して変更しない。 <snapshot-dir> はビルド成果物であり、gitignoredされ、採用側の視点からは読み取り専用です。採用側が行いたいすべての変更は .apache-magpie-overrides/ に記述する必要があります（そこではコミットされ、次の upgrade 後も存続します）。このスキルや、実行時にオーバーライドを参照する他のフレームワークスキルは、決して <snapshot-dir> に書き込みません。
黄金のルール 2 — <committed-lock> はプロジェクトの固定バージョン、<local-lock> はマシンごとの真実。 両者は異なる目的を持ち、異なる場所に存在します。
<committed-lock>はプロジェクトが使用するバージョンを宣言します。最初に/magpie-setup adoptを実行した採用者（または後で/magpie-setup upgradeを実行し、新しい固定を受け入れた採用者）によって編集されます。固定のバンプは意図的なプロジェクトレベルのアクションであり、その変更はそれを提案したPRのgit diffに現れます。<local-lock>はこのマシンがインストールしたものを記録します。/magpie-setup adoptと/magpie-setup upgradeによって静かに更新されます。開発者ごと、チェックアウトごと、ワークツリーごとに存在します。
黄金のルール 3 — ドリフトは表面化され、修正される。 すべてのフレームワークスキル（および /magpie-setup verify）は、実行開始時に <committed-lock> と <local-lock> をチェックします。不一致がある場合、スキルはそのギャップを表面化し、/magpie-setup upgrade を提案します。ユーザーは受け入れるか延期します。受け入れた場合、upgrade は次の処理を行います。
<snapshot-dir>を完全に削除します。- コミットされたロック（プロジェクトが選択した新しいバージョン）に従って再インストールします。
- gitignoredなフレームワークスキルのシンボリックリンクをリフレッシュします — ユーザーのファミリー選択がカバーする新しいフレームワークスキルを追加し、名前変更または削除されたフレームワークスキルを削除します。
- エージェントオーバーライドを新しいフレームワーク構造に照らして調整します（競合を表面化し、自動書き換えは行いません）。
- 新しいフェッチに合わせて
<local-lock>を更新します。
黄金のルール 4 — .gitignore は採用側リポジトリをクリーンに保つ。 採用側リポジトリでgitignoredされる3つのもの：
<snapshot-dir>（フレームワークスナップショット全体 — 潜在的にギガバイト単位）。<local-lock>（マシンごとの状態）。setup adoptがすべてのアクティブターゲットディレクトリに作成するmagpie-*シンボリックリンク —.agents/skills/内の正規リンク（gitignoredなスナップショットをターゲットとする）と.claude/skills//.github/skills// ホールドアウト内のリレーリンク（正規エントリをターゲットとする） — どちらも新しいクローンでは未解決になります。唯一の例外として、各ディレクトリでmagpie-setupだけは無視されません。
コミットされるもの: このスキル（setup、正規の .agents/skills/magpie-setup/ とそのリレー）、<committed-lock>、.apache-magpie-overrides/ ディレクトリ、.gitignore エントリ自体、adopt サブアクションが行うプロジェクトドキュメントの更新。
黄金のルール 5 — .agents/skills/ が正規。他のすべてはそこへのリレー。 採用側プロジェクトが以前に .claude/skills/ や .github/skills/ をどのように構成していたかに関係なく、adopt は常に同じ方法でフレームワークを配線します。正規の magpie-* リンクは .agents/skills/ に存在し、他のすべてのアクティブターゲット（.claude、.github、ホールドアウト）にはスキルごとのリレーシンボリックリンクが正規エントリを指して張られます（.claude/skills/magpie-<n> → ../../.agents/skills/magpie-<n>）。それらのディレクトリにある採用側自身のネイティブ（非 magpie-）スキルは変更されません。agents.md 参照。
黄金のルール 6 — このスキルはコピー、残りはシンボリックリンク。すべて magpie- プレフィックスで。 このスキル（ソース skills/setup/）は、採用側リポジトリにコピーされる唯一のフレームワークスキルです — 正規の .agents/skills/magpie-setup/ としてコミットされ、.claude/skills/magpie-setup と .github/skills/magpie-setup からのコミットされたリレーシンボリックリンクが張られます。他のすべてのフレームワークスキルはシンボリックリンクされます（gitignoredなスナップショットへの正規リンクとリレー）。各スキルは magpie-<framework-skill> という名前になります（例：magpie-security-issue-import → <snapshot-dir>/skills/security-issue-import/）。magpie- プレフィックスはすべてのフレームワークスキルを名前空間化し、採用側のスキルと決して衝突しないようにします。コピーとシンボリックリンクの混在（たとえばセキュリティスキルをコピーするなど）はメンテナンス上の危険を生み出します。コピーはフレームワークの信頼できる情報源から乖離し、ドリフト検出機構（フレームワークバージョンが <snapshot-dir> にあるものだと想定する）が静かに誤適用されます。
黄金のルール 7 — エージェントオーバーライドは実行時に読み取られる。 オーバーライドをサポートするすべてのフレームワークスキルは、実行開始時に .apache-magpie-overrides/<this-skill>.md をチェックし、採用側固有の指示があれば適用してからデフォルトの動作を実行します。オーバーライドファイルはエージェントが解釈するプレーンマークダウンです — テンプレートエンジンもパッチツールもありません。契約については docs/setup/agentic-overrides.md を参照してください。
黄金のルール 8 — 2つのファミリーは常にインストールされ、残りはオプトイン。 2つのスキルファミリーは、すべての adopt / upgrade / worktree-init 実行で無条件に配線され、ユーザーに質問されることは決してありません。
setup-*— ソース名がsetup-で始まるすべてのフレームワークスキル。ただし、ブートストラップ用のsetup自体は除く（これはルール6に従ってmagpie-setupとしてコピーされ、シンボリックリンクされません）。具体的には：setup-isolated-setup-install、setup-isolated-setup-update、setup-isolated-setup-verify、setup-override-upstream、setup-shared-config-sync、および将来フレームワークに追加される新しいsetup-*スキル — それぞれmagpie-setup-*としてシンボリックリンクされます。list-*— ディスカバリファミリー。ソース名がlist-で始まるすべてのフレームワークスキル。現在はlist-skillsのみ（magpie-list-skillsとしてシンボリックリンク）。このプレフィックスにより、フレームワークは将来的にlist-projectsやlist-environmentsなどのスキルを追加できます。