> ## 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: three bugs in `trellis update --migrate` / `init-context`. Not breaking; no `--migrate` required.

## Bug Fixes

### 1. `trellis-` prefix missing from codex / kiro skill paths

`get_trellis_command_path` in `cli_adapter.py` returned bare-name paths, ignoring the prefix 0.5.0-beta.0 introduced across 60+ skill dirs. `check.jsonl` generated by `task.py init-context` on codex / kiro projects pointed at non-existent files.

```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/` blocked Kiro / Antigravity / Windsurf detection

`.agents/skills/` is a shared cross-platform layer (Codex writes, Amp / Cline / Kimi Code / Warp consume via agentskills.io). It was listed in `_ALL_PLATFORM_CONFIG_DIRS`, blocking every detection branch whose exclude set didn't name it. `detect_platform` fell through to `claude`.

* Removed `".agents"` from `_ALL_PLATFORM_CONFIG_DIRS`.
* Added a guarded codex fallback at the end of `detect_platform`:

```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` now accepts `--platform`

Skills / commands are rendered per-platform; the invoking platform is known at render time. Threaded it end-to-end instead of re-detecting from the filesystem.

* `{{CLI_FLAG}}` placeholder added to `resolvePlaceholders` — resolves to the platform's `cliFlag` at configure time.
* `TemplateContext` gained `cliFlag: CliFlag`, asserted against `AIToolConfig.cliFlag` by a registry invariant test.
* `task.py init-context` gained `--platform`, threaded through `cmd_init_context` → `get_check_context(repo_root, platform=...)` → `get_cli_adapter(platform)`.
* `codex/skills/start/SKILL.md` and `copilot/prompts/start.prompt.md` now invoke:

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

Auto-detect remains as fallback when `--platform` is omitted (CLI-direct invocation, `TRELLIS_PLATFORM` env var).

### 4. `migrationGuide` back-fill for 0.5.0-beta.0 and 0.5.0-beta.5

`update.ts` builds the migrate-to-`<version>` task PRD by concatenating every `migrationGuide` between `fromVersion` and `toVersion`. Both breaking 0.5.x releases shipped without the field; users upgrading from 0.4.x saw a PRD containing only 0.3/0.4 historical guides, with nothing about the actual 0.5 breaking changes.

| Manifest            | Back-filled content                                                                                                      |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `0.5.0-beta.0.json` | 0.4→0.5 narrative: skill renames, retired commands, Multi-Agent Pipeline removal, iFlow drop, `task.json` schema cleanup |
| `0.5.0-beta.5.json` | Sub-agent rename: `implement` / `check` / `research` → `trellis-*`                                                       |

`packages/cli/scripts/create-manifest.js` now rejects manifests where `breaking && recommendMigrate && !migrationGuide`. `.trellis/spec/cli/backend/migrations.md` documents the rule.

End-to-end paths verified:

| From → To                      | Guides included                                |
| ------------------------------ | ---------------------------------------------- |
| `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` check docs-site changelog

`packages/cli/scripts/check-docs-changelog.js` runs before version bump. If `docs-site/changelog/v<target>.mdx`, `docs-site/zh/changelog/v<target>.mdx`, or their `docs.json` page entries are missing, the script exits 1. Added after beta.10 itself shipped without a docs-site changelog for this exact reason.

## Upgrade

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

Not breaking.

* **Upgraded from beta.9 and already ran `trellis update --migrate`**: `check.jsonl` in tasks created during that run still points at the old bare-name paths. Re-run `task.py init-context <task-dir> <type> --platform <platform>` on each, or recreate the task.
* **On 0.4.x, never migrated to 0.5 yet**: the migration task PRD now contains the real 0.4→0.5 guide.
* **Codex users with fresh clones missing `.codex/`**: `detect_platform` now returns `codex` instead of `claude` when `.agents/skills/trellis-*` is the only platform signal present.

Install: `npm install -g @mindfoldhq/trellis@beta`