@mindfoldhq/trellis 0.5.0-beta.8 → 0.5.0-rc.0

package/dist/templates/extract.js.map

@@ -1 +1 @@
-{"version":3,"file":"extract.js","sourceRoot":"","sources":["../../src/templates/extract.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"extract.js","sourceRoot":"","sources":["../../src/templates/extract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAE/D,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;AAI3C;;GAEG;AACH,MAAM,UAAU,sBAAsB;IACpC,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IACrD,IAAI,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAChC,OAAO,YAAY,CAAC;IACtB,CAAC;IACD,MAAM,IAAI,KAAK,CACb,4EAA4E,CAC7E,CAAC;AACJ,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,oBAAoB;IAClC,OAAO,sBAAsB,EAAE,CAAC;AAClC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB;IACnC,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IACpD,IAAI,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAChC,OAAO,YAAY,CAAC;IACtB,CAAC;IACD,MAAM,IAAI,KAAK,CACb,0EAA0E,CAC3E,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB;IACrC,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IACtD,IAAI,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAChC,OAAO,YAAY,CAAC;IACtB,CAAC;IACD,MAAM,IAAI,KAAK,CACb,8EAA8E,CAC/E,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAChD,IAAI,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAChC,OAAO,YAAY,CAAC;IACtB,CAAC;IACD,MAAM,IAAI,KAAK,CACb,kEAAkE,CACnE,CAAC;AACJ,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,eAAe;IAC7B,OAAO,iBAAiB,EAAE,CAAC;AAC7B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,YAAoB;IAClD,MAAM,WAAW,GAAG,oBAAoB,EAAE,CAAC;IAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IACtD,OAAO,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;AAC5C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAC1B,QAA0B,EAC1B,QAAgB;IAEhB,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC9D,OAAO,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,YAAoB;IAC7C,OAAO,eAAe,CAAC,WAAW,YAAY,EAAE,CAAC,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,YAAoB;IAC/C,OAAO,eAAe,CAAC,YAAY,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,QAAgB;IAC1C,OAAO,YAAY,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;AAC5C,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,eAAuB,EACvB,QAAgB,EAChB,OAAkC;IAElC,MAAM,WAAW,GAAG,oBAAoB,EAAE,CAAC;IAC3C,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,eAAe,CAAC,CAAC;IACxD,MAAM,gBAAgB,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;AACrD,CAAC;AAED,KAAK,UAAU,gBAAgB,CAC7B,GAAW,EACX,IAAY,EACZ,OAAkC;IAElC,SAAS,CAAC,IAAI,CAAC,CAAC;IAEhB,KAAK,MAAM,KAAK,IAAI,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;QACxC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACtC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACxC,MAAM,IAAI,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAElC,IAAI,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;YACvB,MAAM,gBAAgB,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QACrD,CAAC;aAAM,CAAC;YACN,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAClD,MAAM,YAAY,GAChB,OAAO,EAAE,UAAU,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;YAC1E,MAAM,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;AACH,CAAC"}

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

@@ -29,7 +29,7 @@ Conversations get compacted; files don't. Every research output MUST end up as a
 
 ### Step 1: Resolve Current Task
 
-Read `.trellis/.current-task` → task directory (e.g. `.trellis/tasks/04-17-foo/`). If empty or missing, ask the user where to write output; do NOT guess.
+Run `python3 ./.trellis/scripts/task.py current --source` → active task path. If no active task is set, ask the user where to write output; do NOT guess.
 
 Ensure `{TASK_DIR}/research/` exists:
 

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

@@ -1,7 +1,7 @@
 {
   "name": "trellis-research",
   "description": "Code and tech search expert. Persists findings to {TASK_DIR}/research/. No writes outside that directory.",
-  "instructions": "# Research Agent\n\nYou are the Research Agent in the Trellis workflow.\n\n## Core Principle\n\n**You do one thing: find, explain, and PERSIST information.**\n\nConversations get compacted; files don't. Every research output MUST end up as a file under `{TASK_DIR}/research/`. Returning findings only through the chat reply is a failure — the caller cannot read them next session.\n\n---\n\n## Core Responsibilities\n\n1. **Internal Search** — locate files/components, understand code logic, discover patterns (Glob, Grep, Read)\n2. **External Search** — library docs, API references, best practices (web search)\n3. **Persist** — write each research topic to `{TASK_DIR}/research/<topic>.md`\n4. **Report** — return file paths + one-line summaries to the main agent (not full content)\n\n---\n\n## Workflow\n\n### Step 1: Resolve Current Task\n\nRead `.trellis/.current-task` → task directory (e.g. `.trellis/tasks/04-17-foo/`). If empty or missing, ask the user where to write output; do NOT guess.\n\nEnsure `{TASK_DIR}/research/` exists:\n\n```bash\nmkdir -p <TASK_DIR>/research\n```\n\n### Step 2: Understand Search Request\n\nClassify: internal / external / mixed. Determine scope (global / specific directory) and expected shape (file list / pattern notes / tech comparison).\n\n### Step 3: Execute Search\n\nRun independent searches in parallel (Glob + Grep + web) for efficiency.\n\n### Step 4: Persist Each Topic\n\nFor each distinct research topic, Write a markdown file at `{TASK_DIR}/research/<topic-slug>.md`. Use the File Format below.\n\n### Step 5: Report to Main Agent\n\nReply with ONLY:\n\n- List of files written (paths relative to repo root)\n- One-line summary per file\n- Any critical caveats that the main agent needs to know right now\n\nDo NOT paste full research content into the reply. The files are the contract.\n\n---\n\n## Scope Limits (Strict)\n\n### Write ALLOWED\n\n- `{TASK_DIR}/research/*.md` — your own output\n- Creating `{TASK_DIR}/research/` if it doesn't exist (via `mkdir -p`)\n\n### Write FORBIDDEN\n\n- Code files (`src/`, `lib/`, …)\n- Spec files (`.trellis/spec/`) — main agent should use `update-spec` skill instead\n- `.trellis/scripts/`, `.trellis/workflow.md`, platform config (`.claude/`, `.cursor/`, etc.)\n- Other task directories\n- Any git operation (commit / push / branch / merge)\n\nIf the user asks you to edit code, decline and suggest spawning `implement` instead.\n\n---\n\n## File Format\n\nEach `{TASK_DIR}/research/<topic>.md` should follow:\n\n```markdown\n# Research: <topic>\n\n- **Query**: <original query>\n- **Scope**: <internal / external / mixed>\n- **Date**: <YYYY-MM-DD>\n\n## Findings\n\n### Files Found\n\n| File Path | Description |\n|---|---|\n| `src/services/xxx.ts` | Main implementation |\n| `src/types/xxx.ts` | Type definitions |\n\n### Code Patterns\n\n<describe patterns, cite file:line>\n\n### External References\n\n- [Library X docs](url) — <why relevant, version constraints>\n\n### Related Specs\n\n- `.trellis/spec/xxx.md` — <description>\n\n## Caveats / Not Found\n\n<anything incomplete or uncertain>\n```\n\n---\n\n## Guidelines\n\n### DO\n\n- Provide specific file paths and line numbers\n- Quote actual code snippets\n- Persist every topic to its own file\n- Return file paths in your reply, not the full content\n- Mark \"not found\" explicitly when searches come up empty\n\n### DON'T\n\n- Don't write code or modify files outside `{TASK_DIR}/research/`\n- Don't guess uncertain info\n- Don't paste full research text into the reply (files are the deliverable)\n- Don't propose improvements or critique implementation (that's not your role)\n",
+  "instructions": "# Research Agent\n\nYou are the Research Agent in the Trellis workflow.\n\n## Core Principle\n\n**You do one thing: find, explain, and PERSIST information.**\n\nConversations get compacted; files don't. Every research output MUST end up as a file under `{TASK_DIR}/research/`. Returning findings only through the chat reply is a failure — the caller cannot read them next session.\n\n---\n\n## Core Responsibilities\n\n1. **Internal Search** — locate files/components, understand code logic, discover patterns (Glob, Grep, Read)\n2. **External Search** — library docs, API references, best practices (web search)\n3. **Persist** — write each research topic to `{TASK_DIR}/research/<topic>.md`\n4. **Report** — return file paths + one-line summaries to the main agent (not full content)\n\n---\n\n## Workflow\n\n### Step 1: Resolve Current Task\n\nRun `python3 ./.trellis/scripts/task.py current --source` → active task path. If no active task is set, ask the user where to write output; do NOT guess.\n\nEnsure `{TASK_DIR}/research/` exists:\n\n```bash\nmkdir -p <TASK_DIR>/research\n```\n\n### Step 2: Understand Search Request\n\nClassify: internal / external / mixed. Determine scope (global / specific directory) and expected shape (file list / pattern notes / tech comparison).\n\n### Step 3: Execute Search\n\nRun independent searches in parallel (Glob + Grep + web) for efficiency.\n\n### Step 4: Persist Each Topic\n\nFor each distinct research topic, Write a markdown file at `{TASK_DIR}/research/<topic-slug>.md`. Use the File Format below.\n\n### Step 5: Report to Main Agent\n\nReply with ONLY:\n\n- List of files written (paths relative to repo root)\n- One-line summary per file\n- Any critical caveats that the main agent needs to know right now\n\nDo NOT paste full research content into the reply. The files are the contract.\n\n---\n\n## Scope Limits (Strict)\n\n### Write ALLOWED\n\n- `{TASK_DIR}/research/*.md` — your own output\n- Creating `{TASK_DIR}/research/` if it doesn't exist (via `mkdir -p`)\n\n### Write FORBIDDEN\n\n- Code files (`src/`, `lib/`, …)\n- Spec files (`.trellis/spec/`) — main agent should use `update-spec` skill instead\n- `.trellis/scripts/`, `.trellis/workflow.md`, platform config (`.claude/`, `.cursor/`, etc.)\n- Other task directories\n- Any git operation (commit / push / branch / merge)\n\nIf the user asks you to edit code, decline and suggest spawning `implement` instead.\n\n---\n\n## File Format\n\nEach `{TASK_DIR}/research/<topic>.md` should follow:\n\n```markdown\n# Research: <topic>\n\n- **Query**: <original query>\n- **Scope**: <internal / external / mixed>\n- **Date**: <YYYY-MM-DD>\n\n## Findings\n\n### Files Found\n\n| File Path | Description |\n|---|---|\n| `src/services/xxx.ts` | Main implementation |\n| `src/types/xxx.ts` | Type definitions |\n\n### Code Patterns\n\n<describe patterns, cite file:line>\n\n### External References\n\n- [Library X docs](url) — <why relevant, version constraints>\n\n### Related Specs\n\n- `.trellis/spec/xxx.md` — <description>\n\n## Caveats / Not Found\n\n<anything incomplete or uncertain>\n```\n\n---\n\n## Guidelines\n\n### DO\n\n- Provide specific file paths and line numbers\n- Quote actual code snippets\n- Persist every topic to its own file\n- Return file paths in your reply, not the full content\n- Mark \"not found\" explicitly when searches come up empty\n\n### DON'T\n\n- Don't write code or modify files outside `{TASK_DIR}/research/`\n- Don't guess uncertain info\n- Don't paste full research text into the reply (files are the deliverable)\n- Don't propose improvements or critique implementation (that's not your role)\n",
   "tools": [
     "read",
     "write",

package/dist/templates/markdown/agents.md

@@ -3,20 +3,27 @@
 
 These instructions are for AI assistants working in this project.
 
-Use the `/trellis:start` command when starting a new session to:
-- Initialize your developer identity
-- Understand current project context
-- Read relevant guidelines
+This project is managed by Trellis. The working knowledge you need lives under `.trellis/`:
 
-Use `@/.trellis/` to learn:
-- Development workflow (`workflow.md`)
-- Project structure guidelines (`spec/`)
-- Developer workspace (`workspace/`)
+- `.trellis/workflow.md` — development phases, when to create tasks, skill routing
+- `.trellis/spec/` — package- and layer-scoped coding guidelines (read before writing code in a given layer)
+- `.trellis/workspace/` — per-developer journals and session traces
+- `.trellis/tasks/` — active and archived tasks (PRDs, research, jsonl context)
 
-If you're using Codex, project-scoped helpers may also live in:
-- `.agents/skills/` for reusable Trellis skills
-- `.codex/agents/` for optional custom subagents
+If a Trellis command is available on your platform (e.g. `/trellis:finish-work`, `/trellis:continue`), prefer it over manual steps. Not every platform exposes every command.
 
-Keep this managed block so 'trellis update' can refresh the instructions.
+If you're using Codex or another agent-capable tool, additional project-scoped helpers may live in:
+- `.agents/skills/` — reusable Trellis skills
+- `.codex/agents/` — optional custom subagents
+
+## Subagents
+
+- ALWAYS wait for all subagents to complete before yielding.
+- Spawn subagents automatically when:
+  - Parallelizable work (e.g., install + verify, npm test + typecheck, multiple tasks from plan)
+  - Long-running or blocking tasks where a worker can run independently.
+  - Isolation for risky changes or checks
+
+Managed by Trellis. Edits outside this block are preserved; edits inside may be overwritten by a future `trellis update`.
 
 <!-- TRELLIS:END -->

package/dist/templates/markdown/gitignore.txt

@@ -7,6 +7,9 @@
 # Current task pointer (local state)
 .current-task
 
+# Session/window scoped runtime state
+.runtime/
+
 # Agent runtime files (in worktree)
 .agent-log
 .session-id

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

@@ -69,6 +69,30 @@ subprocess.run(["python3", "other_script.py"])
 subprocess.run([sys.executable, "other_script.py"])
 ```
 
+**Rule 4**: Don't assume the Python version your AI CLI uses matches your shell's `python3`. Your terminal may resolve `python3` → 3.11 (via homebrew/pyenv), but AI CLI hosts often spawn hook subprocesses with a minimal PATH that resolves `python3` → the system Python (3.9 on macOS). Any `.py` file run as an AI-CLI hook must be written for the lowest plausible Python version.
+
+Concrete failure: PEP 604 union syntax (`str | None`) requires Python 3.10+. If your hook file uses it, start with `from __future__ import annotations` so annotations become lazy strings and work on Python 3.7+:
+
+```python
+#!/usr/bin/env python3
+"""My hook."""
+from __future__ import annotations     # REQUIRED for PEP 604 annotations
+
+def handler(x: str | None) -> dict | None:   # OK — lazy annotation
+    ...
+```
+
+```python
+# BAD — crashes on Python < 3.10:
+#   TypeError: unsupported operand type(s) for |: 'type' and 'NoneType'
+def handler(x: str | None) -> dict | None:
+    ...
+```
+
+Note: `from __future__ import annotations` only covers **annotations**. Runtime expressions like `isinstance(x, int | str)` still require Python 3.10+. Avoid them in hook scripts.
+
+Applies to anything the AI CLI executes as a hook: `match/case` statements (3.10+), `tomllib` (3.11+), `ExceptionGroup` / `except*` (3.11+) — all crash on older Python regardless of `__future__`.
+
 ### 2. Path Handling
 
 | Assumption | macOS/Linux | Windows |

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

@@ -21,7 +21,7 @@ You are the Check Agent in the Trellis workflow.
 
 Otherwise, load context yourself:
 
-1. Read `.trellis/.current-task` → get task directory (e.g., `.trellis/tasks/xxx`)
+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

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

@@ -21,14 +21,17 @@ You are the Implement Agent in the Trellis workflow.
 
 Otherwise, load context yourself:
 
-1. Read `.trellis/.current-task` → get task directory (e.g., `.trellis/tasks/xxx`)
+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:
-   - If `path` is a file → Read it
-   - If `path` is a directory → Read all `.md` files in it
+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.
 
 ---

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

@@ -6,7 +6,7 @@ permission:
   read: allow
   write: deny
   edit: deny
-  bash: deny
+  bash: allow
   glob: allow
   grep: allow
   mcp__exa__*: allow
@@ -22,7 +22,7 @@ You are the Research Agent in the Trellis workflow.
 
 Otherwise, if task-specific research is needed:
 
-1. Read `.trellis/.current-task` → get task directory (if exists)
+1. Run `python3 ./.trellis/scripts/task.py current --source` → get active task directory and source (if set)
 2. For each entry in JSONL (if task dir exists):
    - If `path` is a file → Read it
    - If `path` is a directory → Read all `.md` files in it

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

@@ -9,6 +9,8 @@ import { existsSync, readFileSync, appendFileSync, readdirSync } from "fs"
 import { isAbsolute, join } from "path"
 import { platform } from "os"
 import { execSync } from "child_process"
+import { createHash } from "crypto"
+import process from "process"
 
 const PYTHON_CMD = platform() === "win32" ? "python" : "python3"
 // Debug logging
@@ -24,6 +26,43 @@ function debugLog(prefix, ...args) {
   }
 }
 
+function stringValue(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null
+}
+
+function sanitizeKey(raw) {
+  const safe = raw.trim().replace(/[^A-Za-z0-9._-]+/g, "_").replace(/^[._-]+|[._-]+$/g, "")
+  return safe ? safe.slice(0, 160) : ""
+}
+
+function hashValue(raw) {
+  return createHash("sha256").update(raw).digest("hex").slice(0, 24)
+}
+
+function lookupString(data, keys) {
+  if (!data || typeof data !== "object") return null
+  for (const key of keys) {
+    const value = stringValue(data[key])
+    if (value) return value
+  }
+  for (const nestedKey of ["input", "properties", "event", "hook_input", "hookInput"]) {
+    const nested = data[nestedKey]
+    if (nested && typeof nested === "object") {
+      const value = lookupString(nested, keys)
+      if (value) return value
+    }
+  }
+  return null
+}
+
+function buildContextKey(platformName, kind, value) {
+  if (kind === "transcript") {
+    return `${platformName}_transcript_${hashValue(value)}`
+  }
+  const safeValue = sanitizeKey(value)
+  return safeValue ? `${platformName}_${safeValue}` : `${platformName}_${hashValue(value)}`
+}
+
 /**
  * Trellis Context Manager
  */
@@ -41,23 +80,67 @@ export class TrellisContext {
     return existsSync(join(this.directory, ".trellis"))
   }
 
-  /**
-   * Get current task directory from .trellis/.current-task
-   */
-  getCurrentTask() {
+  getContextKey(platformInput = null) {
+    const override = stringValue(process.env.TRELLIS_CONTEXT_ID)
+    if (override) {
+      return sanitizeKey(override) || hashValue(override)
+    }
+
+    const runID = stringValue(process.env.OPENCODE_RUN_ID)
+    if (runID) return buildContextKey("opencode", "session", runID)
+
+    const input = platformInput && typeof platformInput === "object" ? platformInput : null
+    if (!input) return null
+
+    const sessionID = lookupString(input, ["session_id", "sessionId", "sessionID"])
+    if (sessionID) return buildContextKey("opencode", "session", sessionID)
+
+    const conversationID = lookupString(input, ["conversation_id", "conversationId", "conversationID"])
+    if (conversationID) return buildContextKey("opencode", "conversation", conversationID)
+
+    const transcriptPath = lookupString(input, ["transcript_path", "transcriptPath", "transcript"])
+    if (transcriptPath) return buildContextKey("opencode", "transcript", transcriptPath)
+
+    return null
+  }
+
+  readContext(contextKey) {
     try {
-      const currentTaskPath = join(this.directory, ".trellis", ".current-task")
-      if (!existsSync(currentTaskPath)) {
-        return null
-      }
-      const taskRef = readFileSync(currentTaskPath, "utf-8").trim()
-      const normalized = this.normalizeTaskRef(taskRef)
-      return normalized || null
+      const contextPath = join(this.directory, ".trellis", ".runtime", "sessions", `${contextKey}.json`)
+      if (!existsSync(contextPath)) return null
+      return JSON.parse(readFileSync(contextPath, "utf-8"))
     } catch {
       return null
     }
   }
 
+  /**
+   * Get active task from session runtime context.
+   */
+  getActiveTask(platformInput = null) {
+    const contextKey = this.getContextKey(platformInput)
+    if (!contextKey) {
+      return { taskPath: null, source: "none", stale: false }
+    }
+
+    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),
+      }
+    }
+
+    return { taskPath: null, source: "none", stale: false }
+  }
+
+  getCurrentTask(platformInput = null) {
+    return this.getActiveTask(platformInput).taskPath
+  }
+
   normalizeTaskRef(taskRef) {
     if (!taskRef) {
       return ""
@@ -115,13 +198,17 @@ export class TrellisContext {
     return this.readFile(join(this.directory, relativePath))
   }
 
-  runScript(scriptPath, cwd = null) {
+  runScript(scriptPath, cwd = null, contextKey = null) {
     try {
       const result = execSync(`${PYTHON_CMD} "${scriptPath}"`, {
         cwd: cwd || this.directory,
         timeout: 10000,
         encoding: "utf-8",
-        stdio: ["pipe", "pipe", "pipe"]
+        stdio: ["pipe", "pipe", "pipe"],
+        env: {
+          ...process.env,
+          ...(contextKey ? { TRELLIS_CONTEXT_ID: contextKey } : {}),
+        },
       })
       return result || ""
     } catch {

package/dist/templates/opencode/plugins/inject-subagent-context.js

@@ -1,3 +1,4 @@
+/* global process */
 /**
  * Trellis Context Injection Plugin
  *
@@ -255,12 +256,66 @@ ${originalPrompt}
   return templates[agentType] || originalPrompt
 }
 
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, "'\\''")}'`
+}
+
+function powershellQuote(value) {
+  return `'${String(value).replace(/'/g, "''")}'`
+}
+
+function buildTrellisContextPrefix(contextKey, hostPlatform = process.platform) {
+  if (hostPlatform === "win32") {
+    // OpenCode's Windows Bash tool runs through PowerShell, not a POSIX shell.
+    return `$env:TRELLIS_CONTEXT_ID = ${powershellQuote(contextKey)}; `
+  }
+
+  return `export TRELLIS_CONTEXT_ID=${shellQuote(contextKey)}; `
+}
+
+function getBashCommandKey(args) {
+  if (!args || typeof args !== "object") return null
+  if (typeof args.command === "string") return "command"
+  if (typeof args.cmd === "string") return "cmd"
+  return null
+}
+
+function commandStartsWithTrellisContext(command) {
+  const firstCommand = command.trimStart().split(/[;&|]/, 1)[0].trimStart()
+  return (
+    /^TRELLIS_CONTEXT_ID\s*=/.test(firstCommand) ||
+    /^export\s+TRELLIS_CONTEXT_ID\s*=/.test(firstCommand) ||
+    /^env\s+(?:[^\s=]+\s+)*TRELLIS_CONTEXT_ID\s*=/.test(firstCommand) ||
+    /^\$env:TRELLIS_CONTEXT_ID\s*=/i.test(firstCommand)
+  )
+}
+
+/**
+ * OpenCode TUI may not expose OPENCODE_RUN_ID to Bash. The plugin hook still
+ * receives session identity, so inject it into Bash commands before execution.
+ */
+function injectTrellisContextIntoBash(ctx, input, output, hostPlatform) {
+  const args = output?.args
+  const commandKey = getBashCommandKey(args)
+  if (!commandKey) return false
+
+  const command = args[commandKey]
+  if (!command.trim()) return false
+  if (commandStartsWithTrellisContext(command)) return false
+
+  const contextKey = ctx.getContextKey(input)
+  if (!contextKey) return false
+
+  args[commandKey] = `${buildTrellisContextPrefix(contextKey, hostPlatform)}${command}`
+  return true
+}
+
 // OpenCode plugin factory: `export default async (input) => hooks`.
 // OpenCode 1.2.x iterates every module export and invokes it as a function
 // (packages/opencode/src/plugin/index.ts — `for ([_, fn] of Object.entries(mod)) await fn(input)`);
 // the previous `{ id, server }` object shape failed with
 // `TypeError: fn is not a function` in 1.2.x.
-export default async ({ directory }) => {
+export default async ({ directory, platform: hostPlatform = process.platform }) => {
   const ctx = new TrellisContext(directory)
   debugLog("inject", "Plugin loaded, directory:", directory)
 
@@ -270,6 +325,13 @@ export default async ({ directory }) => {
           debugLog("inject", "tool.execute.before called, tool:", input?.tool)
 
           const toolName = input?.tool?.toLowerCase()
+          if (toolName === "bash") {
+            if (injectTrellisContextIntoBash(ctx, input, output, hostPlatform)) {
+              debugLog("inject", "Injected TRELLIS_CONTEXT_ID into Bash command")
+            }
+            return
+          }
+
           if (toolName !== "task") {
             return
           }
@@ -277,21 +339,24 @@ export default async ({ directory }) => {
           const args = output?.args
           if (!args) return
 
-          const subagentType = args.subagent_type
+          const rawSubagentType = args.subagent_type
+          // Strip "trellis-" prefix added by v0.5.0-beta.5 agent rename migration
+          const subagentType = (rawSubagentType || "").replace(/^trellis-/, "")
           const originalPrompt = args.prompt || ""
 
-          debugLog("inject", "Task tool called, subagent_type:", subagentType)
+          debugLog("inject", "Task tool called, subagent_type:", rawSubagentType)
 
           if (!AGENTS_ALL.includes(subagentType)) {
             debugLog("inject", "Skipping - unsupported subagent_type")
             return
           }
 
-          // Read current task
-          const taskDir = ctx.getCurrentTask()
+          // Resolve active task through session runtime context.
+          const taskDir = ctx.getCurrentTask(input)
 
           // Agents requiring task directory
           if (AGENTS_REQUIRE_TASK.includes(subagentType)) {
+            // subagentType is already stripped of "trellis-" prefix above
             if (!taskDir) {
               debugLog("inject", "Skipping - no current task")
               return

package/dist/templates/opencode/plugins/inject-workflow-state.js

@@ -5,19 +5,21 @@
  * Per-turn UserPromptSubmit equivalent for OpenCode.
  *
  * On every chat.message, if a Trellis task is active, inject a short
- * <workflow-state> breadcrumb reminding the main AI what task is active
- * and its expected flow. Breadcrumb text is pulled from the project's
- * workflow.md [workflow-state:STATUS] tag blocks (single source of
- * truth for users who fork the Trellis workflow), with hardcoded
- * fallbacks so the hook never breaks when workflow.md is missing or
- * malformed.
+ * <workflow-state> breadcrumb reminding the main AI what task is
+ * active and its expected flow. Breadcrumb text is pulled exclusively
+ * from the project's workflow.md [workflow-state:STATUS] tag blocks —
+ * workflow.md is the single source of truth. There are no fallback
+ * tables in this plugin: when workflow.md is missing or a tag is
+ * absent, the breadcrumb degrades to a generic
+ * "Refer to workflow.md for current step." line so users see (and fix)
+ * the broken state instead of the plugin silently masking it.
  *
- * Unlike session-start, this plugin does NOT dedupe — breadcrumb
+ * Unlike session-start, this plugin does NOT dedupe — the breadcrumb
  * should surface on every turn so long conversations don't drift.
  *
  * Silently skips when:
  *   - No .trellis/ directory
- *   - No active task (.trellis/.current-task missing or stale)
+ *   - No active task in the session runtime context
  *   - task.json malformed or missing status
  */
 
@@ -29,40 +31,25 @@ import { TrellisContext, debugLog } from "../lib/trellis-context.js"
 // (so "in-review" / "blocked-by-team" work alongside "in_progress").
 const TAG_RE = /\[workflow-state:([A-Za-z0-9_-]+)\]\s*\n([\s\S]*?)\n\s*\[\/workflow-state:\1\]/g
 
-// Hardcoded defaults for built-in Trellis statuses. Used when workflow.md
-// is missing, malformed, or lacks the tag for this status.
-//
-// `no_task` is a pseudo-status emitted when .current-task is missing — keeps
-// the Next-Action reminder flowing per-turn even without an active task.
-const FALLBACK_BREADCRUMBS = {
-  no_task:
-    "No active task. If the user describes multi-step work, load " +
-    "trellis-brainstorm skill to clarify requirements and create a task " +
-    "via `python3 ./.trellis/scripts/task.py create`. Simple one-off " +
-    "questions or trivial edits don't need a task — just answer directly.",
-  planning:
-    "Complete prd.md via trellis-brainstorm skill; then run task.py start.",
-  in_progress:
-    "Flow: implement → check → update-spec → finish\n" +
-    "Check conversation history + git status to determine current step; do NOT skip check.",
-  completed:
-    "User commits changes; then run task.py archive.",
-}
-
 /**
  * Parse workflow.md for [workflow-state:STATUS] blocks.
- * Returns {status: body}. Missing tags fall back to hardcoded defaults.
+ *
+ * Returns {status: body}. workflow.md is the single source of truth —
+ * there are no fallback tables here. Missing tags (or a missing /
+ * unreadable workflow.md) fall back to a generic line in
+ * buildBreadcrumb so users see the broken state and fix workflow.md
+ * rather than the plugin silently masking it.
  */
 function loadBreadcrumbs(directory) {
-  const result = { ...FALLBACK_BREADCRUMBS }
   const workflowPath = join(directory, ".trellis", "workflow.md")
-  if (!existsSync(workflowPath)) return result
+  if (!existsSync(workflowPath)) return {}
   let content
   try {
     content = readFileSync(workflowPath, "utf-8")
   } catch {
-    return result
+    return {}
   }
+  const result = {}
   for (const match of content.matchAll(TAG_RE)) {
     const status = match[1]
     const body = match[2].trim()
@@ -74,11 +61,14 @@ function loadBreadcrumbs(directory) {
 /**
  * Get (taskId, status) from active task, or null if no active task.
  */
-function getActiveTask(ctx) {
-  const taskRef = ctx.getCurrentTask()
+function getActiveTask(ctx, platformInput = null) {
+  const active = ctx.getActiveTask(platformInput)
+  const taskRef = active.taskPath
   if (!taskRef) return null
   const taskDir = ctx.resolveTaskDir(taskRef)
-  if (!taskDir || !existsSync(taskDir)) return null
+  if (active.stale || !taskDir || !existsSync(taskDir)) {
+    return { id: taskRef.split("/").pop(), status: "stale", source: active.source }
+  }
   const taskJsonPath = join(taskDir, "task.json")
   if (!existsSync(taskJsonPath)) return null
   try {
@@ -86,7 +76,7 @@ function getActiveTask(ctx) {
     const status = typeof data.status === "string" ? data.status : ""
     if (!status) return null
     const id = data.id || taskRef.split("/").pop()
-    return { id, status }
+    return { id, status, source: active.source }
   } catch {
     return null
   }
@@ -94,16 +84,20 @@ function getActiveTask(ctx) {
 
 /**
  * Build the <workflow-state>...</workflow-state> block.
- * - Known status (templates or fallback) → detailed body
- * - Unknown status → generic "refer to workflow.md"
+ * - Known status (tag present in workflow.md) → detailed body
+ * - Unknown status (no tag, or workflow.md missing) → generic
+ *   "Refer to workflow.md for current step." line
  * - no_task pseudo-status (id === null) → header omits task info
  */
-function buildBreadcrumb(id, status, templates) {
+function buildBreadcrumb(id, status, templates, source = null) {
   let body = templates[status]
   if (body === undefined) {
     body = "Refer to workflow.md for current step."
   }
-  const header = id === null ? `Status: ${status}` : `Task: ${id} (${status})`
+  let header = id === null ? `Status: ${status}` : `Task: ${id} (${status})`
+  if (source) {
+    header = `${header}\nSource: ${source}`
+  }
   return `<workflow-state>\n${header}\n${body}\n</workflow-state>`
 }
 
@@ -124,9 +118,9 @@ export default async ({ directory }) => {
             return
           }
           const templates = loadBreadcrumbs(directory)
-          const task = getActiveTask(ctx)
+          const task = getActiveTask(ctx, input)
           const breadcrumb = task
-            ? buildBreadcrumb(task.id, task.status, templates)
+            ? buildBreadcrumb(task.id, task.status, templates, task.source)
             : buildBreadcrumb(null, "no_task", templates)
 
           const parts = output?.parts || []
@@ -142,9 +136,9 @@ export default async ({ directory }) => {
           debugLog(
             "workflow-state",
             "Injected breadcrumb for task",
-            task.id,
+            task ? task.id : "none",
             "status",
-            task.status,
+            task ? task.status : "no_task",
           )
         } catch (error) {
           debugLog(