@pennixrv/trellis 0.6.45 → 0.7.0-beta.10

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

@@ -0,0 +1,134 @@
+---
+name: trellis-research
+user-invocable: false
+description: |
+  Child-agent-only research role for Trellis. Main sessions must not load this
+  skill directly. Finds files, patterns, and technical solutions, and persists
+  every finding to the current task's research/ directory. No code changes
+  outside that directory.
+---
+# Research Agent
+
+You are the Research Agent in the Trellis workflow.
+
+## Core Principle
+
+**You do one thing: find, explain, and PERSIST information.**
+
+Conversations get compacted; files don't. Every research output MUST end up as a file under `{TASK_DIR}/research/`. Returning findings only through the chat reply is a failure - the caller cannot read them next session.
+
+## Core Responsibilities
+
+1. **Internal Search** - locate files/components, understand code logic, discover patterns
+2. **External Search** - library docs, API references, best practices
+3. **Persist** - write each research topic to `{TASK_DIR}/research/<topic>.md`
+4. **Report** - return file paths + one-line summaries to the main agent, not full content
+
+---
+
+## Workflow
+
+### Step 1: Resolve Current Task
+
+Run `python3 ./.trellis/scripts/task.py current --source` to get the active task path. Prefer an `Active task: <path>` line in the dispatch prompt when present. If no active task is set, ask the user where to write output; do NOT guess.
+
+Ensure `{TASK_DIR}/research/` exists before writing findings.
+
+### Step 2: Understand Search Request
+
+Classify the request as internal, external, or mixed. Determine scope and expected output shape.
+
+### Step 3: Execute Search
+
+Run independent searches in parallel where possible. Read relevant source files, specs, and documentation before forming conclusions.
+
+### Step 4: Persist Each Topic
+
+For each distinct research topic, write a markdown file at `{TASK_DIR}/research/<topic-slug>.md` using the File Format below.
+
+### Step 5: Report to Main Agent
+
+Reply with ONLY:
+
+- List of files written, paths relative to repo root
+- One-line summary per file
+- Any critical caveats that the main agent needs to know right now
+
+Do NOT paste full research content into the reply. The files are the contract.
+
+---
+
+## Scope Limits
+
+### Write Allowed
+
+- `{TASK_DIR}/research/*.md` - your own output
+- Creating `{TASK_DIR}/research/` if it doesn't exist
+
+### Write Forbidden
+
+- Code files (`src/`, `lib/`, etc.)
+- Spec files (`.trellis/spec/`) - main agent should use the update-spec skill instead
+- `.trellis/scripts/`, `.trellis/workflow.md`, platform config (`.dsh/`, `.claude/`, `.cursor/`, etc.)
+- Other task directories
+- Any git operation
+
+If the user asks you to edit code, decline and suggest spawning `trellis-implement` instead.
+
+---
+
+## File Format
+
+Each `{TASK_DIR}/research/<topic>.md` should follow:
+
+```markdown
+# Research: <topic>
+
+- Query: <original query>
+- Scope: internal / external / mixed
+- Date: YYYY-MM-DD
+
+## Findings
+
+### Files Found
+
+| File Path | Description |
+|---|---|
+| `src/services/xxx.ts` | Main implementation |
+| `src/types/xxx.ts` | Type definitions |
+
+### Code Patterns
+
+<describe patterns, cite file:line>
+
+### External References
+
+- [Library X docs](url) - <why relevant, version constraints>
+
+### Related Specs
+
+- `.trellis/spec/xxx.md` - <description>
+
+## Caveats / Not Found
+
+<anything incomplete or uncertain>
+```
+
+---
+
+## Guidelines
+
+### Do
+
+- Provide specific file paths and line numbers
+- Quote actual code snippets only when they are relevant
+- Persist every topic to its own file
+- Return file paths in your reply, not the full content
+- Mark "not found" explicitly when searches come up empty
+
+### Don't
+
+- Don't write code or modify files outside `{TASK_DIR}/research/`
+- Don't guess uncertain info
+- Don't paste full research text into the reply
+- Don't propose implementation changes unless the main agent explicitly asked for research options

package/dist/templates/dsh/index.d.ts

@@ -1,21 +1,22 @@
 /**
  * DeepSeek Harness (dsh) template module.
  *
- * dsh is a class-2 pull-based, skills-only platform:
- * - Workflow + bundled skills go to the shared `.agents/skills/` root via
- *   the neutral resolver (byte-identical to Codex/Gemini/Pi/Kimi writes).
+ * dsh is a class-2 pull-based platform:
+ * - Workflow/bundled skills go to the shared `.agents/skills/` root via the
+ *   neutral resolver (byte-identical to Codex/Gemini/Pi/Kimi writes).
  * - User-invocable entry points (`trellis-start` / `trellis-continue` /
- *   `trellis-finish-work`, loaded by the dsh agent through its skill-loader
- *   tool) live under `.dsh/skills/<name>/SKILL.md` — dsh's own highest-rank
- *   project skill root.
+ *   `trellis-finish-work`) and Trellis role prompts live under
+ *   `.dsh/skills/trellis-agent-<role>/SKILL.md`.
  * - Operator guide `.dsh/DSH.md`.
  *
- * dsh has no shipped session-start hook, so `trellis-start` is kept as a
- * user-invocable skill. dsh ships no project-level sub-agent definition
- * surface, so no trellis-implement / trellis-check / trellis-research agent
- * prompts are written; implement/check/research run inline through the
- * workflow skills.
+ * dsh has no project-level hooks/settings file Trellis may write and no
+ * declarative custom sub-agent definitions, so the Trellis agent prompts ship
+ * as skills; the main session dispatches them through the `subagent` tool and
+ * trellis-agent-implement / trellis-agent-check get the pull-based prelude.
  */
+import { type AgentTemplate } from "../template-utils.js";
+/** Source role prompts; the configurator installs collision-free DSH skills. */
+export declare function getAllAgents(): AgentTemplate[];
 /** Operator guide copied to `.dsh/DSH.md`. */
 export declare function getDshGuide(): string;
 //# sourceMappingURL=index.d.ts.map

package/dist/templates/dsh/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/dsh/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,8CAA8C;AAC9C,wBAAgB,WAAW,IAAI,MAAM,CAEpC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/dsh/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAIhF,gFAAgF;AAChF,wBAAgB,YAAY,IAAI,aAAa,EAAE,CAE9C;AAED,8CAA8C;AAC9C,wBAAgB,WAAW,IAAI,MAAM,CAEpC"}

package/dist/templates/dsh/index.js

@@ -1,23 +1,25 @@
 /**
  * DeepSeek Harness (dsh) template module.
  *
- * dsh is a class-2 pull-based, skills-only platform:
- * - Workflow + bundled skills go to the shared `.agents/skills/` root via
- *   the neutral resolver (byte-identical to Codex/Gemini/Pi/Kimi writes).
+ * dsh is a class-2 pull-based platform:
+ * - Workflow/bundled skills go to the shared `.agents/skills/` root via the
+ *   neutral resolver (byte-identical to Codex/Gemini/Pi/Kimi writes).
  * - User-invocable entry points (`trellis-start` / `trellis-continue` /
- *   `trellis-finish-work`, loaded by the dsh agent through its skill-loader
- *   tool) live under `.dsh/skills/<name>/SKILL.md` — dsh's own highest-rank
- *   project skill root.
+ *   `trellis-finish-work`) and Trellis role prompts live under
+ *   `.dsh/skills/trellis-agent-<role>/SKILL.md`.
  * - Operator guide `.dsh/DSH.md`.
  *
- * dsh has no shipped session-start hook, so `trellis-start` is kept as a
- * user-invocable skill. dsh ships no project-level sub-agent definition
- * surface, so no trellis-implement / trellis-check / trellis-research agent
- * prompts are written; implement/check/research run inline through the
- * workflow skills.
+ * dsh has no project-level hooks/settings file Trellis may write and no
+ * declarative custom sub-agent definitions, so the Trellis agent prompts ship
+ * as skills; the main session dispatches them through the `subagent` tool and
+ * trellis-agent-implement / trellis-agent-check get the pull-based prelude.
  */
 import { createTemplateReader } from "../template-utils.js";
-const { readTemplate } = createTemplateReader(import.meta.url);
+const { listMdAgents, readTemplate } = createTemplateReader(import.meta.url);
+/** Source role prompts; the configurator installs collision-free DSH skills. */
+export function getAllAgents() {
+    return listMdAgents();
+}
 /** Operator guide copied to `.dsh/DSH.md`. */
 export function getDshGuide() {
     return readTemplate("DSH.md");

package/dist/templates/dsh/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/dsh/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAE5D,MAAM,EAAE,YAAY,EAAE,GAAG,oBAAoB,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAE/D,8CAA8C;AAC9C,MAAM,UAAU,WAAW;IACzB,OAAO,YAAY,CAAC,QAAQ,CAAC,CAAC;AAChC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/dsh/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,oBAAoB,EAAsB,MAAM,sBAAsB,CAAC;AAEhF,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,GAAG,oBAAoB,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAE7E,gFAAgF;AAChF,MAAM,UAAU,YAAY;IAC1B,OAAO,YAAY,EAAE,CAAC;AACxB,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,WAAW;IACzB,OAAO,YAAY,CAAC,QAAQ,CAAC,CAAC;AAChC,CAAC"}

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

@@ -0,0 +1,121 @@
+/* global process */
+/**
+ * Trellis Dynamic Spec Injection Plugin
+ *
+ * OpenCode tool hooks cannot add context to the current model turn. A FULL
+ * spec emission therefore blocks the write once with a model-visible error;
+ * the shared Python engine records the emission, so the model's retry proceeds.
+ */
+
+import { execFileSync } from "child_process";
+import { existsSync } from "fs";
+import { join } from "path";
+import { debugLog } from "../lib/trellis-context.js";
+
+const PYTHON_CMD = process.platform === "win32" ? "python" : "python3";
+
+function runSpecHook(directory, payload) {
+  const hookPath = join(
+    directory,
+    ".opencode",
+    "hooks",
+    "inject-spec-context.py",
+  );
+  if (!existsSync(hookPath)) return null;
+
+  try {
+    const stdout = execFileSync(PYTHON_CMD, [hookPath], {
+      cwd: directory,
+      encoding: "utf-8",
+      input: JSON.stringify(payload),
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 15000,
+    });
+    if (!stdout.trim()) return null;
+    const parsed = JSON.parse(stdout);
+    return parsed?.hookSpecificOutput ?? null;
+  } catch (error) {
+    debugLog(
+      "spec",
+      "Spec hook failed open:",
+      error instanceof Error ? error.message : String(error),
+    );
+    return null;
+  }
+}
+
+function buildToolPayload(directory, input, output) {
+  const tool = input?.tool?.toLowerCase();
+  const args = output?.args;
+  if (!args) return null;
+
+  if (tool === "edit" || tool === "write") {
+    if (typeof args.filePath !== "string" || !args.filePath.trim()) return null;
+    return {
+      hook_event_name: "PreToolUse",
+      session_id: input?.sessionID,
+      cwd: directory,
+      tool_name: tool === "edit" ? "Edit" : "Write",
+      tool_input: { file_path: args.filePath },
+    };
+  }
+
+  if (tool === "apply_patch") {
+    if (typeof args.patchText !== "string" || !args.patchText.trim())
+      return null;
+    return {
+      hook_event_name: "PreToolUse",
+      session_id: input?.sessionID,
+      cwd: directory,
+      tool_name: "apply_patch",
+      tool_input: { command: args.patchText },
+    };
+  }
+
+  return null;
+}
+
+export default async ({ directory }) => ({
+  event: async ({ event }) => {
+    if (
+      process.env.TRELLIS_HOOKS === "0" ||
+      process.env.TRELLIS_DISABLE_HOOKS === "1"
+    ) {
+      return;
+    }
+    if (event?.type !== "session.compacted" || !event?.properties?.sessionID) {
+      return;
+    }
+
+    runSpecHook(directory, {
+      hook_event_name: "SessionStart",
+      session_id: event.properties.sessionID,
+      source: "compact",
+      cwd: directory,
+    });
+  },
+
+  "tool.execute.before": async (input, output) => {
+    if (
+      process.env.TRELLIS_HOOKS === "0" ||
+      process.env.TRELLIS_DISABLE_HOOKS === "1"
+    ) {
+      return;
+    }
+
+    const payload = buildToolPayload(directory, input, output);
+    if (!payload) return;
+
+    const result = runSpecHook(directory, payload);
+    const context = result?.additionalContext;
+    if (result?.permissionDecision !== "deny" || typeof context !== "string") {
+      return;
+    }
+
+    throw new Error(
+      "Trellis loaded governing specs before this tool call. " +
+        "Follow them, then retry the same tool call.\n\n" +
+        context,
+    );
+  },
+});

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

@@ -1,4 +1,4 @@
-/* global process */
+/* global process, console */
 /**
  * Trellis Workflow State Injection Plugin
  *
@@ -9,7 +9,12 @@
  * `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
+ * workflow.md is the single source of truth. When the active task's
+ * task.json selects a workflow variant ("workflow": "<id>"), the tag
+ * blocks are read from .trellis/workflows/<id>.md instead (missing
+ * variant file → one stderr warning + fallback through personal/team/global
+ * defaults; see
+ * resolveWorkflowMd). 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)
@@ -21,7 +26,7 @@
  *   - task.json malformed or missing status
  */
 
-import { existsSync, readFileSync } from "fs"
+import { existsSync, readFileSync, statSync } from "fs"
 import { join } from "path"
 import {
   MESSAGES_TRANSFORM_HOOK,
@@ -111,17 +116,113 @@ function promptHasSkipKeyword(text, keyword) {
   return pattern.test(text)
 }
 
+// Per-task workflow selection (mirrors the Python resolver in
+// .trellis/scripts/common/workflow_selection.py). Ids are restricted to
+// [A-Za-z0-9_-]+ so a task.json value can never traverse outside
+// .trellis/workflows/.
+const WORKFLOW_ID_RE = /^[A-Za-z0-9_-]+$/
+
+// Map a workflow id to its .trellis/workflows/<id>.md file if valid and
+// present, else "". Shared by every resolution layer. Never throws.
+function libraryVariant(directory, workflowId) {
+  if (!workflowId || !WORKFLOW_ID_RE.test(workflowId)) return ""
+  const variantPath = join(directory, ".trellis", "workflows", `${workflowId}.md`)
+  try {
+    if (statSync(variantPath).isFile()) return variantPath
+  } catch {
+    // ENOENT etc. — missing variant file.
+  }
+  return ""
+}
+
+// Personal override id from the gitignored .developer file (`workflow=<id>`
+// line). "" when absent/unreadable. Never throws.
+function developerWorkflowId(directory) {
+  try {
+    const text = readFileSync(join(directory, ".trellis", ".developer"), "utf-8")
+    for (const line of text.split(/\r?\n/)) {
+      if (line.startsWith("workflow=")) return line.slice("workflow=".length).trim()
+    }
+  } catch {
+    // No .developer / unreadable — no personal override.
+  }
+  return ""
+}
+
+// Team-shared default id from config.yaml's top-level `default_workflow:` key.
+// Commented lines (starting with '#') are naturally excluded by the anchor.
+// "" when unset/unreadable. Never throws.
+const DEFAULT_WORKFLOW_RE = /^default_workflow:\s*(['"]?)([A-Za-z0-9_-]+)\1\s*(?:#.*)?$/m
+function configDefaultWorkflowId(directory) {
+  try {
+    const text = readFileSync(join(directory, ".trellis", "config.yaml"), "utf-8")
+    const m = text.match(DEFAULT_WORKFLOW_RE)
+    if (m) return m[2]
+  } catch {
+    // No config.yaml / unreadable — no team default.
+  }
+  return ""
+}
+
+/**
+ * Resolve which workflow markdown file feeds this turn's breadcrumbs.
+ *
+ * Precedence (identical across all Trellis consumers), highest to lowest —
+ * each layer resolves an id to .trellis/workflows/<id>.md and falls through
+ * when unset, invalid, or naming a missing file:
+ *   1. Per-task pin  — active task's task.json "workflow" (session-bound; a
+ *      bad id / missing file warns once on stderr, then falls through).
+ *   2. Personal      — .developer `workflow=<id>` (gitignored, per-developer).
+ *   3. Team default  — config.yaml `default_workflow` (git-tracked, shared).
+ *   4. Global        — .trellis/workflow.md.
+ * With neither a pin nor the personal/team keys set, this is the global path.
+ * Never throws.
+ */
+function resolveWorkflowMd(ctx, directory, platformInput) {
+  const globalPath = join(directory, ".trellis", "workflow.md")
+
+  // 1. Per-task pin (session-bound explicit choice).
+  let workflowId = ""
+  try {
+    const active = ctx.getActiveTask(platformInput)
+    if (active.taskPath && !active.stale) {
+      const taskDir = ctx.resolveTaskDir(active.taskPath)
+      if (taskDir) {
+        const data = JSON.parse(readFileSync(join(taskDir, "task.json"), "utf-8"))
+        if (data && typeof data.workflow === "string") workflowId = data.workflow
+      }
+    }
+  } catch {
+    // No active task / unreadable task.json — not a selection.
+    workflowId = ""
+  }
+  if (workflowId) {
+    const pinned = libraryVariant(directory, workflowId)
+    if (pinned) return pinned
+    console.error(
+      `Warning: active task selects workflow ${JSON.stringify(workflowId)} but .trellis/workflows/ has no matching file; using default workflow resolution`,
+    )
+  }
+
+  // 2. Personal override, then 3. team default — silent on miss (defaults,
+  // not an explicit per-task choice). 4. Global fallback.
+  const personal = libraryVariant(directory, developerWorkflowId(directory))
+  if (personal) return personal
+  const team = libraryVariant(directory, configDefaultWorkflowId(directory))
+  if (team) return team
+  return globalPath
+}
+
 /**
- * Parse workflow.md for [workflow-state:STATUS] blocks.
+ * Parse the resolved workflow markdown 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
+ * Returns {status: body}. The workflow file is the single source of
+ * truth — there are no fallback tables here. Missing tags (or a missing /
+ * unreadable workflow file) 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")
+function loadBreadcrumbs(workflowPath) {
   if (!existsSync(workflowPath)) return {}
   let content
   try {
@@ -228,7 +329,7 @@ export default async ({ directory }) => {
             return
           }
 
-          const templates = loadBreadcrumbs(directory)
+          const templates = loadBreadcrumbs(resolveWorkflowMd(ctx, directory, platformInput))
           const task = getActiveTask(ctx, platformInput)
           const breadcrumb = task
             ? buildBreadcrumb(task.id, task.status, templates, task.candidates)