@mindfoldhq/trellis 0.4.0 → 0.5.0-beta.1

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

@@ -22,7 +22,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`)
-2. Read `{task_dir}/check.jsonl` (or `spec.jsonl` as fallback)
+2. Read `{task_dir}/check.jsonl`
 3. For each entry in JSONL:
    - If `path` is a file → Read it
    - If `path` is a directory → Read all `.md` files in it
@@ -89,32 +89,6 @@ If failed, fix issues and re-run.
 
 ---
 
-## Completion Markers (Ralph Loop)
-
-**CRITICAL**: You are in a loop controlled by the Ralph Loop system.
-The loop will NOT stop until you output ALL required completion markers.
-
-Completion markers are generated from `check.jsonl` in the task directory.
-Each entry's `reason` field becomes a marker: `{REASON}_FINISH`
-
-For example, if check.jsonl contains:
-```json
-{"file": "...", "reason": "TypeCheck"}
-{"file": "...", "reason": "Lint"}
-{"file": "...", "reason": "CodeReview"}
-```
-
-You MUST output these markers when each check passes:
-- `TYPECHECK_FINISH` - After typecheck passes
-- `LINT_FINISH` - After lint passes
-- `CODEREVIEW_FINISH` - After code review passes
-
-If check.jsonl doesn't exist or has no reasons, output: `ALL_CHECKS_FINISH`
-
-**The loop will block you from stopping until all markers are present in your output.**
-
----
-
 ## Report Format
 
 ```markdown
@@ -136,11 +110,10 @@ If check.jsonl doesn't exist or has no reasons, output: `ALL_CHECKS_FINISH`
 
 ### Verification Results
 
-- TypeCheck: Passed TYPECHECK_FINISH
-- Lint: Passed LINT_FINISH
+- TypeCheck: Passed
+- Lint: Passed
 
 ### Summary
 
 Checked X files, found Y issues, all fixed.
-ALL_CHECKS_FINISH
 ```

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

@@ -22,7 +22,7 @@ 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`)
-2. Read `{task_dir}/implement.jsonl` (or `spec.jsonl` as fallback)
+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

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

@@ -23,8 +23,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)
-2. Read `{task_dir}/research.jsonl` if exists
-3. For each entry in JSONL:
+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/plugins/inject-subagent-context.js

@@ -5,60 +5,13 @@
  * Uses OpenCode's tool.execute.before hook.
  */
 
-import { existsSync, writeFileSync, readdirSync } from "fs"
+import { existsSync, readdirSync } from "fs"
 import { join } from "path"
 import { TrellisContext, debugLog } from "../lib/trellis-context.js"
 
 // Supported subagent types
-const AGENTS_ALL = ["implement", "check", "debug", "research"]
-const AGENTS_REQUIRE_TASK = ["implement", "check", "debug"]
-// Agents that don't update phase (can be called at any time)
-const AGENTS_NO_PHASE_UPDATE = ["debug", "research"]
-
-/**
- * Update current_phase in task.json based on subagent_type
- */
-function updateCurrentPhase(ctx, taskDir, subagentType) {
-  if (AGENTS_NO_PHASE_UPDATE.includes(subagentType)) {
-    return
-  }
-
-  const taskJsonPath = join(ctx.directory, taskDir, "task.json")
-  const content = ctx.readFile(taskJsonPath)
-  if (!content) return
-
-  try {
-    const taskData = JSON.parse(content)
-    const currentPhase = taskData.current_phase || 0
-    const nextActions = taskData.next_action || []
-
-    const actionToAgent = {
-      "implement": "implement",
-      "check": "check",
-      "finish": "check"
-    }
-
-    let newPhase = null
-    for (const action of nextActions) {
-      const phaseNum = action.phase || 0
-      const actionName = action.action || ""
-      const expectedAgent = actionToAgent[actionName]
-
-      if (phaseNum > currentPhase && expectedAgent === subagentType) {
-        newPhase = phaseNum
-        break
-      }
-    }
-
-    if (newPhase !== null) {
-      taskData.current_phase = newPhase
-      writeFileSync(taskJsonPath, JSON.stringify(taskData, null, 2))
-      debugLog("inject", "Updated current_phase to:", newPhase)
-    }
-  } catch (e) {
-    debugLog("inject", "Error updating phase:", e.message)
-  }
-}
+const AGENTS_ALL = ["implement", "check", "research"]
+const AGENTS_REQUIRE_TASK = ["implement", "check"]
 
 /**
  * Get context for implement agent
@@ -66,14 +19,8 @@ function updateCurrentPhase(ctx, taskDir, subagentType) {
 function getImplementContext(ctx, taskDir) {
   const parts = []
 
-  let jsonlPath = join(ctx.directory, taskDir, "implement.jsonl")
-  let entries = ctx.readJsonlWithFiles(jsonlPath)
-
-  if (entries.length === 0) {
-    jsonlPath = join(ctx.directory, taskDir, "spec.jsonl")
-    entries = ctx.readJsonlWithFiles(jsonlPath)
-  }
-
+  const jsonlPath = join(ctx.directory, taskDir, "implement.jsonl")
+  const entries = ctx.readJsonlWithFiles(jsonlPath)
   if (entries.length > 0) {
     parts.push(ctx.buildContextFromEntries(entries))
   }
@@ -99,32 +46,13 @@ function getCheckContext(ctx, taskDir) {
 
   const jsonlPath = join(ctx.directory, taskDir, "check.jsonl")
   const entries = ctx.readJsonlWithFiles(jsonlPath)
-
   if (entries.length > 0) {
     parts.push(ctx.buildContextFromEntries(entries))
-  } else {
-    const checkFiles = [
-      [".opencode/commands/trellis/finish-work.md", "Finish work checklist"],
-      [".opencode/commands/trellis/check-cross-layer.md", "Cross-layer check spec"],
-      [".opencode/commands/trellis/check.md", "Check spec"],
-    ]
-    for (const [f, description] of checkFiles) {
-      const content = ctx.readProjectFile(f)
-      if (content) {
-        parts.push(`=== ${f} (${description}) ===\n${content}`)
-      }
-    }
-
-    const specJsonlPath = join(ctx.directory, taskDir, "spec.jsonl")
-    const specEntries = ctx.readJsonlWithFiles(specJsonlPath)
-    for (const entry of specEntries) {
-      parts.push(`=== ${entry.path} (Dev spec) ===\n${entry.content}`)
-    }
   }
 
   const prd = ctx.readProjectFile(join(taskDir, "prd.md"))
   if (prd) {
-    parts.push(`=== ${taskDir}/prd.md (Requirements - for understanding intent) ===\n${prd}`)
+    parts.push(`=== ${taskDir}/prd.md (Requirements) ===\n${prd}`)
   }
 
   return parts.join("\n\n")
@@ -134,75 +62,15 @@ function getCheckContext(ctx, taskDir) {
  * Get context for finish phase (final check before PR)
  */
 function getFinishContext(ctx, taskDir) {
-  const parts = []
-
-  const jsonlPath = join(ctx.directory, taskDir, "finish.jsonl")
-  const entries = ctx.readJsonlWithFiles(jsonlPath)
-
-  if (entries.length > 0) {
-    parts.push(ctx.buildContextFromEntries(entries))
-  } else {
-    const finishWork = ctx.readProjectFile(".opencode/commands/trellis/finish-work.md")
-    if (finishWork) {
-      parts.push(`=== .opencode/commands/trellis/finish-work.md (Finish checklist) ===\n${finishWork}`)
-    }
-  }
-
-  const updateSpec = ctx.readProjectFile(".opencode/commands/trellis/update-spec.md")
-  if (updateSpec) {
-    parts.push(`=== .opencode/commands/trellis/update-spec.md (Spec update process) ===\n${updateSpec}`)
-  }
-
-  const prd = ctx.readProjectFile(join(taskDir, "prd.md"))
-  if (prd) {
-    parts.push(`=== ${taskDir}/prd.md (Requirements - verify all met) ===\n${prd}`)
-  }
-
-  return parts.join("\n\n")
+  // Finish reuses check context (same JSONL source)
+  return getCheckContext(ctx, taskDir)
 }
 
-/**
- * Get context for debug agent
- */
-function getDebugContext(ctx, taskDir) {
-  const parts = []
-
-  const jsonlPath = join(ctx.directory, taskDir, "debug.jsonl")
-  const entries = ctx.readJsonlWithFiles(jsonlPath)
-
-  if (entries.length > 0) {
-    parts.push(ctx.buildContextFromEntries(entries))
-  } else {
-    const specJsonlPath = join(ctx.directory, taskDir, "spec.jsonl")
-    const specEntries = ctx.readJsonlWithFiles(specJsonlPath)
-    for (const entry of specEntries) {
-      parts.push(`=== ${entry.path} (Dev spec) ===\n${entry.content}`)
-    }
-
-    const checkFiles = [
-      [".opencode/commands/trellis/check.md", "Check spec"],
-      [".opencode/commands/trellis/check-cross-layer.md", "Cross-layer check spec"],
-    ]
-    for (const [f, description] of checkFiles) {
-      const content = ctx.readProjectFile(f)
-      if (content) {
-        parts.push(`=== ${f} (${description}) ===\n${content}`)
-      }
-    }
-  }
-
-  const codex = ctx.readProjectFile(join(taskDir, "codex-review-output.txt"))
-  if (codex) {
-    parts.push(`=== ${taskDir}/codex-review-output.txt (Codex Review Results) ===\n${codex}`)
-  }
-
-  return parts.join("\n\n")
-}
 
 /**
  * Get context for research agent
  */
-function getResearchContext(ctx, taskDir) {
+function getResearchContext(ctx) {
   const parts = []
 
   // Dynamic project structure (scan actual spec directory)
@@ -251,15 +119,6 @@ function getResearchContext(ctx, taskDir) {
 - Code search: Use Glob and Grep tools
 - Tech solutions: Use mcp__exa__web_search_exa or mcp__exa__get_code_context_exa`)
 
-  if (taskDir) {
-    const jsonlPath = join(ctx.directory, taskDir, "research.jsonl")
-    const researchEntries = ctx.readJsonlWithFiles(jsonlPath)
-    if (researchEntries.length > 0) {
-      parts.push("\n## Additional Search Context\n")
-      parts.push(ctx.buildContextFromEntries(researchEntries))
-    }
-  }
-
   return parts.join("\n\n")
 }
 
@@ -359,34 +218,6 @@ ${originalPrompt}
 - Fix issues yourself, don't just report
 - Must execute complete checklist`,
 
-    debug: `# Debug Agent Task
-
-You are the Debug Agent in the Multi-Agent Pipeline.
-
-## Your Context
-
-${context}
-
----
-
-## Your Task
-
-${originalPrompt}
-
----
-
-## Workflow
-
-1. **Understand issues** - Analyze issues pointed out
-2. **Locate code** - Find positions that need fixing
-3. **Fix against specs** - Fix following dev specs
-4. **Verify fixes** - Run typecheck
-
-## Important Constraints
-
-- Do NOT execute git commit
-- Run typecheck after each fix`,
-
     research: `# Research Agent Task
 
 You are the Research Agent in the Multi-Agent Pipeline.
@@ -467,8 +298,6 @@ export default {
               debugLog("inject", "Skipping - task directory not found")
               return
             }
-
-            updateCurrentPhase(ctx, taskDir, subagentType)
           }
 
           // Check for [finish] marker
@@ -485,9 +314,6 @@ export default {
                 ? getFinishContext(ctx, taskDir)
                 : getCheckContext(ctx, taskDir)
               break
-            case "debug":
-              context = getDebugContext(ctx, taskDir)
-              break
             case "research":
               context = getResearchContext(ctx, taskDir)
               break

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

@@ -0,0 +1,160 @@
+/* global process */
+/**
+ * Trellis Workflow State Injection Plugin
+ *
+ * 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.
+ *
+ * Unlike session-start, this plugin does NOT dedupe — 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)
+ *   - task.json malformed or missing status
+ */
+
+import { existsSync, readFileSync } from "fs"
+import { join } from "path"
+import { TrellisContext, debugLog } from "../lib/trellis-context.js"
+
+// Supports STATUS values with letters, digits, underscores, hyphens
+// (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.
+ */
+function loadBreadcrumbs(directory) {
+  const result = { ...FALLBACK_BREADCRUMBS }
+  const workflowPath = join(directory, ".trellis", "workflow.md")
+  if (!existsSync(workflowPath)) return result
+  let content
+  try {
+    content = readFileSync(workflowPath, "utf-8")
+  } catch {
+    return result
+  }
+  for (const match of content.matchAll(TAG_RE)) {
+    const status = match[1]
+    const body = match[2].trim()
+    if (body) result[status] = body
+  }
+  return result
+}
+
+/**
+ * Get (taskId, status) from active task, or null if no active task.
+ */
+function getActiveTask(ctx) {
+  const taskRef = ctx.getCurrentTask()
+  if (!taskRef) return null
+  const taskDir = ctx.resolveTaskDir(taskRef)
+  if (!taskDir || !existsSync(taskDir)) return null
+  const taskJsonPath = join(taskDir, "task.json")
+  if (!existsSync(taskJsonPath)) return null
+  try {
+    const data = JSON.parse(readFileSync(taskJsonPath, "utf-8"))
+    const status = typeof data.status === "string" ? data.status : ""
+    if (!status) return null
+    const id = data.id || taskRef.split("/").pop()
+    return { id, status }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Build the <workflow-state>...</workflow-state> block.
+ * - Known status (templates or fallback) → detailed body
+ * - Unknown status → generic "refer to workflow.md"
+ * - no_task pseudo-status (id === null) → header omits task info
+ */
+function buildBreadcrumb(id, status, templates) {
+  let body = templates[status]
+  if (body === undefined) {
+    body = "Refer to workflow.md for current step."
+  }
+  const header = id === null ? `Status: ${status}` : `Task: ${id} (${status})`
+  return `<workflow-state>\n${header}\n${body}\n</workflow-state>`
+}
+
+export default {
+  id: "trellis.inject-workflow-state",
+  server: async ({ directory }) => {
+    const ctx = new TrellisContext(directory)
+    debugLog("workflow-state", "Plugin loaded, directory:", directory)
+
+    return {
+      // chat.message fires on every user message. Inject breadcrumb in-place
+      // so it persists in conversation history.
+      "chat.message": async (input, output) => {
+        try {
+          if (process.env.OPENCODE_NON_INTERACTIVE === "1") {
+            return
+          }
+          if (!ctx.isTrellisProject()) {
+            return
+          }
+          const templates = loadBreadcrumbs(directory)
+          const task = getActiveTask(ctx)
+          const breadcrumb = task
+            ? buildBreadcrumb(task.id, task.status, templates)
+            : buildBreadcrumb(null, "no_task", templates)
+
+          const parts = output?.parts || []
+          const textPartIndex = parts.findIndex(
+            p => p.type === "text" && p.text !== undefined,
+          )
+          if (textPartIndex !== -1) {
+            const originalText = parts[textPartIndex].text || ""
+            parts[textPartIndex].text = `${breadcrumb}\n\n${originalText}`
+          } else {
+            parts.unshift({ type: "text", text: breadcrumb })
+          }
+          debugLog(
+            "workflow-state",
+            "Injected breadcrumb for task",
+            task.id,
+            "status",
+            task.status,
+          )
+        } catch (error) {
+          debugLog(
+            "workflow-state",
+            "Error in chat.message:",
+            error instanceof Error ? error.message : String(error),
+          )
+        }
+      },
+    }
+  },
+}

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

@@ -50,7 +50,7 @@ function getTaskStatus(ctx) {
   }
 
   let hasContext = false
-  for (const jsonlName of ["implement.jsonl", "check.jsonl", "spec.jsonl"]) {
+  for (const jsonlName of ["implement.jsonl", "check.jsonl"]) {
     const jsonlPath = join(taskDir, jsonlName)
     if (existsSync(jsonlPath)) {
       try {
@@ -227,29 +227,74 @@ Read and follow all instructions below carefully.
     }
   }
 
-  // 3. Workflow Guide (ToC only — lazy-load the full file on demand)
+  // 3. Workflow Guide — TOC + Phase Index + Phase 1/2/3 step details.
+  //    Meta sections (Core Principles / Trellis System / Breadcrumbs) are NOT
+  //    injected: Core Principles is short prose; Trellis System duplicates
+  //    commands in step bodies; Breadcrumbs are consumed by UserPromptSubmit hook.
   const workflowContent = ctx.readProjectFile(".trellis/workflow.md")
   if (workflowContent) {
-    const tocLines = [
+    const allLines = workflowContent.split("\n")
+    const overviewLines = [
       "# Development Workflow — Section Index",
       "Full guide: .trellis/workflow.md  (read on demand)",
       "",
+      "## Table of Contents",
     ]
-    for (const line of workflowContent.split("\n")) {
-      if (line.startsWith("## ")) tocLines.push(line)
+    for (const line of allLines) {
+      if (line.startsWith("## ")) overviewLines.push(line)
     }
-    tocLines.push("", "To read a section: use the Read tool on .trellis/workflow.md")
+    overviewLines.push("", "---", "")
+
+    // Extract range from "## Phase Index" up to (but excluding)
+    // "## Workflow State Breadcrumbs". Captures Phase Index + Phase 1/2/3.
+    let rangeStart = -1
+    let rangeEnd = allLines.length
+    for (let i = 0; i < allLines.length; i++) {
+      const stripped = allLines[i].trim()
+      if (rangeStart === -1 && stripped === "## Phase Index") {
+        rangeStart = i
+      } else if (rangeStart !== -1 && stripped === "## Workflow State Breadcrumbs") {
+        rangeEnd = i
+        break
+      }
+    }
+    if (rangeStart !== -1) {
+      overviewLines.push(...allLines.slice(rangeStart, rangeEnd))
+    }
+
     parts.push("<workflow>")
-    parts.push(tocLines.join("\n"))
+    parts.push(overviewLines.join("\n").trimEnd())
     parts.push("</workflow>")
   }
 
-  // 4. Guidelines Index (dynamic discovery, matching Claude's session-start.py)
+  // 4. Guidelines — paths-only for most indexes; guides/ inlined (cross-package,
+  //    broadly useful). Sub-agents get their specific specs via jsonl injection —
+  //    main agent reads paths on demand when editing code directly.
   parts.push("<guidelines>")
-  parts.push("**Note**: The guidelines below are index files — they list available guideline documents and their locations.")
-  parts.push("During actual development, you MUST read the specific guideline files listed in each index's Pre-Development Checklist.\n")
+  parts.push(
+    "Project spec indexes are listed by path below. Each index contains a " +
+    "**Pre-Development Checklist** listing the specific guideline files to " +
+    "read before coding.\n\n" +
+    "- If you're spawning an implement/check sub-agent, context is injected " +
+    "automatically via `{task}/implement.jsonl` / `check.jsonl`. You do NOT " +
+    "need to read these indexes yourself.\n" +
+    "- If you're editing code directly in the main session, Read the relevant " +
+    "index(es) on-demand and follow their Pre-Dev Checklist.\n"
+  )
 
   const specDir = join(directory, ".trellis", "spec")
+
+  // guides/ inlined
+  const guidesIndex = join(specDir, "guides", "index.md")
+  if (existsSync(guidesIndex)) {
+    const content = ctx.readFile(guidesIndex)
+    if (content) {
+      parts.push(`## guides (inlined — cross-package thinking guides)\n${content}\n`)
+    }
+  }
+
+  // Other indexes — paths only
+  const paths = []
   if (existsSync(specDir)) {
     try {
       const subs = readdirSync(specDir).filter(name => {
@@ -262,27 +307,13 @@ Read and follow all instructions below carefully.
       }).sort()
 
       for (const sub of subs) {
-        if (sub === "guides") {
-          const indexFile = join(specDir, sub, "index.md")
-          if (existsSync(indexFile)) {
-            const content = ctx.readFile(indexFile)
-            if (content) {
-              parts.push(`## ${sub}\n${content}\n`)
-            }
-          }
-          continue
-        }
+        if (sub === "guides") continue  // already inlined above
 
         const indexFile = join(specDir, sub, "index.md")
         if (existsSync(indexFile)) {
-          const content = ctx.readFile(indexFile)
-          if (content) {
-            parts.push(`## ${sub}\n${content}\n`)
-          }
+          paths.push(`.trellis/spec/${sub}/index.md`)
         } else {
-          if (allowedPkgs !== null && !allowedPkgs.has(sub)) {
-            continue
-          }
+          if (allowedPkgs !== null && !allowedPkgs.has(sub)) continue
           try {
             const nested = readdirSync(join(specDir, sub)).filter(name => {
               try {
@@ -291,14 +322,10 @@ Read and follow all instructions below carefully.
                 return false
               }
             }).sort()
-
             for (const layer of nested) {
               const nestedIndex = join(specDir, sub, layer, "index.md")
               if (existsSync(nestedIndex)) {
-                const content = ctx.readFile(nestedIndex)
-                if (content) {
-                  parts.push(`## ${sub}/${layer}\n${content}\n`)
-                }
+                paths.push(`.trellis/spec/${sub}/${layer}/index.md`)
               }
             }
           } catch {
@@ -311,6 +338,18 @@ Read and follow all instructions below carefully.
     }
   }
 
+  if (paths.length > 0) {
+    parts.push("## Available spec indexes (read on demand)")
+    for (const p of paths) {
+      parts.push(`- ${p}`)
+    }
+    parts.push("")
+  }
+
+  parts.push(
+    "Discover more via: " +
+    "`python3 ./.trellis/scripts/get_context.py --mode packages`"
+  )
   parts.push("</guidelines>")
 
   // 6. Task status