@mindfoldhq/trellis 0.5.1 → 0.5.3

package/dist/migrations/manifests/0.5.2.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.5.2",
+  "description": "Hotfix Python <=3.11 SyntaxError in SessionStart hook (f-string backslash).",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Bug Fixes:**\n- fix(hooks): SessionStart hook crashes at parse time on Python <=3.11. The Windows path normalizer added in 0.5.0-rc.6 used `f\"{drive}:\\\\{rest.replace('/', '\\\\')}\"`; PEP 498 forbids backslashes inside f-string expression parts, so Python <=3.11 raises `SyntaxError: f-string expression part cannot include a backslash` and the hook exits with code 1 before doing anything. PEP 701 in Python 3.12 lifted the restriction, hiding the bug from 3.12+ users. Codex CLI 0.128 + Trellis 0.5.0 reproduced it in the field. Fixed by lifting the `.replace(...)` out of each f-string expression into a local variable. 9 occurrences across `codex/hooks/session-start.py`, `copilot/hooks/session-start.py`, and `shared-hooks/session-start.py` (Claude Code / Cursor / Gemini CLI / Qoder / CodeBuddy / Factory Droid / Kiro).",
+  "migrations": [],
+  "notes": "Hotfix on top of 0.5.1. Run `trellis update` (no `--migrate` needed). Affects every Python <=3.11 user on a hook-capable platform; Python 3.12+ users were unaffected."
+}

package/dist/migrations/manifests/0.5.3.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.5.3",
+  "description": "Hotfix: fallback for class-1 sub-agent context injection + non-blocking task.py start.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Bug Fixes:**\n- fix(hooks): class-1 platforms (claude / cursor / opencode / kiro / codebuddy / droid) inject sub-agent context (prd.md + implement.jsonl / check.jsonl) via PreToolUse hook. The hook silent-skips on Windows at v2.1.119 (upstream `anthropics/claude-code#53254`); the existing sub-agent definition files trusted the hook to always fire and had no fallback. Added marker-based dual-channel context loading: `inject-subagent-context.py` prepends a `<!-- trellis-hook-injected -->` sentinel to the build_implement_prompt / build_check_prompt / build_finish_prompt outputs (only emitted on the success path). Each class-1 trellis-implement / trellis-check definition now opens with a `Trellis Context Loading Protocol` section that branches on the marker: present → hook injected, proceed; absent → read `Active task` line from dispatch prompt + Read prd.md + the relevant jsonl yourself. workflow.md dispatch protocol scope changed from class-2-only to all platforms (except trellis-research).\n- fix(task): `task.py start` previously hard-failed with `return 1` when no `TRELLIS_CONTEXT_ID` was injected, blocking the AI from continuing. Replaced with a yellow-tagged degraded-mode warning, still flips `task.json.status: planning → in_progress`, returns 0. Happy path (`resolve_context_key()` truthy) is byte-identical. Affects every Windows + Claude Code user where the SessionStart hook can't reach the spawned shell.\n\nClass-2 platforms (codex / copilot / gemini / qoder) untouched — they already use `buildPullBasedPrelude`. trellis-research intentionally not marker'd — research is decoupled from task.",
+  "migrations": [],
+  "notes": "Hotfix on top of 0.5.2. Run `trellis update` (no `--migrate` needed). Affects every class-1 platform user whose SessionStart / PreToolUse hook injection ever fails (Windows + Claude Code, --continue / resume paths, fork distributions, hooks disabled)."
+}

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

@@ -8,6 +8,13 @@ tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__
 
 You are the Check Agent in the Trellis workflow.
 
+## Trellis Context Loading Protocol
+
+Look for the `<!-- trellis-hook-injected -->` marker in your input above.
+
+- **If the marker is present**: prd / spec / research files have already been auto-loaded for you above. Proceed with the check work directly.
+- **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.
+
 ## Context
 
 Before checking, read:

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

@@ -8,6 +8,13 @@ tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__
 
 You are the Implement Agent in the Trellis workflow.
 
+## Trellis Context Loading Protocol
+
+Look for the `<!-- trellis-hook-injected -->` marker in your input above.
+
+- **If the marker is present**: prd / spec / research files have already been auto-loaded for you above. Proceed with the implementation work directly.
+- **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.
+
 ## Context
 
 Before implementing, read:

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

@@ -8,6 +8,13 @@ tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__
 
 You are the Check Agent in the Trellis workflow.
 
+## Trellis Context Loading Protocol
+
+Look for the `<!-- trellis-hook-injected -->` marker in your input above.
+
+- **If the marker is present**: prd / spec / research files have already been auto-loaded for you above. Proceed with the check work directly.
+- **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.
+
 ## Context
 
 Before checking, read:

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

@@ -8,6 +8,13 @@ tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__
 
 You are the Implement Agent in the Trellis workflow.
 
+## Trellis Context Loading Protocol
+
+Look for the `<!-- trellis-hook-injected -->` marker in your input above.
+
+- **If the marker is present**: prd / spec / research files have already been auto-loaded for you above. Proceed with the implementation work directly.
+- **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.
+
 ## Context
 
 Before implementing, read:

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

@@ -47,19 +47,22 @@ def _normalize_windows_shell_path(path_str: str) -> str:
     m = re.match(r"^/([A-Za-z])/(.*)", p)
     if m:
         drive, rest = m.group(1).upper(), m.group(2)
-        return f"{drive}:\\{rest.replace('/', '\\')}"
+        rest = rest.replace('/', '\\')
+        return f"{drive}:\\{rest}"
 
     # Cygwin style: /cygdrive/c/Users/...
     m = re.match(r"^/cygdrive/([A-Za-z])/(.*)", p)
     if m:
         drive, rest = m.group(1).upper(), m.group(2)
-        return f"{drive}:\\{rest.replace('/', '\\')}"
+        rest = rest.replace('/', '\\')
+        return f"{drive}:\\{rest}"
 
     # WSL mounted drive (sometimes leaked into env): /mnt/c/Users/...
     m = re.match(r"^/mnt/([A-Za-z])/(.*)", p)
     if m:
         drive, rest = m.group(1).upper(), m.group(2)
-        return f"{drive}:\\{rest.replace('/', '\\')}"
+        rest = rest.replace('/', '\\')
+        return f"{drive}:\\{rest}"
 
     return path_str
 

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

@@ -50,19 +50,22 @@ def _normalize_windows_shell_path(path_str: str) -> str:
     m = re.match(r"^/([A-Za-z])/(.*)", p)
     if m:
         drive, rest = m.group(1).upper(), m.group(2)
-        return f"{drive}:\\{rest.replace('/', '\\')}"
+        rest = rest.replace('/', '\\')
+        return f"{drive}:\\{rest}"
 
     # Cygwin style: /cygdrive/c/Users/...
     m = re.match(r"^/cygdrive/([A-Za-z])/(.*)", p)
     if m:
         drive, rest = m.group(1).upper(), m.group(2)
-        return f"{drive}:\\{rest.replace('/', '\\')}"
+        rest = rest.replace('/', '\\')
+        return f"{drive}:\\{rest}"
 
     # WSL mounted drive (sometimes leaked into env): /mnt/c/Users/...
     m = re.match(r"^/mnt/([A-Za-z])/(.*)", p)
     if m:
         drive, rest = m.group(1).upper(), m.group(2)
-        return f"{drive}:\\{rest.replace('/', '\\')}"
+        rest = rest.replace('/', '\\')
+        return f"{drive}:\\{rest}"
 
     return path_str
 

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

@@ -7,6 +7,13 @@ tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__
 
 You are the Check Agent in the Trellis workflow.
 
+## Trellis Context Loading Protocol
+
+Look for the `<!-- trellis-hook-injected -->` marker in your input above.
+
+- **If the marker is present**: prd / spec / research files have already been auto-loaded for you above. Proceed with the check work directly.
+- **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.
+
 ## Context
 
 Before checking, read:

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

@@ -7,6 +7,13 @@ tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__
 
 You are the Implement Agent in the Trellis workflow.
 
+## Trellis Context Loading Protocol
+
+Look for the `<!-- trellis-hook-injected -->` marker in your input above.
+
+- **If the marker is present**: prd / spec / research files have already been auto-loaded for you above. Proceed with the implementation work directly.
+- **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.
+
 ## Context
 
 Before implementing, read:

package/dist/templates/droid/droids/trellis-check.md

@@ -8,6 +8,13 @@ tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__
 
 You are the Check Agent in the Trellis workflow.
 
+## Trellis Context Loading Protocol
+
+Look for the `<!-- trellis-hook-injected -->` marker in your input above.
+
+- **If the marker is present**: prd / spec / research files have already been auto-loaded for you above. Proceed with the check work directly.
+- **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.
+
 ## Context
 
 Before checking, read:

package/dist/templates/droid/droids/trellis-implement.md

@@ -8,6 +8,13 @@ tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__
 
 You are the Implement Agent in the Trellis workflow.
 
+## Trellis Context Loading Protocol
+
+Look for the `<!-- trellis-hook-injected -->` marker in your input above.
+
+- **If the marker is present**: prd / spec / research files have already been auto-loaded for you above. Proceed with the implementation work directly.
+- **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.
+
 ## Context
 
 Before implementing, read:

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

@@ -1,7 +1,7 @@
 {
   "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## 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```",
+  "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"],
   "hooks": [
     {

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

@@ -1,7 +1,7 @@
 {
   "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## 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",
+  "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"],
   "hooks": [
     {

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

@@ -15,23 +15,12 @@ permission:
 
 You are the Check Agent in the Trellis workflow.
 
-## Context Self-Loading
+## Trellis Context Loading Protocol
 
-**If you see "# Check Agent Task" header with pre-loaded context above, skip this section.**
+Look for the `<!-- trellis-hook-injected -->` marker in your input above.
 
-Otherwise, load context yourself:
-
-1. Run `python3 ./.trellis/scripts/task.py current --source` → get active task directory and source (e.g., `Current task: .trellis/tasks/xxx`)
-2. Read `{task_dir}/check.jsonl`
-3. For each entry in JSONL:
-   - If `path` is a file → Read it
-   - If `path` is a directory → Read all `.md` files in it
-4. Read `{task_dir}/prd.md` for requirements understanding
-5. Read `.opencode/commands/trellis/finish-work.md` for checklist
-
-Then proceed with the workflow below using the loaded context.
-
----
+- **If the marker is present**: prd / spec / research files have already been auto-loaded for you above. Proceed with the check work directly.
+- **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>` (or run `python3 ./.trellis/scripts/task.py current --source` as a fallback), then Read `<task-path>/prd.md` and the spec files listed in `<task-path>/check.jsonl` yourself before doing the work.
 
 ## Context
 

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

@@ -15,26 +15,12 @@ permission:
 
 You are the Implement Agent in the Trellis workflow.
 
-## Context Self-Loading
+## Trellis Context Loading Protocol
 
-**If you see "# Implement Agent Task" header with pre-loaded context above, skip this section.**
+Look for the `<!-- trellis-hook-injected -->` marker in your input above.
 
-Otherwise, load context yourself:
-
-1. Run `python3 ./.trellis/scripts/task.py current --source` → get active task directory and source (e.g., `Current task: .trellis/tasks/xxx`)
-2. Read `{task_dir}/implement.jsonl`
-3. For each entry in JSONL (JSON object per line):
-   - Skip rows without a `"file"` field (e.g. `{"_example": "..."}` seed rows)
-   - If `file` points at a file → Read it
-   - If `file` ends with `/` (directory) → Read all `.md` files in it
-4. Read `{task_dir}/prd.md` for requirements
-5. Read `{task_dir}/info.md` for technical design (if exists)
-
-**If `implement.jsonl` has no curated entries (only a seed row, or the file is missing)**: read `prd.md` to understand the task domain, then decide which specs apply based on `.trellis/spec/` layout. You can list available specs with `python3 ./.trellis/scripts/get_context.py --mode packages`. Do not block on the missing jsonl — proceed with prd-only context plus your own spec judgment.
-
-Then proceed with the workflow below using the loaded context.
-
----
+- **If the marker is present**: prd / spec / research files have already been auto-loaded for you above. Proceed with the implementation work directly.
+- **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>` (or run `python3 ./.trellis/scripts/task.py current --source` as a fallback), 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.
 
 ## Context
 

package/dist/templates/shared-hooks/inject-subagent-context.py

@@ -329,7 +329,8 @@ def get_finish_context(repo_root: str, task_dir: str) -> str:
 
 def build_implement_prompt(original_prompt: str, context: str) -> str:
     """Build complete prompt for Implement"""
-    return f"""# Implement Agent Task
+    return f"""<!-- trellis-hook-injected -->
+# Implement Agent Task
 
 You are the Implement Agent in the Multi-Agent Pipeline.
 
@@ -363,7 +364,8 @@ All the information you need has been prepared for you:
 
 def build_check_prompt(original_prompt: str, context: str) -> str:
     """Build complete prompt for Check"""
-    return f"""# Check Agent Task
+    return f"""<!-- trellis-hook-injected -->
+# Check Agent Task
 
 You are the Check Agent in the Multi-Agent Pipeline (code and cross-layer checker).
 
@@ -397,7 +399,8 @@ All check specs and dev specs you need:
 
 def build_finish_prompt(original_prompt: str, context: str) -> str:
     """Build complete prompt for Finish (final check before PR)"""
-    return f"""# Finish Agent Task
+    return f"""<!-- trellis-hook-injected -->
+# Finish Agent Task
 
 You are performing the final check before creating a PR.
 

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

@@ -47,19 +47,22 @@ def _normalize_windows_shell_path(path_str: str) -> str:
     m = re.match(r"^/([A-Za-z])/(.*)", p)
     if m:
         drive, rest = m.group(1).upper(), m.group(2)
-        return f"{drive}:\\{rest.replace('/', '\\')}"
+        rest = rest.replace('/', '\\')
+        return f"{drive}:\\{rest}"
 
     # Cygwin style: /cygdrive/c/Users/...
     m = re.match(r"^/cygdrive/([A-Za-z])/(.*)", p)
     if m:
         drive, rest = m.group(1).upper(), m.group(2)
-        return f"{drive}:\\{rest.replace('/', '\\')}"
+        rest = rest.replace('/', '\\')
+        return f"{drive}:\\{rest}"
 
     # WSL mounted drive (sometimes leaked into env): /mnt/c/Users/...
     m = re.match(r"^/mnt/([A-Za-z])/(.*)", p)
     if m:
         drive, rest = m.group(1).upper(), m.group(2)
-        return f"{drive}:\\{rest.replace('/', '\\')}"
+        rest = rest.replace('/', '\\')
+        return f"{drive}:\\{rest}"
 
     return path_str
 

package/dist/templates/trellis/scripts/task.py

@@ -90,20 +90,39 @@ def cmd_start(args: argparse.Namespace) -> int:
     except ValueError:
         task_dir = str(full_path)
 
+    task_json_path = full_path / FILE_TASK_JSON
+
     if not resolve_context_key():
-        print(colored("Error: Cannot set active task without a session identity.", Colors.RED))
-        print(
+        # Degraded mode: no session identity available.
+        # Hook didn't inject TRELLIS_CONTEXT_ID (common on Windows + Claude Code,
+        # --continue resume path, fork distribution, hooks disabled, etc.). Skip
+        # per-session pointer write; AI continues based on conversation context.
+        print(colored(
+            "ℹ Session identity not available; active-task pointer not persisted "
+            "this session (degraded mode). AI continues based on conversation context.",
+            Colors.YELLOW,
+        ))
+        print(colored(
             "Hint: run inside an AI IDE/session that exposes session identity, "
-            "or set TRELLIS_CONTEXT_ID before running task.py start."
-        )
-        return 1
+            "or set TRELLIS_CONTEXT_ID before running task.py start.",
+            Colors.YELLOW,
+        ))
+
+        # Still flip task.json status: planning → in_progress so downstream phases proceed.
+        if task_json_path.is_file():
+            data = read_json(task_json_path)
+            if data and data.get("status") == "planning":
+                data["status"] = "in_progress"
+                if write_json(task_json_path, data):
+                    print(colored("✓ Status: planning → in_progress (degraded)", Colors.GREEN))
+            run_task_hooks("after_start", task_json_path, repo_root)
+        return 0
 
     active = set_active_task(task_dir, repo_root)
     if active:
         print(colored(f"✓ Current task set to: {task_dir}", Colors.GREEN))
         print(f"Source: {active.source}")
 
-        task_json_path = full_path / FILE_TASK_JSON
         if task_json_path.is_file():
             data = read_json(task_json_path)
             if data and data.get("status") == "planning":

package/dist/templates/trellis/workflow.md

@@ -186,7 +186,7 @@ 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/`).
-**Sub-agent dispatch protocol (class-2 platforms: codex / copilot / gemini / qoder)**: When you spawn `trellis-implement` / `trellis-check` / `trellis-research`, your dispatch prompt **MUST** start with one line: `Active task: <task path from \`task.py current\`>`. No exceptions. These platforms have no hook to inject task context into sub-agents, so the sub-agent depends on this line; without it the sub-agent cannot find the task and will block to ask the user.
+**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]
 

package/package.json

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