@mindfoldhq/trellis 0.5.12 → 0.5.14

package/README.md

@@ -7,8 +7,8 @@
 </p>
 
 <p align="center">
-<strong>Make AI coding reliable at team scale.</strong><br/>
-<sub>A team AI coding harness for progressive specs, custom workflows, task context, and memory across Claude Code, Cursor, Codex, OpenCode, Pi Agent, and more.</sub>
+<strong>The harness that makes coding agents production-ready</strong><br/>
+<sub>Start a feature in Gemini, continue in Claude Code, ship it with Codex — or hand it off to a teammate at any step. Context, specs, and standards are shared across every agent and every teammate, so anyone's best spec lifts the whole team.</sub>
 </p>
 
 <p align="center">
@@ -26,7 +26,6 @@
 <a href="https://github.com/mindfold-ai/Trellis/stargazers"><img src="https://img.shields.io/github/stars/mindfold-ai/Trellis?style=flat-square&color=eab308" alt="stars" /></a>
 <a href="https://docs.trytrellis.app/"><img src="https://img.shields.io/badge/docs-trytrellis.app-0f766e?style=flat-square" alt="docs" /></a>
 <a href="https://discord.com/invite/tWcCZ3aRHc"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Discord" /></a>
-<a href="https://linux.do"><img src="https://img.shields.io/badge/LINUX-DO-FFB003.svg?logo=data:image/svg%2bxml;base64,DQo8c3ZnIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgd2lkdGg9IjEwMCIgaGVpZ2h0PSIxMDAiPjxwYXRoIGQ9Ik00Ni44Mi0uMDU1aDYuMjVxMjMuOTY5IDIuMDYyIDM4IDIxLjQyNmM1LjI1OCA3LjY3NiA4LjIxNSAxNi4xNTYgOC44NzUgMjUuNDV2Ni4yNXEtMi4wNjQgMjMuOTY4LTIxLjQzIDM4LTExLjUxMiA3Ljg4NS0yNS40NDUgOC44NzRoLTYuMjVxLTIzLjk3LTIuMDY0LTM4LjAwNC0yMS40M1EuOTcxIDY3LjA1Ni0uMDU0IDUzLjE4di02LjQ3M0MxLjM2MiAzMC43ODEgOC41MDMgMTguMTQ4IDIxLjM3IDguODE3IDI5LjA0NyAzLjU2MiAzNy41MjcuNjA0IDQ2LjgyMS0uMDU2IiBzdHlsZT0ic3Ryb2tlOm5vbmU7ZmlsbC1ydWxlOmV2ZW5vZGQ7ZmlsbDojZWNlY2VjO2ZpbGwtb3BhY2l0eToxIi8+PHBhdGggZD0iTTQ3LjI2NiAyLjk1N3EyMi41My0uNjUgMzcuNzc3IDE1LjczOGE0OS43IDQ5LjcgMCAwIDEgNi44NjcgMTAuMTU3cS00MS45NjQuMjIyLTgzLjkzIDAgOS43NS0xOC42MTYgMzAuMDI0LTI0LjM4N2E2MSA2MSAwIDAgMSA5LjI2Mi0xLjUwOCIgc3R5bGU9InN0cm9rZTpub25lO2ZpbGwtcnVsZTpldmVub2RkO2ZpbGw6IzE5MTkxOTtmaWxsLW9wYWNpdHk6MSIvPjxwYXRoIGQ9Ik03Ljk4IDcwLjkyNmMyNy45NzctLjAzNSA1NS45NTQgMCA4My45My4xMTNRODMuNDI2IDg3LjQ3MyA2Ni4xMyA5NC4wODZxLTE4LjgxIDYuNTQ0LTM2LjgzMi0xLjg5OC0xNC4yMDMtNy4wOS0yMS4zMTctMjEuMjYyIiBzdHlsZT0ic3Ryb2tlOm5vbmU7ZmlsbC1ydWxlOmV2ZW5vZGQ7ZmlsbDojZjlhZjAwO2ZpbGwtb3BhY2l0eToxIi8+PC9zdmc+&style=flat-square" alt="LINUX DO" /></a>
 <a href="https://github.com/mindfold-ai/Trellis/issues"><img src="https://img.shields.io/github/issues/mindfold-ai/Trellis?style=flat-square&color=e67e22" alt="open issues" /></a>
 <a href="https://github.com/mindfold-ai/Trellis/pulls"><img src="https://img.shields.io/github/issues-pr/mindfold-ai/Trellis?style=flat-square&color=9b59b6" alt="open PRs" /></a>
 <a href="https://deepwiki.com/mindfold-ai/Trellis"><img src="https://img.shields.io/badge/Ask-DeepWiki-blue?style=flat-square" alt="Ask DeepWiki" /></a>
@@ -37,68 +36,55 @@
 <img src="assets/trellis-demo.gif" alt="Trellis workflow demo" width="100%">
 </p>
 
-## What is Trellis?
+## Why Trellis?
 
-Trellis is a built-in AI coding harness for teams. It turns the huge system prompt you would normally put in `CLAUDE.md`, `AGENTS.md`, or `.cursorrules` into a progressive wiki of specs, tasks, workflows, and journals that agents load only when needed.
+| Capability | What it changes |
+| --- | --- |
+| **Auto-injected specs** | Write conventions once in `.trellis/spec/`, then let Trellis inject the relevant context into each session instead of repeating yourself. |
+| **Task-centered workflow** | Keep PRDs, implementation context, review context, and task status in `.trellis/tasks/` so AI work stays structured. |
+| **Project memory** | Journals in `.trellis/workspace/` preserve what happened last time, so each new session starts with real context. |
+| **Team-shared standards** | Specs live in the repo, so one person's hard-won workflow or rule can benefit the whole team. |
+| **Multi-platform setup** | Bring the same Trellis structure to 14 AI coding platforms instead of rebuilding your workflow per tool. |
 
-It gives Claude Code, Cursor, Codex, OpenCode, Pi Agent, and other agents the same project source of truth: team standards, task decisions, runbooks, and session memory, without stuffing the whole codebase into every prompt. Trellis is used by individual builders, open-source maintainers, teams inside tech giants, top university labs, and public-company engineering departments working on production monorepos with hundreds of thousands of lines of code.
-
-## How it works
-
-Trellis installs a `.trellis/` directory into your repository and generates the right entry points for each AI coding platform you use.
-
-| Layer                  | Purpose                                                                                |
-| ---------------------- | -------------------------------------------------------------------------------------- |
-| `.trellis/spec/`       | Team standards and coding guidelines that agents can load automatically.               |
-| `.trellis/tasks/`      | PRDs, task context, status, review notes, and acceptance criteria.                     |
-| `.trellis/workspace/`  | Developer-level journals, decisions, and handoff notes for session continuity.         |
-| `.trellis/workflow.md` | The shared lifecycle for planning, building, checking, finishing, and learning.        |
-| Platform adapters      | Generated commands, hooks, skills, prompts, workflows, and agent files for your tools. |
-
-The core loop is short:
-
-1. Capture the task as a PRD.
-2. Inject the relevant project specs.
-3. Let the agent implement inside a clear boundary.
-4. Run checks before handoff.
-5. Promote reusable lessons back into specs.
-6. Record the session so the next agent starts with the decisions and context it needs.
-
-For the deeper product model, see the [docs](https://docs.trytrellis.app/) and [real-world scenarios](https://docs.trytrellis.app/start/real-world-scenarios).
-
-## Install
-
-Prerequisites:
+## Prerequisites:
 
 - **Node.js** >= 18
-- **Python** >= 3.9 for hooks and automation scripts
+- **Python** >= 3.9
 
-Install Trellis:
+## Quick Start
 
 ```bash
-npm install -g @mindfoldhq/trellis@beta
-```
-
-Initialize a repository:
+# 1. Install Trellis
+npm install -g @mindfoldhq/trellis@latest
 
-```bash
-# Start Trellis and create a developer workspace
+# 2. Initialize in your repo
 trellis init -u your-name
+
+# 3. Or initialize with the platforms you actually use
+trellis init --cursor --opencode --codex -u your-name
 ```
 
 See the [Quick Start](https://docs.trytrellis.app/start/install-and-first-task) and [Supported Platforms](https://docs.trytrellis.app/advanced/multi-platform) guides for setup details.
 
-## First task
+## How to Use
 
-Trellis 0.5 is skill-first. On hook-capable or extension-capable platforms, session context loads automatically. On platforms that need a manual entry point, start with:
+The workflow is simple:
 
-```text
-/start or /trellis:start  # Load project context
-```
+1. **Describe what you want** in natural language.
+2. **Brainstorm** with the AI one question at a time until the PRD is clear, then implementation begins.
+3. **Let it run** — the AI calls Trellis Implement and auto-checks the result against specs, lint, type-check, and tests.
+4. **Type `/trellis:finish-work`** when the work is done or the session context fills up. Trellis archives the task and updates journals.
 
-Then describe the task in natural language. Trellis routes the work through skills for brainstorming, spec loading, implementation checks, and knowledge capture. Use `continue` to advance the current task and `finish-work` after human testing and commit.
+## How It Works
 
-## Learn more
+Trellis runs a 4-phase loop with auto-invoked skills and sub-agents:
+
+1. **Plan** — `trellis-brainstorm` walks through requirements one question at a time and writes `prd.md`. Research-heavy items go to a `trellis-research` sub-agent. The result is curated specs + research files referenced from `implement.jsonl` / `check.jsonl`.
+2. **Implement** — a `trellis-implement` sub-agent writes code from the PRD with the curated context auto-injected, no git commit.
+3. **Verify** — a `trellis-check` sub-agent reviews the diff against specs and runs lint, type-check, and tests, self-fixing where it can.
+4. **Finish** — a final check runs, then `trellis-update-spec` promotes new learnings back into `.trellis/spec/` so the next session starts smarter.
+
+## Resources
 
 | Need                            | Link                                                                           |
 | ------------------------------- | ------------------------------------------------------------------------------ |
@@ -106,7 +92,7 @@ Then describe the task in natural language. Trellis routes the work through skil
 | Understand platform differences | [Supported Platforms](https://docs.trytrellis.app/advanced/multi-platform)     |
 | See the workflow in practice    | [Real-World Scenarios](https://docs.trytrellis.app/start/real-world-scenarios) |
 | Start from spec templates       | [Spec Templates](https://docs.trytrellis.app/templates/specs-index)            |
-| Track releases                  | [Changelog](https://docs.trytrellis.app/changelog/v0.5.0-beta.16)              |
+| Track releases                  | [Changelog](https://docs.trytrellis.app/changelog)                             |
 
 ## FAQ
 
@@ -131,6 +117,20 @@ Both. Solo developers use it for memory and repeatable workflow. Teams get the l
 
 </details>
 
+<details>
+<summary><strong>Do I have to write every spec file manually?</strong></summary>
+
+No. Many teams start by letting AI draft specs from existing code and then tighten the important parts by hand. Trellis works best when you keep the high-signal rules explicit and versioned.
+
+</details>
+
+<details>
+<summary><strong>Can teams use this without constant conflicts?</strong></summary>
+
+Yes. Personal workspace journals stay separate per developer, while shared specs and tasks stay in the repo where they can be reviewed and improved like any other project artifact.
+
+</details>
+
 ## Star History
 
 [![Star History Chart](https://api.star-history.com/svg?repos=mindfold-ai/Trellis&type=Date)](https://star-history.com/#mindfold-ai/Trellis&Date)

package/dist/migrations/manifests/0.5.13.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.5.13",
+  "description": "Patch: OpenCode context injection, non-Git session context, hook timeouts, and Copilot SessionStart wording.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Bug Fixes:**\n- fix(opencode): detect Windows POSIX shell dialects before injecting `TRELLIS_CONTEXT_ID`, so Git Bash / MSYS / Cygwin sessions receive `export ...` while PowerShell keeps `$env:...`.\n- fix(context): session context now handles non-Git Trellis roots without reporting fake clean Git state, and falls back to bounded child-repo discovery for unconfigured polyrepo layouts.\n- fix(opencode): Trellis sub-agent dispatch now skips duplicate SessionStart / workflow-state injection, resolves active tasks from session context, `Active task:` hints, or single-session fallback, and marks successfully injected prompts.\n- fix(hooks): default hook timeouts now use 30s for SessionStart and 15s for per-prompt workflow injection across hook-based platforms, avoiding Windows Python cold-start drops.\n- fix(copilot): SessionStart output no longer emits the stale `Copilot currently ignores sessionStart hook output` system message; it keeps `hookSpecificOutput.additionalContext` as the documented payload.\n\n**Internal:**\n- docs(spec): platform and cross-platform spec templates document shell-dialect-aware `TRELLIS_CONTEXT_ID` prefix rules for OpenCode.",
+  "migrations": [],
+  "notes": "Run `trellis update` to refresh hash-tracked hook, OpenCode, session-context, and spec templates. No migration required."
+}

package/dist/migrations/manifests/0.5.14.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.5.14",
+  "description": "Patch: `task.py archive` auto-commit no longer leaks dirty changes from other task dirs into the archive commit, and source-side deletes now stage correctly (no more phantom-delete fixups).",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Bug Fixes:**\n- fix(scripts): `task.py archive` auto-commit is now scoped to just the archived task's source + destination paths (plus any child task dirs whose `task.json` was edited as part of the parent→children relationship update). Dirty changes in OTHER active task dirs no longer get bundled into the archive commit.\n- fix(scripts): after `shutil.move` of a tracked task dir, the source-side deletions are now explicitly staged via `git rm -r --cached --ignore-unmatch`, so the working tree stays clean against HEAD without needing a follow-up fixup commit.\n\n**Internal:**\n- `safe_archive_paths_to_add()` accepts optional `task_name` + `modified_children` parameters; backward-compatible when called with no args (legacy wide scope preserved).\n- New integration test `test/scripts/task-archive.integration.test.ts` covers scope-creep + phantom-delete regressions against the real Python script.",
+  "migrations": [],
+  "notes": "Run `trellis update` to pull in the fixed `.trellis/scripts/common/task_store.py` + `safe_commit.py`. No migration required — script signatures changed but file paths did not."
+}

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

@@ -0,0 +1,9 @@
+{
+  "version": "0.6.0-beta.10",
+  "description": "Beta release for the trellis channel multi-agent collaboration runtime.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Enhancements:**\n- feat(channel): add `trellis channel` multi-agent collaboration runtime with `create`, `send`, `wait`, `spawn`, `run`, `list`, `messages`, `kill`, `rm`, and `prune` subcommands.\n- feat(channel): add Claude stream-json and Codex app-server adapters that translate provider output into channel `message`, `progress`, `done`, and `error` events.\n- feat(channel): store project-scoped channel logs under `~/.trellis/channels/<project>/<channel>/events.jsonl` with locked sequence assignment and lazy legacy-channel relocation.\n\n**Internal:**\n- refactor(channel): isolate adapter parsing, event storage, supervisor shutdown, inbox polling, and stdout pumping under `packages/cli/src/commands/channel/`.",
+  "migrations": [],
+  "notes": "Beta release on top of 0.6.0-beta.9. Run `trellis update` after installing `@mindfoldhq/trellis@beta`. No project-file migration required."
+}

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

@@ -0,0 +1,9 @@
+{
+  "version": "0.6.0-beta.7",
+  "description": "Beta patch: brings the v0.5.12 workflow update fix into the 0.6 beta line.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Bug Fixes:**\n- fix(update): update `.trellis/workflow.md` as a whole hash-tracked template so runtime phase routing markers, including Codex `codex-inline` / `codex-sub-agent` blocks, refresh during `trellis update`.",
+  "migrations": [],
+  "notes": "Beta patch on top of 0.6.0-beta.6. Run `trellis update` to refresh hash-tracked workflow templates. No migration required."
+}

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

@@ -0,0 +1,9 @@
+{
+  "version": "0.6.0-beta.8",
+  "description": "Beta patch: adds task-creation consent gates and planning artifacts across workflow, hooks, skills, and platform templates.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Enhancements:**\n- feat(workflow): no-task turns now classify simple conversation, inline small work, and full Trellis tasks before task creation; complex work asks before creating a task and entering planning.\n- feat(task): `task.py create` now creates a default `prd.md`, while complex tasks require `design.md` and `implement.md` before `task.py start`.\n- feat(context): implement/check context loading now uses the same artifact order across hook-push, pull-prelude, Pi, OpenCode, and inline modes: jsonl entries -> `prd.md` -> optional `design.md` -> optional `implement.md`.\n- feat(codex): Codex no-task breadcrumbs include `<trellis-bootstrap>` plus explicit `<codex-mode>` text, and inline mode keeps implementation/check work in the main session.",
+  "migrations": [],
+  "notes": "Beta patch on top of 0.6.0-beta.7. Run `trellis update` to refresh workflow, hook, skill, agent, and platform templates. No migration required."
+}

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

@@ -0,0 +1,9 @@
+{
+  "version": "0.6.0-beta.9",
+  "description": "Beta patch for trellis upgrade, OpenCode and Copilot context fixes, hook timeout defaults, and manifest continuity.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Enhancements:**\n- feat(upgrade): add `trellis upgrade` with channel-aware defaults (`latest`, `beta`, `rc`), `--tag`, and `--dry-run`; update CLI/session hints to point at the command.\n- docs(brainstorm): simplify bundled brainstorm skill/prompt templates after beta.8 planning artifact routing.\n\n**Bug Fixes:**\n- fix(upgrade): harden upgrade execution with tag validation, no shell on POSIX, Windows `cmd.exe` invocation, and troubleshooting output for npm/PATH failures.\n- fix(opencode): inject `TRELLIS_CONTEXT_ID` using the shell dialect that parses the command and recognize `env ... TRELLIS_CONTEXT_ID=...` prefixes.\n- fix(context): handle non-Git Trellis roots without fake clean Git status and discover child Git repos for unconfigured polyrepos.\n- fix(opencode): isolate Trellis sub-agent context, resolve active tasks from session context / `Active task:` hints / single-session fallback, and preserve beta.8 task artifact order.\n- fix(hooks): raise hook timeout defaults to 30s for SessionStart and 15s for per-prompt workflow injection across hook-based platforms.\n- fix(copilot): remove stale SessionStart `systemMessage` while keeping `hookSpecificOutput.additionalContext`.\n\n**Internal:**\n- chore(manifests): restore `0.5.13.json` on the beta line for stable-to-beta manifest continuity.",
+  "migrations": [],
+  "notes": "Beta patch on top of 0.6.0-beta.8. Run `trellis update` to refresh workflow, hook, OpenCode, Copilot, session-context, and skill templates. No migration required."
+}

package/dist/templates/claude/settings.json

@@ -10,7 +10,7 @@
           {
             "type": "command",
             "command": "{{PYTHON_CMD}} .claude/hooks/session-start.py",
-            "timeout": 10
+            "timeout": 30
           }
         ]
       },
@@ -20,7 +20,7 @@
           {
             "type": "command",
             "command": "{{PYTHON_CMD}} .claude/hooks/session-start.py",
-            "timeout": 10
+            "timeout": 30
           }
         ]
       },
@@ -30,7 +30,7 @@
           {
             "type": "command",
             "command": "{{PYTHON_CMD}} .claude/hooks/session-start.py",
-            "timeout": 10
+            "timeout": 30
           }
         ]
       }
@@ -63,7 +63,7 @@
           {
             "type": "command",
             "command": "{{PYTHON_CMD}} .claude/hooks/inject-workflow-state.py",
-            "timeout": 5
+            "timeout": 15
           }
         ]
       }

package/dist/templates/codebuddy/settings.json

@@ -7,7 +7,7 @@
           {
             "type": "command",
             "command": "{{PYTHON_CMD}} .codebuddy/hooks/session-start.py",
-            "timeout": 10
+            "timeout": 30
           }
         ]
       },
@@ -17,7 +17,7 @@
           {
             "type": "command",
             "command": "{{PYTHON_CMD}} .codebuddy/hooks/session-start.py",
-            "timeout": 10
+            "timeout": 30
           }
         ]
       },
@@ -27,7 +27,7 @@
           {
             "type": "command",
             "command": "{{PYTHON_CMD}} .codebuddy/hooks/session-start.py",
-            "timeout": 10
+            "timeout": 30
           }
         ]
       }
@@ -50,7 +50,7 @@
           {
             "type": "command",
             "command": "{{PYTHON_CMD}} .codebuddy/hooks/inject-workflow-state.py",
-            "timeout": 5
+            "timeout": 15
           }
         ]
       }

package/dist/templates/codex/hooks.json

@@ -6,7 +6,7 @@
           {
             "type": "command",
             "command": "{{PYTHON_CMD}} .codex/hooks/inject-workflow-state.py",
-            "timeout": 5
+            "timeout": 15
           }
         ]
       }

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

@@ -1,13 +1,18 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 """
-Copilot Session Start Hook - Emit Trellis session-start diagnostics.
-
-GitHub Copilot's documented SessionStart behavior ignores hook output, so this
-script must not be treated as proof that model-visible context was injected.
-The JSON shape is kept for parity with other Trellis hooks and future host
-support, but current Copilot users should rely on UserPromptSubmit breadcrumbs
-and hook logs instead.
+Copilot Session Start Hook - Emit Trellis session-start context.
+
+Microsoft VS Code Agent hooks are in preview and have been documented since
+VS Code 1.110 (February 2026). The official documentation
+(https://code.visualstudio.com/docs/copilot/customization/hooks) defines
+`SessionStart.hookSpecificOutput.additionalContext` as the field used to inject
+additional context into the agent's conversation.
+
+This script emits the spec-compliant SessionStart payload. Whether Copilot
+actually consumes `additionalContext` depends on the user's installed VS Code
+and Copilot versions, which is outside Trellis's control. UserPromptSubmit
+breadcrumbs remain available as a per-turn complement.
 """
 
 from __future__ import annotations
@@ -412,10 +417,6 @@ If a task is READY, execute its Next required action without asking whether to c
     context = output.getvalue()
     result = {
         "suppressOutput": True,
-        "systemMessage": (
-            f"Trellis SessionStart diagnostics emitted ({len(context)} chars); "
-            "Copilot currently ignores sessionStart hook output."
-        ),
         "hookSpecificOutput": {
             "hookEventName": "SessionStart",
             "additionalContext": context,

package/dist/templates/copilot/hooks.json

@@ -4,7 +4,7 @@
       {
         "type": "command",
         "command": "{{PYTHON_CMD}} .github/copilot/hooks/session-start.py",
-        "timeout": 10
+        "timeout": 30
       }
     ],
     "userPromptSubmitted": [
@@ -12,7 +12,7 @@
         "type": "command",
         "bash": "{{PYTHON_CMD}} .github/copilot/hooks/inject-workflow-state.py",
         "powershell": "{{PYTHON_CMD}} .github/copilot/hooks/inject-workflow-state.py",
-        "timeoutSec": 5
+        "timeoutSec": 15
       }
     ]
   }

package/dist/templates/cursor/hooks.json

@@ -11,13 +11,13 @@
     "sessionStart": [
       {
         "command": "{{PYTHON_CMD}} .cursor/hooks/session-start.py",
-        "timeout": 10
+        "timeout": 30
       }
     ],
     "beforeSubmitPrompt": [
       {
         "command": "{{PYTHON_CMD}} .cursor/hooks/inject-workflow-state.py",
-        "timeout": 5
+        "timeout": 15
       }
     ],
     "beforeShellExecution": [

package/dist/templates/droid/settings.json

@@ -7,7 +7,7 @@
           {
             "type": "command",
             "command": "{{PYTHON_CMD}} .factory/hooks/session-start.py",
-            "timeout": 10
+            "timeout": 30
           }
         ]
       },
@@ -17,7 +17,7 @@
           {
             "type": "command",
             "command": "{{PYTHON_CMD}} .factory/hooks/session-start.py",
-            "timeout": 10
+            "timeout": 30
           }
         ]
       },
@@ -27,7 +27,7 @@
           {
             "type": "command",
             "command": "{{PYTHON_CMD}} .factory/hooks/session-start.py",
-            "timeout": 10
+            "timeout": 30
           }
         ]
       }
@@ -50,7 +50,7 @@
           {
             "type": "command",
             "command": "{{PYTHON_CMD}} .factory/hooks/inject-workflow-state.py",
-            "timeout": 5
+            "timeout": 15
           }
         ]
       }

package/dist/templates/gemini/settings.json

@@ -7,7 +7,7 @@
           {
             "type": "command",
             "command": "{{PYTHON_CMD}} .gemini/hooks/session-start.py",
-            "timeout": 10000
+            "timeout": 30000
           }
         ]
       }
@@ -19,7 +19,7 @@
           {
             "type": "command",
             "command": "{{PYTHON_CMD}} .gemini/hooks/inject-workflow-state.py",
-            "timeout": 5000
+            "timeout": 15000
           }
         ]
       }

package/dist/templates/markdown/spec/guides/cross-platform-thinking-guide.md.txt

@@ -215,20 +215,26 @@ home = Path.home()
 ```
 
 **Rule 2**: When injecting environment variables into shell commands, generate
-the prefix for the actual host shell. Do not assume `export` works everywhere.
-AI tool "Bash" surfaces on Windows may execute through PowerShell.
+the prefix for the actual shell that will parse the command. Do not choose
+syntax from OS alone. AI tool "Bash" surfaces on Windows may execute through
+PowerShell, Git Bash, MSYS2, or another POSIX-like shell.
 
 ```javascript
 // BAD - breaks when the host shell is PowerShell
 command = `export TRELLIS_CONTEXT_ID=${shellQuote(contextKey)}; ${command}`;
 
-// GOOD - shell-aware command prefix
-const prefix = process.platform === "win32"
+// GOOD - shell-dialect-aware command prefix
+const prefix = process.platform === "win32" && !isWindowsPosixShell(process.env)
   ? `$env:TRELLIS_CONTEXT_ID = ${powershellQuote(contextKey)}; `
   : `export TRELLIS_CONTEXT_ID=${shellQuote(contextKey)}; `;
 command = `${prefix}${command}`;
 ```
 
+On Windows, treat `MSYSTEM`, `MINGW_PREFIX`, `OSTYPE=msys|mingw|cygwin`,
+`SHELL=...bash`, or a platform-specific Git Bash setting as POSIX-shell
+signals. Keep PowerShell as the Windows default when there is no POSIX-shell
+signal.
+
 Also make duplicate-injection detection shell-aware. A guard that only matches
 `export VAR=` will miss PowerShell's `$env:VAR = ...` form and can wrap an
 already-correct command a second time.

package/dist/templates/opencode/lib/trellis-context.js

@@ -63,6 +63,21 @@ function buildContextKey(platformName, kind, value) {
   return safeValue ? `${platformName}_${safeValue}` : `${platformName}_${hashValue(value)}`
 }
 
+// Matches `trellis-implement`, `trellis-check`, `trellis-research` exactly.
+// Used by chat.message plugins to skip injection inside Trellis sub-agent turns.
+const TRELLIS_SUBAGENT_RE = /^trellis-(implement|check|research)$/
+
+/**
+ * Return true when the OpenCode `chat.message` input represents a Trellis
+ * sub-agent turn. `input.agent` is set by OpenCode when a Task tool spawns a
+ * child session with a custom agent (see `packages/opencode/src/tool/task.ts`).
+ */
+export function isTrellisSubagent(input) {
+  if (!input || typeof input !== "object") return false
+  const agent = typeof input.agent === "string" ? input.agent.trim() : ""
+  return TRELLIS_SUBAGENT_RE.test(agent)
+}
+
 /**
  * Trellis Context Manager
  */
@@ -116,27 +131,74 @@ export class TrellisContext {
 
   /**
    * Get active task from session runtime context.
+   *
+   * Resolution order (mirrors Python `active_task.resolve_active_task`):
+   *   1. Lookup the runtime file for the input-derived context key.
+   *   2. If that misses and exactly one session runtime file exists locally,
+   *      use it (`_resolveSingleSessionFallback`). Refuses to guess when 0 or
+   *      ≥2 files exist so multi-window isolation holds.
    */
   getActiveTask(platformInput = null) {
     const contextKey = this.getContextKey(platformInput)
-    if (!contextKey) {
-      return { taskPath: null, source: "none", stale: false }
+    if (contextKey) {
+      const context = this.readContext(contextKey)
+      const taskRef = this.normalizeTaskRef(context?.current_task || "")
+      if (taskRef) {
+        const taskDir = this.resolveTaskDir(taskRef)
+        return {
+          taskPath: taskRef,
+          source: `session:${contextKey}`,
+          stale: !taskDir || !existsSync(taskDir),
+        }
+      }
     }
 
-    const context = this.readContext(contextKey)
-    const taskRef = this.normalizeTaskRef(context?.current_task || "")
-    if (taskRef) {
-      const taskDir = this.resolveTaskDir(taskRef)
-      return {
-        taskPath: taskRef,
-        source: `session:${contextKey}`,
-        stale: !taskDir || !existsSync(taskDir),
-      }
+    const fallback = this._resolveSingleSessionFallback()
+    if (fallback) {
+      return fallback
     }
 
     return { taskPath: null, source: "none", stale: false }
   }
 
+  /**
+   * Mirror of Python `_resolve_single_session_fallback`. Returns the task
+   * pointed at by the sole session runtime file when exactly one exists,
+   * else null.
+   */
+  _resolveSingleSessionFallback() {
+    const sessionsDir = join(this.directory, ".trellis", ".runtime", "sessions")
+    if (!existsSync(sessionsDir)) return null
+
+    let files
+    try {
+      files = readdirSync(sessionsDir)
+        .filter(name => name.endsWith(".json"))
+        .sort()
+    } catch {
+      return null
+    }
+    if (files.length !== 1) return null
+
+    const sessionFile = join(sessionsDir, files[0])
+    let context
+    try {
+      context = JSON.parse(readFileSync(sessionFile, "utf-8"))
+    } catch {
+      return null
+    }
+    const taskRef = this.normalizeTaskRef(context?.current_task || "")
+    if (!taskRef) return null
+
+    const taskDir = this.resolveTaskDir(taskRef)
+    const fallbackKey = files[0].replace(/\.json$/, "")
+    return {
+      taskPath: taskRef,
+      source: `session-fallback:${fallbackKey}`,
+      stale: !taskDir || !existsSync(taskDir),
+    }
+  }
+
   getCurrentTask(platformInput = null) {
     return this.getActiveTask(platformInput).taskPath
   }