trellis-meta

Trellis メタ

このスキルは、プロジェクトで trellis init をすでに実行したローカルの Trellis ユーザー向けです。これを読んだ AI は、ユーザーのプロジェクト内における Trellis のアーキテクチャ、運用モデル、カスタマイズの入口を理解し、ユーザーの依頼に応じて生成済みの .trellis/ とプラットフォームディレクトリ内のファイルを変更できるようになります。

Trellis v0.6 では、v0.6 より前のワークフロー／永続化／プラットフォームモデルに、3 つのアーキテクチャ上の機能が追加されました。1 つ目は、複数の AI ワーカープロセスをプロジェクト単位の JSONL イベントログ ~/.trellis/channels/<project>/<channel>/events.jsonl を介して調整する、複数エージェントのコラボレーションランタイムです。ワーカーの OOM ガード、フォーラム／スレッドチャンネル、永続的な冪等性キー、同梱の .trellis/agents/{check,implement}.md ランタイム定義が含まれます。2 つ目は、セッションをまたぐメモリです。trellis mem list | search | context | extract | projects は、ディスク上にすでにある Claude Code、Codex、Pi Agent の生の JSONL を読み込み、--phase brainstorm|implement|all で範囲を絞り込み、データをアップロードすることはありません。3 つ目は、デュアルパッケージ形式の npm リリースです。@mindfoldhq/trellis（CLI）と @mindfoldhq/trellis-core（/channel、/task、/mem、/testing のサブパスを備えた SDK）が、同一バージョンで連動してリリースされます。これらも、プラットフォームごとの連携ファイルと同等の、主要なカスタマイズ対象として扱ってください。

デフォルトの操作対象は、ユーザーのプロジェクト内にあるローカルファイルです。

• .trellis/：ワークフロー、設定、タスク、仕様、ワークスペース、スクリプト、同梱のランタイムエージェント、ランタイム状態。
• プラットフォームディレクトリ：.claude/、.codex/、.cursor/、.opencode/、.kiro/、.gemini/、.qoder/、.codebuddy/、.github/、.factory/、.pi/、.reasonix/、.kilocode/、.agent/、.devin/、.kimi-code/ など。Pi ではファイル構成に加え、single／parallel／chain のディスパッチモード、スロットルされた進捗カード、isTrellisAgent() による検証を備えたネイティブの trellis_subagent ツールも利用できます。Reasonix では、ワークフロースキルとサブエージェントスキルの両方が .reasonix/skills/<name>/SKILL.md に保存されます。サブエージェントスキルには runAs: subagent のフロントマターが付いています。Kimi Code では、ワークフロースキルは共有の .agents/skills/ レイヤーに置かれ、コマンドとエージェントプロンプトは .kimi-code/skills/<name>/SKILL.md として提供されます。同じエージェントプロンプトは、カスタムサブエージェントとして .kimi-code/agents/<name>.md にもインストールされます。
• 共有スキルレイヤー：.agents/skills/。
• プロジェクトツリー外にあるユーザー所有のチャンネルストア：~/.trellis/channels/<project>/<channel>/events.jsonl。
• trellis mem で検索できる、生のプラットフォーム会話ログ：~/.claude/projects/、~/.codex/sessions/、~/.pi/agent/sessions/（v0.6 系列では OpenCode アダプターの機能が制限されています）。

ユーザーが Trellis のソースリポジトリを持っているとは限らないため、そうした前提を置かないでください。グローバルな npm インストール先や node_modules をデフォルトで変更しないでください。@mindfoldhq/trellis と @mindfoldhq/trellis-core は、リリースごとに同じバージョンと同じ git タグを共有する公開済みパッケージです。

使用方法

1. ローカルの Trellis システムモデルを把握するため、まず references/local-architecture/overview.md を読んでください。
2. 依頼に特定の AI ツールが関係する場合は、references/platform-files/platform-map.md と、該当するプラットフォームファイルの説明を読んでください。
3. 依頼に複数エージェントのディスパッチやチャンネルワーカーが関係する場合は、references/local-architecture/multi-agent-channel.md と、同梱の .trellis/agents/ ファイルを読んでください。
4. ユーザーが動作の変更を求めている場合は、references/customize-local/overview.md を読んでから、該当するカスタマイズ項目を開いてください。
5. 編集する前に、ユーザーのプロジェクト内にある実際のファイルを読み、ローカルの内容を正としてください。

参考資料

ローカルアーキテクチャ

• references/local-architecture/overview.md：レイヤー構造のローカル Trellis アーキテクチャ（ワークフロー／永続化／プラットフォーム／チャネルランタイム）とカスタマイズの原則。
• references/local-architecture/generated-files.md：trellis init が生成するファイルと、そのカスタマイズ可能な範囲（.trellis/agents/ を含む）。
• references/local-architecture/workflow.md：.trellis/workflow.md におけるフェーズ、ルーティング、ワークフロー状態ブロック、選択可能なワークフローテンプレート（native、tdd、channel-driven-subagent-dispatch、マーケットプレイス）。
• references/local-architecture/task-system.md：タスクディレクトリ、アクティブタスク、JSONL コンテキスト、親子タスクツリー、タスクランタイム。
• references/local-architecture/spec-system.md：.trellis/spec/ の構成、注入、registry.spec ソースからの更新方法。
• references/local-architecture/workspace-memory.md：.trellis/workspace/ のジャーナルに加え、セッションをまたいだ想起を行う trellis mem と @mindfoldhq/trellis-core/mem SDK。
• references/local-architecture/context-injection.md：フック、サブエージェントの前置き、チャネルランタイムのワーカー受信箱ルーティング。
• references/local-architecture/multi-agent-channel.md：trellis channel サブコマンド、プロジェクトスコープのイベントストア、フォーラム／スレッドチャネル、ワーカーの OOM ガード、永続的な冪等性、同梱される .trellis/agents/ ランタイムエージェント。
• references/local-architecture/bundled-skills.md：自動ディスパッチされる同梱スキル（trellis-meta、trellis-spec-bootstrap、trellis-session-insight）と、getBundledSkillTemplates() がすべてのプラットフォームのスキルルートにこれらを配置する方法。

プラットフォームファイル

• references/platform-files/overview.md：共有 .trellis/ ファイルとプラットフォームディレクトリの関係、および4種類のプラットフォーム統合モード（フック駆動、エージェントの前置き、メインセッションワークフロー、チャネルランタイム）。
• references/platform-files/platform-map.md：Reasonix や Pi のネイティブ trellis_subagent 拡張機能を含む、サポート対象すべてのプラットフォームにおけるスキル、エージェント、フック、拡張機能のディレクトリとパス。
• references/platform-files/hooks-and-settings.md：設定／構成ファイル、フック、プラグイン、拡張機能と Trellis の連携方法。channel.worker_guard.* と codex.dispatch_mode を扱います。
• references/platform-files/agents.md：プラットフォームごとの trellis-research／trellis-implement／trellis-check サブエージェントファイルに加え、チャネルランタイム向けに同梱される .trellis/agents/{check,implement}.md。
• references/platform-files/skills-and-commands.md：スキル、コマンド、プロンプト、ワークフローの違いと、それらの変更方法。

ローカルのカスタマイズ

• references/customize-local/overview.md：ユーザーのリクエストに適したローカルカスタマイズの開始点を選びます。
• references/customize-local/change-workflow.md：フェーズ、ルーティング、次のアクション、ワークフローの状態、選択されたワークフローテンプレートを変更します。
• references/customize-local/change-task-lifecycle.md：タスクの作成、ステータス、アーカイブの動作、親子リンク、アーカイブのスラッグの競合処理、ライフサイクルフックを変更します。
• references/customize-local/change-context-loading.md：タスク、仕様、ジャーナル、フックのコンテキスト、チャネルの受信メッセージ、trellis mem による再呼び出しの読み込み方法を変更します。
• references/customize-local/change-hooks.md：プラットフォームフック、設定、タスクのライフサイクルフック（hooks.after_*）、シェルセッションブリッジを変更します。
• references/customize-local/change-agents.md：プラットフォームのサブエージェント、バンドルされたチャネルランタイムエージェント、Codex の dispatch_mode 切り替えにわたる、調査、実装、確認エージェントの動作を変更します。
• references/customize-local/change-skills-or-commands.md：ローカルのスキル、コマンド、プロンプト、ワークフローを追加または変更します。アップストリームのバンドル済みスキルの自動ディスパッチについても説明します。
• references/customize-local/change-spec-structure.md：レジストリに登録されたソースを含め、.trellis/spec/ 配下のプロジェクト仕様の構造を調整します。
• references/customize-local/add-project-local-conventions.md：チームのルールをプロジェクトローカルの仕様またはローカルスキルに記述します。

現在のルール

• .trellis/workflow.md はローカルワークフローの信頼できる唯一の情報源です。初期コンテンツは trellis init の実行時にワークフローテンプレート（組み込みの native、tdd、channel-driven-subagent-dispatch、またはマーケットプレイステンプレート）から選択され、trellis workflow --template <id> で再選択できます。有効なテンプレートが参照する .trellis/agents/<name>.md ファイルがない場合、trellis update を案内する警告が stderr に表示されますが、処理は中断されません。
• .trellis/config.yaml は、プロジェクトレベルの Trellis 設定のエントリーポイントです。タスクのライフサイクルフック（hooks.after_create / after_start / after_finish / after_archive）、ジャーナルの形式（session_commit_message / max_journal_lines / session_auto_commit）、チャネルワーカーのガード（channel.worker_guard.idle_timeout / max_live_workers）、Codex のディスパッチモード（codex.dispatch_mode: inline | sub-agent）、仕様レジストリのブロック（registry.spec.source + registry.spec.template）を設定します。
• .trellis/spec/ には、ユーザー固有のコーディング規約と設計上の制約が保存されます。registry.spec が設定されている場合、ファイルは trellis update によって更新されます。ローカルでの編集は、.trellis/.template-hashes.json に「ユーザーによる変更」の競合として表示されます。
• .trellis/tasks/ には、タスクの PRD、設計メモ、実装計画、調査ファイル、JSONL コンテキストが保存されます。タスクは親子ツリーを形成します。task.py create --parent <slug>、task.py add-subtask <parent> <child>、task.py remove-subtask <parent> <child>、task.py list-context <task> を使用します。task.py create は、.trellis/tasks/archive/** にすでに存在する slug を拒否します。
• .trellis/workspace/ には、意図的に記述された開発者ジャーナルが保存されます。セッションをまたぐ生の対話はここには保存されません。ディスク上の ~/.claude/projects/、~/.codex/sessions/、~/.pi/agent/sessions/ に保存され、trellis mem search|extract|context で復元できます。バンドルされている trellis-session-insight スキルでは、mem を使うタイミングを学べます。
• .trellis/agents/{check,implement}.md は、trellis channel spawn --agent <name> で読み込まれる、バンドル済みのプラットフォーム非依存なチャネルランタイムエージェント定義です。編集可能で、不足しているファイルは trellis update によって補完されます。プラットフォームごとの trellis-implement.md / trellis-check.md を編集しても、チャネルランタイムのワーカーの動作は変わりません。
• ~/.trellis/channels/<project>/<channel>/events.jsonl は、プロジェクトおよびチャネルごとのチャネルランタイムイベントログです。ユーザーが所有し、シーケンス番号はファイルロックによって管理され、永続的な idempotencyKey に対応します。.trellis/ 配下には置かれません。
• バンドル済みの複数ファイルスキル（trellis-meta、trellis-spec-bootstrap、trellis-session-insight、trellis-channel）は、packages/cli/src/templates/common/index.ts の getBundledSkillTemplates() によって、各プラットフォームのスキルルートへ自動的にディスパッチされます。packages/cli/src/templates/common/bundled-skills/（上流）に新しいディレクトリを追加すると、次回の trellis update で各プラットフォームに配布されます。
• どのフック、エージェント、スキル、コマンド、プロンプト、ワークフローを実際に実行するかは、プラットフォームの設定ファイルによって決まります。Reasonix には設定ファイルがなく、動作はスキルのフロントマター内に記述されています。
• .trellis/.template-hashes.json と .trellis/.runtime/ は管理／ランタイム状態ファイルです。編集する前に、その必要性を確認してください。

してはいけないこと

• Trellis の上流ソースコードを、ローカルカスタマイズのデフォルトの対象として扱わないでください。
• プロジェクトのニーズに対応するために、グローバルの npm インストールディレクトリや node_modules/@mindfoldhq/trellis、node_modules/@mindfoldhq/trellis-core を変更しないでください。両方のパッケージは同時にリリースされます。
• ユーザーが変更したローカルファイルをデフォルトのテンプレートで上書きしないでください。まず .trellis/.template-hashes.json を確認し、破壊的な上書きではなく .new サイドカーファイルを優先してください。
• チーム内限定のプロジェクトルールを、公開バンドルスキル（trellis-meta、trellis-spec-bootstrap、trellis-session-insight、trellis-channel）に含めないでください。プロジェクトルールは .trellis/spec/、プロジェクトローカルのスキル、現在のタスク、またはワークスペースジャーナルに記述してください。trellis update はバンドルスキルのディレクトリ内にあるものをすべて上書きします。
• ~/.trellis/channels/<project>/<channel>/events.jsonl を手動で編集しないでください。シーケンス番号はファイルロック下で割り当てられ、リプレイセーフな書き込みには trellis channel CLI または @mindfoldhq/trellis-core/channel SDK を使用します。
• チャネルのランタイムワーカーの動作を変更することが目的の場合、.claude/agents/trellis-implement.md（または他のプラットフォーム別サブエージェントファイル）を編集しないでください。代わりに .trellis/agents/<name>.md を編集してください。
• 削除済み、または一度もリリースされていない仕組みを、現在の Trellis の動作として説明しないでください。設定項目が存在すると主張する前に、ローカルの .trellis/config.yaml とインストール済み CLI の trellis --help で確認してください。