@mindfoldhq/trellis 0.6.0-beta.0 → 0.6.0-beta.1

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.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.1.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.6.0-beta.1",
+  "description": "Beta patch: same Codex dispatch fix as 0.5.9 — defaults to inline + workflow.md namespaced into codex-inline / codex-sub-agent.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Bug Fixes:** (mirrors 0.5.9)\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.",
+  "migrations": [],
+  "notes": "Beta patch on top of 0.6.0-beta.0. Run `trellis update` (no `--migrate` needed). Behavior change matches 0.5.9 — if you previously uncommented `dispatch_mode: sub-agent`, that opt-in still routes to the legacy dispatch flow; if commented (the default), behavior switches to inline."
+}

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

@@ -245,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 |
 |---|---|
@@ -257,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 |
 |---|---|
@@ -269,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 |
 |---|---|
@@ -282,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 |
 |---|---|
@@ -293,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
 
@@ -342,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:
 
@@ -350,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`)
@@ -369,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.
 
@@ -410,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]`
 
@@ -440,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]
 
 ---
 
@@ -468,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:
 
@@ -480,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]
 
@@ -496,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
@@ -504,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:
 
@@ -521,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
@@ -532,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.6.0-beta.0",
+  "version": "0.6.0-beta.1",
   "description": "AI capabilities grow like ivy — Trellis provides the structure to guide them along a disciplined path",
   "type": "module",
   "main": "./dist/index.js",