docs: add ensemble package documentation (en/ja)
This commit is contained in:
nrslib
parent
6a42bc79d1
commit
a59ad1d808
@ -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 |
|
||||
|
||||
@ -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)) | バージョン履歴 |
|
||||
|
||||
168
docs/ensemble.ja.md
Normal file
168
docs/ensemble.ja.md
Normal file
@ -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
|
||||
```
|
||||
168
docs/ensemble.md
Normal file
168
docs/ensemble.md
Normal file
@ -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
|
||||
```
|
||||
Loading…
x
Reference in New Issue
Block a user