Skip to main content
Skill-first architecture + hooks for everyone. The first preview of 0.5 reshapes two things at once: how templates are authored (single source, N outputs) and how AI stays on-workflow (per-turn hook, not once-per-session). Plus the largest cleanup since 0.4.0 — iFlow, multi-agent pipeline, Ralph Loop, dispatch/debug/plan agents, and six retired commands are all gone.

​
Skill-first template architecture

Commands and skills now live under packages/cli/src/templates/common/ as a single source of truth (3 commands + 5 skills). All 13 platforms resolve from common/ through per-platform adapters. Eliminates the prior N-copies-of-same-content drift that caused stale commands to linger on some platforms but not others. Two reusable helpers landed alongside:
  • createTemplateReader() (in template-utils.ts) — factory used by 6 platform template modules, replacing boilerplate import { readFileSync } from "fs" scaffolding. Uses fileURLToPath correctly so paths with spaces / on Windows resolve.
  • writeSharedHooks() + writeAgents() + writeSkills() (in configurators/shared.ts) — three-line calls that configurators use to emit their hook / agent / skill set, instead of bespoke file-copy loops.

​
Hooks + agents for 7 new platforms

Qoder, CodeBuddy, Factory Droid, Cursor, Gemini CLI, Kiro, and GitHub Copilot go from commands-only to fully agent-capable. Each ships:
  • Sub-agent definitions (implement / check / research) in the platform’s native format
  • Hook configuration wired via shared-hooks/ Python scripts (session-start, inject-subagent-context, statusline) — single implementation, cross-platform output adapters
Claude Code hooks are also migrated to the shared-hooks set, deleting a 1,435-line platform-specific implementation whose dead fallback code (AGENT_DEBUG, spec.jsonl/research.jsonl reads, hardcoded check-cross-layer.md references) had accumulated across releases.

​
Sub-agent context injection: class-1 hook vs class-2 pull-based

Codex, Copilot, Gemini, and Qoder (class-2) can’t reliably receive hook-modified sub-agent prompts:
  • Codex PreToolUse only fires for Bash; CollabAgentSpawn hook unimplemented (#15486)
  • Copilot preToolUse silently ignored on sub-agents (#2392 / #2540)
  • Gemini’s BeforeTool can’t see the caller’s context (#18128)
  • Qoder has no Task tool + context isolation
These 4 platforms now use a pull-based prelude: sub-agent definitions include an up-front instruction block that makes the sub-agent Read .current-task + prd.md + implement.jsonl/check.jsonl itself on first turn. Class-1 platforms (Claude / Cursor / OpenCode / Kiro / CodeBuddy / Droid) continue with hook-based push injection. Both paths live in shared infrastructure (applyPullBasedPreludeMarkdown / applyPullBasedPreludeToml) so future platforms pick one and it works.

​
Workflow enforcement v2: per-turn breadcrumb hook

New inject-workflow-state.py shared hook fires on every user prompt (UserPromptSubmit equivalent on 8 platforms; chat.message on OpenCode Bun plugin). It injects a ~200-byte <workflow-state> block nudging AI toward the next workflow step based on the active task’s status. Breadcrumb content is pulled from workflow.md [workflow-state:STATUS]...[/workflow-state:STATUS] blocks — users who fork the workflow edit one markdown file, not the hook Python. Covers four states: no_task / planning / in_progress / completed. Custom hyphenated statuses (in-review, blocked-by-team) are recognized via the STATUS regex [A-Za-z0-9_-]+. Unknown statuses emit a generic fallback instead of silent-exiting — the hook never leaves a conversation without guidance. Three-tier fallback (workflow.md missing → partial tag → unknown status) so the hook never breaks. Kiro is the one platform downgraded: its agentSpawn hook is per-sub-agent only, and there’s no upstream equivalent for main-session per-turn injection. Sub-agent context injection still works; per-turn breadcrumb is awaiting upstream support.

​
SessionStart payload restructure

The SessionStart <workflow> block grew from 2.7 KB to 9.5 KB by inlining Phase 1/2/3 step bodies — AI now has step-level how-to up front instead of lazy-loading via get_context.py --mode phase --step X.Y. Funded by shrinking <guidelines> from 10.9 KB to 4.6 KB: the cross-package guides/index.md stays inlined, but other spec/<pkg>/<layer>/index.md files are listed as paths only. Rationale: sub-agents get their specific specs via jsonl injection, and when the main agent needs details it reads on demand. Total session-start payload: 16.7 KB — under Claude Code’s ~20 KB additionalContext truncation threshold. workflow.md itself slimmed 17 KB → 14 KB: English-only (was bilingual), removed What is Trellis intro + File Structure tree + redundant Best Practices section, task.py command table expanded from 5 → 16 subcommands per PR #169’s grouping (lifecycle / context / metadata / hierarchy / PR) with a --help pointer for future-proofing.

​
Legacy cleanup (126-entry safe-file-delete migration)

This release removes four categories of primitives whose replacement is now the default:
  • iFlow platform — CLI unmaintained; entire .iflow/ tree + template source removed
  • Multi-agent pipeline (.trellis/scripts/multi_agent/ + worktree.yaml) — all major CLIs now ship their own worktree support; Trellis doesn’t need to reimplement
  • Ralph Loop hook (ralph-loop.py) — SubagentStop + exit-code-2 enforcement not portable across platforms; check agent’s self-fix loop is sufficient
  • Six commands + three sub-agents — parallel (superseded by native worktrees), onboard / create-command / integrate-skill (low usage), check-cross-layer (merged into check), record-session (subsumed by /finish-work); dispatch / debug / plan agents (replaced by skill routing)
All cleanup is hash-verified: if you modified any of these files locally they stay put with a warning; only pristine Trellis-written copies get removed. 126 safe-file-delete entries cover the full surface across all 13 platforms (with allowed_hashes pulled from historical git versions, so users on any past 0.3.x / 0.4.x version get a clean migration).

​
Command → skill migration (80 new manifest entries)

The 5 skills that users no longer invoke by hand (before-dev / brainstorm / break-loop / check / update-spec) now live under <platform>/skills/trellis-<name>/SKILL.md on every platform. Without migration, a user upgrading from 0.4.x would end up with both the old command file and the new skill file side-by-side. The manifest closes this cleanly:
  • 65 rename entries (13 platforms × 5 commands) — preserves user customizations via move + subsequent template-write prompt (not plain delete)
  • 3 rename entries for finish-work on skill-only platforms (.kiro / .qoder / .agents shared layer) — gains the trellis- prefix too
  • 10 safe-file-delete for the old start command across agent-capable and skill-only platforms — session-start hook replaces the command’s role
  • 2 safe-file-delete for the legacy improve-ut skill (.agent/workflows/ + .agents/skills/)
MigrationItem gained a new reason? field — version-specific context (e.g. “Trellis 0.4.0 skipped hashing this path, so pristine copies show as modified”) is authored inline in the manifest and rendered in the confirm prompt. No more hardcoded version-hints rotting in update.ts.

​
--migrate is now required for breaking releases

Running trellis update against a project whose installed version spans a manifest flagged breaking: true + recommendMigrate: true exits 1 with a clear error telling the user to add --migrate. Previously update would silently skip the rename/delete entries and still bump the .version stamp, leaving the project half-migrated (stale old paths next to new templates). --dry-run bypasses the gate so users can still preview.

​
Confirm-prompt redesign

When a migration file trips the modified-hash check, the interactive prompt now shows:
  1. What the migration does (from the manifest description)
  2. Why prompted — per-entry reason from the manifest, or a generic fallback
  3. Recommendation on each option (Backup / Rename / Skip) including the consequence of skipping (stale path persists to future updates)
Default choice is now backup-rename instead of skip — pressing Enter never destroys user edits or leaves orphan files.

​
Bug fixes

  • Backup no longer snapshots platform worktrees. createFullBackup excludes any /worktrees/ or /worktree/ path, so Claude Code’s .claude/worktrees/, Cursor’s .cursor/worktrees/, and Gemini CLI’s .gemini/worktrees/ don’t get duplicated on every trellis update (one backup could otherwise bloat to 100s of MB once worktrees are in use).
  • copy-templates build step leaks stale files. Added clean to the build chain (clean && tsc && copy-templates) so templates deleted from src/ stop lingering in dist/ and shipping to npm. Without this fix, safe-file-deletes fought re-writes from the stale dist templates in a loop.

​
Other notable changes

  • task.py create stops writing legacy current_phase / next_action fields. FP-analysis outcome: workflow.md’s Phase N.M is documentation layering, not runtime state — task.json.status is the single source of task-level state.
  • inject-subagent-context.py’s update_current_phase() function deleted — it was re-writing the legacy current_phase field on every Task spawn, silently undoing the deprecation.
  • Codex hooks integration: configureCodex now auto-writes shared-hooks (was skipping them); stderr warning on trellis init --codex about features.codex_hooks = true requirement in user’s ~/.codex/config.toml.
  • get_context.py --mode phase (no --step) returns Phase Index + Phase 1/2/3 bodies (was Phase Index only) — agent-less platforms (Kilo / Antigravity / Windsurf) running /start manually get the same content as hook-based platforms.
  • Hook-path CWD robustness (partial): inject-workflow-state.py walks up from CWD to find .trellis/, fixing subdirectory / submodule CWD drift for this hook. Full coverage across all hooks is a post-beta task.

​
Spec docs updated

  • platform-integration.md — new sections: Workflow State Injection (per-turn breadcrumb), Subagent Context Injection: Hook-based vs Pull-based, Guidelines: Paths-only vs Inline, Per-Turn Hook design principle (no silent-exit on “nothing to say”)
  • quality-guidelines.md — new section: Schema Deprecation: Audit ALL Writers, Not Just the Creator (from a Codex cross-review finding where cmd_create dropped a field but a hook kept re-writing it)
  • workflow.md — full English translation; slim structure; task.py 16-subcommand reference table
  • directory-structure.md + script-conventions.md — multi-agent references removed

​
Tests

595 tests passing, lint + typecheck clean. 41 new tests since the first draft of this changelog: workflow-state per-turn breadcrumb (7 cases), Phase Index expansion, paths-only guidelines, update_current_phase deletion regression, UserPromptSubmit platform wiring invariants, breaking-change gate (3 cases: block / dry-run bypass / --migrate pass), 0.5.0-beta.0 manifest shape (65-entry coverage, per-platform path invariant, breaking+recommendMigrate flags), worktree backup exclusion (12 cases across platform conventions + user data + edge cases).

​
Deferred to follow-up beta / rc

  • Kiro agentSpawn hook output-format validation in real environment
  • Cursor / CodeBuddy / Droid sub-agent hook injection real-env testing
  • Full hook-path CWD-robustness across all hooks (Windows cmd / PowerShell)
  • Parent-child Trellis config for submodule / micro-service repos (issue #172)

​
Migration

Run trellis update --migrate (the --migrate flag is required this release — 68 rename entries don’t auto-execute without it, and the new gate will exit 1 telling you to add it). Then the 138-entry safe-file-delete runs. User-modified files are preserved with warnings; only pristine Trellis-written files get cleaned up. Use trellis update --migrate --dry-run first if you want to preview. /trellis:record-session users: this command is removed. Its single job (writing a session journal via add_session.py) is now Step 3 of /trellis:finish-work, which also covers Quality Gate and Commit reminders. Replace any aliases or scripts that invoke record-session with finish-work. Codex users: enable features.codex_hooks = true in ~/.codex/config.toml to receive SessionStart + UserPromptSubmit breadcrumb injection. Without this flag hooks.json is silently ignored by Codex. iFlow users: the .iflow/ directory will be removed. Copy it out first if you want to keep it. Install: npm install -g @mindfoldhq/trellis@beta