@pennixrv/trellis 0.6.17

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

@@ -0,0 +1,240 @@
+/* global process */
+/**
+ * Trellis Workflow State Injection Plugin
+ *
+ * Per-turn UserPromptSubmit equivalent for OpenCode.
+ *
+ * On every model request, inject a short <workflow-state> breadcrumb
+ * into the in-memory copy of the latest user message via
+ * `experimental.chat.messages.transform`. Stored history and the TUI
+ * are not modified (issue #553). Breadcrumb text is pulled exclusively
+ * from the project's workflow.md [workflow-state:STATUS] tag blocks —
+ * workflow.md is the single source of truth. There are no fallback
+ * tables in this plugin: when workflow.md is missing or a tag is
+ * absent, the breadcrumb degrades to a generic
+ * "Refer to workflow.md for current step." line so users see (and fix)
+ * the broken state instead of the plugin silently masking it.
+ *
+ * Silently skips when:
+ *   - No .trellis/ directory
+ *   - No active task in the session runtime context
+ *   - task.json malformed or missing status
+ */
+
+import { existsSync, readFileSync } from "fs"
+import { join } from "path"
+import {
+  MESSAGES_TRANSFORM_HOOK,
+  latestUserPromptText,
+  platformInputFromMessages,
+  prependEphemeralText,
+} from "../lib/context-visibility.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").
+const TAG_RE = /\[workflow-state:([A-Za-z0-9_-]+)\]\s*\n([\s\S]*?)\n\s*\[\/workflow-state:\1\]/g
+
+// Escape hatch for the per-turn breadcrumb (issue #427). Mirrors
+// `common.config.get_prompt_injection_config()` / the shared Python hook's
+// `_resolve_skip_keyword()` + `prompt_has_skip_keyword()`.
+const DEFAULT_PROMPT_INJECTION_SKIP_KEYWORD = "no-trellis"
+
+function stripInlineComment(value) {
+  let inQuote = null
+  for (let idx = 0; idx < value.length; idx++) {
+    const ch = value[idx]
+    if (inQuote) {
+      if (ch === inQuote) inQuote = null
+      continue
+    }
+    if (ch === '"' || ch === "'") {
+      inQuote = ch
+      continue
+    }
+    if (ch === "#" && (idx === 0 || /\s/.test(value[idx - 1]))) return value.slice(0, idx)
+  }
+  return value
+}
+
+function unquoteYaml(s) {
+  if (s.length >= 2 && s[0] === s[s.length - 1] && (s[0] === '"' || s[0] === "'")) return s.slice(1, -1)
+  return s
+}
+
+/**
+ * Line-based parser for ONLY the `prompt_injection:` block of
+ * `.trellis/config.yaml`. Not a general YAML parser — mirrors
+ * `common.config.get_prompt_injection_config()` semantics for this section
+ * only (missing key keeps the default; non-string value keeps the default).
+ */
+function readSkipKeyword(directory) {
+  const path = join(directory, ".trellis", "config.yaml")
+  if (!existsSync(path)) return DEFAULT_PROMPT_INJECTION_SKIP_KEYWORD
+  let text
+  try {
+    text = readFileSync(path, "utf-8")
+  } catch {
+    return DEFAULT_PROMPT_INJECTION_SKIP_KEYWORD
+  }
+
+  let inSection = false
+  let sectionIndent = -1
+  for (const rawLine of text.split(/\r?\n/)) {
+    const trimmed = rawLine.trim()
+    if (!inSection) {
+      if (/^prompt_injection\s*:\s*(#.*)?$/.test(trimmed)) {
+        inSection = true
+        sectionIndent = rawLine.length - rawLine.trimStart().length
+      }
+      continue
+    }
+    if (!trimmed || trimmed.startsWith("#")) continue
+    const indent = rawLine.length - rawLine.trimStart().length
+    if (indent <= sectionIndent) break
+    const m = trimmed.match(/^skip_keyword\s*:\s*(.*)$/)
+    if (!m) continue
+    return unquoteYaml(stripInlineComment(m[1]).trim())
+  }
+  return DEFAULT_PROMPT_INJECTION_SKIP_KEYWORD
+}
+
+/**
+ * Case-insensitive, word-boundary match of `keyword` in `text`. Hyphen
+ * counts as a word char so "no-trellisx" / "xno-trellis" don't match, but
+ * punctuation/whitespace boundaries do. Empty keyword never matches.
+ */
+function promptHasSkipKeyword(text, keyword) {
+  if (!keyword || typeof text !== "string") return false
+  const escaped = keyword.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+  const pattern = new RegExp(`(?<![\\w-])${escaped}(?![\\w-])`, "i")
+  return pattern.test(text)
+}
+
+/**
+ * Parse workflow.md for [workflow-state:STATUS] blocks.
+ *
+ * Returns {status: body}. workflow.md is the single source of truth —
+ * there are no fallback tables here. Missing tags (or a missing /
+ * unreadable workflow.md) fall back to a generic line in
+ * buildBreadcrumb so users see the broken state and fix workflow.md
+ * rather than the plugin silently masking it.
+ */
+function loadBreadcrumbs(directory) {
+  const workflowPath = join(directory, ".trellis", "workflow.md")
+  if (!existsSync(workflowPath)) return {}
+  let content
+  try {
+    content = readFileSync(workflowPath, "utf-8")
+  } catch {
+    return {}
+  }
+  const 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, platformInput = null) {
+  const active = ctx.getActiveTask(platformInput)
+  const taskRef = active.taskPath
+  if (!taskRef) return null
+  const taskDir = ctx.resolveTaskDir(taskRef)
+  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 {
+    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, source: active.source }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Build the <workflow-state>...</workflow-state> block.
+ * - Known status (tag present in workflow.md) → detailed body
+ * - Unknown status (no tag, or workflow.md missing) → generic
+ *   "Refer to workflow.md for current step." line
+ * - no_task pseudo-status (id === null) → header omits task info
+ */
+function buildBreadcrumb(id, status, templates) {
+  let body = templates[status]
+  if (body === undefined) {
+    body = "Refer to workflow.md for current step."
+  }
+  let header = id === null ? `Status: ${status}` : `Task: ${id} (${status})`
+  return `<workflow-state>\n${header}\n${body}\n</workflow-state>`
+}
+
+// OpenCode 1.2.x expects plugins to be factory functions (see inject-subagent-context.js comment).
+export default async ({ directory }) => {
+  const ctx = new TrellisContext(directory)
+  debugLog("workflow-state", "Plugin loaded, directory:", directory)
+
+  return {
+      [MESSAGES_TRANSFORM_HOOK]: async (_input, output) => {
+        try {
+          const messages = output?.messages
+          const platformInput = platformInputFromMessages(messages)
+          // 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(platformInput)) {
+            debugLog("workflow-state", "Skipping trellis subagent turn:", platformInput?.agent)
+            return
+          }
+          if (process.env.TRELLIS_HOOKS === "0" || process.env.TRELLIS_DISABLE_HOOKS === "1") {
+            return
+          }
+          if (process.env.OPENCODE_NON_INTERACTIVE === "1") {
+            return
+          }
+          if (!ctx.isTrellisProject()) {
+            return
+          }
+
+          const originalText = latestUserPromptText(messages)
+
+          // Escape hatch (issue #427): user prompt contains the skip keyword
+          // as a standalone word — emit nothing for this turn only.
+          if (promptHasSkipKeyword(originalText, readSkipKeyword(directory))) {
+            debugLog("workflow-state", "Skipping turn: skip keyword present in prompt")
+            return
+          }
+
+          const templates = loadBreadcrumbs(directory)
+          const task = getActiveTask(ctx, platformInput)
+          const breadcrumb = task
+            ? buildBreadcrumb(task.id, task.status, templates, task.source)
+            : buildBreadcrumb(null, "no_task", templates)
+
+          prependEphemeralText(messages, breadcrumb)
+          debugLog(
+            "workflow-state",
+            "Injected breadcrumb for task",
+            task ? task.id : "none",
+            "status",
+            task ? task.status : "no_task",
+          )
+        } catch (error) {
+          debugLog(
+            "workflow-state",
+            "Error in messages.transform:",
+            error instanceof Error ? error.message : String(error),
+          )
+        }
+      },
+  }
+}

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

@@ -0,0 +1,65 @@
+/* global process */
+/**
+ * Trellis Session Start Plugin
+ *
+ * Injects compact SessionStart context into the copy of the latest user
+ * message that OpenCode sends to the model. Uses
+ * `experimental.chat.messages.transform` so TUI / Web / SQLite history
+ * stay untouched (issue #553).
+ */
+
+import { TrellisContext, debugLog, isTrellisSubagent } from "../lib/trellis-context.js"
+import {
+  MESSAGES_TRANSFORM_HOOK,
+  platformInputFromMessages,
+  prependEphemeralText,
+  transcriptHasAssistantMessage,
+} from "../lib/context-visibility.js"
+import { buildSessionContext } from "../lib/session-utils.js"
+
+const FIRST_REPLY_NOTICE_RE = /<first-reply-notice>[\s\S]*?<\/first-reply-notice>\s*/g
+
+function stripFirstReplyNotice(context) {
+  return context.replace(FIRST_REPLY_NOTICE_RE, "")
+}
+
+// OpenCode 1.2.x expects plugins to be factory functions (see inject-subagent-context.js comment).
+export default async ({ directory }) => {
+  const ctx = new TrellisContext(directory)
+  debugLog("session", "Plugin loaded, directory:", directory)
+
+  return {
+    [MESSAGES_TRANSFORM_HOOK]: async (_input, output) => {
+      try {
+        const messages = output?.messages
+        const platformInput = platformInputFromMessages(messages)
+        const agent = platformInput?.agent || "unknown"
+        debugLog("session", "messages.transform called, agent:", agent)
+
+        if (isTrellisSubagent(platformInput)) {
+          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
+        }
+
+        if (process.env.OPENCODE_NON_INTERACTIVE === "1") {
+          debugLog("session", "Skipping - non-interactive mode")
+          return
+        }
+
+        let context = buildSessionContext(ctx, platformInput)
+        if (transcriptHasAssistantMessage(messages)) {
+          context = stripFirstReplyNotice(context)
+        }
+        debugLog("session", "Built context, length:", context.length)
+        prependEphemeralText(messages, context)
+      } catch (error) {
+        debugLog("session", "Error in messages.transform:", error.message, error.stack)
+      }
+    },
+  }
+}

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

@@ -0,0 +1,37 @@
+---
+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, find, grep
+---
+# Check Agent
+
+You are the Check Agent in the Trellis workflow.
+
+## Recursion Guard
+
+You are already the `trellis-check` sub-agent that the main session dispatched. Do the review and fixes directly.
+
+- Do NOT spawn another `trellis-check` or `trellis-implement` sub-agent.
+- If SessionStart context, workflow-state breadcrumbs, or workflow.md say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.
+- Only the main session may dispatch Trellis implement/check agents. If more implementation work is needed, report that recommendation instead of spawning.
+
+## Core Responsibilities
+
+1. Inspect the current git diff.
+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
+
+- 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,42 @@
+---
+name: trellis-implement
+description: |
+  Code implementation expert. Understands Trellis specs and requirements, then implements features. No git commit allowed.
+tools: read, write, edit, bash, find, grep
+---
+# Implement Agent
+
+You are the Implement Agent in the Trellis workflow.
+
+## Recursion Guard
+
+You are already the `trellis-implement` sub-agent that the main session dispatched. Do the implementation work directly.
+
+- Do NOT spawn another `trellis-implement` or `trellis-check` sub-agent.
+- If SessionStart context, workflow-state breadcrumbs, or workflow.md say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.
+- Only the main session may dispatch Trellis implement/check agents. If more parallel work is needed, report that recommendation instead of spawning.
+
+## Core Responsibilities
+
+1. Understand the active task requirements.
+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
+
+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, find, 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.