> ## 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.10

> 2026-04-22

Hotfix：`trellis update --migrate` / `init-context` 三个 bug。非 breaking，不用加 `--migrate`。

## Bug 修复

### 1. codex / kiro 下 skill 路径缺 `trellis-` 前缀

`cli_adapter.py` 的 `get_trellis_command_path` 返回不带前缀的路径，忽略了 0.5.0-beta.0 对 60+ 个 skill 目录加 `trellis-` 的改名。codex / kiro 项目跑 `task.py init-context` 生成的 `check.jsonl` 指向不存在的文件。

```python theme={null}
elif self.platform == "codex":
    return f".agents/skills/trellis-{name}/SKILL.md"
elif self.platform == "kiro":
    return f".kiro/skills/trellis-{name}/SKILL.md"
```

### 2. `.agents/skills/` 挡住 Kiro / Antigravity / Windsurf 探测

`.agents/skills/` 是跨平台共享层（Codex 写入 / Amp / Cline / Kimi Code / Warp 通过 agentskills.io 消费），之前被列进 `_ALL_PLATFORM_CONFIG_DIRS`，挡住所有没把它加进 exclude 的平台探测分支。`detect_platform` 落回 `claude`。

* 从 `_ALL_PLATFORM_CONFIG_DIRS` 移除 `".agents"`。
* `detect_platform` 末尾加 codex fallback：

```python theme={null}
agents_skills = project_root / ".agents" / "skills"
if agents_skills.is_dir() and not _has_other_platform_dir(project_root, set()):
    for entry in agents_skills.iterdir():
        if entry.is_dir() and entry.name.startswith("trellis-"):
            return "codex"
```

### 3. `init-context` 新增 `--platform`

skill / command 按平台 render，render 时平台已知；改成端到端传递，不再运行时从文件系统重探测。

* `resolvePlaceholders` 新增 `{{CLI_FLAG}}`，configure 时替换为平台 `cliFlag`。
* `TemplateContext` 新增 `cliFlag: CliFlag`，registry invariant 测试断言它和 `AIToolConfig.cliFlag` 一致。
* `task.py init-context` 新增 `--platform`，透过 `cmd_init_context` → `get_check_context(repo_root, platform=...)` → `get_cli_adapter(platform)`。
* `codex/skills/start/SKILL.md` 和 `copilot/prompts/start.prompt.md` 现在这么调：

```bash theme={null}
python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" <type> --platform {{CLI_FLAG}}
```

省略 `--platform` 时走 auto-detect（CLI 手敲、`TRELLIS_PLATFORM` 环境变量）。

### 4. 回填 0.5.0-beta.0 和 0.5.0-beta.5 的 `migrationGuide`

`update.ts` 通过拼接 `fromVersion` 到 `toVersion` 之间所有 `migrationGuide` 生成 migrate-to-`<version>` task PRD。两个 0.5.x breaking 版本都漏写 `migrationGuide`，导致从 0.4.x 升级的用户拿到的 PRD 里全是 0.3/0.4 老内容，0.5 breaking 一字未提。

| Manifest            | 回填内容                                                                                   |
| ------------------- | -------------------------------------------------------------------------------------- |
| `0.5.0-beta.0.json` | 0.4→0.5 narrative：skill 改名、退役命令、Multi-Agent Pipeline 移除、iFlow 下架、`task.json` schema 清理 |
| `0.5.0-beta.5.json` | Sub-agent 改名：`implement` / `check` / `research` → `trellis-*`                          |

`packages/cli/scripts/create-manifest.js` 现在拒绝 `breaking && recommendMigrate && !migrationGuide` 的 manifest。`.trellis/spec/cli/backend/migrations.md` 写入规则。

端到端验证：

| 起点 → 目标                        | 拿到的 guide                                    |
| ------------------------------ | -------------------------------------------- |
| `0.4.0 → 0.5.0-beta.10`        | `0.5.0-beta.0`、`0.5.0-beta.5`                |
| `0.3.9 → 0.5.0-beta.10`        | `0.4.0-beta.1`、`0.5.0-beta.0`、`0.5.0-beta.5` |
| `0.5.0-beta.4 → 0.5.0-beta.10` | `0.5.0-beta.5`                               |

### 5. `release:beta` / `release:rc` / `release:promote` 前置 docs-site changelog 检查

`packages/cli/scripts/check-docs-changelog.js` 在版本 bump 之前跑。若 `docs-site/changelog/v<target>.mdx`、`docs-site/zh/changelog/v<target>.mdx` 或它们在 `docs.json` 里的页面条目缺失，exit 1。beta.10 本身就是漏写 docs-site changelog 发出去的，所以加了这个。

## 升级

```bash theme={null}
trellis update
```

非 breaking。

* **从 beta.9 升上来且跑过 `trellis update --migrate` 的用户**：那次 run 创建的 task 里 `check.jsonl` 还指向旧的不带前缀的路径。对每个 task 重跑 `task.py init-context <task-dir> <type> --platform <平台>` 重生成，或者删掉 task 重建。
* **还在 0.4.x、没升过 0.5 的用户**：migration task PRD 里现在是真实的 0.4→0.5 内容。
* **`.codex/` 缺失的 fresh clone codex 用户**：`detect_platform` 现在会在 `.agents/skills/trellis-*` 是唯一平台信号时返回 `codex`，不再落到 `claude`。

安装：`npm install -g @mindfoldhq/trellis@beta`