From a59ad1d8080e9ec5e0f15455d5a11bef173d7ab2 Mon Sep 17 00:00:00 2001
From: nrslib <38722970+nrslib@users.noreply.github.com>
Date: Sun, 22 Feb 2026 08:16:20 +0900
Subject: [PATCH] docs: add ensemble package documentation (en/ja)

---
 README.md           |   1 +
 docs/README.ja.md   |   1 +
 docs/ensemble.ja.md | 168 ++++++++++++++++++++++++++++++++++++++++++++
 docs/ensemble.md    | 168 ++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 338 insertions(+)
 create mode 100644 docs/ensemble.ja.md
 create mode 100644 docs/ensemble.md

diff --git a/README.md b/README.md
index 4245ed3..17cbd5e 100644
--- a/README.md
+++ b/README.md
@@ -250,6 +250,7 @@ await engine.run();
 | [Agent Guide](./docs/agents.md) | Custom agent configuration |
 | [Builtin Catalog](./docs/builtin-catalog.md) | All builtin pieces and personas |
 | [Faceted Prompting](./docs/faceted-prompting.md) | Prompt design methodology |
+| [Ensemble Packages](./docs/ensemble.md) | Installing and sharing packages |
 | [Task Management](./docs/task-management.md) | Task queuing, execution, isolation |
 | [CI/CD Integration](./docs/ci-cd.md) | GitHub Actions and pipeline mode |
 | [Changelog](./CHANGELOG.md) ([日本語](./docs/CHANGELOG.ja.md)) | Version history |
diff --git a/docs/README.ja.md b/docs/README.ja.md
index 447b077..82df398 100644
--- a/docs/README.ja.md
+++ b/docs/README.ja.md
@@ -261,6 +261,7 @@ await engine.run();
 | [Agent Guide](./agents.md) | カスタムエージェントの設定 |
 | [Builtin Catalog](./builtin-catalog.ja.md) | ビルトイン piece・persona の一覧 |
 | [Faceted Prompting](./faceted-prompting.ja.md) | プロンプト設計の方法論 |
+| [Ensemble Packages](./ensemble.ja.md) | パッケージのインストール・共有 |
 | [Task Management](./task-management.ja.md) | タスクの追加・実行・隔離 |
 | [CI/CD Integration](./ci-cd.ja.md) | GitHub Actions・パイプラインモード |
 | [Changelog](../CHANGELOG.md) ([日本語](./CHANGELOG.ja.md)) | バージョン履歴 |
diff --git a/docs/ensemble.ja.md b/docs/ensemble.ja.md
new file mode 100644
index 0000000..61b75f3
--- /dev/null
+++ b/docs/ensemble.ja.md
@@ -0,0 +1,168 @@
+# Ensemble パッケージ
+
+[English](./ensemble.md)
+
+Ensemble パッケージを使うと、GitHub リポジトリから TAKT のピースやファセットをインストール・共有できます。
+
+## クイックスタート
+
+```bash
+# パッケージをインストール
+takt ensemble add github:nrslib/takt-fullstack
+
+# 特定バージョンを指定してインストール
+takt ensemble add github:nrslib/takt-fullstack@v1.0.0
+
+# インストール済みパッケージを一覧表示
+takt ensemble list
+
+# パッケージを削除
+takt ensemble remove @nrslib/takt-fullstack
+```
+
+[GitHub CLI](https://cli.github.com/) (`gh`) のインストールと認証が必要です。
+
+## パッケージ構造
+
+TAKT パッケージは `takt-package.yaml` マニフェストとコンテンツディレクトリを持つ GitHub リポジトリです。
+
+```
+my-takt-package/
+  takt-package.yaml       # マニフェスト（.takt/takt-package.yaml でも可）
+  facets/
+    personas/
+      expert-coder.md
+    policies/
+      strict-review.md
+    knowledge/
+      domain.md
+    instructions/
+      plan.md
+  pieces/
+    expert.yaml
+```
+
+`facets/` と `pieces/` ディレクトリのみがインポートされます。その他のファイルは無視されます。
+
+### takt-package.yaml
+
+マニフェストは、リポジトリ内のパッケージコンテンツの場所を TAKT に伝えます。
+
+```yaml
+# 説明（任意）
+description: フルスタック開発用ピースとエキスパートレビュアー
+
+# パッケージルートへのパス（リポジトリルートからの相対パス、デフォルト: "."）
+path: .
+
+# TAKT バージョン制約（任意）
+takt:
+  min_version: 0.22.0
+```
+
+マニフェストはリポジトリルート（`takt-package.yaml`）または `.takt/` 内（`.takt/takt-package.yaml`）に配置できます。`.takt/` が優先的に検索されます。
+
+| フィールド | 必須 | デフォルト | 説明 |
+|-----------|------|-----------|------|
+| `description` | いいえ | - | パッケージの説明 |
+| `path` | いいえ | `.` | `facets/` と `pieces/` を含むディレクトリへのパス |
+| `takt.min_version` | いいえ | - | 必要な TAKT の最低バージョン（X.Y.Z 形式） |
+
+## インストール
+
+```bash
+takt ensemble add github:{owner}/{repo}@{ref}
+```
+
+`@{ref}` は省略可能です。省略した場合、リポジトリのデフォルトブランチが使用されます。
+
+インストール前に、パッケージの内容サマリ（ファセット種別ごとの数、ピース名、edit 権限の警告）が表示され、確認を求められます。
+
+### インストール時の処理
+
+1. `gh api` 経由で GitHub から tarball をダウンロード
+2. `facets/` と `pieces/` のファイルのみを展開（`.md`、`.yaml`、`.yml`）
+3. `takt-package.yaml` マニフェストをバリデーション
+4. TAKT バージョン互換性チェック
+5. `~/.takt/ensemble/@{owner}/{repo}/` にファイルをコピー
+6. ロックファイル（`.takt-pack-lock.yaml`）を生成（ソース、ref、コミット SHA）
+
+インストールはアトミックに行われます。途中で失敗しても中途半端な状態は残りません。
+
+### セキュリティ制約
+
+- `.md`、`.yaml`、`.yml` ファイルのみコピー
+- シンボリックリンクはスキップ
+- 1 MB を超えるファイルはスキップ
+- 500 ファイルを超えるパッケージは拒否
+- `path` フィールドのディレクトリトラバーサルを拒否
+- realpath による symlink ベースのトラバーサル検出
+
+## パッケージの使い方
+
+### ピース
+
+インストールされたピースはピース選択 UI の「ensemble」カテゴリにパッケージごとのサブカテゴリとして表示されます。直接指定も可能です。
+
+```bash
+takt --piece @nrslib/takt-fullstack/expert
+```
+
+### @scope 参照
+
+インストール済みパッケージのファセットは、piece YAML で `@{owner}/{repo}/{facet-name}` 構文を使って参照できます。
+
+```yaml
+movements:
+  - name: implement
+    persona: @nrslib/takt-fullstack/expert-coder
+    policy: @nrslib/takt-fullstack/strict-review
+    knowledge: @nrslib/takt-fullstack/domain
+```
+
+### 4層ファセット解決
+
+ensemble パッケージのピースが名前（@scope なし）でファセットを解決する場合、次の順序で検索されます。
+
+1. **パッケージローカル**: `~/.takt/ensemble/@{owner}/{repo}/facets/{type}/`
+2. **プロジェクト**: `.takt/facets/{type}/`
+3. **ユーザー**: `~/.takt/facets/{type}/`
+4. **ビルトイン**: `builtins/{lang}/facets/{type}/`
+
+パッケージのピースは自身のファセットを最優先で見つけつつ、ユーザーやプロジェクトによるオーバーライドも可能です。
+
+## パッケージ管理
+
+### 一覧表示
+
+```bash
+takt ensemble list
+```
+
+インストール済みパッケージのスコープ、説明、ref、コミット SHA を表示します。
+
+### 削除
+
+```bash
+takt ensemble remove @{owner}/{repo}
+```
+
+削除前に、ユーザーやプロジェクトのピースがパッケージのファセットを参照していないかチェックし、影響がある場合は警告します。
+
+## ディレクトリ構造
+
+インストールされたパッケージは `~/.takt/ensemble/` に保存されます。
+
+```
+~/.takt/ensemble/
+  @nrslib/
+    takt-fullstack/
+      takt-package.yaml          # マニフェストのコピー
+      .takt-pack-lock.yaml       # ロックファイル（ソース、ref、コミット）
+      facets/
+        personas/
+        policies/
+        ...
+      pieces/
+        expert.yaml
+```
diff --git a/docs/ensemble.md b/docs/ensemble.md
new file mode 100644
index 0000000..03b6aa7
--- /dev/null
+++ b/docs/ensemble.md
@@ -0,0 +1,168 @@
+# Ensemble Packages
+
+[Japanese](./ensemble.ja.md)
+
+Ensemble packages let you install and share TAKT pieces and facets from GitHub repositories.
+
+## Quick Start
+
+```bash
+# Install a package
+takt ensemble add github:nrslib/takt-fullstack
+
+# Install a specific version
+takt ensemble add github:nrslib/takt-fullstack@v1.0.0
+
+# List installed packages
+takt ensemble list
+
+# Remove a package
+takt ensemble remove @nrslib/takt-fullstack
+```
+
+**Requirements:** [GitHub CLI](https://cli.github.com/) (`gh`) must be installed and authenticated.
+
+## Package Structure
+
+A TAKT package is a GitHub repository with a `takt-package.yaml` manifest and content directories:
+
+```
+my-takt-package/
+  takt-package.yaml       # Package manifest (or .takt/takt-package.yaml)
+  facets/
+    personas/
+      expert-coder.md
+    policies/
+      strict-review.md
+    knowledge/
+      domain.md
+    instructions/
+      plan.md
+  pieces/
+    expert.yaml
+```
+
+Only `facets/` and `pieces/` directories are imported. Other files are ignored.
+
+### takt-package.yaml
+
+The manifest tells TAKT where to find the package content within the repository.
+
+```yaml
+# Optional description
+description: Full-stack development pieces with expert reviewers
+
+# Path to the package root (relative to repo root, default: ".")
+path: .
+
+# Optional TAKT version constraint
+takt:
+  min_version: 0.22.0
+```
+
+The manifest can be placed at the repository root (`takt-package.yaml`) or inside `.takt/` (`.takt/takt-package.yaml`). The `.takt/` location is checked first.
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `description` | No | - | Package description |
+| `path` | No | `.` | Path to the directory containing `facets/` and `pieces/` |
+| `takt.min_version` | No | - | Minimum TAKT version required (X.Y.Z format) |
+
+## Installation
+
+```bash
+takt ensemble add github:{owner}/{repo}@{ref}
+```
+
+The `@{ref}` is optional. Without it, the repository's default branch is used.
+
+Before installing, TAKT displays a summary of the package contents (facet counts by type, piece names, and edit permission warnings) and asks for confirmation.
+
+### What happens during install
+
+1. Downloads the tarball from GitHub via `gh api`
+2. Extracts only `facets/` and `pieces/` files (`.md`, `.yaml`, `.yml`)
+3. Validates the `takt-package.yaml` manifest
+4. Checks TAKT version compatibility
+5. Copies files to `~/.takt/ensemble/@{owner}/{repo}/`
+6. Generates a lock file (`.takt-pack-lock.yaml`) with source, ref, and commit SHA
+
+Installation is atomic — if it fails partway, no partial state is left behind.
+
+### Security constraints
+
+- Only `.md`, `.yaml`, `.yml` files are copied
+- Symbolic links are skipped
+- Files exceeding 1 MB are skipped
+- Packages with more than 500 files are rejected
+- Directory traversal in `path` field is rejected
+- Symlink-based traversal is detected via realpath validation
+
+## Using Package Content
+
+### Pieces
+
+Installed pieces appear in the piece selection UI under the "ensemble" category, organized by package. You can also specify them directly:
+
+```bash
+takt --piece @nrslib/takt-fullstack/expert
+```
+
+### @scope references
+
+Facets from installed packages can be referenced in piece YAML using `@{owner}/{repo}/{facet-name}` syntax:
+
+```yaml
+movements:
+  - name: implement
+    persona: @nrslib/takt-fullstack/expert-coder
+    policy: @nrslib/takt-fullstack/strict-review
+    knowledge: @nrslib/takt-fullstack/domain
+```
+
+### 4-layer facet resolution
+
+When a piece from an ensemble package resolves facets by name (without @scope), the resolution order is:
+
+1. **Package-local**: `~/.takt/ensemble/@{owner}/{repo}/facets/{type}/`
+2. **Project**: `.takt/facets/{type}/`
+3. **User**: `~/.takt/facets/{type}/`
+4. **Builtin**: `builtins/{lang}/facets/{type}/`
+
+This means package pieces automatically find their own facets first, while still allowing user/project overrides.
+
+## Managing Packages
+
+### List
+
+```bash
+takt ensemble list
+```
+
+Shows installed packages with their scope, description, ref, and commit SHA.
+
+### Remove
+
+```bash
+takt ensemble remove @{owner}/{repo}
+```
+
+Before removing, TAKT checks if any user/project pieces reference the package's facets and warns about potential breakage.
+
+## Directory Structure
+
+Installed packages are stored under `~/.takt/ensemble/`:
+
+```
+~/.takt/ensemble/
+  @nrslib/
+    takt-fullstack/
+      takt-package.yaml          # Copy of the manifest
+      .takt-pack-lock.yaml       # Lock file (source, ref, commit)
+      facets/
+        personas/
+        policies/
+        ...
+      pieces/
+        expert.yaml
+```