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

Accumulated since beta.8: new joiner-onboarding task, polyrepo detection, AI-facing bootstrap PRDs, workflow tightening on all platforms, Qoder session-boundary command split, task.json schema unification, and orphan-script cleanup. Not breaking; no `--migrate` required.

## New Features

### 1. Joiner onboarding task

`trellis init` now dispatches on two filesystem flags:

| `.trellis/` | `.trellis/.developer` | Generated task                                 |
| ----------- | --------------------- | ---------------------------------------------- |
| missing     | n/a                   | `00-bootstrap-guidelines` (creator, unchanged) |
| present     | missing               | `00-join-<slug>` (new: joiner flow)            |
| present     | present               | none (same-dev re-init)                        |

`.trellis/.developer` is the per-checkout signal because it's listed in `.trellis/.gitignore` and therefore absent on fresh clones. `.trellis/workspace/<name>/` cannot serve this role — it's committed to git.

The joiner task is auto-set as the current task, so the new developer's first `/trellis:continue` lands on an onboarding PRD covering four topics: Trellis workflow, runtime mechanics (SessionStart hook, `<workflow-state>` injection, `trellis-implement` / `trellis-check` sub-agents, per-task jsonl manifests), project spec (`.trellis/spec/`), and assigned-work lookup via `task.py list --assignee <name>`.

### 2. AI-facing bootstrap / joiner PRDs

Both onboarding PRDs are now addressed to the AI, not the developer. Opening line:

```
**You (the AI) are running this task. The developer does not read this file.**
```

Content shifted from user-facing prompts (`Ask AI:`, `Read workflow.md`) to AI-side instructions (`Explain`, `Summarize X for them`, `If archive is empty, skip — don't invent examples`). Each PRD ends with a "Suggested opening line" template used verbatim on first response.

### 3. Polyrepo detection

`detectMonorepo()` gains a 7th parser that scans up to 2 levels deep for sibling `.git` directories or worktree gitlinks. Fires only when all 6 workspace parsers miss and no submodules are declared — workspace configs (pnpm-workspace.yaml, Cargo workspaces, etc.) take precedence.

* `DetectedPackage` gains `isGitRepo: boolean` (mutually exclusive with `isSubmodule`)
* `writeMonorepoConfig` emits `git: true` to bridge to the runtime schema already consumed by `get_git_packages()` in `config.py`
* `--monorepo` failure prints a 7-marker checklist + manual `config.yaml` example instead of a one-line error
* Init confirm prompt labels polyrepo packages with `(git repo)`
* `config.yaml` template documents the `git: true` field

Covers the "meta-repo" layout (multiple independent repos under a parent directory).

## Workflow Tightening (all platforms)

### 4. Task-creation trigger words

`workflow.md [workflow-state:no_task]` + `shared-hooks/inject-workflow-state.py` + OpenCode plugin now list explicit trigger words that require a task:

* **Chinese**: `重构` / `抽成` / `独立` / `分发` / `拆出来` / `搞一个` / `做成` / `接入` / `集成`
* **English**: `refactor` / `rewrite` / `extract` / `productize` / `publish` / `build X` / `design Y`

Exemption requires all three: (a) zero file writes this turn, (b) answer fits one reply, (c) no external research. Otherwise: create a task.

### 5. Research delegation

`common/skills/brainstorm.md` adds a "Delegate to trellis-research sub-agent" section with anti-pattern:

> Inline WebFetch/WebSearch (3+ calls) in the main session is an anti-pattern. Correct pattern: spawn `trellis-research` sub-agent via Task tool. Sub-agent writes findings to `{TASK_DIR}/research/<topic>.md`; returns path + one-line summary.

`workflow.md [workflow-state:in_progress]` renames the flow description from generic verbs (`implement → check → update`) to concrete agent types (`trellis-implement → trellis-check → trellis-update-spec → finish`).

## Qoder UX Fix

### 6. Session-boundary commands split out of the skill matcher

Before beta.9, all Qoder Trellis entry points — including `finish-work` and `continue` — lived as `.qoder/skills/trellis-*/SKILL.md`. Invocation was nondeterministic (depended on the skill matcher scoring user phrasing against each skill's description).

Now session-boundary commands are Qoder Custom Commands:

* `.qoder/commands/trellis-finish-work.md` (YAML frontmatter: `name`, `description`)
* `.qoder/commands/trellis-continue.md`

Users invoke via `/trellis-finish-work` / `/trellis-continue` (exact match).

Auto-trigger workflows (`brainstorm`, `before-dev`, `check`, `update-spec`, `break-loop`) remain as `.qoder/skills/trellis-<name>/SKILL.md`.

Infra change in `configurators/shared.ts`:

* New `wrapWithCommandFrontmatter(filePath, content)` helper
* New `COMMAND_DESCRIPTIONS` registry (short, imperative, distinct from `SKILL_DESCRIPTIONS` prose for the matcher)
* `collectBothTemplates` takes an optional `wrapCmd` callback

## Internal Cleanup

### 7. `task.json` schema unification

New shared factory in `packages/cli/src/utils/task-json.ts`:

```ts theme={null}
export type TaskJson = { /* 24 canonical fields */ };
export function emptyTaskJson(overrides?: Partial<TaskJson>): TaskJson;
```

Mirrors the shape produced by `.trellis/scripts/common/task_store.py cmd_create`. Now used by:

* `init.ts getBootstrapTaskJson` (bootstrap task writer)
* `update.ts` migration-task block

Fixes a gap from beta.0: `cmd_create` was canonicalized, but the two TypeScript writers kept their own divergent shapes.

Side effects:

* Migration tasks no longer emit legacy `current_phase: 0` / `next_action: [...]` (dead since Multi-Agent Pipeline removal)
* Bootstrap task checklist moved from structured `subtasks: [{name, status}]` in task.json to markdown `- [ ]` items in prd.md. `task.json.subtasks` is now `string[]` (child task dir names) across all tasks.

### 8. Orphan file cleanup

Hash-verified `safe-file-delete` entries in the manifest:

| Path                                   | Reason                                                                         | Hashes                |
| -------------------------------------- | ------------------------------------------------------------------------------ | --------------------- |
| `.trellis/scripts/common/phase.py`     | Multi-Agent Pipeline era orphan; not imported in 0.5                           | 1                     |
| `.trellis/scripts/create_bootstrap.py` | Legacy 4th task.json writer, replaced by `init.ts getBootstrapTaskJson` in 0.4 | 3 (covers 0.3+ users) |

Pristine copies auto-delete; locally-modified copies preserved with a warning.

Related dead code removed:

* `TaskData` TypedDict (`common/types.py`): drops `current_phase: int` and `next_action: list[dict]` fields
* `script-conventions.md` spec: removes `phase.py` / `create_bootstrap.py` / `multi_agent/` from directory trees

### 9. Orphan markdown templates removed

`packages/cli/src/templates/markdown/spec/`: removed 5 orphan `.md` files never imported by `markdown/index.ts`:

* `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`

These shipped in `dist/` as dead weight (\~35 KB) but never landed on user disks (paired `.md.txt` stubs are what the configurator writes). No migration entry needed. Resolves a duplication bug present since early 0.1.x.

## Upgrade

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

Not breaking.

* **All platforms**: `workflow.md` + shared hooks auto-sync the trigger-words + research-delegation changes. Hash-matched auto-update; `Modified by you` prompt if customized.
* **Qoder**: old `.qoder/skills/trellis-{finish-work,continue}/SKILL.md` hash-verified auto-delete; new `.qoder/commands/trellis-{finish-work,continue}.md` written by the configure step.
* **Python scripts**: `phase.py` + `create_bootstrap.py` hash-verified auto-delete from `.trellis/scripts/`.
* **Existing tasks**: untouched. Python readers (`task.py`, `get_context.py`) treat missing canonical fields as `None`. Newly-created bootstrap / migration tasks from beta.9 onward produce the canonical shape.

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