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

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.
@@ -587,3 +593,41 @@ const { getMigrationsForVersion } = require('./dist/migrations/index.js');
 console.log('From 0.2.12:', getMigrationsForVersion('0.2.12', 'CURRENT').length);
 "
 ```
+
+## Release Checklist: Bundled Assets
+
+When release notes or docs claim an asset is bundled, installed automatically, or
+included with Trellis, verify the whole distribution path:
+
+- [ ] Source file exists in the branch being tagged, not only in another branch,
+  docs submodule, or marketplace tree.
+- [ ] `pnpm build` copies the asset into `dist/templates/**`.
+- [ ] `npm pack --dry-run --json` includes the expected `dist/**` path.
+- [ ] The built binary installs the asset in a fresh temp repository.
+- [ ] `.trellis/.template-hashes.json` tracks the generated asset path.
+- [ ] `trellis update --dry-run` reports `Already up to date!` in that temp
+  repository.
+
+**Why this matters**: docs/changelog text can move independently from the code
+branch that owns distributable templates. A feature can be documented as bundled
+while the published npm tarball still lacks the files.
+
+```bash
+pnpm --filter @mindfoldhq/trellis build
+
+cd packages/cli
+npm pack --dry-run --json | grep 'dist/templates/common/bundled-skills/<skill>/SKILL.md'
+cd ../..
+
+tmpdir=$(mktemp -d /tmp/trellis-built-bin-smoke-XXXXXX)
+printf '{"name":"trellis-smoke","version":"0.0.0"}\n' > "$tmpdir/package.json"
+git -C "$tmpdir" init -q
+(
+  cd "$tmpdir"
+  node /path/to/Trellis/packages/cli/bin/trellis.js init -u smoke --yes --claude --codex
+  test -f .claude/skills/<skill>/SKILL.md
+  test -f .agents/skills/<skill>/SKILL.md
+  grep -q '<skill>' .trellis/.template-hashes.json
+  node /path/to/Trellis/packages/cli/bin/trellis.js update --dry-run
+)
+```

package/dist/templates/markdown/spec/guides/index.md.txt

@@ -34,6 +34,8 @@ These guides help you **ask the right questions before coding**.
 - [ ] Data format changes between layers
 - [ ] Multiple consumers need the same data
 - [ ] You're not sure where to put some logic
+- [ ] You are adding an event kind, JSONL record, RPC payload, or config field
+- [ ] UI / command code starts casting raw payload fields directly
 
 → Read [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md)
 
@@ -44,9 +46,25 @@ These guides help you **ask the right questions before coding**.
 - [ ] You're adding a new field to multiple places
 - [ ] **You're modifying any constant or config**
 - [ ] **You're creating a new utility/helper function** ← Search first!
+- [ ] Two files read the same untyped payload field with local casts
+- [ ] Multiple branches update the same derived state from `kind` / `action`
 
 → Read [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md)
 
+### When Verifying AI Cross-Review Results
+
+- [ ] Reviewer claims "user input can be malicious" → Check the actual data source (internal manifest? user config? external API?)
+- [ ] Reviewer flags "missing validation" → Is the data from a trusted internal source?
+- [ ] Reviewer says "behavior change" → Read the code comments — is it intentional design?
+- [ ] Reviewer identifies a "bug" in test → Mentally delete the feature being tested — does the test still pass? If yes → tautological test
+
+**Common AI reviewer false-positive patterns**:
+1. **Trust boundary confusion**: Treating internal data (bundled JSON manifests) as untrusted external input
+2. **Ignoring design comments**: Flagging intentional behavior documented in code comments as bugs
+3. **Variable misreading**: Not tracing a variable to its actual definition (e.g., Map keyed by path vs name)
+
+**Verification rule**: Every CRITICAL/WARNING finding must be verified against the actual code before prioritizing. Budget ~35% false-positive rate for AI reviews.
+
 ---
 
 ## Pre-Modification Rule (CRITICAL)

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

@@ -34,14 +34,18 @@ Look for the `<!-- trellis-hook-injected -->` marker in your input above.
 
 Before checking, read:
 - `.trellis/spec/` - Development guidelines
+- Task `prd.md` - Requirements document
+- Task `design.md` - Technical design (if exists)
+- Task `implement.md` - Execution plan (if exists)
 - Pre-commit checklist for quality standards
 
 ## Core Responsibilities
 
 1. **Get code changes** - Use git diff to get uncommitted code
-2. **Check against specs** - Verify code follows guidelines
-3. **Self-fix** - Fix issues yourself, not just report them
-4. **Run verification** - typecheck and lint
+2. **Review task artifacts** - Check changes against prd.md, design.md if present, and implement.md if present
+3. **Check against specs** - Verify code follows guidelines
+4. **Self-fix** - Fix issues yourself, not just report them
+5. **Run verification** - typecheck and lint
 
 ## Important
 
@@ -60,10 +64,12 @@ git diff --name-only  # List changed files
 git diff              # View specific changes
 ```
 
-### Step 2: Check Against Specs
+### Step 2: Check Against Specs and Task Artifacts
 
-Read relevant specs in `.trellis/spec/` to check code:
+Read the task's prd.md, design.md if present, and implement.md if present, then read relevant specs in `.trellis/spec/` to check code:
 
+- Does it satisfy the task requirements
+- Does it follow the technical design and implementation plan when present
 - Does it follow directory structure conventions
 - Does it follow naming conventions
 - Does it follow code patterns

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
   }

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

@@ -14,29 +14,44 @@ import { TrellisContext, debugLog } from "../lib/trellis-context.js"
 const AGENTS_ALL = ["implement", "check", "research"]
 const AGENTS_REQUIRE_TASK = ["implement", "check"]
 
+// Match `Active task: <path>` on the first non-empty line of the dispatch
+// prompt. Mirrors the contract in workflow.md's [workflow-state:in_progress]
+// breadcrumb so multi-window users can disambiguate which task is targeted.
+const ACTIVE_TASK_HINT_RE = /^\s*Active task:\s*(\S+)\s*$/m
+
+function extractActiveTaskHint(prompt) {
+  if (typeof prompt !== "string" || !prompt) return null
+  const match = prompt.match(ACTIVE_TASK_HINT_RE)
+  return match ? match[1].trim() : null
+}
+
 /**
- * Get context for implement agent
+ * Get context for implement agent. `taskDir` may be relative
+ * (`.trellis/tasks/foo`) or absolute; both are resolved via
+ * `ctx.resolveTaskDir`.
  */
 function getImplementContext(ctx, taskDir) {
   const parts = []
+  const taskDirFull = ctx.resolveTaskDir(taskDir)
+  if (!taskDirFull) return ""
 
-  const jsonlPath = join(ctx.directory, taskDir, "implement.jsonl")
+  const jsonlPath = join(taskDirFull, "implement.jsonl")
   const entries = ctx.readJsonlWithFiles(jsonlPath)
   if (entries.length > 0) {
     parts.push(ctx.buildContextFromEntries(entries))
   }
 
-  const prd = ctx.readProjectFile(join(taskDir, "prd.md"))
+  const prd = ctx.readFile(join(taskDirFull, "prd.md"))
   if (prd) {
     parts.push(`=== ${taskDir}/prd.md (Requirements) ===\n${prd}`)
   }
 
-  const design = ctx.readProjectFile(join(taskDir, "design.md"))
+  const design = ctx.readFile(join(taskDirFull, "design.md"))
   if (design) {
     parts.push(`=== ${taskDir}/design.md (Technical Design) ===\n${design}`)
   }
 
-  const implementPlan = ctx.readProjectFile(join(taskDir, "implement.md"))
+  const implementPlan = ctx.readFile(join(taskDirFull, "implement.md"))
   if (implementPlan) {
     parts.push(`=== ${taskDir}/implement.md (Execution Plan) ===\n${implementPlan}`)
   }
@@ -45,28 +60,30 @@ function getImplementContext(ctx, taskDir) {
 }
 
 /**
- * Get context for check agent
+ * Get context for check agent. `taskDir` may be relative or absolute.
  */
 function getCheckContext(ctx, taskDir) {
   const parts = []
+  const taskDirFull = ctx.resolveTaskDir(taskDir)
+  if (!taskDirFull) return ""
 
-  const jsonlPath = join(ctx.directory, taskDir, "check.jsonl")
+  const jsonlPath = join(taskDirFull, "check.jsonl")
   const entries = ctx.readJsonlWithFiles(jsonlPath)
   if (entries.length > 0) {
     parts.push(ctx.buildContextFromEntries(entries))
   }
 
-  const prd = ctx.readProjectFile(join(taskDir, "prd.md"))
+  const prd = ctx.readFile(join(taskDirFull, "prd.md"))
   if (prd) {
     parts.push(`=== ${taskDir}/prd.md (Requirements) ===\n${prd}`)
   }
 
-  const design = ctx.readProjectFile(join(taskDir, "design.md"))
+  const design = ctx.readFile(join(taskDirFull, "design.md"))
   if (design) {
     parts.push(`=== ${taskDir}/design.md (Technical Design) ===\n${design}`)
   }
 
-  const implementPlan = ctx.readProjectFile(join(taskDir, "implement.md"))
+  const implementPlan = ctx.readFile(join(taskDirFull, "implement.md"))
   if (implementPlan) {
     parts.push(`=== ${taskDir}/implement.md (Execution Plan) ===\n${implementPlan}`)
   }
@@ -143,7 +160,8 @@ function getResearchContext(ctx) {
  */
 function buildPrompt(agentType, originalPrompt, context, isFinish = false) {
   const templates = {
-    implement: `# Implement Agent Task
+    implement: `<!-- trellis-hook-injected -->
+# Implement Agent Task
 
 You are the Implement Agent in the Multi-Agent Pipeline.
 
@@ -172,7 +190,8 @@ ${originalPrompt}
 - Follow all dev specs injected above
 - Report list of modified/created files when done`,
 
-    check: isFinish ? `# Finish Agent Task
+    check: isFinish ? `<!-- trellis-hook-injected -->
+# Finish Agent Task
 
 You are performing the final check before creating a PR.
 
@@ -207,7 +226,8 @@ ${originalPrompt}
 - If critical CODE issues found, report them clearly (fix specs, not code)
 - Verify all acceptance criteria in prd.md are met
 - Verify design.md and implement.md constraints when those files are present` :
-      `# Check Agent Task
+      `<!-- trellis-hook-injected -->
+# Check Agent Task
 
 You are the Check Agent in the Multi-Agent Pipeline.
 
@@ -235,7 +255,8 @@ ${originalPrompt}
 - Fix issues yourself, don't just report
 - Must execute complete checklist`,
 
-    research: `# Research Agent Task
+    research: `<!-- trellis-hook-injected -->
+# Research Agent Task
 
 You are the Research Agent in the Multi-Agent Pipeline.
 
@@ -280,9 +301,29 @@ 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.
+function envValue(env, key) {
+  const value = env?.[key]
+  return typeof value === "string" && value.trim() ? value.trim() : null
+}
+
+function shellBasename(value) {
+  return value.replace(/\\/g, "/").split("/").pop()?.toLowerCase() || ""
+}
+
+function isWindowsPosixShell(env = process.env) {
+  if (envValue(env, "MSYSTEM")) return true
+  if (envValue(env, "MINGW_PREFIX")) return true
+  if (envValue(env, "OPENCODE_GIT_BASH_PATH")) return true
+
+  const ostype = envValue(env, "OSTYPE")?.toLowerCase() || ""
+  if (/(msys|mingw|cygwin)/.test(ostype)) return true
+
+  const shell = shellBasename(envValue(env, "SHELL") || "")
+  return /^(bash|sh|zsh)(\.exe)?$/.test(shell)
+}
+
+function buildTrellisContextPrefix(contextKey, hostPlatform = process.platform, env = process.env) {
+  if (hostPlatform === "win32" && !isWindowsPosixShell(env)) {
     return `$env:TRELLIS_CONTEXT_ID = ${powershellQuote(contextKey)}; `
   }
 
@@ -301,7 +342,7 @@ function commandStartsWithTrellisContext(command) {
   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\s+(?:(?:-\S+|[A-Za-z_][A-Za-z0-9_]*=\S*)\s+)*TRELLIS_CONTEXT_ID\s*=/.test(firstCommand) ||
     /^\$env:TRELLIS_CONTEXT_ID\s*=/i.test(firstCommand)
   )
 }
@@ -310,7 +351,7 @@ function commandStartsWithTrellisContext(command) {
  * 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) {
+function injectTrellisContextIntoBash(ctx, input, output, hostPlatform, env) {
   const args = output?.args
   const commandKey = getBashCommandKey(args)
   if (!commandKey) return false
@@ -322,7 +363,7 @@ function injectTrellisContextIntoBash(ctx, input, output, hostPlatform) {
   const contextKey = ctx.getContextKey(input)
   if (!contextKey) return false
 
-  args[commandKey] = `${buildTrellisContextPrefix(contextKey, hostPlatform)}${command}`
+  args[commandKey] = `${buildTrellisContextPrefix(contextKey, hostPlatform, env)}${command}`
   return true
 }
 
@@ -331,7 +372,7 @@ function injectTrellisContextIntoBash(ctx, input, output, hostPlatform) {
 // (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, platform: hostPlatform = process.platform }) => {
+export default async ({ directory, platform: hostPlatform = process.platform, env = process.env }) => {
   const ctx = new TrellisContext(directory)
   debugLog("inject", "Plugin loaded, directory:", directory)
 
@@ -345,7 +386,7 @@ export default async ({ directory, platform: hostPlatform = process.platform })
 
           const toolName = input?.tool?.toLowerCase()
           if (toolName === "bash") {
-            if (injectTrellisContextIntoBash(ctx, input, output, hostPlatform)) {
+            if (injectTrellisContextIntoBash(ctx, input, output, hostPlatform, env)) {
               debugLog("inject", "Injected TRELLIS_CONTEXT_ID into Bash command")
             }
             return
@@ -370,8 +411,53 @@ export default async ({ directory, platform: hostPlatform = process.platform })
             return
           }
 
-          // Resolve active task through session runtime context.
-          const taskDir = ctx.getCurrentTask(input)
+          // Resolve active task in this priority order (only later steps
+          // run when earlier ones miss):
+          //   1. Exact session runtime context lookup for input.sessionID
+          //   2. `Active task: <path>` hint in the dispatch prompt
+          //      (explicit per-dispatch override — beats single-session
+          //      inference so multi-window users can disambiguate)
+          //   3. Single-session fallback — only when exactly 1 session
+          //      runtime file exists locally
+          let taskDir = null
+          let taskSource = null
+
+          const contextKey = ctx.getContextKey(input)
+          if (contextKey) {
+            const context = ctx.readContext(contextKey)
+            const exactRef = ctx.normalizeTaskRef(context?.current_task || "")
+            if (exactRef) {
+              taskDir = exactRef
+              taskSource = `session:${contextKey}`
+            }
+          }
+
+          if (!taskDir) {
+            const hintRef = extractActiveTaskHint(originalPrompt)
+            if (hintRef) {
+              const hintNormalized = ctx.normalizeTaskRef(hintRef)
+              if (hintNormalized) {
+                const hintDir = ctx.resolveTaskDir(hintNormalized)
+                if (hintDir && existsSync(hintDir)) {
+                  taskDir = hintNormalized
+                  taskSource = "prompt-hint"
+                  debugLog("inject", "Resolved task from Active task: hint:", hintNormalized)
+                }
+              }
+            }
+          }
+
+          if (!taskDir) {
+            const fallback = ctx._resolveSingleSessionFallback()
+            if (fallback?.taskPath) {
+              const fallbackDir = ctx.resolveTaskDir(fallback.taskPath)
+              if (fallbackDir && existsSync(fallbackDir)) {
+                taskDir = fallback.taskPath
+                taskSource = fallback.source
+                debugLog("inject", "Resolved task via single-session fallback:", taskDir, "source:", taskSource)
+              }
+            }
+          }
 
           // Agents requiring task directory
           if (AGENTS_REQUIRE_TASK.includes(subagentType)) {
@@ -380,8 +466,8 @@ export default async ({ directory, platform: hostPlatform = process.platform })
               debugLog("inject", "Skipping - no current task")
               return
             }
-            const taskDirFull = join(directory, taskDir)
-            if (!existsSync(taskDirFull)) {
+            const taskDirFull = ctx.resolveTaskDir(taskDir)
+            if (!taskDirFull || !existsSync(taskDirFull)) {
               debugLog("inject", "Skipping - task directory not found")
               return
             }

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

@@ -25,7 +25,7 @@
 
 import { existsSync, readFileSync } from "fs"
 import { join } from "path"
-import { TrellisContext, debugLog } from "../lib/trellis-context.js"
+import { TrellisContext, debugLog, isTrellisSubagent } from "../lib/trellis-context.js"
 
 // Supports STATUS values with letters, digits, underscores, hyphens
 // (so "in-review" / "blocked-by-team" work alongside "in_progress").
@@ -108,6 +108,13 @@ export default async ({ directory }) => {
       // so it persists in conversation history.
       "chat.message": async (input, output) => {
         try {
+          // Skip Trellis sub-agent turns — the per-turn breadcrumb is for the
+          // main session only; sub-agent context comes from the parent's
+          // tool.execute.before injection.
+          if (isTrellisSubagent(input)) {
+            debugLog("workflow-state", "Skipping trellis subagent turn:", input?.agent)
+            return
+          }
           if (process.env.TRELLIS_HOOKS === "0" || process.env.TRELLIS_DISABLE_HOOKS === "1") {
             return
           }

package/dist/templates/opencode/plugins/session-start.js

@@ -6,7 +6,7 @@
  * Uses OpenCode's chat.message hook directly so the context persists in history.
  */
 
-import { TrellisContext, contextCollector, debugLog } from "../lib/trellis-context.js"
+import { TrellisContext, contextCollector, debugLog, isTrellisSubagent } from "../lib/trellis-context.js"
 import {
   buildSessionContext,
   hasPersistedInjectedContext,
@@ -43,6 +43,14 @@ export default async ({ directory, client }) => {
         const agent = input.agent || "unknown"
         debugLog("session", "chat.message called, sessionID:", sessionID, "agent:", agent)
 
+        // Skip Trellis sub-agent turns — sub-agent context is injected by
+        // `inject-subagent-context.js` on the parent's tool.execute.before;
+        // re-injecting the main-session SessionStart here would drown that.
+        if (isTrellisSubagent(input)) {
+          debugLog("session", "Skipping trellis subagent turn:", agent)
+          return
+        }
+
         if (process.env.TRELLIS_HOOKS === "0" || process.env.TRELLIS_DISABLE_HOOKS === "1") {
           debugLog("session", "Skipping - TRELLIS_HOOKS disabled")
           return

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

@@ -19,10 +19,11 @@ You are already the `trellis-check` sub-agent that the main session dispatched.
 ## Core Responsibilities
 
 1. Inspect the current git diff.
-2. Read and follow the spec and research files listed in the task's `check.jsonl`.
-3. Review all changed code against the task PRD and project specs.
-4. Fix issues directly when they are within scope.
-5. Run the relevant lint, typecheck, and focused tests available for the touched code.
+2. Read `prd.md`, `design.md` if present, and `implement.md` if present.
+3. Read and follow the spec and research files listed in the task's `check.jsonl`.
+4. Review all changed code against the task artifacts and project specs.
+5. Fix issues directly when they are within scope.
+6. Run the relevant lint, typecheck, and focused tests available for the touched code.
 
 ## Review Priorities
 

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

@@ -19,10 +19,11 @@ You are already the `trellis-implement` sub-agent that the main session dispatch
 ## Core Responsibilities
 
 1. Understand the active task requirements.
-2. Read and follow the spec and research files listed in the task's `implement.jsonl`.
-3. Implement the requested change using existing project patterns.
-4. Run the relevant lint, typecheck, and focused tests available for the touched code.
-5. Report files changed and verification results.
+2. Read `prd.md`, `design.md` if present, and `implement.md` if present.
+3. Read and follow the spec and research files listed in the task's `implement.jsonl`.
+4. Implement the requested change using existing project patterns.
+5. Run the relevant lint, typecheck, and focused tests available for the touched code.
+6. Report files changed and verification results.
 
 ## Forbidden Operations