@mindfoldhq/trellis 0.5.0-beta.14 → 0.5.0-beta.16

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

@@ -255,6 +255,46 @@ ${originalPrompt}
   return templates[agentType] || originalPrompt
 }
 
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, "'\\''")}'`
+}
+
+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)
+  )
+}
+
+/**
+ * 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) {
+  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] = `export TRELLIS_CONTEXT_ID=${shellQuote(contextKey)}; ${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)`);
@@ -270,6 +310,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)) {
+              debugLog("inject", "Injected TRELLIS_CONTEXT_ID into Bash command")
+            }
+            return
+          }
+
           if (toolName !== "task") {
             return
           }
@@ -277,21 +324,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

@@ -17,7 +17,7 @@
  *
  * 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
  */
 
@@ -32,25 +32,32 @@ const TAG_RE = /\[workflow-state:([A-Za-z0-9_-]+)\]\s*\n([\s\S]*?)\n\s*\[\/workf
 // 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
+// `no_task` is a pseudo-status emitted when no session active task exists — keeps
 // the Next-Action reminder flowing per-turn even without an active task.
 const FALLBACK_BREADCRUMBS = {
   no_task:
     "No active task.\n" +
-    "Trigger words in the user message that REQUIRE creating a task " +
-    "(non-negotiable, do NOT self-exempt): 重构 / 抽成 / 独立 / 分发 / " +
-    "拆出来 / 搞一个 / 做成 / 接入 / 集成 / refactor / rewrite / extract / " +
-    "productize / publish / build X / design Y.\n" +
-    "Task is NOT required ONLY if ALL three hold: (a) zero file writes " +
-    "this turn, (b) answer fits in one reply with no multi-round plan, " +
-    "(c) no research beyond reading 1-2 repo files.\n" +
-    "When in doubt: create task. Over-tasking is cheap; under-tasking " +
-    "leaks plans and research into main context.\n" +
+    "Trigger words in the user message that suggest creating a task: " +
+    "重构 / 抽成 / 独立 / 分发 / 拆出来 / 搞一个 / 做成 / 接入 / 集成 / " +
+    "refactor / rewrite / extract / productize / publish / build X / design Y.\n" +
+    "Task is NOT required if ALL three hold: (a) zero file writes this turn, " +
+    "(b) answer fits in one reply with no multi-round plan, (c) no research " +
+    "beyond reading 1-2 repo files.\n" +
+    "When in doubt and no override below applies: prefer creating a task — " +
+    "over-tasking is cheap; under-tasking leaks plans and research into " +
+    "main context.\n" +
     "Flow: load `trellis-brainstorm` skill → it creates the task via " +
     "`python3 ./.trellis/scripts/task.py create` and drives requirements Q&A. " +
     "For research-heavy work (tool comparison, docs, cross-platform survey), " +
     "spawn `trellis-research` sub-agents via Task tool — NEVER do 3+ inline " +
-    "WebFetch/WebSearch/`gh api` calls in the main conversation.",
+    "WebFetch/WebSearch/`gh api` calls in the main conversation.\n" +
+    "User override (per-turn escape hatch): if the user's CURRENT message " +
+    "contains an explicit opt-out phrase (\"跳过 trellis\" / \"别走流程\" / " +
+    "\"小修一下\" / \"直接改\" / \"先别建任务\" / \"skip trellis\" / " +
+    "\"no task\" / \"just do it\" / \"don't create a task\"), honor it for " +
+    "this turn — briefly acknowledge (\"好，本轮跳过 trellis 流程\") and " +
+    "proceed without creating a task. Per-turn only; does not carry forward; " +
+    "do NOT invent an override the user did not say.",
   planning:
     "Complete prd.md via trellis-brainstorm skill; then run task.py start.\n" +
     "Research belongs in `{task_dir}/research/*.md`, written by " +
@@ -60,9 +67,19 @@ const FALLBACK_BREADCRUMBS = {
     "Flow: trellis-implement → trellis-check → trellis-update-spec → finish\n" +
     "Next required action: inspect conversation history + git status, then " +
     "execute the next uncompleted step in that sequence.\n" +
-    "For agent-capable platforms, do NOT edit code in the main session; " +
-    "dispatch `trellis-implement` for implementation and dispatch " +
-    "`trellis-check` before reporting completion.",
+    "For agent-capable platforms, the default is to dispatch " +
+    "`trellis-implement` for implementation and `trellis-check` before " +
+    "reporting completion — do not edit code in the main session by default.\n" +
+    "Use the exact Trellis agent type names when spawning sub-agents: " +
+    "`trellis-implement`, `trellis-check`, or `trellis-research`. " +
+    "Generic/default/generalPurpose sub-agents do not receive " +
+    "`implement.jsonl` / `check.jsonl` injection.\n" +
+    "User override (per-turn escape hatch): if the user's CURRENT message " +
+    "explicitly tells the main session to handle it directly (\"你直接改\" / " +
+    "\"别派 sub-agent\" / \"main session 写就行\" / \"do it inline\" / " +
+    "\"不用 sub-agent\"), honor it for this turn and edit code directly. " +
+    "Per-turn only; does not carry forward; do NOT invent an override the " +
+    "user did not say.",
   completed:
     "User commits changes; then run task.py archive.",
 }
@@ -92,11 +109,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 {
@@ -104,7 +124,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
   }
@@ -116,12 +136,15 @@ function getActiveTask(ctx) {
  * - Unknown status → generic "refer to workflow.md"
  * - 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>`
 }
 
@@ -142,9 +165,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 || []
@@ -160,9 +183,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(

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

@@ -52,16 +52,17 @@ function hasCuratedJsonlEntry(jsonlPath) {
  * Check current task status and return structured status string.
  * JavaScript equivalent of _get_task_status in Claude's session-start.py.
  */
-function getTaskStatus(ctx) {
-  const taskRef = ctx.getCurrentTask()
+function getTaskStatus(ctx, platformInput = null) {
+  const active = ctx.getActiveTask(platformInput)
+  const taskRef = active.taskPath
   if (!taskRef) {
-    return "Status: NO ACTIVE TASK\nNext: Describe what you want to work on"
+    return `Status: NO ACTIVE TASK\nSource: ${active.source}\nNext: Describe what you want to work on`
   }
 
   const taskDir = ctx.resolveTaskDir(taskRef)
 
-  if (!taskDir || !existsSync(taskDir)) {
-    return `Status: STALE POINTER\nTask: ${taskRef}\nNext: Task directory not found. Run: python3 ./.trellis/scripts/task.py finish`
+  if (active.stale || !taskDir || !existsSync(taskDir)) {
+    return `Status: STALE POINTER\nTask: ${taskRef}\nSource: ${active.source}\nNext: Task directory not found. Run: python3 ./.trellis/scripts/task.py finish`
   }
 
   let taskData = {}
@@ -79,7 +80,7 @@ function getTaskStatus(ctx) {
 
   if (taskStatus === "completed") {
     const dirName = basename(taskDir)
-    return `Status: COMPLETED\nTask: ${taskTitle}\nNext: Archive with \`python3 ./.trellis/scripts/task.py archive ${dirName}\` or start a new task`
+    return `Status: COMPLETED\nTask: ${taskTitle}\nSource: ${active.source}\nNext: Archive with \`python3 ./.trellis/scripts/task.py archive ${dirName}\` or start a new task`
   }
 
   let hasContext = false
@@ -94,18 +95,23 @@ function getTaskStatus(ctx) {
   const hasPrd = existsSync(join(taskDir, "prd.md"))
 
   if (!hasPrd) {
-    return `Status: NOT READY\nTask: ${taskTitle}\nMissing: prd.md not created\nNext: Write PRD (see workflow.md Phase 1.1) then curate implement.jsonl per Phase 1.3`
+    return `Status: NOT READY\nTask: ${taskTitle}\nSource: ${active.source}\nMissing: prd.md not created\nNext: Write PRD (see workflow.md Phase 1.1) then curate implement.jsonl per Phase 1.3`
   }
 
   if (!hasContext) {
-    return `Status: NOT READY\nTask: ${taskTitle}\nMissing: implement.jsonl / check.jsonl missing or empty\nNext: Curate entries per workflow.md Phase 1.3 (spec + research files only), then \`task.py start\``
+    return `Status: NOT READY\nTask: ${taskTitle}\nSource: ${active.source}\nMissing: implement.jsonl / check.jsonl missing or empty\nNext: Curate entries per workflow.md Phase 1.3 (spec + research files only), then \`task.py start\``
   }
 
   return (
     `Status: READY\nTask: ${taskTitle}\n` +
+    `Source: ${active.source}\n` +
     "Next required action: dispatch `trellis-implement` per Phase 2.1. " +
-    "For agent-capable platforms, do NOT edit code in the main session. " +
-    "After implementation, dispatch `trellis-check` per Phase 2.2 before reporting completion."
+    "For agent-capable platforms, the default is to NOT edit code in the main session. " +
+    "After implementation, dispatch `trellis-check` per Phase 2.2 before reporting completion.\n" +
+    "User override (per-turn escape hatch): if the user's CURRENT message explicitly tells the " +
+    "main session to handle it directly (\"你直接改\" / \"别派 sub-agent\" / \"main session 写就行\" / " +
+    "\"do it inline\" / \"不用 sub-agent\"), honor it for this turn and edit code directly. " +
+    "Per-turn only; do NOT invent an override the user did not say."
   )
 }
 
@@ -113,7 +119,7 @@ function getTaskStatus(ctx) {
  * Load Trellis config for session-start decisions.
  * Calls get_context.py --mode packages --json for reliable config data.
  */
-function loadTrellisConfig(directory) {
+function loadTrellisConfig(directory, contextKey = null) {
   const scriptPath = join(directory, ".trellis", "scripts", "get_context.py")
   if (!existsSync(scriptPath)) {
     return { isMonorepo: false, packages: {}, specScope: null, activeTaskPackage: null, defaultPackage: null }
@@ -124,6 +130,10 @@ function loadTrellisConfig(directory) {
       timeout: 5000,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"],
+      env: {
+        ...process.env,
+        ...(contextKey ? { TRELLIS_CONTEXT_ID: contextKey } : {}),
+      },
     })
     const data = JSON.parse(output)
     if (data.mode !== "monorepo") {
@@ -226,11 +236,14 @@ function resolveSpecScope(config) {
 /**
  * Build session context for injection
  */
-export function buildSessionContext(ctx) {
+export function buildSessionContext(ctx, platformInput = null) {
   const directory = ctx.directory
   const trellisDir = join(directory, ".trellis")
+  const contextKey = typeof ctx.getContextKey === "function"
+    ? ctx.getContextKey(platformInput)
+    : null
 
-  const config = loadTrellisConfig(directory)
+  const config = loadTrellisConfig(directory, contextKey)
   const allowedPkgs = resolveSpecScope(config)
 
   const parts = []
@@ -251,7 +264,7 @@ Read and follow all instructions below carefully.
   // 2. Current Context (dynamic)
   const contextScript = join(trellisDir, "scripts", "get_context.py")
   if (existsSync(contextScript)) {
-    const output = ctx.runScript(contextScript)
+    const output = ctx.runScript(contextScript, undefined, contextKey)
     if (output) {
       parts.push("<current-state>")
       parts.push(output)
@@ -385,7 +398,7 @@ Read and follow all instructions below carefully.
   parts.push("</guidelines>")
 
   // 6. Task status
-  const taskStatus = getTaskStatus(ctx)
+  const taskStatus = getTaskStatus(ctx, platformInput)
   parts.push(`<task-status>\n${taskStatus}\n</task-status>`)
 
   // 7. Final directive
@@ -514,7 +527,7 @@ export default async ({ directory, client }) => {
           }
 
           // Build context
-          const context = buildSessionContext(ctx)
+          const context = buildSessionContext(ctx, input)
           debugLog("session", "Built context, length:", context.length)
 
           // Inject context directly into output.parts so it gets persisted by updatePart

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

@@ -0,0 +1,28 @@
+---
+name: trellis-check
+description: |
+  Code quality check expert. Reviews changes against Trellis specs, fixes issues directly, and verifies quality gates.
+tools: Read, Write, Edit, Bash, Glob, Grep
+---
+# Check Agent
+
+You are the Check Agent in the Trellis workflow.
+
+## 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.
+
+## Review Priorities
+
+- Behavioral regressions and missing requirements.
+- Spec or platform contract violations.
+- Missing or weak tests for logic changes.
+- Cross-platform path, command, and encoding assumptions.
+
+## Output
+
+Report findings fixed, files changed, and verification results. If no issues remain, say that clearly.

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

@@ -0,0 +1,33 @@
+---
+name: trellis-implement
+description: |
+  Code implementation expert. Understands Trellis specs and requirements, then implements features. No git commit allowed.
+tools: Read, Write, Edit, Bash, Glob, Grep
+---
+# Implement Agent
+
+You are the Implement Agent in the Trellis workflow.
+
+## 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.
+
+## Forbidden Operations
+
+Do not run:
+
+- `git commit`
+- `git push`
+- `git merge`
+
+## Working Rules
+
+- Read adjacent code and tests before editing.
+- Keep changes scoped to the task.
+- Do not revert unrelated user or concurrent changes.
+- Fix root causes rather than masking symptoms.
+- Prefer existing local helpers and platform patterns over new abstractions.

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

@@ -0,0 +1,25 @@
+---
+name: trellis-research
+description: |
+  Code and technical research expert. Finds relevant files, patterns, docs, and persists findings to the current task's research/ directory.
+tools: Read, Write, Bash, Glob, Grep
+---
+# Research Agent
+
+You are the Research Agent in the Trellis workflow.
+
+## Core Principle
+
+Persist every finding to a file. Chat context is temporary; files under the task directory survive compaction and handoff.
+
+## Core Responsibilities
+
+1. Resolve the active task with `python3 ./.trellis/scripts/task.py current --source`.
+2. Create `<task-dir>/research/` when it does not exist.
+3. Search internal code, specs, and relevant external documentation.
+4. Write each distinct topic to `<task-dir>/research/<topic-slug>.md`.
+5. Report only file paths and concise summaries to the caller.
+
+## Scope Limits
+
+Write only under the current task's `research/` directory. Do not edit code, specs, platform config, or task files outside research artifacts.