Skip to main content
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/.developerGenerated task
missingn/a00-bootstrap-guidelines (creator, unchanged)
presentmissing00-join-<slug> (new: joiner flow)
presentpresentnone (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: 
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:
PathReasonHashes
.trellis/scripts/common/phase.pyMulti-Agent Pipeline era orphan; not imported in 0.51
.trellis/scripts/create_bootstrap.pyLegacy 4th task.json writer, replaced by init.ts getBootstrapTaskJson in 0.43 (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

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