> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trytrellis.app/llms.txt
> Use this file to discover all available pages before exploring further.

# v0.5.0-beta.9

> 2026-04-22

自 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/a                   | `00-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` 新增共享工厂：

```ts theme={null}
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.py`     | Multi-Agent Pipeline 时代遗留，0.5 无 importer                         | 1             |
| `.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。

## 升级

```bash theme={null}
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`