trellis-meta

Trellis メタスキル

バージョンの互換性

項目	値
Trellis CLI Version	0.4.0-beta.8
Skill Last Updated	2026-03-24
Min Claude Code Version	1.0.0+
Min Node.js Version	>=18.17.0

⚠️ バージョンの不一致に関する警告: Trellis CLI のバージョンが上記と異なる場合、一部の機能がドキュメントどおりに動作しない可能性があります。trellis --version を実行して確認してください。

---

プラットフォームの互換性

機能サポート一覧

機能	Claude Code	iFlow	Cursor	OpenCode	Codex	Kilo	Kiro	Gemini CLI	Antigravity	Qoder	CodeBuddy
コアシステム
ワークスペースシステム	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full
タスクシステム	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full
仕様システム	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full
コマンド／スキル	✅ Full	✅ Full	✅ Full	✅ Full	✅ Skills	✅ Full	✅ Skills	✅ TOML	✅ Workflows	✅ Skills	✅ Full
エージェント定義	✅ Full	✅ Full	⚠️ Manual	✅ Full	✅ TOML	⚠️ Manual	⚠️ Manual	⚠️ Manual	⚠️ Manual	⚠️ Manual	⚠️ Manual
共有エージェントスキル	—	—	—	—	✅ Full	—	—	—	—	—	—
フック依存の機能
SessionStart フック	✅ Full	✅ Full	❌ None	❌ None	⚠️ Optional	❌ None	❌ None	❌ None	❌ None	❌ None	❌ None
PreToolUse フック	✅ Full	✅ Full	❌ None	❌ None	❌ None	❌ None	❌ None	❌ None	❌ None	❌ None	❌ None
SubagentStop フック	✅ Full	✅ Full	❌ None	❌ None	❌ None	❌ None	❌ None	❌ None	❌ None	❌ None	❌ None
コンテキストの自動注入	✅ Full	✅ Full	❌ Manual	❌ Manual	❌ Manual	❌ Manual	❌ Manual	❌ Manual	❌ Manual	❌ Manual	❌ Manual
Ralph Loop	✅ Full	✅ Full	❌ None	❌ None	❌ None	❌ None	❌ None	❌ None	❌ None	❌ None	❌ None
マルチエージェント／セッション
マルチエージェント（現在のディレクトリ）	✅ Full	✅ Full	⚠️ Limited	⚠️ Limited	⚠️ Limited	⚠️ Limited	⚠️ Limited	⚠️ Limited	⚠️ Limited	⚠️ Limited	⚠️ Limited
マルチセッション（worktrees）	✅ Full	✅ Full	❌ None	❌ None	❌ None	❌ None	❌ None	❌ None	❌ None	❌ None	❌ None

凡例

• ✅ Full：機能はドキュメントどおりに動作します
• ⚠️ Limited/Manual：動作しますが、手動の手順が必要です
• ❌ None/Manual：サポートされていないか、手動での回避策が必要です

プラットフォームのカテゴリ

フルフック対応（Claude Code、iFlow）

すべての機能がドキュメントどおりに動作します。フックにより、コンテキストの自動注入と品質の徹底が可能になります。iFlow は Claude Code と同じ Python フックシステムを共有しています。

部分的なフック対応（Codex）

• 動作する機能：ワークスペース、タスク、仕様、スキル（.codex/skills/ と .agents/skills/ の共有レイヤー）、TOML エージェント定義（.codex/agents/）、オプションの SessionStart フック
• 動作しない機能：PreToolUse、SubagentStop、Ralph Loop、Multi-Session
• 注：SessionStart フックには、~/.codex/config.toml の codex_hooks = true が必要です

コマンドのみ対応（Cursor、OpenCode、Kilo、Kiro、Gemini CLI、Antigravity、Qoder、CodeBuddy）

• 動作する機能：ワークスペース、タスク、仕様、コマンド／スキル（プラットフォーム固有の形式）
• 動作しない機能：フック、自動注入、Ralph Loop、Multi-Session
• 回避策：セッション開始時に仕様ファイルを手動で読み込みます。品質ゲートは自動では適用されません
• 注：各プラットフォームは独自のコマンド形式を使用します（Kiro／Qoder は Skills、Gemini は TOML、Antigravity は Workflows、CodeBuddy はネストされた Markdown コマンドを使用します）

移植性を考慮した設計

Trellis をカスタマイズする際は、プラットフォームとの互換性を考慮してください。

┌─────────────────────────────────────────────────────────────┐
│                 PORTABLE (All 11 Platforms)                  │
│  - .trellis/workspace/    - .trellis/tasks/                 │
│  - .trellis/spec/         - Platform commands/skills        │
│  - File-based configs     - JSONL context files             │
│  - config.yaml            - Monorepo packages support       │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│         SHARED AGENT SKILLS (agentskills.io standard)       │
│  - .agents/skills/          (Codex + universal agent CLIs)  │
└─────────────────────────────┬───────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│              HOOK-CAPABLE (Claude Code + iFlow)              │
│  - .claude/hooks/ or .iflow/hooks/                          │
│  - settings.json hook configuration                         │
│  - Auto context injection   - SubagentStop control          │
│  - Ralph Loop               - Multi-Session worktrees       │
│  - Task lifecycle hooks     - Dynamic spec discovery        │
└─────────────────────────────────────────────────────────────┘

---

目的

これは Trellis のメタスキルです。変更を加えていない元の Trellis システムについて記述しています。特定のプロジェクト向けに Trellis をカスタマイズする場合は、変更内容をプロジェクトローカルのスキル（trellis-local）に記録し、このメタスキルを標準の Trellis の信頼できるリファレンスとして維持してください。

スキル階層

~/.claude/skills/
└── trellis-meta/              # THIS SKILL - Original Trellis documentation
                               # ⚠️ DO NOT MODIFY for project-specific changes

project/.claude/skills/
└── trellis-local/             # Project-specific customizations
                               # ✅ Record all modifications here

なぜ分けるのですか？

• ユーザーが、Trellis のカスタマイズ内容が異なる複数のプロジェクトを持つ場合があるため
• 各プロジェクトの trellis-local スキルが、そのプロジェクト独自の変更を記録するため
• メタスキルを、元の Trellis のリファレンスとして変更のない状態に保てるため
• アップグレードを容易にするため：メタスキルと新しい Trellis バージョンを比較できます

---

自己反復プロトコル

プロジェクト向けに Trellis を変更する際は、次の手順に従ってください。

1. 既存のプロジェクトスキルを確認する

# Look for project-local skill
ls -la .claude/skills/trellis-local/

2. 存在しない場合はプロジェクトスキルを作成する

trellis-local が存在しない場合は、作成してください。

mkdir -p .claude/skills/trellis-local

次に、.claude/skills/trellis-local/SKILL.md を作成してください。

---
name: trellis-local
description: |
  Project-specific Trellis customizations for [PROJECT_NAME].
  This skill documents modifications made to the vanilla Trellis system
  in this project. Inherits from trellis-meta for base documentation.
---

# Trellis Local - [PROJECT_NAME]

## Base Version

Trellis version: X.X.X (from package.json or trellis --version)
Date initialized: YYYY-MM-DD

## Customizations

### Commands Added

(none yet)

### Agents Modified

(none yet)

### Hooks Changed

(none yet)

### Specs Customized

(none yet)

### Workflow Changes

(none yet)

---

## Changelog

### YYYY-MM-DD

- Initial setup

3. 変更をすべて記録する

Trellis に変更を加える際は、どのような変更であっても trellis-local/SKILL.md を更新してください。

例：新しいコマンドの追加

### Commands Added

#### /trellis:my-command

- **File**: `.claude/commands/trellis/my-command.md`
- **Purpose**: [what it does]
- **Added**: 2026-01-31
- **Why**: [reason for adding]

例：フックの変更

### Hooks Changed

#### inject-subagent-context.py

- **Change**: Added support for `my-agent` type
- **Lines modified**: 45-67
- **Date**: 2026-01-31
- **Why**: [reason]

4. プロジェクトの変更でメタスキルを変更しない

trellis-meta スキルを更新するのは、次の場合に限ってください。

• Trellis の新バージョンがリリースされたとき
• オリジナルのドキュメントの誤りを修正するとき
• オリジナルの機能に関する不足しているドキュメントを追加するとき

---

アーキテクチャの概要

Trellis は、コンテキストを強制的に注入することで、AI アシスタントを構造化された開発パートナーへと変えます。

システムレイヤー

┌─────────────────────────────────────────────────────────────────────┐
│                        USER INTERACTION                              │
│  /trellis:start  /trellis:brainstorm  /trellis:parallel             │
│  /trellis:finish-work  /trellis:before-dev  /trellis:check          │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────┐
│                         SKILLS LAYER                                 │
│  .claude/commands/trellis/*.md   (17 slash commands)                │
│  .claude/agents/*.md             (6 sub-agent definitions)          │
│  .agents/skills/*/SKILL.md       (shared agent skills layer)        │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────┐
│                          HOOKS LAYER                                 │
│  SessionStart      → session-start.py (workflow + context + status) │
│  PreToolUse:Agent  → inject-subagent-context.py (spec injection)    │
│  SubagentStop      → ralph-loop.py (quality enforcement)            │
│  Task Lifecycle    → config.yaml hooks (after_create/start/finish/  │
│                      archive → e.g. Linear sync)                    │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────┐
│                       PERSISTENCE LAYER                              │
│  .trellis/workspace/  (journals, session history)                   │
│  .trellis/tasks/      (task tracking, context files, subtasks)      │
│  .trellis/spec/       (coding guidelines, monorepo per-package)     │
│  .trellis/config.yaml (packages, hooks, update.skip, spec_scope)   │
└─────────────────────────────────────────────────────────────────────┘

主な設計原則

原則	説明
仕様は記憶させずに注入する	フックが仕様を適用し、エージェントは常にコンテキストを受け取ります
書く前に読む	コードを書く前にガイドラインを理解します
階層化されたコンテキスト	関連する仕様のみを読み込みます（JSONL ファイル経由）
人間がコミットする	AI はコミットせず、人間が先に検証します
純粋なディスパッチャー	ディスパッチエージェントはオーケストレーションのみを行います

---

コアコンポーネント

1. ワークスペースシステム

開発者ごとに分離し、セッションをまたいで開発の進捗を追跡します。

.trellis/workspace/
├── index.md                    # Global overview
└── {developer}/                # Per-developer
    ├── index.md                # Personal index (@@@auto markers)
    └── journal-N.md            # Session journals (max 2000 lines)

主なファイル：.trellis/.developer（識別情報）、ジャーナル（セッション履歴）

2. タスクシステム

フェーズベースの実行、親子関係のあるサブタスク、ライフサイクルフックを使用して作業項目を追跡します。

.trellis/tasks/{MM-DD-slug}/
├── task.json           # Metadata, phases, branch, subtasks
├── prd.md              # Requirements
├── info.md             # Technical design (optional)
├── implement.jsonl     # Context for implement agent
├── check.jsonl         # Context for check agent
├── debug.jsonl         # Context for debug agent
├── research.jsonl      # Context for research agent (optional)
└── cr.jsonl            # Context for code review (optional)

3. 仕様システム

エージェントに注入されるコーディング規約を管理します。単一リポジトリとモノレポの両方のレイアウトに対応しています。

# Single repo
.trellis/spec/
├── frontend/           # Frontend guidelines
├── backend/            # Backend guidelines
└── guides/             # Thinking guides

# Monorepo (per-package)
.trellis/spec/
├── <package-name>/     # Per-package specs
│   ├── backend/
│   ├── frontend/
│   └── unit-test/
└── guides/             # Shared thinking guides

4. フックシステム

コンテキストを自動的に注入し、品質を確保します。

Claude Code / iFlow フック（settings.json）：

フック	実行タイミング	目的
SessionStart	起動、クリア、コンパクトのイベント	ワークフロー、ガイドライン、タスクの状態を注入
PreToolUse:Agent	サブエージェントの起動前	JSONL 経由で仕様を注入
PreToolUse:Task	Task ツールの実行前（旧式）	Agent と同じ（CC では Task を Agent に名称変更）
SubagentStop:check	check エージェントの停止時	検証を徹底（Ralph Loop）

タスクライフサイクルフック（config.yaml）：

イベント	実行タイミング	目的
after_create	タスク作成時	例：Linear の課題を作成
after_start	タスク開始時	例：Linear のステータスを更新
after_finish	タスク完了時	例：Linear を完了済みにする
after_archive	タスクのアーカイブ時	例：Linear の課題をクローズ

5. エージェントシステム

各フェーズに特化したエージェントです。

エージェント	目的	制約
dispatch	パイプラインを統括	ディスパッチ専用
plan	要件を評価	不明確な要件は拒否可能
research	コードパターンを検索	読み取り専用
implement	コードを作成	git commit は不可
check	レビューと自己修正	Ralph Loop が制御
debug	問題を修正	正確な修正のみ

6. マルチエージェントパイプライン

Git worktree を使って、分離されたセッションを並行して実行します。

plan.py → start.py → Dispatch → implement → check → create-pr

---

カスタマイズガイド

コマンドの追加

1. .claude/commands/trellis/my-command.md を作成します
2. 変更内容を trellis-local スキルに反映します

エージェントの追加

1. YAML frontmatter を含む .claude/agents/my-agent.md を作成します
2. 新しいエージェントタイプを処理するように inject-subagent-context.py を更新します
3. タスクディレクトリに my-agent.jsonl を作成します
4. trellis-local スキルを更新します

フックの変更

1. .claude/hooks/ 内のフックスクリプトを編集します
2. 変更内容を trellis-local スキルに記載します
3. 変更した行とその理由を記録します

仕様の拡張

1. .trellis/spec/my-category/ に新しいカテゴリを作成します
2. index.md とガイドラインファイルを追加します
3. JSONL コンテキストファイルから参照します
4. trellis-local スキルを更新します

タスクワークフローの変更

1. task.json の next_action 配列を変更します
2. 必要に応じて dispatch またはフックスクリプトを更新します
3. 変更内容を trellis-local スキルに記載します

---

リソース

参照ドキュメントは、プラットフォームとの互換性に応じて整理されています。

references/
├── core/              # All Platforms (Claude Code, Cursor, etc.)
├── claude-code/       # Claude Code Only
├── how-to-modify/     # Modification Guides
└── meta/              # Documentation & Templates

core/ - すべてのプラットフォーム

ドキュメント	内容
overview.md	コアシステムの概要
files.md	.trellis/ 内のすべてのファイルとその用途
workspace.md	ワークスペースシステム、ジャーナル、開発者 ID
tasks.md	タスクシステム、サブタスク、ライフサイクルフック、JSONL
specs.md	仕様システム、モノレポの構成、ガイドライン
scripts.md	プラットフォームに依存しないスクリプト
config.md	config.yaml の完全なリファレンス

claude-code/ - Claude Code 専用

ドキュメント	内容
overview.md	Claude Code の機能紹介
hooks.md	フックシステム、コンテキスト注入
agents.md	エージェントの種類、呼び出し、Task ツール
ralph-loop.md	品質を確保する仕組み
multi-session.md	並列の worktree セッション
worktree-config.md	worktree.yaml の設定
scripts.md	Claude Code 専用スクリプト

how-to-modify/ - 変更ガイド

ドキュメント	シナリオ
overview.md	すべての変更のクイックリファレンス
add-command.md	スラッシュコマンドの追加
add-agent.md	新しいエージェントの種類の追加
add-spec.md	spec カテゴリーの追加
add-phase.md	ワークフローフェーズの追加
modify-hook.md	フックの動作の変更
change-verify.md	検証コマンドの変更

meta/ - ドキュメント

ドキュメント	内容
platform-compatibility.md	プラットフォーム対応状況の詳細な一覧
self-iteration-guide.md	カスタマイズのドキュメント化方法
trellis-local-template.md	プロジェクトローカルなスキルのテンプレート

---

クイックリファレンス

主要スクリプト

スクリプト	目的
get_context.py	セッションのコンテキストを取得（テキスト／JSON）
task.py	タスク管理（16 個のサブコマンド）
add_session.py	セッションを記録
create_bootstrap.py	初回の spec ブートストラップ
multi_agent/start.py	並列エージェントを起動
multi_agent/status.py	エージェントのステータスを監視
multi_agent/create_pr.py	worktree から PR を作成

主要パス

パス	目的
.trellis/.developer	開発者の識別情報
.trellis/.current-task	アクティブなタスクへのポインター
.trellis/workflow.md	メインのワークフロー文書
.trellis/config.yaml	プロジェクト設定（パッケージ、フック）
.trellis/worktree.yaml	マルチセッション設定
.claude/settings.json	フックの設定
.agents/skills/	共有エージェントスキル（agentskills.io）

---

クイックリファレンス

アップグレード手順

Trellis を新しいバージョンにアップグレードする場合：

1. 比較 新しいメタスキルと現在のものを比較します
2. 確認 新しいバージョンの変更内容を確認します
3. チェック trellis-local に競合がないか確認します
4. マージ カスタマイズを保持しながら慎重にマージします
5. 更新 移行に関するメモを trellis-local に追加します

## Changelog

### 2026-02-01 - Upgraded to Trellis X.Y.Z

- Merged new hook behavior from meta-skill
- Kept custom agent `my-agent`
- Updated check.jsonl template