trellis-meta

Trellis Meta

此技能面向已在项目中运行过 trellis init 的 Trellis 本地用户。阅读后，AI 应了解该用户项目中的 Trellis 架构、运行模式和自定义入口，并根据用户的请求修改生成的 .trellis/ 和平台目录文件。

Trellis v0.6 在 v0.6 之前的工作流／持久化／平台模型之上新增了三个架构层面。第一，多 Agent 协作运行时：trellis channel 通过项目范围的 JSONL 事件日志 ~/.trellis/channels/<project>/<channel>/events.jsonl 协调多个 AI 工作进程，并提供工作进程 OOM 防护、论坛／线程频道、持久化幂等键，以及内置的 .trellis/agents/{check,implement}.md 运行时定义。第二，跨会话记忆：trellis mem list | search | context | extract | projects 读取磁盘上已有的 Claude Code、Codex 和 Pi Agent 原始 JSONL 日志，按 --phase brainstorm|implement|all 切分，且绝不上传任何内容。第三，双包 npm 发布：@mindfoldhq/trellis（CLI）和 @mindfoldhq/trellis-core（包含 /channel、/task、/mem、/testing 子路径的 SDK）使用同一个版本同步发布。请将这些视为一等自定义入口，与各平台集成文件同等对待。

默认操作范围是用户项目中的本地文件：

• .trellis/：工作流、配置、任务、规格、工作区、脚本、内置运行时 Agent 和运行时状态。
• 平台目录：.claude/、.codex/、.cursor/、.opencode/、.kiro/、.gemini/、.qoder/、.codebuddy/、.github/、.factory/、.pi/、.reasonix/、.kilocode/、.agent/、.devin/、.kimi-code/ 等类似目录。Pi 还提供原生 trellis_subagent 工具，支持 single／parallel／chain 调度模式、限流进度卡片，以及 isTrellisAgent() 验证。Reasonix 将工作流技能和子 Agent 技能都存储为 .reasonix/skills/<name>/SKILL.md；子 Agent 技能带有 runAs: subagent frontmatter。Kimi Code 将工作流技能保存在共享 .agents/skills/ 层，将命令和 Agent 提示词作为 .kimi-code/skills/<name>/SKILL.md 提供，并将相同的 Agent 提示词安装为 .kimi-code/agents/<name>.md 下的自定义子 Agent。
• 共享技能层：.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. 首先阅读 references/local-architecture/overview.md，了解本地 Trellis 系统模型。
2. 如果请求涉及特定 AI 工具，请阅读 references/platform-files/platform-map.md 和相关平台文件说明。
3. 如果请求涉及多 Agent 调度或频道工作进程，请阅读 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、marketplace）。
• 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：钩子、子 Agent 前导内容，以及渠道运行时工作线程收件箱路由。
• references/local-architecture/multi-agent-channel.md：trellis channel 子命令、项目级事件存储、论坛／线程渠道、工作线程 OOM 防护、持久幂等机制，以及随附的 .trellis/agents/ 运行时 Agent。
• references/local-architecture/bundled-skills.md：自动分发的内置技能（trellis-meta、trellis-spec-bootstrap、trellis-session-insight），以及 getBundledSkillTemplates() 如何将它们分发到每个平台的技能根目录。

平台文件

• references/platform-files/overview.md：共享 .trellis/ 文件与平台目录的关系，以及四种平台集成模式（钩子驱动、Agent 前导内容、主会话工作流、渠道运行时）。
• references/platform-files/platform-map.md：所有受支持平台中技能、Agent、钩子和扩展的目录与路径，包括 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 子 Agent 文件，以及渠道运行时随附的 .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：更改任务创建、状态、归档行为、父子链接、归档 slug 冲突处理和生命周期钩子。
• references/customize-local/change-context-loading.md：更改任务、规范、日志、钩子上下文、频道收件箱消息和 trellis mem 召回内容的加载方式。
• references/customize-local/change-hooks.md：更改平台钩子、设置、任务生命周期钩子（hooks.after_*）和 shell 会话桥接。
• references/customize-local/change-agents.md：更改平台子 Agent、内置频道运行时 Agent 和 Codex dispatch_mode 开关中的研究、实现和检查 Agent 行为。
• 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 文件若缺失，会向 stderr 发出非阻塞警告，提示运行 trellis update。
• .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 是捆绑的、跨平台的频道运行时 Agent 定义，由 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 时，它就会分发到每个平台。
• 平台设置/配置文件决定实际运行哪些钩子、Agent、技能、命令、提示词和工作流。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（或任何其他平台专属子 Agent 文件）；请改为编辑 .trellis/agents/<name>.md。
• 请勿将已移除或从未发布的机制描述为 Trellis 当前行为；在声称某个配置项存在前，请对照本地 .trellis/config.yaml 和已安装 CLI 的 trellis --help 进行核实。