@mindfoldhq/trellis 0.6.0-beta.9 → 0.6.0-rc.0

package/dist/migrations/manifests/0.6.0-beta.18.json

@@ -0,0 +1,16 @@
+{
+  "version": "0.6.0-beta.18",
+  "description": "Beta patch: channel worker OOM guard, simplified channel message routing, bundled Trellis spec bootstrap skill docs, and safer task archive auto-commit failures.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Enhancements:**\n- feat(channel): default OOM guard for `trellis channel spawn`. Workers that stay continuously idle past `channel.worker_guard.idle_timeout` (default `5m`) are self-terminated with `killed{reason:\"idle-timeout\"}`. Mid-turn workers are not killed by idle cleanup.\n- feat(channel): spawn-time live-worker budget per project/scope. Default `channel.worker_guard.max_live_workers: 6`. Expired idle workers are cleaned first; if the budget is still exhausted, `spawn` rejects with live-worker details and kill / override hints.\n- feat(channel): simplified worker message routing by removing message tags from channel send/wait/run internals.\n- feat(config): `.trellis/config.yaml` gains a `channel.worker_guard` section via `trellis update`.\n- feat(skills): Trellis beta bundle includes the built-in `trellis-spec-bootstarp` skill for bootstrapping `.trellis/spec/` from the real codebase.\n**Bug Fixes:**\n- fix(cli): `task.py archive` now fails when its auto-commit fails instead of reporting a successful archive with uncommitted changes.",
+  "migrations": [],
+  "configSectionsAdded": [
+    {
+      "file": ".trellis/config.yaml",
+      "sentinel": "worker_guard:",
+      "sectionHeading": "Channel worker OOM guard"
+    }
+  ],
+  "notes": "Beta patch on top of 0.6.0-beta.17. `trellis update` appends `channel.worker_guard` defaults for existing projects. To opt out, set `channel.worker_guard.idle_timeout: 0` and / or `channel.worker_guard.max_live_workers: 0`, or pass `--idle-timeout 0` / `--max-live-workers 0` per spawn."
+}

package/dist/migrations/manifests/0.6.0-beta.19.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.6.0-beta.19",
+  "description": "Beta patch: Pi trellis_subagent native progress cards, durable channel idempotency, task create/archive collision guard, workflow breadcrumb clarification, and Codex 0.131 timeout bounds.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Enhancements:**\n- feat(pi): Pi extension now exposes `trellis_subagent` with native progress cards, `single` / `parallel` / `chain` dispatch modes, throttled live updates, and Trellis-agent validation (#286, #290).\n**Bug Fixes:**\n- fix(core): channel `sendMessage` and `postThread` accept durable `idempotencyKey` values so retries return the original JSONL event and do not duplicate strict-delivery `undeliverable` events.\n- fix(cli): `task.py create` now rejects slugs that already exist under `.trellis/tasks/archive/**` and prints the archived path (#291).\n- fix(workflow): `[workflow-state:in_progress]` now distinguishes sub-agent types from skills so agents do not call missing `trellis-implement` / `trellis-research` skills (#283).\n- fix(codex): `.codex/config.toml` emits `min_wait_timeout_ms`, `default_wait_timeout_ms`, and `max_wait_timeout_ms` together so Codex CLI 0.131+ accepts merged multi_agent_v2 timeout config (#294).\n**Internal:**\n- chore(release): restore the shipped `0.5.17` migration manifest so manifest continuity and update-chain checks pass for the beta release.",
+  "migrations": [],
+  "notes": "Beta patch on top of 0.6.0-beta.18. Run `trellis update` to refresh Pi, Codex, workflow, and task templates. No migration command is required."
+}

package/dist/migrations/manifests/0.6.0-beta.20.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.6.0-beta.20",
+  "description": "Beta patch: bundle the Trellis spec bootstrap skill in the CLI package and clarify Codex CLI 0.131+ timeout-bounds requirements.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Bug Fixes:**\n- fix(skills): `trellis-spec-bootstarp` is now included under `dist/templates/common/bundled-skills/`, so fresh `trellis init` and `trellis update` install the built-in spec bootstrap skill and track its reference files.\n- fix(docs): the v0.6.0-beta.19 changelog now states that the full Codex `multi_agent_v2` timeout-bounds config requires Codex CLI 0.131.0+.",
+  "migrations": [],
+  "notes": "Beta patch on top of 0.6.0-beta.19. Run `trellis update` to install the bundled `trellis-spec-bootstarp` skill. Codex users should use Codex CLI 0.131.0+ for the full multi_agent_v2 timeout-bounds config."
+}

package/dist/migrations/manifests/0.6.0-beta.21.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.6.0-beta.21",
+  "description": "Beta patch: stop writing the [features.multi_agent_v2] block to the generated Codex config.toml so Codex CLI 0.130 and the Codex desktop app can load the config.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Bug Fixes:**\n- fix(codex): `trellis init` / `trellis update` no longer write a `[features.multi_agent_v2]` block to `.codex/config.toml`. Codex CLI changed `features` deserialization between 0.130 and 0.131; the structured table form is only accepted by 0.131+. On 0.130 and earlier — including the Codex CLI bundled in the Codex desktop app — it failed with `data did not match any variant of untagged enum FeatureToml in features.multi_agent_v2`, aborting the entire config load and blocking Codex from starting. Codex's own default for multi_agent_v2 is used instead.",
+  "migrations": [],
+  "notes": "Beta patch on top of 0.6.0-beta.20. Run `trellis update` to regenerate `.codex/config.toml` without the multi_agent_v2 block. Tune multi_agent_v2 in your user-level ~/.codex/config.toml if needed."
+}

package/dist/migrations/manifests/0.6.0-beta.22.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.6.0-beta.22",
+  "description": "Beta patch: remove the duplicated pull-based prelude from the generated Codex sub-agent toml files, and restore the 0.5.19 migration manifest that was missing on the beta branch.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Bug Fixes:**\n- fix(codex): the generated `.codex/agents/trellis-check.toml` and `trellis-implement.toml` no longer contain the \"Required: Load Trellis Context First\" prelude twice. The codex toml source templates carried an inline copy that predated the code-injected prelude (`injectPullBasedPreludeToml`); the injector then added a second copy. The inline copies are removed so the injector is the single source, and a regression test asserts the prelude appears exactly once across all class-2 platforms.\n- fix(migrations): restore `src/migrations/manifests/0.5.19.json`, which was missing on the 0.6.0-beta branch. Its absence broke the manifest-continuity guard and would break `trellis update` for users on 0.5.19.",
+  "migrations": [],
+  "notes": "Beta patch on top of 0.6.0-beta.21. Run `trellis update` to regenerate `.codex/agents/` without the duplicated prelude."
+}

package/dist/migrations/manifests/0.6.0-beta.23.json

@@ -0,0 +1,88 @@
+{
+  "version": "0.6.0-beta.23",
+  "description": "Beta patch: dispatch channel runtime agent definitions, refresh registry-backed spec via update, add Reasonix platform support, ship trellis-session-insight bundled skill, and rename trellis-spec-bootstarp → trellis-spec-bootstrap.",
+  "breaking": false,
+  "recommendMigrate": true,
+  "changelog": "**Enhancements:**\n- feat(cli): `trellis init` and `trellis update` now ship `.trellis/agents/{check,implement}.md`, so switching to a channel-driven workflow no longer fails with \"Agent 'check' not found\" (#323).\n- feat(cli): `trellis update` refreshes registry-backed `.trellis/spec` templates through the existing hash/conflict flow. `trellis init --template <id>` persists the spec source/template in `.trellis/config.yaml` so subsequent updates can re-fetch it. Supports direct spec registries and marketplace-style registries (#324).\n- feat(platform): add **Reasonix** (DeepSeek-Reasonix) as the 15th supported AI coding tool via `trellis init --reasonix`. Subagent skills (`trellis-implement`, `trellis-check`) carry `runAs: subagent` frontmatter so Reasonix spawns them as isolated subagent loops (#301).\n- feat(skills): bundle `trellis-session-insight` skill that teaches the AI how and when to reach for `trellis mem` to recall past conversations across Claude Code and Codex sessions. Auto-dispatched to every supported platform on init/update.\n- feat(workflow): `trellis workflow --template <id>` and `trellis init --workflow <id>` print a stderr warning when the resolved workflow references `.trellis/agents/<name>.md` files that are missing on disk, pointing the user at `trellis update`.\n\n**Bug Fixes:**\n- fix(skills): rename bundled `trellis-spec-bootstarp` → `trellis-spec-bootstrap` (typo). `trellis update --migrate` ships a `rename-dir` migration that renames the installed directory across 13 platform skill roots; missing roots are silently skipped. Historical migration manifests `0.5.17.json` and `0.6.0-beta.18.json` keep the typoed text because they describe what already shipped to users on those versions (#296).",
+  "migrations": [
+    {
+      "type": "rename-dir",
+      "from": ".claude/skills/trellis-spec-bootstarp",
+      "to": ".claude/skills/trellis-spec-bootstrap",
+      "description": "Claude Code: rename installed bundled skill directory from typoed name to corrected name."
+    },
+    {
+      "type": "rename-dir",
+      "from": ".cursor/skills/trellis-spec-bootstarp",
+      "to": ".cursor/skills/trellis-spec-bootstrap",
+      "description": "Cursor: rename installed bundled skill directory from typoed name to corrected name."
+    },
+    {
+      "type": "rename-dir",
+      "from": ".opencode/skills/trellis-spec-bootstarp",
+      "to": ".opencode/skills/trellis-spec-bootstrap",
+      "description": "OpenCode: rename installed bundled skill directory from typoed name to corrected name."
+    },
+    {
+      "type": "rename-dir",
+      "from": ".agents/skills/trellis-spec-bootstarp",
+      "to": ".agents/skills/trellis-spec-bootstrap",
+      "description": "Codex / Gemini CLI (shared): rename installed bundled skill directory from typoed name to corrected name."
+    },
+    {
+      "type": "rename-dir",
+      "from": ".kiro/skills/trellis-spec-bootstarp",
+      "to": ".kiro/skills/trellis-spec-bootstrap",
+      "description": "Kiro: rename installed bundled skill directory from typoed name to corrected name."
+    },
+    {
+      "type": "rename-dir",
+      "from": ".qoder/skills/trellis-spec-bootstarp",
+      "to": ".qoder/skills/trellis-spec-bootstrap",
+      "description": "Qoder: rename installed bundled skill directory from typoed name to corrected name."
+    },
+    {
+      "type": "rename-dir",
+      "from": ".codebuddy/skills/trellis-spec-bootstarp",
+      "to": ".codebuddy/skills/trellis-spec-bootstrap",
+      "description": "CodeBuddy: rename installed bundled skill directory from typoed name to corrected name."
+    },
+    {
+      "type": "rename-dir",
+      "from": ".github/skills/trellis-spec-bootstarp",
+      "to": ".github/skills/trellis-spec-bootstrap",
+      "description": "GitHub Copilot: rename installed bundled skill directory from typoed name to corrected name."
+    },
+    {
+      "type": "rename-dir",
+      "from": ".factory/skills/trellis-spec-bootstarp",
+      "to": ".factory/skills/trellis-spec-bootstrap",
+      "description": "Droid: rename installed bundled skill directory from typoed name to corrected name."
+    },
+    {
+      "type": "rename-dir",
+      "from": ".pi/skills/trellis-spec-bootstarp",
+      "to": ".pi/skills/trellis-spec-bootstrap",
+      "description": "Pi Agent: rename installed bundled skill directory from typoed name to corrected name."
+    },
+    {
+      "type": "rename-dir",
+      "from": ".agent/skills/trellis-spec-bootstarp",
+      "to": ".agent/skills/trellis-spec-bootstrap",
+      "description": "Antigravity: rename installed bundled skill directory from typoed name to corrected name."
+    },
+    {
+      "type": "rename-dir",
+      "from": ".windsurf/skills/trellis-spec-bootstarp",
+      "to": ".windsurf/skills/trellis-spec-bootstrap",
+      "description": "Windsurf: rename installed bundled skill directory from typoed name to corrected name."
+    },
+    {
+      "type": "rename-dir",
+      "from": ".kilocode/skills/trellis-spec-bootstarp",
+      "to": ".kilocode/skills/trellis-spec-bootstrap",
+      "description": "Kilo: rename installed bundled skill directory from typoed name to corrected name."
+    }
+  ],
+  "notes": "Beta patch on top of 0.6.0-beta.22. Run `trellis update --migrate` to rename installed `trellis-spec-bootstarp/` skill directories to `trellis-spec-bootstrap/` across every platform you have configured (silently skips ones you do not). Plain `trellis update` also installs the new `trellis-session-insight` bundled skill and the `.trellis/agents/{check,implement}.md` channel runtime files."
+}

package/dist/migrations/manifests/0.6.0-rc.0.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.6.0-rc.0",
+  "description": "First release candidate for v0.6.0. Feature surface frozen; entering stabilization. Only fix since 0.6.0-beta.23 is removing explicit mcp__exa__* tools from bundled Claude-style sub-agent defs so they no longer silent-skip on installs without the Exa MCP server.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Bug Fixes:**\n- fix(agents): drop explicit `mcp__exa__*` tools from bundled `trellis-implement` and `trellis-check` agent definitions. Claude Code silently skips agent registration when an explicit MCP tool name fails to resolve, so users without the Exa MCP server installed had every Trellis sub-agent disappear from the dispatch list. `trellis-research` keeps external search by folding `mcp__exa__*` + `mcp__chrome-devtools__*` into a single `mcp__*` wildcard, which Claude Code resolves lazily and does not silent-skip on. OpenCode files use a different permission syntax and are unchanged (#302).\n\n**Internal:**\n- chore(release): v0.6 feature surface frozen at this RC. Open feature requests (#193, #318, #320, #325, #326, etc.) are deferred to v0.7 or later. Further changes on this line will be bug-only `0.6.0-rc.*` cuts.",
+  "migrations": [],
+  "notes": "First release candidate for v0.6.0. Run `npm install -g @mindfoldhq/trellis@rc && trellis update` to pick up the agent silent-skip fix. If you are coming from a beta older than 0.6.0-beta.23, also pass `--migrate` to apply the rename-dir migration that moves `trellis-spec-bootstarp/` to `trellis-spec-bootstrap/` across configured platform skill roots."
+}

package/dist/templates/claude/agents/trellis-check.md

@@ -2,7 +2,7 @@
 name: trellis-check
 description: |
   Code quality check expert. Reviews code changes against specs and self-fixes issues.
-tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa
+tools: Read, Write, Edit, Bash, Glob, Grep
 ---
 # Check Agent
 
@@ -27,14 +27,18 @@ Look for the `<!-- trellis-hook-injected -->` marker in your input above.
 
 Before checking, read:
 - `.trellis/spec/` - Development guidelines
+- Task `prd.md` - Requirements document
+- Task `design.md` - Technical design (if exists)
+- Task `implement.md` - Execution plan (if exists)
 - Pre-commit checklist for quality standards
 
 ## Core Responsibilities
 
 1. **Get code changes** - Use git diff to get uncommitted code
-2. **Check against specs** - Verify code follows guidelines
-3. **Self-fix** - Fix issues yourself, not just report them
-4. **Run verification** - typecheck and lint
+2. **Review task artifacts** - Check changes against prd.md, design.md if present, and implement.md if present
+3. **Check against specs** - Verify code follows guidelines
+4. **Self-fix** - Fix issues yourself, not just report them
+5. **Run verification** - typecheck and lint
 
 ## Important
 
@@ -53,10 +57,12 @@ git diff --name-only  # List changed files
 git diff              # View specific changes
 ```
 
-### Step 2: Check Against Specs
+### Step 2: Check Against Specs and Task Artifacts
 
-Read relevant specs in `.trellis/spec/` to check code:
+Read the task's prd.md, design.md if present, and implement.md if present, then read relevant specs in `.trellis/spec/` to check code:
 
+- Does it satisfy the task requirements
+- Does it follow the technical design and implementation plan when present
 - Does it follow directory structure conventions
 - Does it follow naming conventions
 - Does it follow code patterns

package/dist/templates/claude/agents/trellis-implement.md

@@ -2,7 +2,7 @@
 name: trellis-implement
 description: |
   Code implementation expert. Understands specs and requirements, then implements features. No git commit allowed.
-tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa
+tools: Read, Write, Edit, Bash, Glob, Grep
 ---
 # Implement Agent
 

package/dist/templates/claude/agents/trellis-research.md

@@ -2,7 +2,7 @@
 name: trellis-research
 description: |
   Code and tech search expert. Finds files, patterns, and tech solutions, and PERSISTS every finding to the current task's research/ directory. No code modifications outside that directory.
-tools: Read, Write, Glob, Grep, Bash, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa, Skill, mcp__chrome-devtools__*
+tools: Read, Write, Glob, Grep, Bash, Skill, mcp__*
 ---
 # Research Agent
 

package/dist/templates/codebuddy/agents/trellis-check.md

@@ -2,7 +2,7 @@
 name: trellis-check
 description: |
   Code quality check expert. Reviews code changes against specs and self-fixes issues.
-tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa
+tools: Read, Write, Edit, Bash, Glob, Grep
 ---
 # Check Agent
 
@@ -27,14 +27,18 @@ Look for the `<!-- trellis-hook-injected -->` marker in your input above.
 
 Before checking, read:
 - `.trellis/spec/` - Development guidelines
+- Task `prd.md` - Requirements document
+- Task `design.md` - Technical design (if exists)
+- Task `implement.md` - Execution plan (if exists)
 - Pre-commit checklist for quality standards
 
 ## Core Responsibilities
 
 1. **Get code changes** - Use git diff to get uncommitted code
-2. **Check against specs** - Verify code follows guidelines
-3. **Self-fix** - Fix issues yourself, not just report them
-4. **Run verification** - typecheck and lint
+2. **Review task artifacts** - Check changes against prd.md, design.md if present, and implement.md if present
+3. **Check against specs** - Verify code follows guidelines
+4. **Self-fix** - Fix issues yourself, not just report them
+5. **Run verification** - typecheck and lint
 
 ## Important
 
@@ -53,10 +57,12 @@ git diff --name-only  # List changed files
 git diff              # View specific changes
 ```
 
-### Step 2: Check Against Specs
+### Step 2: Check Against Specs and Task Artifacts
 
-Read relevant specs in `.trellis/spec/` to check code:
+Read the task's prd.md, design.md if present, and implement.md if present, then read relevant specs in `.trellis/spec/` to check code:
 
+- Does it satisfy the task requirements
+- Does it follow the technical design and implementation plan when present
 - Does it follow directory structure conventions
 - Does it follow naming conventions
 - Does it follow code patterns

package/dist/templates/codebuddy/agents/trellis-implement.md

@@ -2,7 +2,7 @@
 name: trellis-implement
 description: |
   Code implementation expert. Understands specs and requirements, then implements features. No git commit allowed.
-tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa
+tools: Read, Write, Edit, Bash, Glob, Grep
 ---
 # Implement Agent
 

package/dist/templates/codebuddy/agents/trellis-research.md

@@ -2,7 +2,7 @@
 name: trellis-research
 description: |
   Code and tech search expert. Finds files, patterns, and tech solutions, and PERSISTS every finding to the current task's research/ directory. No code modifications outside that directory.
-tools: Read, Write, Glob, Grep, Bash, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa, Skill, mcp__chrome-devtools__*
+tools: Read, Write, Glob, Grep, Bash, Skill, mcp__*
 ---
 # Research Agent
 

package/dist/templates/codex/agents/trellis-check.toml

@@ -12,31 +12,6 @@ CRITICAL — Recursion guard (read first):
 
 ---
 
-## Required: Load Trellis Context First
-
-This platform does NOT auto-inject task context via hook. Before doing anything else, you MUST load context yourself.
-
-### Step 1: Find the active task path
-
-Try in order — stop at the first one that yields a task path:
-
-1. **Look at the dispatch prompt** you received from the main agent. If its first line is `Active task: <path>` (e.g. `Active task: .trellis/tasks/04-17-foo`), use that path. The main agent is required to include this line on class-2 platforms.
-2. **Run** `python3 ./.trellis/scripts/task.py current --source` and read the `Current task:` line.
-3. **If both fail** (no `Active task:` line in the prompt and `task.py current` returns no task), ask the user which task to work on; do NOT guess.
-
-### Step 2: Load task context from the resolved path
-
-1. Read `<task-path>/check.jsonl` — JSONL list of spec/research files relevant to this agent.
-2. For each entry in the JSONL, Read its `file` path — these are the specs and research notes you must follow.
-   **Skip rows without a `"file"` field** (e.g. `{"_example": "..."}` seed rows left over from `task.py create` before the curator ran).
-3. Read the task's `prd.md` (requirements), then `design.md` if present (technical design), then `implement.md` if present (execution plan).
-
-If `check.jsonl` has no curated entries (only a seed row, or the file is missing), fall back to: read the task artifacts, list available specs with `python3 ./.trellis/scripts/get_context.py --mode packages`, and pick the specs that match the task domain yourself. Do NOT block on the missing jsonl — lightweight tasks may be PRD-only, while complex tasks may also include `design.md` and `implement.md`.
-
-If the resolved task path has no `prd.md`, ask the user what to work on; do NOT proceed without context.
-
----
-
 You are the Trellis reviewer agent.
 
 Your job is to review code changes against specs AND fix issues directly — not just report them. You have write access; use it.

package/dist/templates/codex/agents/trellis-implement.toml

@@ -12,31 +12,6 @@ CRITICAL — Recursion guard (read first):
 
 ---
 
-## Required: Load Trellis Context First
-
-This platform does NOT auto-inject task context via hook. Before doing anything else, you MUST load context yourself.
-
-### Step 1: Find the active task path
-
-Try in order — stop at the first one that yields a task path:
-
-1. **Look at the dispatch prompt** you received from the main agent. If its first line is `Active task: <path>` (e.g. `Active task: .trellis/tasks/04-17-foo`), use that path. The main agent is required to include this line on class-2 platforms.
-2. **Run** `python3 ./.trellis/scripts/task.py current --source` and read the `Current task:` line.
-3. **If both fail** (no `Active task:` line in the prompt and `task.py current` returns no task), ask the user which task to work on; do NOT guess.
-
-### Step 2: Load task context from the resolved path
-
-1. Read `<task-path>/implement.jsonl` — JSONL list of spec/research files relevant to this agent.
-2. For each entry in the JSONL, Read its `file` path — these are the specs and research notes you must follow.
-   **Skip rows without a `"file"` field** (e.g. `{"_example": "..."}` seed rows left over from `task.py create` before the curator ran).
-3. Read the task's `prd.md` (requirements), then `design.md` if present (technical design), then `implement.md` if present (execution plan).
-
-If `implement.jsonl` has no curated entries (only a seed row, or the file is missing), fall back to: read the task artifacts, list available specs with `python3 ./.trellis/scripts/get_context.py --mode packages`, and pick the specs that match the task domain yourself. Do NOT block on the missing jsonl — lightweight tasks may be PRD-only, while complex tasks may also include `design.md` and `implement.md`.
-
-If the resolved task path has no `prd.md`, ask the user what to work on; do NOT proceed without context.
-
----
-
 You are the Trellis implementer agent.
 
 Rules:

package/dist/templates/codex/config.toml

@@ -5,8 +5,6 @@
 #
 #   [projects."/abs/path/to/this/repo"]
 #   trust_level = "trusted"
-#
-# Without trust, the [features] block below is loaded but disabled.
 
 # Keep AGENTS.md as the primary project instruction file.
 project_doc_fallback_filenames = ["AGENTS.md"]
@@ -19,17 +17,12 @@ project_doc_fallback_filenames = ["AGENTS.md"]
 # Codex 0.129+ additionally gates each installed hook behind a one-time
 # `/hooks` TUI review; until the user approves it, the hook stays inactive.
 
-# multi_agent_v2 forces structured subagent orchestration with the
-# `wait` tool — parent must block on terminal status before acting,
-# instead of cancelling / re-spawning. Incompatible with
-# [agents].max_threads (codex will reject the combination).
-# `enabled = true` is required inside the table — the table form does
-# NOT auto-enable the feature without it.
-# - max_concurrent_threads_per_session: bumps default 4 → 6.
-# - min_wait_timeout_ms: 480000 ms = 8 min. Codex default is 10 s, too
-#   short for Trellis subagents that routinely take 2-10 min. Hard
-#   ceiling is 3,600,000 (1 h).
-[features.multi_agent_v2]
-enabled = true
-max_concurrent_threads_per_session = 6
-min_wait_timeout_ms = 480000
+# NOTE: Trellis intentionally does NOT write a [features.multi_agent_v2]
+# block here. Codex CLI changed `features` deserialization between 0.130
+# and 0.131: the structured table form (with max_concurrent_threads_per_session
+# / *_wait_timeout_ms) is only accepted by 0.131+. On 0.130 and earlier —
+# including the codex CLI bundled inside the Codex desktop app — it fails
+# with `data did not match any variant of untagged enum FeatureToml`, which
+# aborts the entire config load and blocks Codex from starting. Codex's own
+# default for multi_agent_v2 is used instead; tune it in your user-level
+# config if needed.

package/dist/templates/codex/hooks/session-start.py

@@ -18,6 +18,28 @@ import warnings
 from io import StringIO
 from pathlib import Path
 
+# Force UTF-8 on stdin/stdout/stderr on Windows. Default codepage there is
+# cp936 / cp1252 / etc. — non-ASCII content (Chinese task names, prd snippets)
+# both in stdin (hook payload from host CLI) and stdout (our emitted blocks)
+# raises UnicodeDecodeError / UnicodeEncodeError. Equivalent to `python -X utf8`
+# but applied per-stream so we don't depend on host CLI's command wiring.
+if sys.platform.startswith("win"):
+    import io as _io
+    for _stream_name in ("stdin", "stdout", "stderr"):
+        _stream = getattr(sys, _stream_name, None)
+        if _stream is None:
+            continue
+        if hasattr(_stream, "reconfigure"):
+            try:
+                _stream.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+            except Exception:
+                pass
+        elif hasattr(_stream, "detach"):
+            try:
+                setattr(sys, _stream_name, _io.TextIOWrapper(_stream.detach(), encoding="utf-8", errors="replace"))
+            except Exception:
+                pass
+
 
 def _normalize_windows_shell_path(path_str: str) -> str:
     """Normalize Unix-style shell paths to real Windows paths.

package/dist/templates/codex/hooks.json

@@ -5,7 +5,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "{{PYTHON_CMD}} .codex/hooks/inject-workflow-state.py",
+            "command": "{{PYTHON_CMD}} -X utf8 .codex/hooks/inject-workflow-state.py",
             "timeout": 15
           }
         ]

package/dist/templates/common/bundled-skills/trellis-meta/references/local-architecture/task-system.md

@@ -44,6 +44,33 @@ The Trellis task system is stored entirely under `.trellis/tasks/` in the user p
 | `commit` / `pr_url` | Commit and PR information after completion. |
 | `meta` | Extension fields. |
 
+## Parent / Child Task Trees
+
+Parent/child task relationships are for work structure. A parent task groups related deliverables under one source requirement set; it is not a dependency scheduler and does not replace the child task's own planning artifacts.
+
+Use a parent task when a request has multiple independently verifiable deliverables. The parent owns:
+
+- Source requirements and user-facing scope.
+- The map of child tasks and their responsibility boundaries.
+- Cross-child acceptance criteria and final integration review.
+
+Use child tasks for deliverables that can move through planning, implementation, check, and archive independently. If one child depends on another, write that dependency in the child `prd.md` / `implement.md`; do not rely on tree position to imply ordering.
+
+Create new children with:
+
+```bash
+python3 ./.trellis/scripts/task.py create "<child title>" --slug <child-slug> --parent <parent-dir>
+```
+
+Link or unlink existing tasks with:
+
+```bash
+python3 ./.trellis/scripts/task.py add-subtask <parent-dir> <child-dir>
+python3 ./.trellis/scripts/task.py remove-subtask <parent-dir> <child-dir>
+```
+
+`children` on the parent is a historical list. When a child is archived, Trellis keeps that child name in the parent so progress like `[2/3 done]` remains meaningful after completed children move to `archive/`.
+
 The AI should not treat phase numbers as task status. Task progress is mainly determined by `status`, artifact presence (`prd.md`, optional `design.md` / `implement.md`), whether JSONL context is configured for sub-agent mode, and the phase descriptions in `workflow.md`.
 
 ## Active Task

package/dist/templates/common/bundled-skills/trellis-session-insight/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: trellis-session-insight
+description: "Reach into past AI conversation history through the `trellis mem` CLI. Use whenever the user asks 'how did we solve X last time', 'have we discussed this before', 'what was the decision on X', 'remind me what we did in this task', '上次怎么解的', '之前讨论过吗', '想起一段对话', or when starting a brainstorm that overlaps prior work, debugging a familiar bug, continuing a task across sessions, or doing a finish-work review. Returns raw past dialogue; decide for the moment whether to update spec, append to task notes, quote inline in the answer, or just internalize."
+---
+
+# Trellis Session Insight
+
+This skill teaches an AI **how to call `trellis mem`** — the project's cross-session memory feedstock — and **when reaching for it is the right move**.
+
+It is intentionally a **capability skill, not a workflow**. There is no fixed output file, no required write-back step, no "always run after finish-work" rule. What to do with what `mem` returns is a judgement call made in the moment of the conversation. The skill exists so the AI knows the capability is there and can decide.
+
+## What `trellis mem` is
+
+A local CLI that indexes the user's past Claude Code and Codex conversation logs (the JSONL files each platform stores under `~/.claude/projects/` and `~/.codex/sessions/`) and lets you list, search, slice by Trellis task boundaries, and dump cleaned dialogue from them. OpenCode logs are not yet indexable (provider adapter pending) — when an OpenCode session is the obvious target, surface that limitation rather than guessing.
+
+Nothing in `mem` is uploaded. All reads are local.
+
+## When to reach for it
+
+The bar is "would a senior teammate ask 'didn't we already talk about this?'" — those are the moments. Some concrete patterns:
+
+- **Brainstorm rerun risk.** Starting a new task that touches an area the user has been in before, and you want to check whether a decision was already made — before re-asking the user.
+- **Familiar-bug debugging.** The current bug pattern feels like one the user reported / fixed before. Pulling the relevant past session can save a full debugging loop.
+- **Cross-session continuation.** The user resumes work after a gap and says "where were we" / "继续上次的" without being specific.
+- **Decision retrieval.** The user references "the decision we made about X" but the decision lives in an old brainstorm, not in any `prd.md` / `spec/`.
+- **Finish-work retrospective.** When the user explicitly asks for a wrap-up of what was decided / what hurt / what surprised them in this task — not as a forced step on every finish-work.
+- **Pattern-spotting across past work.** The user asks "do I keep making the same mistake on X" / "我每次都踩这个坑吗" — search across sessions answers that.
+
+If none of these apply, don't call `mem`. It is a tool, not a ceremony.
+
+## When NOT to reach for it
+
+- The relevant context is already in the current turn, `prd.md`, `design.md`, recent `git log`, or the open files. `mem` is for stuff that has fallen out of immediate reach.
+- The user is asking about a fact in the code, not a fact from a past conversation. `git log -p` / `grep` / reading the file directly is faster and more authoritative.
+- You are in a sub-agent (`trellis-implement` / `trellis-check`) whose dispatch prompt already includes the curated `implement.jsonl` / `check.jsonl` context. Adding `mem` on top usually just clutters.
+- The user has explicitly said "don't dig through history, just answer what I asked".
+
+## What to do with what `mem` returns
+
+Treat the output as **raw material**, not a deliverable. Once you have it, decide based on the live conversation:
+
+- **Quote inline in your reply** if a specific past exchange answers the user's current question — and cite the session-id / phase so the user can verify.
+- **Update `<task>/prd.md` or `<task>/design.md`** if `mem` surfaced a load-bearing decision that should have been written down but wasn't. Surface the proposed edit to the user first.
+- **Append to a task-local notes file** (e.g. `<task>/notes.md` or extending an existing one) if the finding belongs to the current task's record but doesn't fit the PRD.
+- **Update `.trellis/spec/`** if the finding is a project-wide convention or gotcha that would help future tasks. Run the `trellis-update-spec` skill for that — `session-insight` ends at the discovery.
+- **Just absorb it** for the next few turns and answer better, without writing anything. This is often the right move for one-off recall.
+
+Trellis does not prescribe a single destination. Forcing every recall into a fixed file makes the file grow into noise. Let the situation decide.
+
+## How to call it
+
+Full CLI reference is in `references/cli-quick-reference.md`. The 80% case is one of:
+
+```bash
+# Find sessions whose contents mention a keyword (project-scope is default;
+# add --global to search every project on this machine).
+trellis mem search "<keyword>"
+
+# Dump dialogue from one session, optionally filtered by phase or keyword.
+trellis mem extract <session-id> --phase brainstorm
+trellis mem extract <session-id> --grep "<keyword>"
+
+# Drill into a session: top-N hit turns + surrounding context.
+trellis mem context <session-id> --turns 3 --around 2
+
+# When you do not know the session id yet, start with list + filter.
+trellis mem list --task <task-dir>
+trellis mem projects   # → list active project cwds, then narrow
+```
+
+Phase slicing (`--phase brainstorm|implement|all`) cuts the session at `task.py create` and `task.py start` boundaries. For a finish-work review of the current task, `--phase brainstorm` recovers the planning discussion and `--phase implement` recovers the execution loop. Default is `all`.
+
+## Triggering patterns
+
+`references/triggering-patterns.md` lists more verbatim user phrasings (English + Chinese) that should make you think "reach for `mem`" — keep that handy when training instinct.
+
+## Out of scope
+
+- `mem` does not edit code or update files. Any write-back is your decision in the moment.
+- `mem` is read-only on the platform JSONL stores. It does not push or sync to remote.
+- This skill does not replace `trellis-update-spec` (which is the right tool for promoting a finding into project-wide guidance) or the platform-native task / spec workflow.

package/dist/templates/common/bundled-skills/trellis-session-insight/references/cli-quick-reference.md

@@ -0,0 +1,66 @@
+# `trellis mem` CLI Reference
+
+Full flag reference for the five subcommands. Pin this as the authoritative source — `trellis mem help` prints the same content at runtime, so anything here that drifts is a bug.
+
+## Subcommands
+
+| Command | Purpose |
+|---|---|
+| `list` | List sessions. Default subcommand when none is given. |
+| `search <keyword>` | Find sessions whose contents match a keyword. |
+| `context <session-id>` | Drill into one session: top-N hit turns + surrounding context. Pair with `--grep` for keyword anchoring. |
+| `extract <session-id>` | Dump cleaned dialogue. Combine with `--phase` / `--grep` to slice. |
+| `projects` | List active project `cwd` values with session counts. Use this to discover which `--cwd` to pass to other subcommands. |
+
+## Flags (apply where meaningful)
+
+| Flag | Subcommands | Meaning |
+|---|---|---|
+| `--platform claude\|codex\|opencode\|all` | all | Default `all`. OpenCode adapter is currently a stub on `0.6.0-beta.*` — see "Caveats" below. |
+| `--since YYYY-MM-DD` | list / search | Inclusive lower date bound. |
+| `--until YYYY-MM-DD` | list / search | Inclusive upper date bound. |
+| `--global` | list / search | Include sessions from every project on this machine. Default is the current project `cwd`. |
+| `--cwd <path>` | list / search | Force a specific project cwd instead of inferring from where you are. |
+| `--limit N` | list / search | Cap output rows. Default `50`. |
+| `--grep KW` | extract / context | Filter turns by keyword. Multi-token AND when whitespace-separated. |
+| `--phase brainstorm\|implement\|all` | extract | Slice session by Trellis task boundaries. `brainstorm` = `[task.py create, task.py start)`. `implement` = `[task.py start, task.py finish)` window. Default `all`. |
+| `--turns N` | context | Number of hit turns to return. Default `3`. |
+| `--around N` | context | Surrounding turns to include per hit. Default `1`. |
+| `--max-chars N` | context | Total character budget. Default `6000` (~1500 tokens). |
+| `--include-children` | search / context | Merge OpenCode sub-agent sessions into their parent session. |
+| `--json` | all | Emit machine-parseable JSON instead of human-readable output. |
+| `--task <task-dir>` | list | Narrow to sessions whose context-key resolved to a given task directory (uses `.trellis/.runtime/sessions/*.json`). |
+
+## Common one-liners
+
+```bash
+# What past sessions discussed "deadlock" anywhere on this machine?
+trellis mem search "deadlock" --global --limit 20
+
+# Inside a specific session, surface the top 5 turns that mention "lock contention"
+# plus 2 turns of surrounding context.
+trellis mem context 5842592d --grep "lock contention" --turns 5 --around 2
+
+# Recover the brainstorm window for a session — useful when continuing a task
+# the user started a week ago.
+trellis mem extract 5842592d --phase brainstorm
+
+# List every project this machine has Trellis sessions for, with counts.
+trellis mem projects
+```
+
+## Output shapes
+
+- **Default human output** (no `--json`): wrapped to a terminal, with session ids highlighted and turn markers visible. Suitable to read inline but messy to paste into a markdown file.
+- **`--json`**: stable schema, safe to parse and process. When piping `mem` output into a follow-up step (e.g. summarizing for a Lessons section), prefer `--json`.
+
+## Caveats
+
+- **OpenCode adapter is a stub on `0.6.0-beta.*`.** When `--platform` resolves to OpenCode (or `all` and OpenCode would be included), `mem` prints a one-line "reader unavailable" notice and continues with the other platforms. Don't promise OpenCode coverage in your reply until the adapter ships.
+- **`--phase` slicing depends on `task.py create` / `task.py start` invocations appearing in the recorded bash calls of the session.** Sessions where the user ran `task.py` from a different terminal — outside the recorded AI loop — will not have phase boundaries. `--phase all` is the safe fallback.
+- **`mem` indexes platform JSONL files directly.** If the user has cleared their Claude / Codex session storage, `mem` cannot recover what is no longer on disk.
+- **`mem` is read-only.** No remote sync, no edits to platform JSONL. Any write you do based on `mem` findings is your own follow-up call into the editing tools available to you.
+
+## When you need more than this reference
+
+Run `trellis mem help` in the user's shell. The runtime help is authoritative and will be ahead of this reference during fast-moving beta releases.