@mindfoldhq/trellis 0.5.3 → 0.5.5

package/dist/configurators/codex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codex.d.ts","sourceRoot":"","sources":["../../src/configurators/codex.ts"],"names":[],"mappings":"AAoBA;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmF/D"}
+{"version":3,"file":"codex.d.ts","sourceRoot":"","sources":["../../src/configurators/codex.ts"],"names":[],"mappings":"AAuBA;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAyG/D"}

package/dist/configurators/codex.js

@@ -1,8 +1,9 @@
 import path from "node:path";
 import { AI_TOOLS } from "../types/ai-tools.js";
 import { getAllAgents, getAllCodexSkills, getAllHooks, getConfigTemplate, getHooksConfig, } from "../templates/codex/index.js";
+import { getCommandTemplates } from "../templates/common/index.js";
 import { ensureDir, writeFile } from "../utils/file-writer.js";
-import { resolvePlaceholders, resolveAllAsSkillsNeutral, resolveBundledSkills, applyPullBasedPreludeToml, writeSkills, writeSharedHooks, replacePythonCommandLiterals, } from "./shared.js";
+import { resolvePlaceholders, resolvePlaceholdersNeutral, resolveAllAsSkillsNeutral, resolveBundledSkills, applyPullBasedPreludeToml, wrapWithSkillFrontmatter, writeSkills, writeSharedHooks, replacePythonCommandLiterals, } from "./shared.js";
 /**
  * Configure Codex by writing:
  * - .agents/skills/ — shared skills from common source
@@ -18,6 +19,18 @@ export async function configureCodex(cwd) {
     // safe when both writers produce identical output).
     const sharedSkillsRoot = path.join(cwd, ".agents", "skills");
     await writeSkills(sharedSkillsRoot, resolveAllAsSkillsNeutral(AI_TOOLS.codex.templateContext), resolveBundledSkills(AI_TOOLS.codex.templateContext));
+    // Additionally write `trellis-start` to .agents/skills/ — Codex-specific.
+    // The SessionStart hook was removed (de-recursion fix); inject-workflow-state.py
+    // injects a `<trellis-bootstrap>` block on no_task turns instructing the AI to
+    // invoke `$trellis-start` to load workflow context. Without this skill, that
+    // invocation has nothing to resolve. Other agent-capable platforms keep their
+    // working SessionStart hooks and don't need this.
+    const startTemplate = getCommandTemplates().find((t) => t.name === "start");
+    if (startTemplate) {
+        const trellisStartDir = path.join(sharedSkillsRoot, "trellis-start");
+        ensureDir(trellisStartDir);
+        await writeFile(path.join(trellisStartDir, "SKILL.md"), wrapWithSkillFrontmatter("trellis-start", resolvePlaceholdersNeutral(startTemplate.content, AI_TOOLS.codex.templateContext)));
+    }
     const codexRoot = path.join(cwd, ".codex");
     // Codex-specific skills (platform-specific) → .codex/skills/
     const codexSkillsRoot = path.join(codexRoot, "skills");

package/dist/configurators/codex.js.map

@@ -1 +1 @@
-{"version":3,"file":"codex.js","sourceRoot":"","sources":["../../src/configurators/codex.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"codex.js","sourceRoot":"","sources":["../../src/configurators/codex.ts"],"names":[],"mappings":"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"}

package/dist/migrations/manifests/0.5.4.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.5.4",
+  "description": "Patch: guard sub-agent recursion (#237) + fix compareVersions on hyphenated prereleases (#230).",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Bug Fixes:**\n- fix(workflow): guard sub-agent recursion (#237). On Codex, `[workflow-state:in_progress]` reaches the sub-agent's turn too, and the sub-agent followed its own dispatch instruction — spawning another `trellis-implement` instead of doing the work. Scoped the dispatch rule to the main session and added a self-exemption to all platform `trellis-implement` / `trellis-check` agent definitions.\n- fix(compare-versions): preserve hyphens inside prerelease identifiers (#230 by @voidborne-d). `String.split(\"-\", 2)` truncates the tail in JavaScript (unlike Python `maxsplit`), so `compareVersions(\"1.0.0-alpha-1\", \"1.0.0-alpha-2\")` returned `0` — the two versions sorted as equal. Fixed. Adds 20 test cases in `packages/cli/test/utils/compare-versions.test.ts`.",
+  "migrations": [],
+  "notes": "Patch on top of 0.5.3. Run `trellis update` (no `--migrate` needed). Affects every platform whose per-turn workflow-state breadcrumb can reach sub-agent turns (Codex confirmed; risk applies more broadly)."
+}

package/dist/migrations/manifests/0.5.5.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.5.5",
+  "description": "Patch: structural fix for Codex sub-agent recursion (#240, #242) — drop SessionStart hook, bootstrap via trellis-start skill.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Bug Fixes:**\n- fix(codex): drop SessionStart hook, bootstrap via `trellis-start` skill (#240, #242). Codex fires SessionStart for every spawn, and its hook input exposes no `agent_id` / `agent_type` field (`openai/codex#16226`) — so the dispatch directive in `codex/hooks/session-start.py` kept reaching sub-agent sessions, the sub-agent mistook itself for the main session and re-dispatched its own sub-agent (recursive turtles). The 0.5.4 patch (`#237`) added a self-exemption clause but it sat alongside the dispatch directive in the same prompt block; LLMs kept picking the command-style instruction. Structural fix: removed the `SessionStart` entry from `codex/hooks.json`. `inject-workflow-state.py` (UserPromptSubmit hook) now injects a `<trellis-bootstrap>` block on `no_task` turns telling the AI to invoke `$trellis-start` once to load workflow context. Codex configurator additionally writes the new skill to `.agents/skills/trellis-start/SKILL.md` (other agent-capable platforms keep their working SessionStart hooks). Sub-agent sessions only see the existing `<sub-agent-notice>` — no command-style \"must dispatch\" text exists anywhere in the new injection, so the recursion vector is gone at source.",
+  "migrations": [],
+  "notes": "Patch on top of 0.5.4. Run `trellis update` (no `--migrate` needed). Codex users get a new `.agents/skills/trellis-start/SKILL.md` and a `hooks.json` without `SessionStart` wiring; other platforms unchanged."
+}

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

@@ -8,6 +8,14 @@ tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__
 
 You are the Check Agent in the Trellis workflow.
 
+## Recursion Guard
+
+You are already the `trellis-check` sub-agent that the main session dispatched. Do the review and fixes directly.
+
+- Do NOT spawn another `trellis-check` or `trellis-implement` sub-agent.
+- If SessionStart context, workflow-state breadcrumbs, or workflow.md say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.
+- Only the main session may dispatch Trellis implement/check agents. If more implementation work is needed, report that recommendation instead of spawning.
+
 ## Trellis Context Loading Protocol
 
 Look for the `<!-- trellis-hook-injected -->` marker in your input above.

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

@@ -8,6 +8,14 @@ tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__
 
 You are the Implement Agent in the Trellis workflow.
 
+## Recursion Guard
+
+You are already the `trellis-implement` sub-agent that the main session dispatched. Do the implementation work directly.
+
+- Do NOT spawn another `trellis-implement` or `trellis-check` sub-agent.
+- If SessionStart context, workflow-state breadcrumbs, or workflow.md say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.
+- Only the main session may dispatch Trellis implement/check agents. If more parallel work is needed, report that recommendation instead of spawning.
+
 ## Trellis Context Loading Protocol
 
 Look for the `<!-- trellis-hook-injected -->` marker in your input above.

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

@@ -8,6 +8,14 @@ tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__
 
 You are the Check Agent in the Trellis workflow.
 
+## Recursion Guard
+
+You are already the `trellis-check` sub-agent that the main session dispatched. Do the review and fixes directly.
+
+- Do NOT spawn another `trellis-check` or `trellis-implement` sub-agent.
+- If SessionStart context, workflow-state breadcrumbs, or workflow.md say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.
+- Only the main session may dispatch Trellis implement/check agents. If more implementation work is needed, report that recommendation instead of spawning.
+
 ## Trellis Context Loading Protocol
 
 Look for the `<!-- trellis-hook-injected -->` marker in your input above.

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

@@ -8,6 +8,14 @@ tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__
 
 You are the Implement Agent in the Trellis workflow.
 
+## Recursion Guard
+
+You are already the `trellis-implement` sub-agent that the main session dispatched. Do the implementation work directly.
+
+- Do NOT spawn another `trellis-implement` or `trellis-check` sub-agent.
+- If SessionStart context, workflow-state breadcrumbs, or workflow.md say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.
+- Only the main session may dispatch Trellis implement/check agents. If more parallel work is needed, report that recommendation instead of spawning.
+
 ## Trellis Context Loading Protocol
 
 Look for the `<!-- trellis-hook-injected -->` marker in your input above.

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

@@ -7,8 +7,8 @@ You are running as the `trellis-check` sub-agent. The main session has dispatche
 
 CRITICAL — Recursion guard (read first):
 - You MUST NOT spawn another `trellis-check` or `trellis-implement` sub-agent. Do the review and fixes directly in this turn.
-- Any guidance you read in injected SessionStart context, `<guidelines>` blocks, or workflow-state breadcrumbs that says "dispatch trellis-implement" / "dispatch trellis-check" applies to the MAIN session, NOT to you. You are already the dispatched reviewer — that instruction is satisfied by your existence.
-- Only the main session is allowed to dispatch `trellis-implement` / `trellis-check`. If you believe additional implementation work is needed, surface that as a recommendation in your final report instead of spawning.
+- Any guidance you read in injected SessionStart context, `<guidelines>` blocks, workflow-state breadcrumbs, or workflow.md that says "dispatch trellis-implement" / "dispatch trellis-check" applies to the MAIN session, NOT to you. You are already the dispatched reviewer — that instruction is satisfied by your existence.
+- Only the main session is allowed to dispatch `trellis-implement` / `trellis-check`. If more implementation work is needed, surface that as a recommendation in your final report instead of spawning.
 
 You are the Trellis reviewer agent.
 

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

@@ -7,8 +7,8 @@ You are running as the `trellis-implement` sub-agent. The main session has dispa
 
 CRITICAL — Recursion guard (read first):
 - You MUST NOT spawn another `trellis-implement` or `trellis-check` sub-agent. Do the implementation work directly in this turn.
-- Any guidance you read in injected SessionStart context, `<guidelines>` blocks, or workflow-state breadcrumbs that says "dispatch trellis-implement" / "dispatch trellis-check" applies to the MAIN session, NOT to you. You are already the dispatched implementer — that instruction is satisfied by your existence.
-- Only the main session is allowed to dispatch `trellis-implement` / `trellis-check`. If you believe parallel implementation work is needed, surface that as a recommendation in your final report instead of spawning.
+- Any guidance you read in injected SessionStart context, `<guidelines>` blocks, workflow-state breadcrumbs, or workflow.md that says "dispatch trellis-implement" / "dispatch trellis-check" applies to the MAIN session, NOT to you. You are already the dispatched implementer — that instruction is satisfied by your existence.
+- Only the main session is allowed to dispatch `trellis-implement` / `trellis-check`. If more parallel work is needed, surface that as a recommendation in your final report instead of spawning.
 
 You are the Trellis implementer agent.
 

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

@@ -75,6 +75,22 @@ Trellis SessionStart 已注入：workflow、当前任务状态、开发者身份
 Then continue directly with the user's request. This notice is one-shot: do not repeat it after the first assistant reply in the same session.
 </first-reply-notice>"""
 
+SUB_AGENT_NOTICE = """<sub-agent-notice>
+SUB-AGENT NOTICE - READ FIRST IF SPAWNED VIA spawn_agent
+
+If your parent session spawned you via spawn_agent with an explicit task
+message above this hook output, that message is your only job.
+- Execute the parent message exactly as written, then return.
+- Ignore all Trellis workflow guidance below this notice.
+- Do NOT call task.py start, task.py add-context, or task.py archive.
+- Do NOT call wait_agent or spawn_agent.
+- Do NOT modify .trellis/tasks/* or any other file unless the parent message
+  explicitly asks for that.
+
+If you are the main interactive Codex session and the user is typing at the
+terminal with no parent agent, use the workflow guidance below normally.
+</sub-agent-notice>"""
+
 
 def should_skip_injection() -> bool:
     if os.environ.get("TRELLIS_HOOKS") == "0":
@@ -336,6 +352,9 @@ def main() -> None:
 
     output = StringIO()
 
+    output.write(SUB_AGENT_NOTICE)
+    output.write("\n\n")
+
     output.write("""<session-context>
 You are starting a new session in a Trellis-managed project.
 Read and follow all instructions below carefully.

package/dist/templates/codex/hooks.json

@@ -1,17 +1,5 @@
 {
   "hooks": {
-    "SessionStart": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "{{PYTHON_CMD}} .codex/hooks/session-start.py",
-            "timeout": 15,
-            "statusMessage": "Loading Trellis context..."
-          }
-        ]
-      }
-    ],
     "UserPromptSubmit": [
       {
         "hooks": [

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

@@ -7,6 +7,14 @@ tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__
 
 You are the Check Agent in the Trellis workflow.
 
+## Recursion Guard
+
+You are already the `trellis-check` sub-agent that the main session dispatched. Do the review and fixes directly.
+
+- Do NOT spawn another `trellis-check` or `trellis-implement` sub-agent.
+- If SessionStart context, workflow-state breadcrumbs, or workflow.md say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.
+- Only the main session may dispatch Trellis implement/check agents. If more implementation work is needed, report that recommendation instead of spawning.
+
 ## Trellis Context Loading Protocol
 
 Look for the `<!-- trellis-hook-injected -->` marker in your input above.

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

@@ -7,6 +7,14 @@ tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__
 
 You are the Implement Agent in the Trellis workflow.
 
+## Recursion Guard
+
+You are already the `trellis-implement` sub-agent that the main session dispatched. Do the implementation work directly.
+
+- Do NOT spawn another `trellis-implement` or `trellis-check` sub-agent.
+- If SessionStart context, workflow-state breadcrumbs, or workflow.md say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.
+- Only the main session may dispatch Trellis implement/check agents. If more parallel work is needed, report that recommendation instead of spawning.
+
 ## Trellis Context Loading Protocol
 
 Look for the `<!-- trellis-hook-injected -->` marker in your input above.

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

@@ -7,6 +7,14 @@ description: |
 
 You are the Check Agent in the Trellis workflow.
 
+## Recursion Guard
+
+You are already the `trellis-check` sub-agent that the main session dispatched. Do the review and fixes directly.
+
+- Do NOT spawn another `trellis-check` or `trellis-implement` sub-agent.
+- If SessionStart context, workflow-state breadcrumbs, or workflow.md say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.
+- Only the main session may dispatch Trellis implement/check agents. If more implementation work is needed, report that recommendation instead of spawning.
+
 ## Context
 
 Before checking, read:

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

@@ -7,6 +7,14 @@ description: |
 
 You are the Implement Agent in the Trellis workflow.
 
+## Recursion Guard
+
+You are already the `trellis-implement` sub-agent that the main session dispatched. Do the implementation work directly.
+
+- Do NOT spawn another `trellis-implement` or `trellis-check` sub-agent.
+- If SessionStart context, workflow-state breadcrumbs, or workflow.md say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.
+- Only the main session may dispatch Trellis implement/check agents. If more parallel work is needed, report that recommendation instead of spawning.
+
 ## Context
 
 Before implementing, read:

package/dist/templates/kiro/agents/trellis-check.json

@@ -1,8 +1,14 @@
 {
   "name": "trellis-check",
   "description": "Code quality check expert. Reviews code changes against specs and self-fixes issues.",
-  "instructions": "# Check Agent\n\nYou are the Check Agent in the Trellis workflow.\n\n## Trellis Context Loading Protocol\n\nLook for the `<!-- trellis-hook-injected -->` marker in your input above.\n\n- **If the marker is present**: prd / spec / research files have already been auto-loaded for you above. Proceed with the check work directly.\n- **If the marker is absent**: hook injection didn't fire (Windows + Claude Code, `--continue` resume, fork distribution, hooks disabled, etc.). Find the active task path from your dispatch prompt's first line `Active task: <path>`, then Read `<task-path>/prd.md` and the spec files listed in `<task-path>/check.jsonl` yourself before doing the work.\n\n## Context\n\nBefore checking, read:\n- `.trellis/spec/` - Development guidelines\n- Pre-commit checklist for quality standards\n\n## Core Responsibilities\n\n1. **Get code changes** - Use git diff to get uncommitted code\n2. **Check against specs** - Verify code follows guidelines\n3. **Self-fix** - Fix issues yourself, not just report them\n4. **Run verification** - typecheck and lint\n\n## Important\n\n**Fix issues yourself**, don't just report them.\n\nYou have write and edit tools, you can modify code directly.\n\n---\n\n## Workflow\n\n### Step 1: Get Changes\n\n```bash\ngit diff --name-only  # List changed files\ngit diff              # View specific changes\n```\n\n### Step 2: Check Against Specs\n\nRead relevant specs in `.trellis/spec/` to check code:\n\n- Does it follow directory structure conventions\n- Does it follow naming conventions\n- Does it follow code patterns\n- Are there missing types\n- Are there potential bugs\n\n### Step 3: Self-Fix\n\nAfter finding issues:\n\n1. Fix the issue directly (use edit tool)\n2. Record what was fixed\n3. Continue checking other issues\n\n### Step 4: Run Verification\n\nRun project's lint and typecheck commands to verify changes.\n\nIf failed, fix issues and re-run.\n\n---\n\n## Report Format\n\n```markdown\n## Self-Check Complete\n\n### Files Checked\n\n- src/components/Feature.tsx\n- src/hooks/useFeature.ts\n\n### Issues Found and Fixed\n\n1. `<file>:<line>` - <what was fixed>\n2. `<file>:<line>` - <what was fixed>\n\n### Issues Not Fixed\n\n(If there are issues that cannot be self-fixed, list them here with reasons)\n\n### Verification Results\n\n- TypeCheck: Passed\n- Lint: Passed\n\n### Summary\n\nChecked X files, found Y issues, all fixed.\n```",
-  "tools": ["read", "write", "shell", "glob", "grep"],
+  "instructions": "# Check Agent\n\nYou are the Check Agent in the Trellis workflow.\n\n## Recursion Guard\n\nYou are already the `trellis-check` sub-agent that the main session dispatched. Do the review and fixes directly.\n\n- Do NOT spawn another `trellis-check` or `trellis-implement` sub-agent.\n- If SessionStart context, workflow-state breadcrumbs, or workflow.md say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.\n- Only the main session may dispatch Trellis implement/check agents. If more implementation work is needed, report that recommendation instead of spawning.\n\n## Trellis Context Loading Protocol\n\nLook for the `<!-- trellis-hook-injected -->` marker in your input above.\n\n- **If the marker is present**: prd / spec / research files have already been auto-loaded for you above. Proceed with the check work directly.\n- **If the marker is absent**: hook injection didn't fire (Windows + Claude Code, `--continue` resume, fork distribution, hooks disabled, etc.). Find the active task path from your dispatch prompt's first line `Active task: <path>`, then Read `<task-path>/prd.md` and the spec files listed in `<task-path>/check.jsonl` yourself before doing the work.\n\n## Context\n\nBefore checking, read:\n- `.trellis/spec/` - Development guidelines\n- Pre-commit checklist for quality standards\n\n## Core Responsibilities\n\n1. **Get code changes** - Use git diff to get uncommitted code\n2. **Check against specs** - Verify code follows guidelines\n3. **Self-fix** - Fix issues yourself, not just report them\n4. **Run verification** - typecheck and lint\n\n## Important\n\n**Fix issues yourself**, don't just report them.\n\nYou have write and edit tools, you can modify code directly.\n\n---\n\n## Workflow\n\n### Step 1: Get Changes\n\n```bash\ngit diff --name-only  # List changed files\ngit diff              # View specific changes\n```\n\n### Step 2: Check Against Specs\n\nRead relevant specs in `.trellis/spec/` to check code:\n\n- Does it follow directory structure conventions\n- Does it follow naming conventions\n- Does it follow code patterns\n- Are there missing types\n- Are there potential bugs\n\n### Step 3: Self-Fix\n\nAfter finding issues:\n\n1. Fix the issue directly (use edit tool)\n2. Record what was fixed\n3. Continue checking other issues\n\n### Step 4: Run Verification\n\nRun project's lint and typecheck commands to verify changes.\n\nIf failed, fix issues and re-run.\n\n---\n\n## Report Format\n\n```markdown\n## Self-Check Complete\n\n### Files Checked\n\n- src/components/Feature.tsx\n- src/hooks/useFeature.ts\n\n### Issues Found and Fixed\n\n1. `<file>:<line>` - <what was fixed>\n2. `<file>:<line>` - <what was fixed>\n\n### Issues Not Fixed\n\n(If there are issues that cannot be self-fixed, list them here with reasons)\n\n### Verification Results\n\n- TypeCheck: Passed\n- Lint: Passed\n\n### Summary\n\nChecked X files, found Y issues, all fixed.\n```",
+  "tools": [
+    "read",
+    "write",
+    "shell",
+    "glob",
+    "grep"
+  ],
   "hooks": [
     {
       "on": "agentSpawn",

package/dist/templates/kiro/agents/trellis-implement.json

@@ -1,8 +1,14 @@
 {
   "name": "trellis-implement",
   "description": "Code implementation expert. Understands specs and requirements, then implements features. No git commit allowed.",
-  "instructions": "# Implement Agent\n\nYou are the Implement Agent in the Trellis workflow.\n\n## Trellis Context Loading Protocol\n\nLook for the `<!-- trellis-hook-injected -->` marker in your input above.\n\n- **If the marker is present**: prd / spec / research files have already been auto-loaded for you above. Proceed with the implementation work directly.\n- **If the marker is absent**: hook injection didn't fire (Windows + Claude Code, `--continue` resume, fork distribution, hooks disabled, etc.). Find the active task path from your dispatch prompt's first line `Active task: <path>`, then Read `<task-path>/prd.md`, `<task-path>/info.md` (if it exists), and the spec files listed in `<task-path>/implement.jsonl` yourself before doing the work.\n\n## Context\n\nBefore implementing, read:\n- `.trellis/workflow.md` - Project workflow\n- `.trellis/spec/` - Development guidelines\n- Task `prd.md` - Requirements document\n- Task `info.md` - Technical design (if exists)\n\n## Core Responsibilities\n\n1. **Understand specs** - Read relevant spec files in `.trellis/spec/`\n2. **Understand requirements** - Read prd.md and info.md\n3. **Implement features** - Write code following specs and design\n4. **Self-check** - Ensure code quality\n5. **Report results** - Report completion status\n\n## Forbidden Operations\n\n**Do NOT execute these git commands:**\n\n- `git commit`\n- `git push`\n- `git merge`\n\n---\n\n## Workflow\n\n### 1. Understand Specs\n\nRead relevant specs based on task type:\n\n- Spec layers: `.trellis/spec/<package>/<layer>/`\n- Shared guides: `.trellis/spec/guides/`\n\n### 2. Understand Requirements\n\nRead the task's prd.md and info.md:\n\n- What are the core requirements\n- Key points of technical design\n- Which files to modify/create\n\n### 3. Implement Features\n\n- Write code following specs and technical design\n- Follow existing code patterns\n- Only do what's required, no over-engineering\n\n### 4. Verify\n\nRun project's lint and typecheck commands to verify changes.\n\n---\n\n## Report Format\n\n```markdown\n## Implementation Complete\n\n### Files Modified\n\n- `src/components/Feature.tsx` - New component\n- `src/hooks/useFeature.ts` - New hook\n\n### Implementation Summary\n\n1. Created Feature component...\n2. Added useFeature hook...\n\n### Verification Results\n\n- Lint: Passed\n- TypeCheck: Passed\n```\n\n---\n\n## Code Standards\n\n- Follow existing code patterns\n- Don't add unnecessary abstractions\n- Only do what's required, no over-engineering\n- Keep code readable",
-  "tools": ["read", "write", "shell", "glob", "grep"],
+  "instructions": "# Implement Agent\n\nYou are the Implement Agent in the Trellis workflow.\n\n## Recursion Guard\n\nYou are already the `trellis-implement` sub-agent that the main session dispatched. Do the implementation work directly.\n\n- Do NOT spawn another `trellis-implement` or `trellis-check` sub-agent.\n- If SessionStart context, workflow-state breadcrumbs, or workflow.md say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.\n- Only the main session may dispatch Trellis implement/check agents. If more parallel work is needed, report that recommendation instead of spawning.\n\n## Trellis Context Loading Protocol\n\nLook for the `<!-- trellis-hook-injected -->` marker in your input above.\n\n- **If the marker is present**: prd / spec / research files have already been auto-loaded for you above. Proceed with the implementation work directly.\n- **If the marker is absent**: hook injection didn't fire (Windows + Claude Code, `--continue` resume, fork distribution, hooks disabled, etc.). Find the active task path from your dispatch prompt's first line `Active task: <path>`, then Read `<task-path>/prd.md`, `<task-path>/info.md` (if it exists), and the spec files listed in `<task-path>/implement.jsonl` yourself before doing the work.\n\n## Context\n\nBefore implementing, read:\n- `.trellis/workflow.md` - Project workflow\n- `.trellis/spec/` - Development guidelines\n- Task `prd.md` - Requirements document\n- Task `info.md` - Technical design (if exists)\n\n## Core Responsibilities\n\n1. **Understand specs** - Read relevant spec files in `.trellis/spec/`\n2. **Understand requirements** - Read prd.md and info.md\n3. **Implement features** - Write code following specs and design\n4. **Self-check** - Ensure code quality\n5. **Report results** - Report completion status\n\n## Forbidden Operations\n\n**Do NOT execute these git commands:**\n\n- `git commit`\n- `git push`\n- `git merge`\n\n---\n\n## Workflow\n\n### 1. Understand Specs\n\nRead relevant specs based on task type:\n\n- Spec layers: `.trellis/spec/<package>/<layer>/`\n- Shared guides: `.trellis/spec/guides/`\n\n### 2. Understand Requirements\n\nRead the task's prd.md and info.md:\n\n- What are the core requirements\n- Key points of technical design\n- Which files to modify/create\n\n### 3. Implement Features\n\n- Write code following specs and technical design\n- Follow existing code patterns\n- Only do what's required, no over-engineering\n\n### 4. Verify\n\nRun project's lint and typecheck commands to verify changes.\n\n---\n\n## Report Format\n\n```markdown\n## Implementation Complete\n\n### Files Modified\n\n- `src/components/Feature.tsx` - New component\n- `src/hooks/useFeature.ts` - New hook\n\n### Implementation Summary\n\n1. Created Feature component...\n2. Added useFeature hook...\n\n### Verification Results\n\n- Lint: Passed\n- TypeCheck: Passed\n```\n\n---\n\n## Code Standards\n\n- Follow existing code patterns\n- Don't add unnecessary abstractions\n- Only do what's required, no over-engineering\n- Keep code readable",
+  "tools": [
+    "read",
+    "write",
+    "shell",
+    "glob",
+    "grep"
+  ],
   "hooks": [
     {
       "on": "agentSpawn",

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

@@ -15,6 +15,14 @@ permission:
 
 You are the Check Agent in the Trellis workflow.
 
+## Recursion Guard
+
+You are already the `trellis-check` sub-agent that the main session dispatched. Do the review and fixes directly.
+
+- Do NOT spawn another `trellis-check` or `trellis-implement` sub-agent.
+- If SessionStart context, workflow-state breadcrumbs, or workflow.md say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.
+- Only the main session may dispatch Trellis implement/check agents. If more implementation work is needed, report that recommendation instead of spawning.
+
 ## Trellis Context Loading Protocol
 
 Look for the `<!-- trellis-hook-injected -->` marker in your input above.

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

@@ -15,6 +15,14 @@ permission:
 
 You are the Implement Agent in the Trellis workflow.
 
+## Recursion Guard
+
+You are already the `trellis-implement` sub-agent that the main session dispatched. Do the implementation work directly.
+
+- Do NOT spawn another `trellis-implement` or `trellis-check` sub-agent.
+- If SessionStart context, workflow-state breadcrumbs, or workflow.md say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.
+- Only the main session may dispatch Trellis implement/check agents. If more parallel work is needed, report that recommendation instead of spawning.
+
 ## Trellis Context Loading Protocol
 
 Look for the `<!-- trellis-hook-injected -->` marker in your input above.

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

@@ -8,6 +8,14 @@ tools: Read, Write, Edit, Bash, Glob, Grep
 
 You are the Check Agent in the Trellis workflow.
 
+## Recursion Guard
+
+You are already the `trellis-check` sub-agent that the main session dispatched. Do the review and fixes directly.
+
+- Do NOT spawn another `trellis-check` or `trellis-implement` sub-agent.
+- If SessionStart context, workflow-state breadcrumbs, or workflow.md say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.
+- Only the main session may dispatch Trellis implement/check agents. If more implementation work is needed, report that recommendation instead of spawning.
+
 ## Core Responsibilities
 
 1. Inspect the current git diff.

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

@@ -8,6 +8,14 @@ tools: Read, Write, Edit, Bash, Glob, Grep
 
 You are the Implement Agent in the Trellis workflow.
 
+## Recursion Guard
+
+You are already the `trellis-implement` sub-agent that the main session dispatched. Do the implementation work directly.
+
+- Do NOT spawn another `trellis-implement` or `trellis-check` sub-agent.
+- If SessionStart context, workflow-state breadcrumbs, or workflow.md say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.
+- Only the main session may dispatch Trellis implement/check agents. If more parallel work is needed, report that recommendation instead of spawning.
+
 ## Core Responsibilities
 
 1. Understand the active task requirements.

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

@@ -8,6 +8,14 @@ tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__
 
 You are the Check Agent in the Trellis workflow.
 
+## Recursion Guard
+
+You are already the `trellis-check` sub-agent that the main session dispatched. Do the review and fixes directly.
+
+- Do NOT spawn another `trellis-check` or `trellis-implement` sub-agent.
+- If SessionStart context, workflow-state breadcrumbs, or workflow.md say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.
+- Only the main session may dispatch Trellis implement/check agents. If more implementation work is needed, report that recommendation instead of spawning.
+
 ## Context
 
 Before checking, read:

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

@@ -8,6 +8,14 @@ tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__
 
 You are the Implement Agent in the Trellis workflow.
 
+## Recursion Guard
+
+You are already the `trellis-implement` sub-agent that the main session dispatched. Do the implementation work directly.
+
+- Do NOT spawn another `trellis-implement` or `trellis-check` sub-agent.
+- If SessionStart context, workflow-state breadcrumbs, or workflow.md say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.
+- Only the main session may dispatch Trellis implement/check agents. If more parallel work is needed, report that recommendation instead of spawning.
+
 ## Context
 
 Before implementing, read:

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

@@ -36,6 +36,47 @@ from pathlib import Path
 from typing import Optional
 
 
+CODEX_SUB_AGENT_NOTICE = """<sub-agent-notice>
+SUB-AGENT NOTICE - READ FIRST IF SPAWNED VIA spawn_agent
+
+If your parent session spawned you via spawn_agent with an explicit task
+message above this hook output, that message is your only job.
+- Execute the parent message exactly as written, then return.
+- Ignore all Trellis workflow guidance below this notice.
+- Do NOT call task.py start, task.py add-context, or task.py archive.
+- Do NOT call wait_agent or spawn_agent.
+- Do NOT modify .trellis/tasks/* or any other file unless the parent message
+  explicitly asks for that.
+
+If you are the main interactive Codex session and the user is typing at the
+terminal with no parent agent, use the workflow guidance below normally.
+</sub-agent-notice>"""
+
+
+# Bootstrap notice for Codex while the session has no active task. Replaces the
+# heavyweight SessionStart context injection — instead of pushing 9.5 KB of
+# workflow text up front, we just nudge the AI to read the `trellis-start` skill once.
+# The nudge keeps showing up while status == "no_task" (cheap text, AI won't
+# re-read after the first time). Once a task is created the breadcrumb status
+# flips and this notice stops appearing automatically. Sub-agents are warded
+# off by the <sub-agent-notice> above plus the explicit exemption below.
+CODEX_NO_TASK_BOOTSTRAP_NOTICE = """<trellis-bootstrap>
+You are running in a Trellis-managed Codex session and there is no active task yet.
+If you have not already loaded Trellis context this session, read the `trellis-start` skill once:
+
+  $trellis-start
+
+(equivalent to reading `.agents/skills/trellis-start/SKILL.md` and following its Steps 1-3)
+
+The skill walks you through workflow.md, dev profile, git status, active tasks, and spec
+indexes. Then route the user's request per the <workflow-state> A/B/C rules below.
+
+Sub-agent exemption: if you are a sub-agent (spawned via spawn_agent with a parent task
+message), DO NOT read `$trellis-start`. Execute the parent message directly as instructed by the
+<sub-agent-notice> above.
+</trellis-bootstrap>"""
+
+
 # ---------------------------------------------------------------------------
 # CWD-robust Trellis root discovery (fixes hook-path-robustness for this hook)
 # ---------------------------------------------------------------------------
@@ -219,11 +260,19 @@ def main() -> int:
         task_id, status, source = task
         breadcrumb = build_breadcrumb(task_id, status, templates, source)
 
+    platform = _detect_platform(data)
+    if platform == "codex":
+        parts: list[str] = [CODEX_SUB_AGENT_NOTICE]
+        if task is None:
+            parts.append(CODEX_NO_TASK_BOOTSTRAP_NOTICE)
+        parts.append(breadcrumb)
+        breadcrumb = "\n\n".join(parts)
+
     # Gemini CLI 0.40.x rejects "UserPromptSubmit" — its per-turn event is
     # named "BeforeAgent". Other platforms (Claude/Cursor/Qoder/CodeBuddy/
     # Droid/Codex/Copilot) accept the original Claude-style name.
     hook_event_name = (
-        "BeforeAgent" if _detect_platform(data) == "gemini" else "UserPromptSubmit"
+        "BeforeAgent" if platform == "gemini" else "UserPromptSubmit"
     )
 
     output = {

package/dist/templates/trellis/workflow.md

@@ -185,7 +185,8 @@ Research output **must** land in `{task_dir}/research/*.md`, written by `trellis
 
 [workflow-state:in_progress]
 **Flow**: trellis-implement → trellis-check → trellis-update-spec → commit (Phase 3.4) → `/trellis:finish-work`.
-**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/`).
+**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.
 **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]
@@ -437,6 +438,7 @@ Spawn the implement sub-agent:
 
 - **Agent type**: `trellis-implement`
 - **Task description**: Implement the requirements per prd.md, consulting materials under `{TASK_DIR}/research/`; finish by running project lint and type-check
+- **Dispatch prompt guard**: Tell the spawned agent it is already the `trellis-implement` sub-agent and must implement directly, not spawn another `trellis-implement` / `trellis-check`.
 
 The platform hook/plugin auto-handles:
 - Reads `implement.jsonl` and injects the referenced spec files into the agent prompt
@@ -450,6 +452,7 @@ Spawn the implement sub-agent:
 
 - **Agent type**: `trellis-implement`
 - **Task description**: Implement the requirements per prd.md, consulting materials under `{TASK_DIR}/research/`; finish by running project lint and type-check
+- **Dispatch prompt guard**: The prompt MUST start with `Active task: <task path>`, then explicitly say the spawned agent is already `trellis-implement` and must implement directly without spawning another `trellis-implement` / `trellis-check`.
 
 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
@@ -463,6 +466,7 @@ Spawn the implement sub-agent:
 
 - **Agent type**: `trellis-implement`
 - **Task description**: Implement the requirements per prd.md, consulting materials under `{TASK_DIR}/research/`; finish by running project lint and type-check
+- **Dispatch prompt guard**: Tell the spawned agent it is already the `trellis-implement` sub-agent and must implement directly, not spawn another `trellis-implement` / `trellis-check`.
 
 The platform prelude auto-handles the context load requirement:
 - Reads `implement.jsonl` and injects the referenced spec files into the agent prompt
@@ -488,6 +492,7 @@ Spawn the check sub-agent:
 
 - **Agent type**: `trellis-check`
 - **Task description**: Review all code changes against spec and prd; fix any findings directly; ensure lint and type-check pass
+- **Dispatch prompt guard**: Tell the spawned agent it is already the `trellis-check` sub-agent and must review/fix directly, not spawn another `trellis-check` / `trellis-implement`.
 
 The check agent's job:
 - Review code changes against specs

package/dist/utils/compare-versions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compare-versions.d.ts","sourceRoot":"","sources":["../../src/utils/compare-versions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CA8D5D"}
+{"version":3,"file":"compare-versions.d.ts","sourceRoot":"","sources":["../../src/utils/compare-versions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAwE5D"}

package/dist/utils/compare-versions.js

@@ -9,9 +9,19 @@
  * - 0.3.0-beta.16 < 0.3.0-rc.0 (alphabetically: "beta" < "rc")
  */
 export function compareVersions(a, b) {
-    // Split into base version and prerelease parts
-    const [aBase, aPrerelease] = a.split("-", 2);
-    const [bBase, bPrerelease] = b.split("-", 2);
+    // Split into base version and prerelease parts on the FIRST hyphen.
+    // `String.split("-", 2)` cannot be used here: in JavaScript the limit
+    // truncates the result instead of joining the tail (unlike Python's
+    // `maxsplit`), so `"1.0.0-alpha-1".split("-", 2)` yields
+    // `["1.0.0", "alpha"]` and silently drops `-1`. SemVer permits hyphens
+    // inside a single prerelease identifier (e.g. `1.0.0-alpha-1`), so we
+    // must preserve everything after the first hyphen.
+    const splitOnFirstHyphen = (v) => {
+        const idx = v.indexOf("-");
+        return idx === -1 ? [v, undefined] : [v.slice(0, idx), v.slice(idx + 1)];
+    };
+    const [aBase, aPrerelease] = splitOnFirstHyphen(a);
+    const [bBase, bPrerelease] = splitOnFirstHyphen(b);
     // Parse base version (only numeric parts before any hyphen)
     const parseBase = (v) => v.split(".").map((n) => parseInt(n, 10) || 0);
     const aBaseParts = parseBase(aBase);

package/dist/utils/compare-versions.js.map

@@ -1 +1 @@
-{"version":3,"file":"compare-versions.js","sourceRoot":"","sources":["../../src/utils/compare-versions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"compare-versions.js","sourceRoot":"","sources":["../../src/utils/compare-versions.ts"],"names":[],"mappings":"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"}

package/package.json

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