Skip to main content

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.

After upgrading Codex 0.129, run /hooks once and approve the Trellis hook (without approval the workflow won’t auto-inject; details below). New codex.dispatch_mode knob lets Codex projects opt into inline dispatch. Fixes: Codex sub-agent wait_agent deadlock (#240 follow-up, #241), Kiro CLI rejecting agent JSON (#247), Windows trellis init not finding python3 / py -3 (#236). No new migrations.

​
Codex 0.129 compatibility

​
/hooks review gate (TUI approval required)

Codex 0.129 gates each installed hook behind a one-time /hooks TUI review. Until the user runs /hooks in Codex and approves the Trellis UserPromptSubmit hook, the workflow breadcrumb won’t auto-inject; every fresh Codex session looks like Trellis isn’t wired in. The existing <trellis-bootstrap> fallback in inject-workflow-state.py covers this gap: when the hook hasn’t fired, the fallback directs the AI to read the trellis-start skill manually so the workflow still runs (just less smoothly). No Trellis code change needed for the fallback. Run /hooks once after upgrading Codex to restore full auto-injection.

​
[features].codex_hooks to [features].hooks rename

Codex 0.129 renamed [features].codex_hooks to [features].hooks (legacy name still works but emits a deprecation warning on startup). Trellis docs (advanced/multi-platform, advanced/architecture, advanced/custom-hooks, advanced/appendix-f, start/install-and-first-task, start/everyday-use, start/how-it-works), the spec/cli/backend/platform-integration.md rules, and the trellis init runtime warning now point at the new name. The uninstall scrubber recognizes both hooks = true and the legacy codex_hooks = true so older projects still clean up cleanly.

​
Enhancements

​
Codex configurable dispatch mode

New project-level knob in .trellis/config.yaml: 
codex:
  dispatch_mode: sub-agent # default; set to "inline" to skip sub-agent dispatch
When inline is set, the <workflow-state> breadcrumb tells the main Codex agent to load trellis-before-dev, edit code directly, then load trellis-check for lint / typecheck / tests, instead of dispatching trellis-implement / trellis-check sub-agents. Mechanism: inject-workflow-state.py reads the config and resolves [workflow-state:in_progress-inline] / [workflow-state:planning-inline] blocks from workflow.md when codex+inline is set; get_context.py --platform codex swaps to the [Kilo, Antigravity, Windsurf] block content. Per-turn override phrases (do it inline / 你直接改 / etc.) keep working in both modes. Codex-only. Class-1 platforms (Claude Code, Cursor, OpenCode, Kiro, CodeBuddy, Droid) and the other class-2 platforms keep the dispatch default. .codex/agents/*.toml files are still written; sub-agent infrastructure stays installed.

​
configSectionsAdded manifest field

New optional manifest field declares which top-level keys this release introduces in .trellis/config.yaml: 
{
  "version": "0.5.7",
  "configSectionsAdded": [
    {
      "file": ".trellis/config.yaml",
      "sentinel": "codex:",
      "sectionHeading": "Codex (sub-agent dispatch behavior)",
    },
  ],
}
trellis update walks each manifest’s configSectionsAdded, and for each entry whose sentinel is missing from the user’s target file, appends the section content extracted from the bundled template. Append-only, idempotent (sentinel check on rerun). User customizations stay untouched. Future config additions declare a new entry in their own manifest, no update.ts change needed per addition. Replaces the prior “modified-file confirm prompt” path, where users who customized config.yaml had to either accept template (losing edits) or skip (missing the new section).

​
Bug Fixes

​
Codex sub-agent collab tools, structural disable (#240 follow-up, #241)

v0.5.5 removed the SessionStart injection vector. v0.5.6 added prompt-layer fork_turns="none" guidance to AGENTS.md. Both were prompt-layer mitigations. Ca11back’s reproduction on #241 showed the prompt-layer fix didn’t reach reality:
  • The main agent still spawned trellis-research with default fork_turns="all" despite the AGENTS.md rule.
  • The child inherited the parent’s transcript including prior spawn_agent(...) tool-call records.
  • The child read AGENTS.md’s “ALWAYS wait for every spawned subagent…” rule, applied it to itself, and called wait_agent on the inherited records.
  • No agents to wait for. No agents completed yet. Stuck.
Structural fix: each packages/cli/src/templates/codex/agents/trellis-{implement,check,research}.toml now contains: 
[features]
multi_agent = false

[features.multi_agent_v2]
enabled = false
With both flags off, Codex doesn’t register spawn_agent / wait_agent / list_agents / close_agent for the sub-agent. Adds [issue-241-followup] regression test asserting all three template toml files retain the disable block.

​
Codex trellis-start skill missing on update path

0.5.5’s configureCodex() writes .agents/skills/trellis-start/SKILL.md so the <trellis-bootstrap> notice from inject-workflow-state.py resolves to a real skill. But collectPlatformTemplates.codex.collectTemplates() (used by trellis update) was missed. Result: users upgrading from 0.4.x to 0.5.5/0.5.6 ran the safe-file-delete migration that removed .agents/skills/start/, then trellis update regenerated all the other trellis-* skill dirs from collectTemplates, but never wrote trellis-start. Their AI then reported “no .agents/skills/trellis-start/SKILL.md” on every turn that hit <trellis-bootstrap>. Fix: extracted resolveCodexTrellisStartSkill() helper in configurators/shared.ts, called from both configureCodex() (init) and collectPlatformTemplates.codex (update) so the file shows up on both paths. No drift possible. Both call the same helper.

​
Kiro CLI agent JSON schema migration (#247)

Kiro CLI rejected Trellis’s pre-0.5.7 agent JSON with “invalid agent”. Three schema changes per Kiro’s Agent Configuration Reference:
  1. instructions becomes prompt. Kiro CLI no longer accepts instructions.
  2. Adds allowedTools field mirroring tools. Kiro splits “available tools” from “permitted tools”; without allowedTools the agent can’t actually invoke anything.
  3. hooks array becomes object keyed by event name: 
    // before
"hooks": [
  { "on": "agentSpawn", "command": "...", "timeout_ms": 30000 }
]
// after
"hooks": {
  "agentSpawn": [{ "command": "..." }]
}
    on field removed (event is now the key). timeout_ms removed.
Affects all three trellis-{implement,check,research}.json files. Adds [issue-247] regression test asserting the new schema (prompt present, instructions absent, allowedTools array, hooks object not array).

​
Windows Python detection fallback chain (#236)

trellis init previously tried only python --version on Windows. If the host had Python under python3 (Microsoft Store) or py -3 (python.org launcher) but not python, init failed outright with Python command "python" not found. resolveSupportedPython() in packages/cli/src/commands/init.ts now walks a per-platform candidate list:
PlatformCandidate order
Windowspython, python3, py -3
Otherpython3, python
First candidate whose --version matches Python ≥ 3.9 wins. The resolved command is cached via setResolvedPythonCommand() in configurators/shared.ts so replacePythonCommandLiterals() and all downstream template / configurator writes pick up the same value. Two env-var escape hatches:
  • TRELLIS_PYTHON_CMD=<cmd> for explicit override (no probe).
  • TRELLIS_SKIP_PYTHON_CHECK=1 for skipping the probe entirely (pre-existing).
Failure case throws an aggregated error listing every candidate’s probe result plus a Windows-specific install hint pointing at python.org with the “Add Python to PATH” reminder. 6 new unit tests in packages/cli/test/commands/init-internals.test.ts cover the fallback chain, env-var overrides, sandbox-restricted EPERM, and aggregated failure mode.

​
Upgrade

npm install -g @mindfoldhq/trellis@latest
trellis update
No --migrate needed. Codex users get hardened sub-agent role files; Windows users no longer need to install 0.4.0 first. Codex 0.129+ users should run /hooks once after upgrading Codex to approve the Trellis UserPromptSubmit hook.