跳转到主要内容
自 beta.8 以来累积内容：新增 joiner 引导任务、polyrepo 布局探测、onboarding PRD 改为 AI 视角、所有平台 workflow 收紧、Qoder session 边界命令拆分、task.json schema 统一、孤儿脚本清理。非 breaking，trellis update 不需加 --migrate。

​
新功能

​
1. Joiner 引导任务

trellis init 现在按两个文件的存在状态分三种场景派发：
.trellis/.trellis/.developer生成的 task
不存在n/a00-bootstrap-guidelines（creator，不变）
存在不存在00-join-<slug>（新：joiner 流程）
存在存在不生成 task（同人 re-init）
选 .trellis/.developer 作为 per-checkout 信号的原因：它在 .trellis/.gitignore 里声明过，天然不进 git，新克隆的 checkout 永远不存在此文件。.trellis/workspace/<name>/ 不能做此信号——该目录进 git，新克隆时已经存在。 joiner task 创建时自动设为 current-task，新开发者第一次 /trellis:continue 直接落在引导 PRD 上，覆盖四项：Trellis 工作流、运行时机制（SessionStart hook、<workflow-state> 注入、trellis-implement / trellis-check sub-agent、per-task jsonl manifest）、项目 spec（.trellis/spec/）、本人分配任务（task.py list --assignee <name>）。

​
2. Bootstrap / Joiner PRD 改为 AI 视角

两份 onboarding PRD 现在是写给 AI 的指令，不是给开发者的文档。开头明确声明： 
**You (the AI) are running this task. The developer does not read this file.**
正文从给用户的提示（Ask AI:、Read workflow.md）改为给 AI 的指令（Explain、Summarize X for them、If archive is empty, skip — don't invent examples）。PRD 末尾包含 “Suggested opening line” 模板，AI 第一次回应用户时原样使用。

​
3. Polyrepo 布局探测

detectMonorepo() 新增第 7 个 parser，向下扫最多 2 层找兄弟 .git 目录或 worktree gitlink。只在前 6 个 workspace parser 全 miss 且没声明 submodule 时才触发，workspace 配置（pnpm-workspace.yaml、Cargo workspaces 等）始终优先。
  • DetectedPackage 加 isGitRepo: boolean（与 isSubmodule 互斥）
  • writeMonorepoConfig 输出 git: true，桥接到 config.py 的 get_git_packages() 已有运行时 schema
  • --monorepo 失败时打印 7 项检查清单 + config.yaml 手写示例
  • init 确认 prompt 给 polyrepo 包标 (git repo)
  • config.yaml 模板文档化 git: true 字段
覆盖”meta-repo”布局（多个独立 git 仓库并排在一个父目录下）。

​
Workflow 收紧（所有平台）

​
4. Task 创建触发词

workflow.md [workflow-state:no_task] + shared-hooks/inject-workflow-state.py + OpenCode plugin 现在列出触发任务创建的明确关键词：
  • 中文：重构 / 抽成 / 独立 / 分发 / 拆出来 / 搞一个 / 做成 / 接入 / 集成
  • 英文：refactor / rewrite / extract / productize / publish / build X / design Y
豁免条件必须三项全满足：(a) 本轮零文件写入，(b) 单次回答可覆盖，(c) 无外部调研。否则：必须建 task。

​
5. 调研任务 sub-agent 化

common/skills/brainstorm.md 新增 “Delegate to trellis-research sub-agent” 段，带反面案例：
主会话里 3+ 次 inline WebFetch/WebSearch 是 anti-pattern。正确做法：通过 Task 工具启动 trellis-research sub-agent；sub-agent 写结果到 {TASK_DIR}/research/<topic>.md，返回路径 + 一行摘要。
workflow.md [workflow-state:in_progress] 里的流程描述从泛泛动词（implement → check → update）改为具体 agent 类型（trellis-implement → trellis-check → trellis-update-spec → finish）。

​
Qoder 体验修复

​
6. Session 边界命令从 skill matcher 拆出

beta.9 之前 Qoder 所有 Trellis 入口——包括 finish-work 和 continue——都以 .qoder/skills/trellis-*/SKILL.md 形式存在。调起方式非确定性（依赖 skill matcher 对用户措辞与 skill 描述打分）。 beta.9 把 session 边界命令拆成 Qoder Custom Command：
  • .qoder/commands/trellis-finish-work.md（YAML frontmatter：name、description）
  • .qoder/commands/trellis-continue.md
用户通过 /trellis-finish-work / /trellis-continue 调起（精确匹配）。 自动触发的 workflow（brainstorm、before-dev、check、update-spec、break-loop）仍保留为 .qoder/skills/trellis-<name>/SKILL.md。 configurators/shared.ts 基础设施变更：
  • 新 wrapWithCommandFrontmatter(filePath, content) helper
  • 新 COMMAND_DESCRIPTIONS registry（短、祈使句，与 matcher 用的 SKILL_DESCRIPTIONS 长文本分离）
  • collectBothTemplates 增加可选 wrapCmd 回调

​
内部清理

​
7. task.json schema 统一

packages/cli/src/utils/task-json.ts 新增共享工厂： 
export type TaskJson = { /* 24 个规范字段 */ };
export function emptyTaskJson(overrides?: Partial<TaskJson>): TaskJson;
复刻 .trellis/scripts/common/task_store.py cmd_create 产出的 shape。现在以下 writer 都走这个工厂：
  • init.ts getBootstrapTaskJson（bootstrap task writer）
  • update.ts migration-task 写入块
修复 beta.0 遗留 gap：当时 cmd_create 已规范化，但两个 TypeScript writer 保持各自偏差 shape。 连带变更：
  • Migration task 不再写 legacy current_phase: 0 / next_action: [...]（Multi-Agent Pipeline 下线后即为死字段）
  • Bootstrap task checklist 从 task.json 里结构化 subtasks: [{name, status}] 迁到 prd.md 的 - [ ] markdown。所有 task 的 task.json.subtasks 现在统一为 string[]（子 task 目录名）。

​
8. 孤儿文件清理

Manifest 里 hash 验证的 safe-file-delete 条目：
路径原因Hash 数
.trellis/scripts/common/phase.pyMulti-Agent Pipeline 时代遗留，0.5 无 importer1
.trellis/scripts/create_bootstrap.py早期第 4 个 task.json writer，0.4 被 init.ts getBootstrapTaskJson 替换3（覆盖 0.3+ 用户）
未改过的自动删；改过的保留并 warn。 相关 dead code 清理：
  • TaskData TypedDict（common/types.py）删掉 current_phase: int 和 next_action: list[dict] 字段
  • script-conventions.md spec 目录树删掉 phase.py / create_bootstrap.py / multi_agent/

​
9. 删掉孤儿 markdown 模板

packages/cli/src/templates/markdown/spec/ 下 5 个从未被 markdown/index.ts import 的 .md 文件：
  • spec/backend/index.md
  • spec/backend/directory-structure.md
  • spec/backend/script-conventions.md
  • spec/guides/code-reuse-thinking-guide.md
  • spec/guides/cross-platform-thinking-guide.md
仅以 dead weight 形式（~35 KB）留在 dist/，从未铺到用户盘（configurator 写的是对应的 .md.txt stub）。不需要 migration 条目。修复存在于早期 0.1.x 以来的重复 bug。

​
升级

trellis update
非 breaking。
  • 所有平台：workflow.md + shared hooks 自动同步触发词 + 调研委派改动。没改过的 hash 匹配自动更新；改过的标准 Modified by you prompt。
  • Qoder：旧 .qoder/skills/trellis-{finish-work,continue}/SKILL.md 走 hash 验证自动删；新 .qoder/commands/trellis-{finish-work,continue}.md 由 configure 步骤写入。
  • Python 脚本：phase.py + create_bootstrap.py 走 hash 验证从 .trellis/scripts/ 自动删。
  • 已有 task：不动。Python readers（task.py、get_context.py）对缺失规范字段当 None 处理。beta.9 起新建的 bootstrap / migration task 按规范 shape 落。
安装：npm install -g @mindfoldhq/trellis@beta