@mindfoldhq/trellis 0.4.0-beta.9 → 0.4.0-rc.0

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

@@ -3,11 +3,7 @@
  * Trellis Session Start Plugin
  *
  * Injects context when user sends the first message in a session.
- * Uses OpenCode's chat.message + experimental.chat.messages.transform hooks.
- *
- * Compatibility:
- * - If oh-my-opencode handles via .claude/hooks/, this plugin skips
- * - Otherwise, this plugin handles injection
+ * Uses OpenCode's chat.message hook directly so the context persists in history.
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from "fs"
@@ -29,14 +25,12 @@ function getTaskStatus(ctx) {
     return "Status: NO ACTIVE TASK\nNext: Describe what you want to work on"
   }
 
-  // Resolve task directory
   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`
   }
 
-  // Read task.json
   let taskData = {}
   const taskJsonPath = join(taskDir, "task.json")
   if (existsSync(taskJsonPath)) {
@@ -55,7 +49,6 @@ function getTaskStatus(ctx) {
     return `Status: COMPLETED\nTask: ${taskTitle}\nNext: Archive with \`python3 ./.trellis/scripts/task.py archive ${dirName}\` or start a new task`
   }
 
-  // Check if context is configured (jsonl files exist and non-empty)
   let hasContext = false
   for (const jsonlName of ["implement.jsonl", "check.jsonl", "spec.jsonl"]) {
     const jsonlPath = join(taskDir, jsonlName)
@@ -105,7 +98,6 @@ function loadTrellisConfig(directory) {
     if (data.mode !== "monorepo") {
       return { isMonorepo: false, packages: {}, specScope: null, activeTaskPackage: null, defaultPackage: null }
     }
-    // Convert packages array to dict keyed by name
     const pkgDict = {}
     for (const pkg of (data.packages || [])) {
       pkgDict[pkg.name] = pkg
@@ -135,7 +127,6 @@ function checkLegacySpec(directory, config) {
   const specDir = join(directory, ".trellis", "spec")
   if (!existsSync(specDir)) return null
 
-  // Check for legacy flat spec dirs
   let hasLegacy = false
   for (const name of ["backend", "frontend"]) {
     if (existsSync(join(specDir, name, "index.md"))) {
@@ -145,7 +136,6 @@ function checkLegacySpec(directory, config) {
   }
   if (!hasLegacy) return null
 
-  // Check which packages are missing spec/<pkg>/ directory
   const pkgNames = Object.keys(config.packages).sort()
   const missing = pkgNames.filter(name => !existsSync(join(specDir, name)))
 
@@ -193,7 +183,6 @@ function resolveSpecScope(config) {
       }
     }
     if (valid.size > 0) return valid
-    // All invalid: fallback
     if (activeTaskPackage && activeTaskPackage in packages) return new Set([activeTaskPackage])
     if (defaultPackage && defaultPackage in packages) return new Set([defaultPackage])
     return null
@@ -209,10 +198,7 @@ function resolveSpecScope(config) {
 function buildSessionContext(ctx) {
   const directory = ctx.directory
   const trellisDir = join(directory, ".trellis")
-  const claudeDir = join(directory, ".claude")
-  const opencodeDir = join(directory, ".opencode")
 
-  // Load config for scope filtering and legacy detection
   const config = loadTrellisConfig(directory)
   const allowedPkgs = resolveSpecScope(config)
 
@@ -241,11 +227,20 @@ Read and follow all instructions below carefully.
     }
   }
 
-  // 3. Workflow Guide
-  const workflow = ctx.readProjectFile(".trellis/workflow.md")
-  if (workflow) {
+  // 3. Workflow Guide (ToC only — lazy-load the full file on demand)
+  const workflowContent = ctx.readProjectFile(".trellis/workflow.md")
+  if (workflowContent) {
+    const tocLines = [
+      "# Development Workflow — Section Index",
+      "Full guide: .trellis/workflow.md  (read on demand)",
+      "",
+    ]
+    for (const line of workflowContent.split("\n")) {
+      if (line.startsWith("## ")) tocLines.push(line)
+    }
+    tocLines.push("", "To read a section: use the Read tool on .trellis/workflow.md")
     parts.push("<workflow>")
-    parts.push(workflow)
+    parts.push(tocLines.join("\n"))
     parts.push("</workflow>")
   }
 
@@ -267,7 +262,6 @@ Read and follow all instructions below carefully.
       }).sort()
 
       for (const sub of subs) {
-        // Always include guides/ regardless of scope
         if (sub === "guides") {
           const indexFile = join(specDir, sub, "index.md")
           if (existsSync(indexFile)) {
@@ -281,14 +275,11 @@ Read and follow all instructions below carefully.
 
         const indexFile = join(specDir, sub, "index.md")
         if (existsSync(indexFile)) {
-          // Flat spec dir: spec/<layer>/index.md (single-repo)
           const content = ctx.readFile(indexFile)
           if (content) {
             parts.push(`## ${sub}\n${content}\n`)
           }
         } else {
-          // Nested package dirs (monorepo): spec/<pkg>/<layer>/index.md
-          // Apply scope filter
           if (allowedPkgs !== null && !allowedPkgs.has(sub)) {
             continue
           }
@@ -322,131 +313,164 @@ Read and follow all instructions below carefully.
 
   parts.push("</guidelines>")
 
-  // 5. Session Instructions - try both .claude and .opencode
-  let startMd = ctx.readFile(join(claudeDir, "commands", "trellis", "start.md"))
-  if (!startMd) {
-    startMd = ctx.readFile(join(opencodeDir, "commands", "trellis", "start.md"))
-  }
-  if (startMd) {
-    parts.push("<instructions>")
-    parts.push(startMd)
-    parts.push("</instructions>")
-  }
-
-  // 6. Task status (R2: check task state for session resume)
+  // 6. Task status
   const taskStatus = getTaskStatus(ctx)
   parts.push(`<task-status>\n${taskStatus}\n</task-status>`)
 
-  // 7. Final directive (R3: active, not passive)
+  // 7. Final directive
   parts.push(`<ready>
-Context loaded. Steps 1-3 (workflow, context, guidelines) are already injected above — do NOT re-read them.
-Start from Step 4. Wait for user's first message, then follow <instructions> to handle their request.
+Context loaded. Workflow index, project state, and guidelines are already injected above — do NOT re-read them.
+Wait for the user's first message, then handle it following the workflow guide.
 If there is an active task, ask whether to continue it.
 </ready>`)
 
   return parts.join("\n\n")
 }
 
-export default async ({ directory }) => {
-  const ctx = new TrellisContext(directory)
-  debugLog("session", "Plugin loaded, directory:", directory)
+function getTrellisMetadata(metadata) {
+  if (!metadata || typeof metadata !== "object") {
+    return {}
+  }
 
-  return {
-    // chat.message - triggered when user sends a message
-    "chat.message": async (input) => {
-      try {
-        const sessionID = input.sessionID
-        const agent = input.agent || "unknown"
-        debugLog("session", "chat.message called, sessionID:", sessionID, "agent:", agent)
-
-        // Skip in non-interactive mode
-        if (process.env.OPENCODE_NON_INTERACTIVE === "1") {
-          debugLog("session", "Skipping - non-interactive mode")
-          return
-        }
+  const trellis = metadata.trellis
+  if (!trellis || typeof trellis !== "object") {
+    return {}
+  }
 
-        // Check if we should skip (omo will handle)
-        if (ctx.shouldSkipHook("session-start")) {
-          debugLog("session", "Skipping - omo will handle via .claude/hooks/")
-          return
-        }
+  return trellis
+}
 
-        // Only inject on first message
-        if (contextCollector.isProcessed(sessionID)) {
-          debugLog("session", "Skipping - session already processed")
-          return
-        }
+function markPartAsSessionStart(part) {
+  const metadata = part.metadata && typeof part.metadata === "object"
+    ? part.metadata
+    : {}
+  part.metadata = {
+    ...metadata,
+    trellis: {
+      ...getTrellisMetadata(metadata),
+      sessionStart: true,
+    },
+  }
+}
 
-        // Mark session as processed
-        contextCollector.markProcessed(sessionID)
+function hasSessionStartMarker(part) {
+  if (!part || part.type !== "text" || typeof part.text !== "string") {
+    return false
+  }
 
-        // Build and store context
-        const context = buildSessionContext(ctx)
-        debugLog("session", "Built context, length:", context.length)
+  return getTrellisMetadata(part.metadata).sessionStart === true
+}
 
-        contextCollector.store(sessionID, context)
-        debugLog("session", "Context stored for session:", sessionID)
+export function hasInjectedTrellisContext(messages) {
+  if (!Array.isArray(messages)) {
+    return false
+  }
 
-      } catch (error) {
-        debugLog("session", "Error in chat.message:", error.message, error.stack)
-      }
-    },
+  return messages.some(message => {
+    if (!message?.info || message.info.role !== "user" || !Array.isArray(message.parts)) {
+      return false
+    }
 
-    // experimental.chat.messages.transform - modify messages before sending to AI
-    "experimental.chat.messages.transform": async (input, output) => {
-      try {
-        const { messages } = output
-        debugLog("session", "messages.transform called, messageCount:", messages?.length)
+    return message.parts.some(hasSessionStartMarker)
+  })
+}
 
-        if (!messages || messages.length === 0) {
-          return
-        }
+async function hasPersistedInjectedContext(client, directory, sessionID) {
+  try {
+    const response = await client.session.messages({
+      path: { id: sessionID },
+      query: { directory },
+      throwOnError: true,
+    })
+    return hasInjectedTrellisContext(response.data || [])
+  } catch (error) {
+    debugLog(
+      "session",
+      "Failed to read session history for dedupe:",
+      error instanceof Error ? error.message : String(error),
+    )
+    return false
+  }
+}
 
-        // Find last user message
-        let lastUserMessageIndex = -1
-        for (let i = messages.length - 1; i >= 0; i--) {
-          if (messages[i].info?.role === "user") {
-            lastUserMessageIndex = i
-            break
-          }
-        }
+export default {
+  id: "trellis.session-start",
+  server: async ({ directory, client }) => {
+    const ctx = new TrellisContext(directory)
+    debugLog("session", "Plugin loaded, directory:", directory)
 
-        if (lastUserMessageIndex === -1) {
-          debugLog("session", "No user message found")
-          return
+    return {
+      // Clear in-memory dedupe after compaction so context can be re-injected.
+      event: ({ event }) => {
+        try {
+          if (event?.type === "session.compacted" && event?.properties?.sessionID) {
+            const sessionID = event.properties.sessionID
+            contextCollector.clear(sessionID)
+            debugLog("session", "Cleared processed flag after compaction for session:", sessionID)
+          }
+        } catch (error) {
+          debugLog(
+            "session",
+            "Error in event hook:",
+            error instanceof Error ? error.message : String(error),
+          )
         }
+      },
 
-        const lastUserMessage = messages[lastUserMessageIndex]
-        const sessionID = lastUserMessage.info?.sessionID
+      // chat.message - triggered when user sends a message.
+      // Modify the message in-place so the context is persisted with updateMessage/updatePart.
+      "chat.message": async (input, output) => {
+        try {
+          const sessionID = input.sessionID
+          const agent = input.agent || "unknown"
+          debugLog("session", "chat.message called, sessionID:", sessionID, "agent:", agent)
+
+          // Skip in non-interactive mode
+          if (process.env.OPENCODE_NON_INTERACTIVE === "1") {
+            debugLog("session", "Skipping - non-interactive mode")
+            return
+          }
 
-        debugLog("session", "Found user message, sessionID:", sessionID)
+          // Only inject on first message
+          if (contextCollector.isProcessed(sessionID)) {
+            debugLog("session", "Skipping - session already processed")
+            return
+          }
 
-        if (!sessionID || !contextCollector.hasPending(sessionID)) {
-          debugLog("session", "No pending context for session")
-          return
-        }
+          if (await hasPersistedInjectedContext(client, ctx.directory, sessionID)) {
+            contextCollector.markProcessed(sessionID)
+            debugLog("session", "Skipping - session already contains persisted Trellis context")
+            return
+          }
 
-        // Get and consume pending context
-        const pending = contextCollector.consume(sessionID)
+          // Build context
+          const context = buildSessionContext(ctx)
+          debugLog("session", "Built context, length:", context.length)
+
+          // Inject context directly into output.parts so it gets persisted by updatePart
+          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 = `${context}\n\n---\n\n${originalText}`
+            markPartAsSessionStart(parts[textPartIndex])
+            debugLog("session", "Injected context into chat.message text part, length:", context.length)
+          } else {
+            // No existing text part: prepend a new one
+            const injectedPart = { type: "text", text: context }
+            markPartAsSessionStart(injectedPart)
+            parts.unshift(injectedPart)
+            debugLog("session", "Prepended new text part with context, length:", context.length)
+          }
 
-        // Find first text part
-        const textPartIndex = lastUserMessage.parts?.findIndex(
-          p => p.type === "text" && p.text !== undefined
-        )
+          contextCollector.markProcessed(sessionID)
 
-        if (textPartIndex === -1) {
-          debugLog("session", "No text part found in user message")
-          return
+        } catch (error) {
+          debugLog("session", "Error in chat.message:", error.message, error.stack)
         }
-
-        // Prepend context to the text part (same approach as omo)
-        const originalText = lastUserMessage.parts[textPartIndex].text || ""
-        lastUserMessage.parts[textPartIndex].text = `${pending.content}\n\n---\n\n${originalText}`
-
-        debugLog("session", "Injected context by prepending to text, length:", pending.content.length)
-
-      } catch (error) {
-        debugLog("session", "Error in messages.transform:", error.message, error.stack)
       }
     }
   }

package/dist/templates/trellis/workflow.md

@@ -196,21 +196,30 @@ python3 ./.trellis/scripts/task.py create "<title>" --slug <task-name>
 1. Create or select task
    --> python3 ./.trellis/scripts/task.py create "<title>" --slug <name> or list
 
-2. Write code according to guidelines
+2. Start task (mark as current)
+   --> python3 ./.trellis/scripts/task.py start <name>
+   --> Writes .trellis/.current-task; future sessions see it in <current-state>
+
+3. Write code according to guidelines
    --> Read .trellis/spec/ docs relevant to your task
    --> For cross-layer: read .trellis/spec/guides/
 
-3. Self-test
+4. Self-test
    --> Run project's lint/test commands (see spec docs)
    --> Manual feature testing
 
-4. Commit code
+5. Commit code
    --> git add <files>
    --> git commit -m "type(scope): description"
        Format: feat/fix/docs/refactor/test/chore
 
-5. Record session (one command)
+6. Record session (one command)
    --> python3 ./.trellis/scripts/add_session.py --title "Title" --commit "hash"
+
+7. Finish task (clear current)
+   --> python3 ./.trellis/scripts/task.py finish
+   --> Only when the task is fully done; otherwise leave it set so the
+       next session resumes where you left off
 ```
 
 ### Code Quality Checklist
@@ -315,11 +324,15 @@ tasks/
 **Commands**:
 ```bash
 python3 ./.trellis/scripts/task.py create "<title>" [--slug <name>]   # Create task directory
+python3 ./.trellis/scripts/task.py start <name>    # Set as current task (writes .current-task, triggers after_start hooks)
+python3 ./.trellis/scripts/task.py finish          # Clear current task (triggers after_finish hooks)
 python3 ./.trellis/scripts/task.py archive <name>  # Archive to archive/{year-month}/
 python3 ./.trellis/scripts/task.py list            # List active tasks
 python3 ./.trellis/scripts/task.py list-archive    # List archived tasks
 ```
 
+**Current task mechanism**: `task.py start <name>` writes the selected task path to `.trellis/.current-task`. The SessionStart hook reads this file to inject `## CURRENT TASK` into every new session's context, so the AI immediately knows what you're working on without being told. Run `task.py finish` when you're done — subsequent sessions will show `(none)` until you start another task.
+
 ---
 
 ## Best Practices

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindfoldhq/trellis",
-  "version": "0.4.0-beta.9",
+  "version": "0.4.0-rc.0",
   "description": "AI capabilities grow like ivy — Trellis provides the structure to guide them along a disciplined path",
   "type": "module",
   "main": "./dist/index.js",