simple-agent-extension 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d5b57957c947b2f4c126dca54b41f69e67d8d2cbfc3a9447a31bea468b03cf76
+  data.tar.gz: 2aafa730f3def389acfd18c2cec0807dfcd78aa1148199ca7a6129ab93fe7c49
+SHA512:
+  metadata.gz: 6bcc677fcc9c6afe8f01f67e77b7a65e86fda1a45ea951a21a362eb88e8b3650ec34e90399292cb3b9b0dacdb082e8c8a5ea3bc0033dbf13f3476366ed4491f2
+  data.tar.gz: f86cf67049dbc0bb7c16ed8c708ebb2e4b6c903240f1f260a2d88eb4be75e8a60c3922550ac1c99962393f5dcacee17c6c6c2ea72780a890f304b4e6d9c78bbd

data/.rubocop.yml

@@ -0,0 +1,16 @@
+require:
+  - standard
+  - standard-custom
+  - standard-performance
+  - rubocop-performance
+
+inherit_gem:
+  standard: config/base.yml
+  standard-custom: config/base.yml
+  standard-performance: config/base.yml
+
+AllCops:
+  TargetRubyVersion: 3.3
+  Exclude:
+    - vendor/**/*
+    - spec/vendor/**/*

data/.standard.yml

@@ -0,0 +1,5 @@
+ruby_version: 3.3
+ignore:
+  - vendor/**/*
+  - spec/vendor/**/*
+  - spec/tmp/**/*

data/AGENTS.md

@@ -0,0 +1,29 @@
+# Test
+
+## Design
+
+ * prefer Unit Test
+ * prefer black-box testing
+ * prefer dependency-injection with test-specific (sub)class over test-double object ( not prohibitted that )
+ * prefer blank-slate with specific behavior over intricate complex real object
+ * don't replicate tests in E2E ( tests outside of unit tests ) that are already covered by unit tests
+ * group tests for a method using `desribe`
+ * specify the conditions in `describe` and the results in `it`
+ * avoid helper methods that hide the actual methods being called
+
+## Assertions
+
+Use `power_assert` for test assertions. Prefer its block form for value and
+behavior checks:
+
+```ruby
+assert { actual == expected }
+```
+
+Do not introduce Minitest matcher expectations such as `must_equal` or
+`wont_equal`. Use Minitest's exception assertions only when the behavior under
+test is raising an error, for example `assert_raises`.
+
+# Ruby Style
+
+Follow StandardRB for Ruby code style and linting.

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+## [0.2.1] 2026-10-02
+
+- feat: support Claude Code
+- docs: add ADR
+
+## [0.2.0] 2026-10-01
+
+- feat: `agents` subcommand
+- feat: readable reploy results
+- feat: `--agent` option and `deploy_to` DSL
+- test: remove several dangerous or unnecessary tests
+
+## [0.1.0] 2026-09-30
+
+- Initial Release
+
+## 2026-08-24
+
+- Unreleased

data/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, Colorful Company,Inc.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,215 @@
+# SimpleAgentExtension
+
+`simple-agent-extension` compiles each single source package into Agent-specific artifacts and can deploy a fresh build to locally installed Agents.
+
+## Installation
+
+Requires Ruby 3.3 or later.
+
+The gem is not published to RubyGems.org yet, so install it from GitHub with Bundler:
+
+```ruby
+# Gemfile
+group :development do
+  gem "simple-agent-extension", github: "colorfulcompany/simple-agent-extension"
+end
+```
+
+```sh
+bundle install
+```
+
+Then run the CLI through Bundler:
+
+```sh
+bundle exec simple-agent-extension packages
+```
+
+Pin a release with `tag:` so the checkout does not move:
+
+```ruby
+gem "simple-agent-extension",
+  github: "colorfulcompany/simple-agent-extension",
+  tag: "v0.1.0"
+```
+
+`branch:` and `ref:` are also available; note that `branch:` follows new commits rather than pinning.
+
+## Usage
+
+### Defining a package
+
+A **package** is an author-owned unit under the source root. It holds one or more **extensions**, one per extension type:
+
+```text
+packages/
+└── awesome-package/          # package
+    ├── skill/                # extension (type: skill)
+    │   ├── SKILL.md          # entrypoint
+    │   ├── metadata.yaml     # compiler input, never distributed
+    │   └── references/       # bundled as-is
+    └── agent/                # extension (type: agent)
+        ├── awesome-worker.md
+        └── metadata.yaml
+```
+
+- Supported extension types are `skill` and `agent`. Either may stand alone; a package does not need both.
+- A `skill` entrypoint is always `SKILL.md`.
+- An `agent` entrypoint is the single top-level `*.md` file. Anything other than exactly one is an error.
+- Every other file under an extension directory is copied into the artifact unchanged, nested directories included. `metadata.yaml` is the one exception.
+
+### Extension metadata
+
+`metadata.yaml` belongs to one extension. It sits beside that extension's entrypoint and is optional.
+
+```yaml
+name: awesome-worker
+
+deploy_to:
+  - opencode
+
+adaptive:
+  permissions:
+    read: allow
+    edit: ask
+
+static:
+  common:
+    description: Short summary the Agent uses to decide when to load this extension.
+  agents:
+    opencode:
+      mode: subagent
+```
+
+| Key | Meaning |
+|---|---|
+| `name` | Extension identity: the name the artifact is deployed under. |
+| `deploy_to` | Agent names this extension is distributed to. Omitting the key distributes to every configured Agent. |
+| `adaptive` | Source fragments whose artifact representation the selected Agent decides. An Agent that has a rule for the field rewrites it; a field with no rule passes through unchanged. |
+| `static.common` | Written to every Agent's artifact without adaptation. |
+| `static.agents.<agent>` | Written only to that Agent's artifact, without adaptation. |
+
+`adaptive` does not mean dynamic. The value is fixed in the file; the key declares that the artifact representation belongs to the Agent rather than to the author.
+
+#### Distribution targets
+
+`deploy_to` limits which Agents an extension reaches.
+
+- No build artifact is produced for an Agent the extension does not name.
+- An extension carrying `deploy_to` is never written to the shared directory. That directory is read by every Agent, so sharing would undo the limit.
+
+#### Name resolution
+
+The extension identity is resolved in this order, later winning:
+
+```text
+package directory name
+  < entrypoint frontmatter `name`
+  < metadata.yaml top-level `name`
+```
+
+#### Metadata precedence
+
+Artifact frontmatter is composed in this order, later winning:
+
+```text
+entrypoint frontmatter
+  < static.common
+  < Agent-specific adapted fragments (from `adaptive`)
+  < static.agents.<agent>
+```
+
+#### Adaptation across Agents
+
+One `adaptive` fragment becomes different artifact metadata per Agent. The `permissions` fragment above compiles to:
+
+| Agent | Artifact metadata |
+|---|---|
+| `claude` | agent: `tools: Read, Edit`; skill: `allowed-tools: Read` |
+| `copilot` | `tools: [read]` |
+| `opencode` | `permission: {read: allow, edit: ask}` |
+
+`claude` maps known lowercase tool names such as `read` and `webfetch` to Claude Code's names (`Read`, `WebFetch`) and passes any other name through unchanged. `deny` becomes `disallowedTools` on an agent and `disallowed-tools` on a skill. An agent's `tools` lists both `allow` and `ask` tools, because Claude Code's `tools` limits which tools exist rather than pre-approving them.
+
+A skill whose metadata is left unchanged by adaptation and carries no Agent-specific static fragments is written once to the shared skill directory. Otherwise it is written into that Agent's own configuration tree ( written with Ruby ). An agent extension is always Agent-specific. `claude` does not read the shared skill directory, so its skills are always written to `~/.claude/skills`.
+
+### Commands
+
+`-h` / `--help` lists every command with a one-line summary.
+
+snapshot as below:
+
+```sh
+simple-agent-extension packages
+simple-agent-extension build
+simple-agent-extension deploy
+simple-agent-extension agents
+```
+
+All commands resolve `--source-root` from `./packages` and `--build-root` from `./build` by default. Either root may be outside the repository.
+
+```sh
+simple-agent-extension deploy \
+  --source-root /work/extensions/packages \
+  --build-root /work/extensions/build \
+  --agent opencode
+```
+
+`--agent NAME` is repeatable, matching the list shape of `deploy_to`. Without it, every configured Agent is targeted. Unlike `deploy_to`, a name no configured Agent answers to stops the command.
+
+```sh
+simple-agent-extension build --agent copilot --agent opencode
+```
+
+`--agent` narrows which Agents a run operates on. It does not declare distribution, so it does not change an artifact's scope.
+
+`--force` is valid only with `deploy`. It creates deployment directories for an Agent whose configuration root is not already present.
+
+### External Agent registrations
+
+Pass `--agent-dir DIRECTORY` one or more times to load trusted local Agent definitions.
+
+- Only direct `*.rb` children are loaded; subdirectories are ignored.
+- Each file must be self-contained. A registration cannot define an Agent that refers to an Agent defined in a sibling file, such as a subclass of one. Load order is an implementation detail, so such a definition is unsupported even when a particular filename ordering happens to make it load.
+- Each loaded file must add a new `SimpleAgentExtension::Agents::*` subclass of `SimpleAgentExtension::AgentBase`.
+- Duplicate Agent names and registration failures stop the command before build or deploy begins.
+
+Agent registrations are executable Ruby and are not sandboxed. Do not load untrusted directories.
+
+## Development
+
+### Repository tasks
+
+`Rakefile` is for development tasks:
+
+```sh
+bundle exec rake spec
+bundle exec standardrb
+```
+
+### Local gem source
+
+Geminabox is a development-only dependency that serves the public Compact Index API locally. It is for package verification and does not become a runtime dependency of `simple-agent-extension`.
+
+Start the loopback-only server in one terminal:
+
+```sh
+bundle exec rake geminabox:start
+```
+
+In another terminal, build and publish the local package:
+
+```sh
+bundle exec rake geminabox:push
+```
+
+Then install it from the local source in an isolated gem home if desired:
+
+```sh
+gem_home="$(mktemp -d)"
+GEM_HOME="$gem_home" GEM_PATH="$gem_home" \
+  gem install --clear-sources --source http://127.0.0.1:9292 \
+  --no-document simple-agent-extension
+```
+
+Set `GEMINABOX_DATA`, `GEMINABOX_PORT`, or `GEMINABOX_URL` to use a non-default temporary location or port.

data/Rakefile

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+require "yard/rake/yardoc_task"
+require "standard/rake"
+
+Minitest::TestTask.create(:spec) do |t|
+  t.libs.concat(%w[lib spec])
+  t.test_globs = [File.join(__dir__, "spec/**/*_spec.rb")]
+end
+
+namespace :geminabox do
+  desc "Start a loopback-only local Geminabox server"
+  task :start do
+    data = ENV.fetch("GEMINABOX_DATA", File.join(__dir__, "tmp/geminabox"))
+    port = ENV.fetch("GEMINABOX_PORT", "9292")
+
+    exec(
+      {"GEMINABOX_DATA" => data},
+      "bundle", "exec", "rackup",
+      "--server", "puma",
+      "--host", "127.0.0.1",
+      "--port", port,
+      File.join(__dir__, "config/geminabox.ru")
+    )
+  end
+
+  desc "Build and publish the local package to Geminabox"
+  task :push do
+    artifact = File.join(__dir__, "tmp", "simple-agent-extension.gem")
+    url = ENV.fetch("GEMINABOX_URL", "http://127.0.0.1:9292")
+
+    mkdir_p File.dirname(artifact)
+    sh "gem", "build", "simple-agent-extension.gemspec", "--output", artifact
+    sh "bundle", "exec", "gem", "inabox", "--overwrite", "--host", url, artifact
+  end
+end
+
+YARD::Rake::YardocTask.new do |t|
+end
+
+task default: :spec

data/adr/adr-0001-single-source-multi-agent-compilation.md

@@ -0,0 +1,118 @@
+---
+title: "ADR-0001: Single-source の extension を compile して multi-agent に対応する"
+status: "Accepted"
+date: "2026-10-02"
+authors: "T.Watanabe (maintainer)"
+tags: ["architecture", "decision", "single-source", "multi-agent", "compile"]
+supersedes: ""
+superseded_by: ""
+---
+
+# ADR-0001: Single-source の extension を compile して multi-agent に対応する
+
+## Status
+
+Proposed | **Accepted** | Rejected | Superseded | Deprecated
+
+## Context
+
+Copilot CLI、OpenCode、Claude Code などの coding agent 製品は、skill や subagent という概念をほぼ共通に持つ。ただし、表現方法は製品ごとに異なる。
+
+- **ファイル名と配置先**: `<name>.agent.md` と `<name>.md`、`~/.copilot` と `~/.config/opencode` と `~/.claude` など。
+- **metadata の語彙と意味**: 同じ「ツール権限」が `tools`、`permission`、`allowed-tools` / `disallowed-tools` になり、許可・確認・拒否の意味づけも異なる。
+- **共通規約の範囲**: 共通の skill ディレクトリ（`~/.agents/skills`）を読む製品と読まない製品がある。subagent に共通規約はない。
+
+一方で、skill や subagent の本文（指示内容）は製品に依存しない。作者は一つの機能を一度だけ書き、複数の Agent で使いたい。製品ごとにコピーを手で保守すると、内容が少しずつずれ、どれが正なのか分からなくなる。
+
+### 用語
+
+本 ADR 群で使う基本的な用語を挙げる。
+
+| 用語 | 意味 |
+|---|---|
+| Agent | Copilot CLI、OpenCode、Claude Code などの coding agent 製品。 |
+| package | 作者が一つの機能として書く source のまとまり。一つ以上の extension を含む。 |
+| extension | package を構成する type 別の要素（現在は skill または agent）。作者が書く single source の単位。 |
+| artifact | extension を一つの Agent 向けに compile した結果。そのまま配置できる。 |
+| Agent class | 一つの Agent 製品の規約（ファイル名、配置先、metadata の語彙）を知るツール側の class。 |
+
+## Decision
+
+**Agent に依存しない single source を作者が書き、Agent ごとに compile して製品固有の artifact を得る。**
+
+```mermaid
+flowchart LR
+  E["extension<br/>(single source)"] --> C((compile))
+  D["Agent class<br/>(one per product)"] --> C
+  C --> A1["artifact for Agent A"]
+  C --> A2["artifact for Agent B"]
+  C --> A3["artifact for Agent C"]
+```
+
+作者は「何をさせたいか」を extension として一つだけ書く。それを製品ごとに「どう表すか」は、製品ごとに一つあるツール側の Agent class が知っており、compile が両者を組み合わせて Agent ごとの artifact を作る。必要であれば、作者が Agent 固有の指定を extension に書き添えることもできる。extension の中身は ADR-0002 で定める。
+
+### 設計原則
+
+今後の変更はこれらの原則に従う。原則を変える場合は、本 ADR を置き換える新しい ADR を書く。ADR-0002 以降は、これらの原則を具体化したものである。
+
+- **PRI-001 Single source**: extension を唯一の正とし、原則として Agent 非依存に書く。製品ごとのコピーは持たない。
+- **PRI-002 製品の知識は Agent class に閉じる**: ファイル名、配置先、metadata の語彙といった製品間の差異は Agent class だけが知る。新しい製品への対応は Agent class の追加で行い、既存の extension や compile の流れは変えない。既存の extension を変えずにその製品向けの artifact が得られることを、対応できたことの基準とする。
+- **PRI-003 Agent 固有の記述は metadata の決まった場所に限る**: 作者が Agent 固有の指定を書く必要がある場合は、metadata の決まった場所に書く（ADR-0002）。本文に製品ごとの分岐を持ち込まない。
+- **PRI-004 本文は変換しない**: compile が変えるのは metadata（frontmatter）、ファイル名、配置先の分類だけである。本文と同梱ファイルはそのまま渡す。
+- **PRI-005 metadata の翻訳は field 単位**: Agent class は `(type, field)` ごとの規則で、一つの field の値をその Agent の表現（0 個以上の field）に変える。規則のない field はそのまま通す。
+- **PRI-006 変換と判断は compile で完結する**: compile 結果は配置可能な最終形の artifact である。配置時には変換も判断もしない。
+
+## Consequences
+
+### Positive
+
+- **POS-001**: 一つの機能を一度書けば、対応するすべての Agent で使える。製品ごとのコピーがずれることもない。
+- **POS-002**: 新しい Agent 製品への対応は Agent class の追加で済む。既存の source を書き換える必要はない。
+- **POS-003**: 翻訳規則は一つの field に閉じた小さな変換なので、Agent ごとに独立してテストできる。
+- **POS-004**: 作者は、多くの場合、製品固有の規約（ファイル名、配置先、権限の語彙）を覚えなくてよい。製品固有の機能を使いたいときだけ、該当 Agent 向けの metadata を書けばよい。
+- **POS-005**: compile 結果を配置前に確認・diff できる。変換の問題と配置の問題を分けて調べられる。
+
+### Negative
+
+- **NEG-001**: 作者とインストール先の間に変換工程が入る。利用には build と deploy が必要になる。
+- **NEG-002**: 製品間で意味が完全には一致しない概念がある（例: Claude Code の subagent `tools` は許可と確認を区別しない）。compile の結果は近似になりうる。
+- **NEG-003**: Agent 製品の仕様変更に合わせて、ツール側の Agent class を追従させ続ける必要がある。
+- **NEG-004**: 本文は変換しないため、本文に製品固有の記述が必要な場合は単一の source では表現できない。
+- **NEG-005**: 翻訳は field 単位のため、複数の field にまたがる変換は表現できない。複数の規則が同じ出力 field を生成した場合の扱いも未定義。
+
+## Alternatives Considered
+
+### 製品ごとに source を個別に保守
+
+- **ALT-001**: **Description**: Agent ごとに skill / agent ファイルを用意し、手で同期する。
+- **ALT-002**: **Rejection Reason**: 内容がずれやすく、正がどれか分からなくなる。対応製品が増えるほど保守の負担が増える。
+
+### 特定製品の形式を正として他製品へ変換
+
+- **ALT-003**: **Description**: たとえば Copilot の形式で書き、そこから他の製品の形式を生成する。
+- **ALT-004**: **Rejection Reason**: source の語彙が特定製品に縛られ、その製品の仕様変更が全体に波及する。他の製品にしかない表現も扱いにくい。
+
+### 共通規約（`~/.agents/skills` など）だけに依存
+
+- **ALT-005**: **Description**: 変換を行わず、共通ディレクトリへのコピーや symlink だけで済ませる。
+- **ALT-006**: **Rejection Reason**: 共通ディレクトリを読まない製品があり、subagent には共通規約もない。metadata の語彙の差も解消できない。
+
+### source 内に製品ごとの条件分岐を書く（テンプレート）
+
+- **ALT-007**: **Description**: ERB などで `if agent == ...` のように本文や frontmatter を分岐させる。
+- **ALT-008**: **Rejection Reason**: 製品の知識が本文を含む source 全体に広がり、本文が単体で読める文書でなくなる。Agent 固有の記述は metadata の決まった場所（`static.agents.<agent>`）に限る方がよい。
+
+### metadata 全体を受け取る翻訳器
+
+- **ALT-009**: **Description**: Agent class が metadata 全体を受け取り、最終的な frontmatter を組み立てる。
+- **ALT-010**: **Rejection Reason**: 優先順位や name の扱いといった共通の規則が各 Agent class に重複し、テストも難しくなる。
+
+### 配置時にその場で変換（中間成果物なし）
+
+- **ALT-011**: **Description**: 変換結果をファイルに残さず、配置先へ直接書き込む。
+- **ALT-012**: **Rejection Reason**: 変換結果を検査できず、ファイル名や配置先の誤りを追跡しにくい。
+
+## References
+
+- **REF-001**: ADR-0002（extension と metadata DSL）、ADR-0003（artifact scope）、ADR-0004（外部 Agent と実行時の選択）
+- **REF-002**: `README.md` 冒頭

data/adr/adr-0002-source-package-model-and-metadata-dsl.md

@@ -0,0 +1,92 @@
+---
+title: "ADR-0002: Source package モデルと metadata DSL"
+status: "Accepted"
+date: "2026-10-02"
+authors: "T.Watanabe (maintainer)"
+tags: ["architecture", "decision", "dsl", "metadata", "package"]
+supersedes: ""
+superseded_by: ""
+---
+
+# ADR-0002: Source package モデルと metadata DSL
+
+## Status
+
+Proposed | **Accepted** | Rejected | Superseded | Deprecated
+
+## Context
+
+作者は Agent 製品ごとの差異を意識せずに一つの source を書きたい。一方で、権限表現のように Agent ごとに表現が異なる metadata や、特定 Agent にしか書けない metadata、特定 Agent にしか配りたくない extension が存在する。
+
+- skill と subagent を一つの機能として組み合わせて配布したい。
+- entrypoint（`SKILL.md` や agent の `*.md`）は単体でも有効な文書であり、その frontmatter も尊重したい。
+
+## Decision
+
+本 ADR は ADR-0001 の PRI-001（single source）、PRI-003（Agent 固有の記述の置き場所）、PRI-004（本文は変換しない）を具体化する。
+
+### Package と extension
+
+- **package** は `<source_root>/<package>/` にある作者単位のまとまり。
+- **extension** は package 内の type 別要素で、`<package>/<type>/` 一つが一 extension。type は現在 `skill` と `agent`。
+
+ADR-0001 の図で compile の入力となる extension は、次の構成を持つ。
+
+```text
+<package>/<type>/
+├── <entrypoint>.md   frontmatter + 本文（単体でも有効な文書）
+├── metadata.yaml     任意。compile の入力で、配布しない
+└── その他            同梱ファイル。そのまま配布する
+```
+
+- entrypoint は type が決める。skill は `SKILL.md`、agent は直下のただ一つの `*.md`（0 または 2 以上はエラー）。
+
+### Extension metadata DSL（`metadata.yaml`、任意）
+
+| Key | 意味 |
+|---|---|
+| `name` | extension identity。配置名になる。 |
+| `deploy_to` | 配布先 Agent 名の制約。省略時は構成済み全 Agent。 |
+| `adaptive` | Agent が artifact 表現を決める source fragment。規則のない field はそのまま通る。 |
+| `static.common` | 全 Agent に適応なしで書かれる fragment。 |
+| `static.agents.<agent>` | 指定 Agent にのみ適応なしで書かれる fragment。 |
+
+- `adaptive` は「動的」ではなく「表現の決定権が Agent 側にある」ことを宣言する。
+- `deploy_to` は選択の制約であり section に属さず、artifact metadata にも現れない。互換性の宣言ではない。対象外の Agent には artifact を一切生成しない。
+
+### 優先順位（後勝ち）
+
+- **Identity**: package ディレクトリ名 < entrypoint frontmatter `name` < `metadata.yaml` top-level `name`
+- **Artifact metadata**: entrypoint frontmatter < `static.common` < Agent 適応済み fragment（`adaptive` 由来）< `static.agents.<agent>`
+
+## Consequences
+
+### Positive
+
+- **POS-001**: 作者は一つの source で複数 Agent をカバーでき、Agent 固有の差は `adaptive` と `static.agents` に局所化される。
+- **POS-002**: entrypoint 単体でも有効な文書のまま、`metadata.yaml` で上書き・補完できる。
+- **POS-003**: `deploy_to` により未検証の Agent への配布を作者が制限できる。
+
+### Negative
+
+- **NEG-001**: 優先順位が 4 段あり、最終 metadata の出所を追うには規則の理解が必要。
+- **NEG-002**: `adaptive` の field 語彙（例: `permissions`）は Agent 側の翻訳規則に暗黙に依存し、DSL として明示的に固定されていない。
+- **NEG-003**: `deploy_to` の未知の Agent 名は警告のみで無視されるため、typo が配布漏れとして見逃されうる。
+- **NEG-004**: source 構造の不正（未対応 type、空 package など）を一括検出する仕組みはまだない。
+
+## Alternatives Considered
+
+### 未知の `deploy_to` 名を厳格にエラー
+
+- **ALT-001**: **Description**: 構成済み Agent に存在しない名前を build エラーにする。
+- **ALT-002**: **Rejection Reason**: 外部 Agent を読み込んだかどうかで source の妥当性が変わってしまう。source 検証が整備されるまでは警告に留める。
+
+### Agent ごとのファイル名をユーザー設定可能にする
+
+- **ALT-003**: **Description**: artifact のファイル名を metadata で指定可能にする。
+- **ALT-004**: **Rejection Reason**: ファイル名は Agent 製品の規約であり、作者が決めるものではない。
+
+## References
+
+- **REF-001**: ADR-0001（翻訳規則）、ADR-0003（`deploy_to` と scope）
+- **REF-002**: `README.md`「Extension metadata」

data/adr/adr-0003-compile-time-artifact-scope.md

@@ -0,0 +1,67 @@
+---
+title: "ADR-0003: Compile 時に決定する artifact scope（shared / own）"
+status: "Accepted"
+date: "2026-10-02"
+authors: "T.Watanabe (maintainer)"
+tags: ["architecture", "decision", "scope", "skill", "deploy"]
+supersedes: ""
+superseded_by: ""
+---
+
+# ADR-0003: Compile 時に決定する artifact scope（shared / own）
+
+## Status
+
+Proposed | **Accepted** | Rejected | Superseded | Deprecated
+
+## Context
+
+一部の Agent 製品は共通の skill ディレクトリ（`~/.agents/skills`）を読む。同一内容の skill をそこに一度だけ置けば重複を避けられるが、次の場合は共有できない。
+
+- Agent 固有の適応で metadata が変わる skill を共有ディレクトリに置くと、他の Agent が誤った metadata を読む。
+- `deploy_to` で配布先を限定した extension を共有ディレクトリに置くと、全 Agent に届いてしまい制限が無効になる。
+- 共有 skill ディレクトリを読まない Agent（Claude Code）がある。
+- agent（subagent）には共有の配置先がない。
+
+## Decision
+
+本 ADR は ADR-0001 の PRI-002（製品の知識は Agent class に閉じる）と PRI-006（判断は compile で完結する）を、配置先の分類に適用する。
+
+各 artifact を **`shared`** または **`own`** のいずれかに分類し、その判定を **compile 時に**行って compile 結果に記録する。
+
+判定規則（上から順に適用）:
+
+1. extension が `deploy_to` を持つ → `own`
+2. Agent がその type の共有をサポートしない（agent type 全般、Claude Code の skill）→ `own`
+3. Agent 適応で metadata が変化した、または `static.agents.<agent>` が存在する → `own`
+4. それ以外 → `shared`
+
+`static.common` は全 Agent に共通のため判定に影響しない。PRI-006 に従い、deploy は記録された scope をそのまま使う。
+
+## Consequences
+
+### Positive
+
+- **POS-001**: 同一内容の skill を共有ディレクトリに一度だけ配置でき、Agent 間の重複を避けられる。
+- **POS-002**: Agent 固有の内容が他の Agent へ漏れることを構造的に防ぐ。
+
+### Negative
+
+- **NEG-001**: metadata の小さな差でも `own` に切り替わるため、作者が意図せず配置先が変わることがある。
+- **NEG-002**: shared artifact は、実行時に対象の Agent を絞っても、共有ディレクトリ経由で他の Agent に届く。この到達範囲を制御する仕組みは未決定。
+
+## Alternatives Considered
+
+### 常に Agent 固有ディレクトリへ配置
+
+- **ALT-001**: **Description**: 共有ディレクトリを使わず、すべて `own` にする。
+- **ALT-002**: **Rejection Reason**: 共有ディレクトリを読む Agent 間で同一 skill が重複し、共通規約を活かせない。
+
+### 作者が scope を明示指定
+
+- **ALT-003**: **Description**: `metadata.yaml` に `shared: true` のような指定を設ける。
+- **ALT-004**: **Rejection Reason**: 内容が Agent 固有である場合に誤指定で漏洩しうる。内容から機械的に導出する方が安全。
+
+## References
+
+- **REF-001**: ADR-0001、ADR-0002（`deploy_to`）