dsh-plugin-trellis-workflow

Trellis workflow enforcement for the DeepSeek Harness (dsh): per-turn workflow state injection plus a trellis-start entry gate, replacing the session-start and user-prompt hooks dsh does not ship.

The gap it closes

Trellis classifies dsh as a class-2 pull-based platform and ships hasHooks: false. It writes skills and scripts, but no SessionStart hook and no UserPromptSubmit hook. On dsh that means:

• nothing reminds the agent that a Trellis task workflow is in force, so the workflow is skipped unless the user names a skill;
• trellis-start is a user-invocable skill that never fires on its own.

Trellis's own generated .dsh/DSH.md says as much: "no session-start hook auto-injects workflow context, so the agent loads the Trellis skills on demand."

This plugin supplies the missing channel with dsh-native mechanisms — no hooks required:

Missing Trellis channel	Mechanism used here
SessionStart context injection	agent/created and agent/inbox/inserted listeners refresh state
UserPromptSubmit breadcrumb	a systemPrompt.context contribution whose text is a function, re-evaluated on every model step
Entry routing to trellis-start	the rendered state block itself, gated on no_task

Behaviour

• Project-aware. Resolves the Trellis project root by walking up from session.header.cwd, confirming directory containment through the composed filesystem service. A workspace with no .trellis/ gets no injection at all, so unrelated projects are untouched.
• Read-only. Reads the session-scoped active-task pointer at .trellis/.runtime/sessions/<sessionId>.json, then that task's task.json. It never writes to .trellis/ and never runs shell commands.
• States. Contributes one block per step: task_active (task path and status), no_task (the trellis-start entry gate), task_error (unreadable pointer), unknown (state could not be measured). It contributes nothing until the first measurement completes rather than inventing a status.
• Session-isolated. State is keyed per session, so concurrent sessions cannot cross-contaminate.
• Cheap. One cached lookup per session, refreshed when the pointer can have moved (session start, a new user message, or the step before a model call).

The rendered block looks like this:

[trellis-workflow-state]
project=/path/to/trellis-project
status=task_active
task=.trellis/tasks/09-18-example
task_status=in_progress

强制路由：本任务处于 Trellis 任务流程中。
- 动手改代码前：先加载 trellis-before-dev，读 .trellis/spec/ 对应层规范。
- 改完代码：走 trellis-check。
- 收尾：走 trellis-finish-work 归档任务并写 journal。

状态来源=dsh 主机侧缓存。确切当前态：
  python3 ./.trellis/scripts/task.py current --source
本平台没有 SessionStart / UserPromptSubmit hook，此块即官方面包屑的等价物。

The routing text is written in Chinese to match the target project's convention; the rest of the block is language-neutral.

Requirements

• dsh with the systemPrompt service composed (present in the shipped base bundle)
• A Trellis-managed workspace (a project containing .trellis/)
• Node.js >= 20

Install

dsh plugin --profile <profile> add dsh-plugin-trellis-workflow

No profile file edit is needed. The command writes the dependency, appends the package to dsh.profile.bundles, and the profile boot merges this package's cordis.patch.yml as one insert.

Restart the profile afterwards. Node caches imported modules, so a restart is also required after editing src/index.js.

Configuration

Row config is set in the composition, not through a settings page:

key	default	meaning
enabled	true	false keeps the row mounted but contributes nothing
contextOrder	900	position among prompt runtime contexts; dsh's built-ins sit at 110 / 115 / 120, so this block renders after the sandbox, approval, and delegation notices. Must be a finite number.

To override, patch the row in the profile's own cordis.patch.yml:

- id: trellis-workflow
  config:
    contextOrder: 950

Uninstall

dsh plugin --profile <profile> remove dsh-plugin-trellis-workflow

Development

git clone git@github.com:elmersky/dsh-plugin-trellis-workflow.git
cd dsh-plugin-trellis-workflow
npm test                                  # smoke test
npm publish --dry-run                     # inspect the publish payload

Mount a checkout directly into a profile. pnpm records an absolute file: spec and links the directory, so edits to src/index.js are visible to the profile immediately — a restart is still needed to reload the module:

dsh plugin --profile <profile> add /absolute/path/to/dsh-plugin-trellis-workflow

Verify what actually composed:

dsh --profile <profile> --dump-config | grep -A4 trellis-workflow

Expect a # == dsh-plugin-trellis-workflow layer marker and exactly one trellis-workflow row. Two rows mean a stale hand-written mount line is still present alongside this bundle.

Package layout and why it is shaped this way

package.json declares dsh.bundle.patch, which is what makes this package a profile bundle rather than a plain dependency. The same declaration serves both the npm install and the local file: install, so publishing changes only the dependency spec — never the composition.

The row id equals the package name on purpose: the row resolves its module by package name through the profile's node_modules, so keeping the two identical makes the composed row and the dependency line correspond at a glance.

The prompt context is registered inside ctx.inject(['systemPrompt'], scope => …) rather than directly from apply(). This is not stylistic. systemPrompt.context() files the contribution into the layer belonging to the calling context's scope, and an agent assembles its prompt by merging the global layer plus the layers along its own scope-parent chain. A profile-row plugin's own context is not on that chain, so registering during apply() stores the contribution somewhere the agent never reads: the row activates, logs nothing, and injects nothing. Injecting the service instead yields a context already scoped per agent — the same route dsh's own sandbox:policy and approval:policy contexts take. test/smoke.js asserts the injection form so a regression here fails without a restart.

Status

0.1.0 — first release. Verified: composition resolves, the module loads, and the behaviour above is exercised by test/smoke.js plus the runtime contracts of systemPrompt.context and assemble.agent.session. Not yet verified on a public registry install; see the repository issues for tracking.

Licence

MIT