@mindfoldhq/trellis 0.5.3 → 0.5.4

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/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/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/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.4",
   "description": "AI capabilities grow like ivy — Trellis provides the structure to guide them along a disciplined path",
   "type": "module",
   "main": "./dist/index.js",