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

> 2026-04-28

beta.17 更新了内置 Trellis 元信息、Pi subagent 和 task context wiring 相关的生成模板与平台集成。

## Enhancements

### Bundled `trellis-meta` skill

`trellis-meta` 现在通过内置 skill template pipeline 安装，不再要求额外走 marketplace 安装。

| 范围                | beta.17 行为                                                               |
| ----------------- | ------------------------------------------------------------------------ |
| Template source   | `packages/cli/src/templates/common/bundled-skills/trellis-meta/`         |
| Template reader   | `getBundledSkillTemplates()` 读取完整 skill 目录                               |
| Template resolver | `resolveBundledSkills()` 在 `SKILL.md` 和 `references/**` 内解析 placeholders |
| Template writer   | `writeSkills()` 同时写 workflow skills 和 bundled multi-file skills          |
| Template tracking | `collectSkillTemplates()` 把每个 bundled skill 文件纳入 update hash tracking    |

每个平台 skill root 都会在 `trellis init` 和 `trellis update` 时收到 `trellis-meta/SKILL.md` 及其 reference files。

### Pi subagent launcher and config

生成的 Pi extension 现在用 Windows-safe process path 启动嵌套 Pi subagent，并支持 per-agent model settings。

| 能力               | beta.17 行为                                                                  |
| ---------------- | --------------------------------------------------------------------------- |
| CLI resolution   | 可解析 `@mariozechner/pi-coding-agent/dist/cli.js`，存在时通过 `process.execPath` 运行 |
| Fallback         | 找不到 JS entrypoint 时继续使用 `spawn("pi", ...)`                                  |
| Prompt transport | 通过 stdin 传递 delegated prompt，不再作为 argv 参数传递                                 |
| Output mode      | 子 Pi 进程使用 `--mode text -p --no-session`                                     |
| Context          | 向子进程转发 `TRELLIS_CONTEXT_ID`                                                 |
| Cancellation     | 把 `AbortSignal` 接到 child process kill/reject 行为                             |
| Output bounds    | stdout/stderr 使用 bounded buffer，并带 truncation notice                        |

Subagent run configuration 可以来自 `.pi/agents/*.md` frontmatter，也可以来自单次 tool input：

```yaml theme={null}
---
model: anthropic/claude-sonnet-4
thinking: high
fallbackModels:
  - openai/gpt-5-mini
---
```

Extension 会把这些字段映射到 Pi CLI args：

| 输入                   | 子 Pi args                                                   |
| -------------------- | ----------------------------------------------------------- |
| `model` + `thinking` | 当 model 没有 thinking suffix 时使用 `--model <model>:<thinking>` |
| 只有 `model`           | `--model <model>`                                           |
| 只有 `thinking`        | `--thinking <level>`                                        |

Pi 仍然把 Trellis workflow skills 保留在 `.pi/skills`。共享 `.agents/skills` 要等 shared skill 文本平台中立后再启用。

### Workflow task slug wording

Trellis brainstorm instructions 现在明确说明：`task.py create --slug <auto>` 接收不带日期前缀的 slug。

`task.py create` 会自动添加 `MM-DD-` 目录前缀，所以命令示例不再暗示调用方需要在 `--slug` 里包含日期。

## Behavior Changes

### Init completion output

`trellis init` 不再打印 promotional completion block。

Init completion path 现在只保留 generated files、next actions 和可测试的 onboarding output。Integration coverage 会断言被移除的 promotional pain-point copy 不会返回。

## Bug Fixes

### Subagent context wiring

生成文件和 dogfood 平台文件现在能在更多 host-specific payload formats 下保留 subagent context。

| Host / file                                                                        | beta.17 行为                                                                                                          |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `.claude/hooks/inject-subagent-context.py`                                         | 解析 Cursor-style custom subagent payload，例如 `{ custom: { name } }` 和 `{ type: { case: "custom", value: { name } } }` |
| `.claude/hooks/inject-workflow-state.py` / `.codex/hooks/inject-workflow-state.py` | workflow-state breadcrumbs 要求使用精确的 `trellis-implement`、`trellis-check` 或 `trellis-research` agent name              |
| `.cursor/hooks/session-start.py`                                                   | 当 `CLAUDE_ENV_FILE` bridge 可用时，通过它为后续 Bash commands 保留 `TRELLIS_CONTEXT_ID`                                         |
| `AGENTS.md` template                                                               | 记录 subagents 必须在 yielding 前完成，以及什么时候应该 spawn subagents                                                              |

这些变更让 `implement.jsonl` 和 `check.jsonl` context loading 继续绑定到能获得 injected task context 的 Trellis agent names。

## Upgrade

已有项目：

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

这个 beta 不需要 `--migrate`。