@mindfoldhq/trellis 0.5.7 → 0.5.9

package/dist/migrations/manifests/0.5.7.json

@@ -9,7 +9,7 @@
     {
       "file": ".trellis/config.yaml",
       "sentinel": "codex:",
-      "sectionHeading": "Codex (sub-agent dispatch behavior)"
+      "sectionHeading": "Codex (dispatch behavior)"
     }
   ],
   "notes": "Patch on top of 0.5.6. Run `trellis update` (no `--migrate` needed). Codex users get the new `dispatch_mode` knob (default unchanged), hardened sub-agent role files, plus the previously-init-only `trellis-start` skill on the update path. Kiro users get an agent JSON that Kiro CLI no longer rejects. Codex 0.129+ users should run `/hooks` once after upgrading Codex to approve the Trellis `UserPromptSubmit` hook."

package/dist/migrations/manifests/0.5.8.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.5.8",
+  "description": "Bug fixes for Codex sub-agent behavior. AI no longer gets stuck waiting on sub-agents that don't exist; `trellis-research` on Codex no longer silently exits without producing files. Pure prompt-layer trim.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Bug Fixes:**\n- **Removing the sub-agent guidance in `AGENTS.md` stops Codex from calling / waiting on research agents.** Deleted the `## Subagents` section (36 lines, including the \"ALWAYS wait for every spawned subagent\" rule).\n- **Sub-agent mode fix: `trellis-research` on Codex no longer exits prematurely / produces no research files due to missing task context** (the main agent now includes the `Active task:` line when dispatching to research agents too).\n\n**Added:**\n- `CoreRule` block prepended to the `trellis-brainstorm` skill (adapted from https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/SKILL.md ).\n\nNon-Codex platforms (Claude Code, Cursor, OpenCode, Kiro, CodeBuddy, Droid) unchanged.",
+  "migrations": [],
+  "notes": "Pure prompt-layer trim. No Python or TypeScript edits. `trellis update` refreshes AGENTS.md / workflow.md / brainstorm skill content."
+}

package/dist/migrations/manifests/0.5.9.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.5.9",
+  "description": "Patch: codex dispatch defaults to inline + workflow.md namespaced into codex-inline / codex-sub-agent.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Bug Fixes:**\n- fix(codex): default `codex.dispatch_mode` flipped from `sub-agent` to `inline`. Codex sub-agents run with `fork_turns=\"none\"` isolation and can't inherit the parent session's task context, so they exit silently or recursively dispatch. Inline keeps the main Codex agent in charge so context isn't lost. Set `codex.dispatch_mode: sub-agent` in `.trellis/config.yaml` to opt back into the legacy dispatch flow. Invalid values fall back to inline.\n- fix(workflow): namespace `--platform codex` into virtual platforms `codex-inline` / `codex-sub-agent` so `workflow.md` `[Platform A, B, ...]` blocks render the correct guidance per mode. `inject-workflow-state.py` emits a `<codex-mode>` banner in the per-turn UserPromptSubmit prompt so Codex knows which mode it is in, and `[workflow-state:STATUS-inline]` blocks now drive the breadcrumb path for inline mode.\n\n**Internal:**\n- chore(manifests): restore `0.6.0-beta.0.json` on main. The version was published from `feat/v0.6.0-beta` but its manifest never landed on main, breaking adjacent-version update chains for users who hop between stable and beta lines.",
+  "migrations": [],
+  "notes": "Patch on top of 0.5.8. Run `trellis update` (no `--migrate` needed). Existing Codex projects keep working: if you previously uncommented `dispatch_mode: sub-agent`, that opt-in still routes to the legacy dispatch flow; if the line is commented (the default), behavior switches to inline."
+}

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

@@ -0,0 +1,16 @@
+{
+  "version": "0.6.0-beta.0",
+  "description": "First 0.6 beta. Adds `trellis mem`: search past Claude Code / Codex / OpenCode sessions by keyword, read the turns around each match, and dump full conversations.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**New feature: `trellis mem`**\n- `trellis mem` searches past Claude Code / Codex / OpenCode sessions by keyword and reads the turns around each match. Five subcommands wired through commander as a passthrough group: `projects`, `list`, `search`, `context`, `extract`. Strips hook injections, AGENTS.md preambles, and tool-call noise so search hits reflect real dialogue. Handles compaction (Claude `isCompactSummary` + Codex `compacted` events). Adds zod ^4 as a runtime dep.\n- 84 unit tests added on top of the integrated POC source: 11 pure helpers (Tier 1, 44 cases), 3 platform parsers with inline fixtures (Tier 2, 24 cases), 5 subcommand integration smoke (Tier 3, 16 cases). mem.ts statement coverage 81.89% / function 89.04% / line 87.93%.",
+  "migrations": [],
+  "configSectionsAdded": [
+    {
+      "file": ".trellis/config.yaml",
+      "sentinel": "codex:",
+      "sectionHeading": "Codex (sub-agent dispatch behavior)"
+    }
+  ],
+  "notes": "First public 0.6 beta. Install: `npm install -g @mindfoldhq/trellis@beta`. The `trellis mem` command is opt-in (only fires when invoked). Codex 0.129+ users should run `/hooks` once to approve the Trellis `UserPromptSubmit` hook."
+}

package/dist/templates/codex/skills/brainstorm/SKILL.md

@@ -5,6 +5,14 @@ description: "Collaborative requirements discovery session optimized for AI codi
 
 # Brainstorm - Requirements Discovery (AI Coding Enhanced)
 
+**CoreRule**: Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.
+
+---
+
 Guide AI through collaborative requirements discovery **before implementation**, optimized for AI coding workflows:
 
 * **Task-first** (capture ideas immediately)

package/dist/templates/common/skills/brainstorm.md

@@ -1,5 +1,13 @@
 # Brainstorm - Requirements Discovery (AI Coding Enhanced)
 
+**CoreRule**: Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.
+
+---
+
 Guide AI through collaborative requirements discovery **before implementation**, optimized for AI coding workflows:
 
 * **Task-first** (capture ideas immediately)
@@ -197,6 +205,8 @@ Why:
 - It returns only `{file path, one-line summary}` to the main agent
 - Independent topics can be **parallelized** — spawn multiple sub-agents in one tool call
 
+> **Codex exception**: on Codex CLI, do NOT dispatch `trellis-research` for research-first mode — do the research inline (WebFetch / WebSearch in the main session) and write findings to `{TASK_DIR}/research/<topic>.md` yourself. Reason: Codex `spawn_agent` runs sub-agents with `fork_turns="none"` (isolated context, no parent session inheritance), so the research sub-agent cannot resolve the active task path via `task.py current` and silently aborts without producing files. Inline research on Codex avoids this failure mode. The 3+ inline research calls limit (B rule in `workflow.md`) is relaxed for Codex specifically.
+
 Agent type: `trellis-research`
 Task description template: "Research <specific question>; persist findings to `{TASK_DIR}/research/<topic-slug>.md`."
 

package/dist/templates/copilot/prompts/brainstorm.prompt.md

@@ -4,12 +4,20 @@ description: "Trellis Copilot prompt: Brainstorm - Requirements Discovery (AI Co
 
 # Brainstorm - Requirements Discovery (AI Coding Enhanced)
 
+**CoreRule**: Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.
+
+---
+
 Guide AI through collaborative requirements discovery **before implementation**, optimized for AI coding workflows:
 
 * **Task-first** (capture ideas immediately)
 * **Action-before-asking** (reduce low-value questions)
 * **Research-first** for technical choices (avoid asking users to invent options)
-* **Diverge �?Converge** (expand thinking, then lock MVP)
+* **Diverge �?Converge** (expand thinking, then lock MVP)
 
 ---
 
@@ -30,19 +38,19 @@ Triggered from `/` when the user describes a development task, especially when:
    Always ensure a task exists at the start so the user's ideas are recorded immediately.
 
 2. **Action before asking**
-   If you can derive the answer from repo code, docs, configs, conventions, or quick research �?do that first.
+   If you can derive the answer from repo code, docs, configs, conventions, or quick research �?do that first.
 
 3. **One question per message**
    Never overwhelm the user with a list of questions. Ask one, update PRD, repeat.
 
 4. **Prefer concrete options**
-   For preference/decision questions, present 2�? feasible, specific approaches with trade-offs.
+   For preference/decision questions, present 2�? feasible, specific approaches with trade-offs.
 
 5. **Research-first for technical choices**
    If the decision depends on industry conventions / similar tools / established patterns, do research first, then propose options.
 
-6. **Diverge �?Converge**
-   After initial understanding, proactively consider future evolution, related scenarios, and failure/edge cases �?then converge to an MVP with explicit out-of-scope.
+6. **Diverge �?Converge**
+   After initial understanding, proactively consider future evolution, related scenarios, and failure/edge cases �?then converge to an MVP with explicit out-of-scope.
 
 7. **No meta questions**
    Do not ask "should I search?" or "can you paste the code so I can continue?"
@@ -55,7 +63,7 @@ Triggered from `/` when the user describes a development task, especially when:
 Before any Q&A, ensure a task exists. If none exists, create one immediately.
 
 * Use a **temporary working title** derived from the user's message.
-* It's OK if the title is imperfect �?refine later in PRD.
+* It's OK if the title is imperfect �?refine later in PRD.
 
 ```bash
 TASK_DIR=$(python3 ./.trellis/scripts/task.py create "brainstorm: <short goal>" --slug <auto>)
@@ -138,8 +146,8 @@ Write findings into PRD:
 | Complexity   | Criteria                                               | Action                                      |
 | ------------ | ------------------------------------------------------ | ------------------------------------------- |
 | **Trivial**  | Single-line fix, typo, obvious change                  | Skip brainstorm, implement directly         |
-| **Simple**   | Clear goal, 1�? files, scope well-defined              | Ask 1 confirm question, then implement      |
-| **Moderate** | Multiple files, some ambiguity                         | Light brainstorm (2�? high-value questions) |
+| **Simple**   | Clear goal, 1�? files, scope well-defined              | Ask 1 confirm question, then implement      |
+| **Moderate** | Multiple files, some ambiguity                         | Light brainstorm (2�? high-value questions) |
 | **Complex**  | Vague goal, architectural choices, multiple approaches | Full brainstorm                             |
 
 > Note: Task already exists from Step 0. Classification only affects depth of brainstorming.
@@ -150,7 +158,7 @@ Write findings into PRD:
 
 Before asking ANY question, run the following gate:
 
-### Gate A �?Can I derive this without the user?
+### Gate A �?Can I derive this without the user?
 
 If answer is available via:
 
@@ -158,9 +166,9 @@ If answer is available via:
 * docs/specs/conventions
 * quick market/OSS research
 
-�?**Do not ask.** Fetch it, summarize, update PRD.
+�?**Do not ask.** Fetch it, summarize, update PRD.
 
-### Gate B �?Is this a meta/lazy question?
+### Gate B �?Is this a meta/lazy question?
 
 Examples:
 
@@ -168,21 +176,21 @@ Examples:
 * "Can you paste the code so I can proceed?"
 * "What does the code look like?" (when repo is available)
 
-�?**Do not ask.** Take action.
+�?**Do not ask.** Take action.
 
-### Gate C �?What type of question is it?
+### Gate C �?What type of question is it?
 
 * **Blocking**: cannot proceed without user input
 * **Preference**: multiple valid choices, depends on product/UX/risk preference
 * **Derivable**: should be answered by inspection/research
 
-�?Only ask **Blocking** or **Preference**.
+�?Only ask **Blocking** or **Preference**.
 
 ---
 
 ## Step 4: Research-first Mode (Mandatory for technical choices)
 
-### Trigger conditions (any �?research-first)
+### Trigger conditions (any �?research-first)
 
 * The task involves selecting an approach, library, protocol, framework, template system, plugin mechanism, or CLI UX convention
 * The user asks for "best practice", "how others do it", "recommendation"
@@ -190,10 +198,10 @@ Examples:
 
 ### Research steps
 
-1. Identify 2�? comparable tools/patterns
+1. Identify 2�? comparable tools/patterns
 2. Summarize common conventions and why they exist
 3. Map conventions onto our repo constraints
-4. Produce **2�? feasible approaches** for our project
+4. Produce **2�? feasible approaches** for our project
 
 ### Research output format (PRD)
 
@@ -236,15 +244,15 @@ Then ask **one** preference question:
 
 ---
 
-## Step 5: Expansion Sweep (DIVERGE) �?Required after initial understanding
+## Step 5: Expansion Sweep (DIVERGE) �?Required after initial understanding
 
 After you can summarize the goal, proactively broaden thinking before converging.
 
-### Expansion categories (keep to 1�? bullets each)
+### Expansion categories (keep to 1�? bullets each)
 
 1. **Future evolution**
 
-   * What might this feature become in 1�? months?
+   * What might this feature become in 1�? months?
    * What extension points are worth preserving now?
 
 2. **Related scenarios**
@@ -264,9 +272,9 @@ I understand you want to implement: <current goal>.
 
 Before diving into design, let me quickly diverge to consider three categories (to avoid rework later):
 
-1. Future evolution: <1�? bullets>
-2. Related scenarios: <1�? bullets>
-3. Failure/edge cases: <1�? bullets>
+1. Future evolution: <1�? bullets>
+2. Related scenarios: <1�? bullets>
+3. Failure/edge cases: <1�? bullets>
 
 For this MVP, which would you like to include (or none)?
 
@@ -278,8 +286,8 @@ For this MVP, which would you like to include (or none)?
 
 Then update PRD:
 
-* What's in MVP �?`Requirements`
-* What's excluded �?`Out of Scope`
+* What's in MVP �?`Requirements`
+* What's excluded �?`Out of Scope`
 
 ---
 
@@ -292,7 +300,7 @@ Then update PRD:
 * After each user answer:
 
   * Update PRD immediately
-  * Move answered items from `Open Questions` �?`Requirements`
+  * Move answered items from `Open Questions` �?`Requirements`
   * Update `Acceptance Criteria` with testable checkboxes
   * Clarify `Out of Scope`
 
@@ -308,20 +316,20 @@ Then update PRD:
 ```markdown
 For <topic>, which approach do you prefer?
 
-1. **Option A** �?<what it means + trade-off>
-2. **Option B** �?<what it means + trade-off>
-3. **Option C** �?<what it means + trade-off>
-4. **Other** �?describe your preference
+1. **Option A** �?<what it means + trade-off>
+2. **Option B** �?<what it means + trade-off>
+3. **Option C** �?<what it means + trade-off>
+4. **Other** �?describe your preference
 ```
 
 ---
 
 ## Step 7: Propose Approaches + Record Decisions (Complex tasks)
 
-After requirements are clear enough, propose 2�? approaches (if not already done via research-first):
+After requirements are clear enough, propose 2�? approaches (if not already done via research-first):
 
 ```markdown
-Based on current information, here are 2�? feasible approaches:
+Based on current information, here are 2�? feasible approaches:
 
 **Approach A: <name>** (Recommended)
 
@@ -465,17 +473,17 @@ After brainstorm completes (Step 8 confirmation approved), the flow continues to
 ```text
 Brainstorm
   Step 0: Create task directory + seed PRD
-  Step 1�?: Discover requirements, research, converge
-  Step 8: Final confirmation �?user approves
-  �?
+  Step 1�?: Discover requirements, research, converge
+  Step 8: Final confirmation �?user approves
+  �?
 Task Workflow Phase 2 (Prepare for Implementation)
   Code-Spec Depth Check (if applicable)
-  �?Research codebase (based on confirmed PRD)
-  �?Configure code-spec context (jsonl files)
-  �?Activate task
-  �?
+  �?Research codebase (based on confirmed PRD)
+  �?Configure code-spec context (jsonl files)
+  �?Activate task
+  �?
 Task Workflow Phase 3 (Execute)
-  Implement �?Check �?Complete
+  Implement �?Check �?Complete
 ```
 
 The task directory and PRD already exist from brainstorm, so Phase 1 of the Task Workflow is skipped entirely.

package/dist/templates/markdown/agents.md

@@ -16,42 +16,6 @@ If you're using Codex or another agent-capable tool, additional project-scoped h
 - `.agents/skills/` — reusable Trellis skills
 - `.codex/agents/` — optional custom subagents
 
-## Subagents
-
-- ALWAYS wait for every spawned subagent to reach a terminal status before yielding, acting on partial results, or spawning followups.
-  - On Codex, this means calling the `wait` tool with the subagent's thread id (requires `multi_agent_v2`). Do NOT infer completion from elapsed time.
-  - On Claude Code / OpenCode, this means awaiting the Task/agent tool result before continuing.
-- NEVER cancel or re-spawn a subagent that hasn't finished. If a subagent appears stuck, raise the wait timeout (Codex default 30s, max 1h) before judging it broken.
-- Spawn subagents automatically when:
-  - Parallelizable work (e.g., install + verify, npm test + typecheck, multiple tasks from plan)
-  - Long-running or blocking tasks where a worker can run independently
-  - Isolation for risky changes or checks
-
-### Codex-only — `spawn_agent` parameters
-
-When calling `spawn_agent`, ALWAYS pass `fork_turns="none"`. Without it the child inherits the parent transcript and sees your prior `spawn_agent(...)` records, then applies the "wait for spawned subagents" rule to itself — causing `wait_agent` self-deadlock.
-
-```text
-spawn_agent(agent_type="trellis-implement", message="...", fork_turns="none")
-```
-
-### Codex-only — multi-subagent close-loop
-
-When `wait` returns a `completed` notification, treat it as an event signal — not as "all done". Run this loop:
-
-1. Maintain an `expected_agents` set of dispatched sub-agent thread IDs.
-2. After each `wait` update:
-   1. Call `list_agents` to inspect ALL live agents' status.
-   2. For each agent now in a terminal state:
-      - Verify its promised deliverable exists (e.g. `{task_dir}/research/*.md`).
-      - Read or summarize as needed.
-      - `close_agent` to release the slot.
-      - Remove from `expected_agents`.
-   3. If `expected_agents` still contains running agents → keep waiting.
-   4. If `expected_agents` is empty → continue main flow.
-3. Never `wait` on an agent that has already reported `completed`.
-4. If a `completed` agent is missing its deliverable, treat it as failed — surface that in your report instead of re-waiting.
-
 Managed by Trellis. Edits outside this block are preserved; edits inside may be overwritten by a future `trellis update`.
 
 <!-- TRELLIS:END -->

package/dist/templates/shared-hooks/inject-workflow-state.py

@@ -227,20 +227,49 @@ def _read_trellis_config(root: Path) -> dict:
         return {}
 
 
+def _codex_mode_banner(config: dict) -> str:
+    """Emit a `<codex-mode>` banner for the additionalContext payload.
+
+    Reads `codex.dispatch_mode` from .trellis/config.yaml; defaults to
+    `inline` when missing or invalid because Codex sub-agents run with
+    `fork_turns="none"` isolation and can't inherit the parent session's
+    task context. The banner makes the active mode explicit to Codex AI
+    per turn, complementing the workflow-state body which is per-status.
+    Mode tells AI which dispatch protocol to follow; workflow-state tells
+    AI what step it's at.
+    """
+    mode = "inline"
+    if isinstance(config, dict):
+        codex_cfg = config.get("codex")
+        if isinstance(codex_cfg, dict):
+            cfg_mode = codex_cfg.get("dispatch_mode")
+            if cfg_mode in ("inline", "sub-agent"):
+                mode = cfg_mode
+    return f"<codex-mode>{mode}</codex-mode>"
+
+
 def resolve_breadcrumb_key(
     status: str, platform: str | None, config: dict
 ) -> str:
     """Pick the breadcrumb tag key based on Codex dispatch_mode.
 
-    Codex users may opt into ``codex.dispatch_mode: inline`` to have the main
-    agent edit code directly. When the opt-in is set, route to the parallel
-    ``<status>-inline`` tag block so the breadcrumb body matches the inline
-    workflow. Other platforms / modes return the plain status unchanged.
+    Codex defaults to ``inline`` because sub-agents run with ``fork_turns="none"``
+    isolation and can't inherit the parent session's task context. Users can
+    opt into ``codex.dispatch_mode: sub-agent`` in ``.trellis/config.yaml``
+    to use the parallel ``<status>-inline`` tag → ``<status>`` flip. Invalid
+    or missing values fall back to inline.
+
+    Non-codex platforms return the plain status unchanged.
     """
-    if platform == "codex" and isinstance(config, dict):
-        codex_cfg = config.get("codex")
-        if isinstance(codex_cfg, dict) and codex_cfg.get("dispatch_mode") == "inline":
-            return f"{status}-inline"
+    if platform == "codex":
+        mode = "inline"
+        if isinstance(config, dict):
+            codex_cfg = config.get("codex")
+            if isinstance(codex_cfg, dict):
+                cfg_mode = codex_cfg.get("dispatch_mode")
+                if cfg_mode in ("inline", "sub-agent"):
+                    mode = cfg_mode
+        return f"{status}-inline" if mode == "inline" else status
     return status
 
 
@@ -311,6 +340,7 @@ def main() -> int:
         parts: list[str] = [CODEX_SUB_AGENT_NOTICE]
         if task is None:
             parts.append(CODEX_NO_TASK_BOOTSTRAP_NOTICE)
+        parts.append(_codex_mode_banner(config))
         parts.append(breadcrumb)
         breadcrumb = "\n\n".join(parts)
 

package/dist/templates/trellis/config.yaml

@@ -59,12 +59,14 @@ max_journal_lines: 2000
 # default_package: frontend
 
 #-------------------------------------------------------------------------------
-# Codex (sub-agent dispatch behavior)
+# Codex (dispatch behavior)
 #-------------------------------------------------------------------------------
-# Opt out of "main session must dispatch trellis-implement / trellis-check
-# sub-agents" and let the main agent edit code inline. Codex-only knob;
-# other platforms ignore it. Default ("sub-agent") preserves existing
-# behavior, so nothing changes unless you uncomment the block below.
+# Codex-only knob; other platforms ignore it. Default ("inline") makes the
+# main Codex agent edit code directly because Codex sub-agents run with
+# `fork_turns="none"` isolation and can't inherit the parent session's
+# task context. Set to "sub-agent" to opt into the legacy dispatch model
+# (main agent spawns trellis-implement / trellis-check / trellis-research
+# sub-agents).
 #
 # codex:
-#   dispatch_mode: sub-agent  # or "inline" to let the main agent edit code directly
+#   dispatch_mode: inline  # or "sub-agent" to dispatch trellis-* sub-agents

package/dist/templates/trellis/scripts/common/workflow_phase.py

@@ -145,17 +145,29 @@ def _platform_matches(platform: str, block_names: list[str]) -> bool:
 
 
 def resolve_effective_platform(platform: str, config: dict) -> str:
-    """Map platform name through codex inline-mode opt-in.
+    """Map ``codex`` to a dispatch-mode-namespaced virtual platform name.
 
-    When ``codex.dispatch_mode`` is set to ``"inline"`` in .trellis/config.yaml
-    and the caller is running with ``--platform codex``, swap the name to
-    ``"kilo"`` so ``filter_platform`` surfaces the inline workflow content
-    that already lives in the ``[Kilo, Antigravity, Windsurf]`` blocks.
+    When ``--platform codex`` is passed, return ``"codex-inline"`` (default)
+    or ``"codex-sub-agent"`` based on ``.trellis/config.yaml`` ``codex.dispatch_mode``.
+    ``filter_platform`` then surfaces blocks whose marker lists include the
+    namespaced name (e.g. ``[codex-sub-agent, ...]`` or ``[codex-inline, Kilo,
+    Antigravity, Windsurf]``).
+
+    Default is ``inline`` because Codex sub-agents run with ``fork_turns="none"``
+    isolation and can't inherit the parent session's task context — inline
+    keeps the main agent in charge so context isn't lost. Invalid / missing
+    values also fall back to inline.
+
+    Other platforms are returned unchanged.
     """
     if platform == "codex":
+        mode = "inline"
         codex_cfg = config.get("codex") if isinstance(config, dict) else None
-        if isinstance(codex_cfg, dict) and codex_cfg.get("dispatch_mode") == "inline":
-            return "kilo"
+        if isinstance(codex_cfg, dict):
+            cfg_mode = codex_cfg.get("dispatch_mode")
+            if cfg_mode in ("inline", "sub-agent"):
+                mode = cfg_mode
+        return f"codex-{mode}"
     return platform
 
 

package/dist/templates/trellis/workflow.md

@@ -151,7 +151,7 @@ Phase 3: Finish  → distill lessons + wrap-up
 
 [workflow-state:no_task]
 No active task. **A Direct answer** — pure Q&A / explanation / lookup / chat; no file writes + one-line answer + repo reads ≤ 2 files → AI judges, no override needed.
-**B Create a task** — any implementation / code change / build / refactor work. Entry sequence: (1) `python3 ./.trellis/scripts/task.py create "<title>"` to create the task (status=planning, breadcrumb switches to [workflow-state:planning] for brainstorm + jsonl phase guidance) → (2) load `trellis-brainstorm` skill to discuss requirements with the user and iterate on prd.md → (3) once prd is done and jsonl is curated, run `task.py start <task-dir>` to enter [workflow-state:in_progress] for the implementation skeleton. For research-heavy work, dispatch `trellis-research` sub-agents — main agent must NOT do 3+ inline WebFetch / WebSearch / `gh api` calls. **"It looks small" is NOT grounds for downgrading B to A or C**.
+**B Create a task** — any implementation / code change / build / refactor work. Entry sequence: (1) `python3 ./.trellis/scripts/task.py create "<title>"` to create the task (status=planning, breadcrumb switches to [workflow-state:planning] for brainstorm + jsonl phase guidance) → (2) load `trellis-brainstorm` skill to discuss requirements with the user and iterate on prd.md → (3) once prd is done and jsonl is curated, run `task.py start <task-dir>` to enter [workflow-state:in_progress] for the implementation skeleton. **"It looks small" is NOT grounds for downgrading B to A or C**.
 **C Inline change** (per-turn only, escape hatch for B) — the user's CURRENT message MUST contain one of: "skip trellis" / "no task" / "just do it" / "don't create a task" / "跳过 trellis" / "别走流程" / "小修一下" / "直接改" / "先别建任务" → briefly acknowledge ("ok, skipping trellis flow this turn"), then inline. **Without seeing one of these phrases you must NOT inline on your own**; do not invent an override the user never said.
 [/workflow-state:no_task]
 
@@ -169,7 +169,6 @@ No active task. **A Direct answer** — pure Q&A / explanation / lookup / chat;
 Load the `trellis-brainstorm` skill and iterate on prd.md with the user.
 Phase 1.3 (required, once): before `task.py start`, you MUST curate `implement.jsonl` and `check.jsonl` — list the spec / research files sub-agents need so they get the right context injected. You may skip only if the jsonl already has agent-curated entries (the seed `_example` row alone doesn't count).
 Then run `task.py start <task-dir>` to flip status to in_progress.
-Research output **must** land in `{task_dir}/research/*.md`, written by `trellis-research` sub-agents. The main agent should not inline WebFetch / WebSearch — the PRD only links to research files.
 [/workflow-state:planning]
 
 <!-- Per-turn breadcrumb: shown throughout Phase 1 when codex.dispatch_mode=inline.
@@ -182,7 +181,6 @@ Research output **must** land in `{task_dir}/research/*.md`, written by `trellis
 Load the `trellis-brainstorm` skill and iterate on prd.md with the user.
 Phase 1.3 jsonl curation is **skipped** in inline dispatch mode — the main session loads `trellis-before-dev` directly in Phase 2 and reads spec context itself, so there is no sub-agent to inject jsonl into.
 Then run `task.py start <task-dir>` to flip status to in_progress.
-Research output **must** land in `{task_dir}/research/*.md`. In inline mode the main session may do research itself or dispatch `trellis-research` sub-agents.
 [/workflow-state:planning-inline]
 
 ### Phase 2: Execute
@@ -200,7 +198,7 @@ Research output **must** land in `{task_dir}/research/*.md`. In inline mode the
 **Flow**: trellis-implement → trellis-check → trellis-update-spec → commit (Phase 3.4) → `/trellis:finish-work`.
 **Main-session default (no override)**: dispatch the `trellis-implement` / `trellis-check` sub-agents — the main agent does NOT edit code by default. Phase 3.4 commit (required, once): after trellis-update-spec, or whenever implementation is verifiably complete, the main agent **drives the commit** — state the commit plan in user-facing text, then run `git commit` — BEFORE suggesting `/trellis:finish-work`. `/finish-work` refuses to run on a dirty working tree (paths outside `.trellis/workspace/` and `.trellis/tasks/`).
 **Sub-agent self-exemption**: if you are already running as `trellis-implement`, implement directly from the loaded task context and do NOT spawn another `trellis-implement`; if you are already running as `trellis-check`, review/fix directly and do NOT spawn another `trellis-check`. The default dispatch rule applies to the main session only.
-**Sub-agent dispatch protocol (all platforms, all sub-agents EXCEPT trellis-research)**: When you spawn `trellis-implement` / `trellis-check`, your dispatch prompt **MUST** start with one line: `Active task: <task path from \`task.py current\`>`. No exceptions. On class-2 platforms (codex / copilot / gemini / qoder) the sub-agent depends on this line because there is no hook to inject task context. On class-1 platforms (claude / cursor / opencode / kiro / codebuddy / droid) the line is normally redundant — the hook injects context directly — but it serves as a critical fallback when the hook fails (Windows + Claude Code PreToolUse silent skip, `--continue` resume, fork distribution, hooks disabled, etc.). `trellis-research` does not need this line because it operates without a task binding.
+**Sub-agent dispatch protocol (all platforms, all sub-agents)**: When you spawn `trellis-implement` / `trellis-check` / `trellis-research`, your dispatch prompt **MUST** start with one line: `Active task: <task path from \`task.py current\`>`. No exceptions. On class-2 platforms (codex / copilot / gemini / qoder) the sub-agent depends on this line because there is no hook to inject task context. On class-1 platforms (claude / cursor / opencode / kiro / codebuddy / droid) the line is normally redundant — the hook injects context directly — but it serves as a critical fallback when the hook fails (Windows + Claude Code PreToolUse silent skip, `--continue` resume, fork distribution, hooks disabled, etc.). For `trellis-research`, the line tells the sub-agent which `{task_dir}/research/` to write into.
 **Inline override** (per-turn only, escape hatch for sub-agent dispatch): the user's CURRENT message MUST explicitly contain one of: "do it inline" / "no sub-agent" / "你直接改" / "别派 sub-agent" / "main session 写就行" / "不用 sub-agent". **Without seeing one of these phrases you must NOT inline on your own**; do not invent an override the user never said.
 [/workflow-state:in_progress]
 
@@ -247,7 +245,7 @@ If you reach this state with uncommitted code, return to Phase 3.4 first — `/f
 
 When a user request matches one of these intents, load the corresponding skill (or dispatch the corresponding sub-agent) first — do not skip skills.
 
-[Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
+[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
 
 | User intent | Route |
 |---|---|
@@ -259,9 +257,9 @@ When a user request matches one of these intents, load the corresponding skill (
 
 **Why `trellis-before-dev` is NOT in this table:** you are not the one writing code — the `trellis-implement` sub-agent is. Sub-agent platforms get spec context via `implement.jsonl` injection / prelude, not via the main thread loading `trellis-before-dev`.
 
-[/Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
+[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
 
-[Kilo, Antigravity, Windsurf]
+[codex-inline, Kilo, Antigravity, Windsurf]
 
 | User intent | Skill |
 |---|---|
@@ -271,11 +269,11 @@ When a user request matches one of these intents, load the corresponding skill (
 | Stuck / fixed same bug several times | `trellis-break-loop` |
 | Spec needs update | `trellis-update-spec` |
 
-[/Kilo, Antigravity, Windsurf]
+[/codex-inline, Kilo, Antigravity, Windsurf]
 
 ### DO NOT skip skills
 
-[Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
+[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
 
 | What you're thinking | Why it's wrong |
 |---|---|
@@ -284,9 +282,9 @@ When a user request matches one of these intents, load the corresponding skill (
 | "I already know the spec" | The spec may have been updated since you last read it; the sub-agent gets the fresh copy, you may not |
 | "Code first, check later" | `trellis-check` surfaces issues you won't notice yourself; earlier is cheaper |
 
-[/Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
+[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
 
-[Kilo, Antigravity, Windsurf]
+[codex-inline, Kilo, Antigravity, Windsurf]
 
 | What you're thinking | Why it's wrong |
 |---|---|
@@ -295,7 +293,7 @@ When a user request matches one of these intents, load the corresponding skill (
 | "I already know the spec" | The spec may have been updated since you last read it; read again |
 | "Code first, check later" | `trellis-check` surfaces issues you won't notice yourself; earlier is cheaper |
 
-[/Kilo, Antigravity, Windsurf]
+[/codex-inline, Kilo, Antigravity, Windsurf]
 
 ### Loading Step Detail
 
@@ -344,7 +342,7 @@ Return to this step whenever requirements change and revise `prd.md`.
 
 Research can happen at any time during requirement exploration. It isn't limited to local code — you can use any available tool (MCP servers, skills, web search, etc.) to look up external information, including third-party library docs, industry practices, API references, etc.
 
-[Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
+[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
 
 Spawn the research sub-agent:
 
@@ -352,13 +350,13 @@ Spawn the research sub-agent:
 - **Task description**: Research <specific question>
 - **Key requirement**: Research output MUST be persisted to `{TASK_DIR}/research/`
 
-[/Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
+[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
 
-[Kilo, Antigravity, Windsurf]
+[codex-inline, Kilo, Antigravity, Windsurf]
 
-Do the research in the main session directly and write findings into `{TASK_DIR}/research/`.
+Do the research in the main session directly and write findings into `{TASK_DIR}/research/`. (For `codex-inline` this avoids the `fork_turns="none"` isolation that prevents `trellis-research` sub-agents from resolving the active task path.)
 
-[/Kilo, Antigravity, Windsurf]
+[/codex-inline, Kilo, Antigravity, Windsurf]
 
 **Research artifact conventions**:
 - One file per research topic (e.g. `research/auth-library-comparison.md`)
@@ -371,7 +369,7 @@ Brainstorm and research can interleave freely — pause to research a technical
 
 #### 1.3 Configure context `[required · once]`
 
-[Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
+[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
 
 Curate `implement.jsonl` and `check.jsonl` so the Phase 2 sub-agents get the right spec context. These files were seeded on `task create` with a single self-describing `_example` line; your job here is to fill in real entries.
 
@@ -412,13 +410,13 @@ Delete the seed `_example` line once real entries exist (optional — it's skipp
 
 Skip when: `implement.jsonl` has agent-curated entries (the seed row alone doesn't count).
 
-[/Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
+[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
 
-[Kilo, Antigravity, Windsurf]
+[codex-inline, Kilo, Antigravity, Windsurf]
 
 Skip this step. Context is loaded directly by the `trellis-before-dev` skill in Phase 2.
 
-[/Kilo, Antigravity, Windsurf]
+[/codex-inline, Kilo, Antigravity, Windsurf]
 
 #### 1.4 Activate task `[required · once]`
 
@@ -442,11 +440,11 @@ If `task.py start` errors with a session-identity message (no context key from h
 | `research/` has artifacts (complex tasks) | recommended |
 | `info.md` technical design (complex tasks) | optional |
 
-[Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
+[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
 
 | `implement.jsonl` has agent-curated entries (not just the seed row) | ✅ |
 
-[/Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
+[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
 
 ---
 
@@ -470,7 +468,7 @@ The platform hook/plugin auto-handles:
 
 [/Claude Code, Cursor, OpenCode, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
 
-[Codex]
+[codex-sub-agent]
 
 Spawn the implement sub-agent:
 
@@ -482,7 +480,7 @@ The Codex sub-agent definition auto-handles the context load requirement:
 - Resolves the active task with `task.py current --source`, then reads `prd.md` and `info.md` if present
 - Reads `implement.jsonl` and requires the agent to load each referenced spec file before coding
 
-[/Codex]
+[/codex-sub-agent]
 
 [Kiro]
 
@@ -498,7 +496,7 @@ The platform prelude auto-handles the context load requirement:
 
 [/Kiro]
 
-[Kilo, Antigravity, Windsurf]
+[codex-inline, Kilo, Antigravity, Windsurf]
 
 1. Load the `trellis-before-dev` skill to read project guidelines
 2. Read `{TASK_DIR}/prd.md` for requirements
@@ -506,11 +504,11 @@ The platform prelude auto-handles the context load requirement:
 4. Implement the code per requirements
 5. Run project lint and type-check
 
-[/Kilo, Antigravity, Windsurf]
+[/codex-inline, Kilo, Antigravity, Windsurf]
 
 #### 2.2 Quality check `[required · repeatable]`
 
-[Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
+[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
 
 Spawn the check sub-agent:
 
@@ -523,9 +521,9 @@ The check agent's job:
 - Auto-fix issues it finds
 - Run lint and typecheck to verify
 
-[/Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
+[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
 
-[Kilo, Antigravity, Windsurf]
+[codex-inline, Kilo, Antigravity, Windsurf]
 
 Load the `trellis-check` skill and verify the code per its guidance:
 - Spec compliance
@@ -534,7 +532,7 @@ Load the `trellis-check` skill and verify the code per its guidance:
 
 If issues are found → fix → re-check, until green.
 
-[/Kilo, Antigravity, Windsurf]
+[/codex-inline, Kilo, Antigravity, Windsurf]
 
 #### 2.3 Rollback `[on demand]`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindfoldhq/trellis",
-  "version": "0.5.7",
+  "version": "0.5.9",
   "description": "AI capabilities grow like ivy — Trellis provides the structure to guide them along a disciplined path",
   "type": "module",
   "main": "./dist/index.js",