1264459640/dsh-trellis

---

Overview

dsh-trellis is an engineering workflow extension for DeepSeek Harness (DSH), inspired by the stage specifications and state machine design of Trellis.

In complex, multi-turn AI coding workflows, typical pain points include:

1. Writing code without a clear design: Jumping directly into implementation often causes structural drift or regressions.
2. Fragmented task checklists: Maintaining separate checklists across different notes or files leads to state divergence.
3. Missing quality verification: Marking tasks as done without running tests or consulting human reviewers.

dsh-trellis addresses these issues through a unified step state machine, explicit stage progressions, and runtime tool filtering to ensure that models follow a disciplined "plan first, implement later, verify before closing" workflow.

---

Core Features

• Structured Stage Progression: Standardized workflow tracks for feature development (feat), bug fixes (issue), and code refactoring (refactor).
• Single Execution Contract: Uses task.json.steps as the single authoritative source of truth for step statuses, preventing checklist divergence.
• Verification Gates: Standard step states (pending, in_progress, verifying, blocked, completed) with explicit support for automated AI testing and human sign-off gates before marking steps complete.
• Optional Read-Only Planning: When enabled via settings, code-writing tools (write / edit) are filtered out during planning phases, leaving only a sandboxed artifact channel for design documentation.
• Session-Level Isolation: Session pointers are stored independently under .trellis/.runtime/sessions/, preventing multi-session or subagent race conditions.
• Dual-Mode Task Board: A dense compact task list by default (type badge + title + stage + step summary), expanding into a full-screen kanban with workflow-stage lanes, auto-collapsed empty lanes, live search, type filters, and an archive lane. The UI is fully iconized (self-contained inline SVG icon set), and the details inspector provides a Step Tracker pipeline, an artifact file tree, and capsule-style property tags. The board stays deliberately restrained — it never mutates task state directly; the only advance path is the Advance Task button injecting an instruction into the composer for the Agent to execute, and artifact clicks produce native @.trellis/tasks/... file references handled by DSH.
• Git Cleanliness Check (scoped mode supported): Automatically verifies that the Git working tree is clean and committed before closing or archiving a task. When the working tree contains uncommitted changes unrelated to the current task, pass the task's actual changed files via modified_files to trellis_task_update / trellis_task_archive: the check then scopes to those files (which must themselves be committed), and uncommitted changes outside the list only emit a warning instead of blocking. Omitting the parameter keeps the global strict check.

---

Getting Started

1. Installation

Ensure Node.js ≥ 20 is installed, then run in your terminal:

dsh plugin --profile web add @banana-peeljj12/dsh-trellis@latest

After installation, restart the DSH service.

Desktop app (DeepSeek Harness App): use the bundled carrier CLI. The ordinary dsh CLI refuses to touch the desktop profile with error: profile "desktop" is managed exclusively by the Electron application (that name is hard-coded as protected). Use the CLI shipped inside the app instead:

& "F:\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd" plugin --profile desktop add link:F:\dsh-plugins\dsh-trellis

For a local development checkout, install it as link:<absolute repo path>. Afterwards fully quit and relaunch the desktop app (including the tray icon — confirm no DeepSeek Harness.exe remains in Task Manager) for the change to take effect.

Version compatibility: the @deepseek-ai/dsh-* peer ranges a plugin declares must cover the running DSH version. DSH validates those ranges both in the install preflight (before pnpm runs) and at profile startup; a mismatch produces installation rejected and the plugin is not loaded. This is a declaration problem, not a code problem: on a 0.2.0-rc.2 runtime, ^0.1.7-rc.1 (= >=0.1.7-rc.1 <0.2.0-0) does not cover it and must be raised to ^0.2.0-rc.2. If the plugin suddenly stops working after a DSH upgrade, check the peer ranges first. This repository currently targets DSH 0.2.0-rc.2; see docs/ref/dsh-0.2.0-rc.2-audit.md for the audit evidence.

2. Configure Allowed Directories (Important)

By default, the plugin will not intercept any unconfigured workspaces. Add your target workspace directory to the allowlist:

1. Open the DSH Web UI and navigate to bottom-left Settings → Plugins → Trellis Workflow;
2. Under Allowed Projects (allowlist), add the absolute path of your workspace root directory — either type it manually or click Browse… to pick a folder via the system folder picker, then click Save (hot-reloaded).

Note: To prevent the model from editing source code prior to plan approval, enable Enforce Read-Only Planning (enforceReadonlyPlanning) in the same settings panel.

3. Usage

When describing complex tasks in chat, the model will guide you through creating and advancing Trellis tasks:

• New Features: Creates feat-mm-dd-name, advancing through prd → design → design-review → impl → review → check;
• Bug Fixes: Creates issue-mm-dd-name, advancing through report → analyze → fix → fix-note;
• Refactoring: Creates refactor-mm-dd-name, advancing through scan → design → apply → done.

To bypass workflow interception in a specific turn, include no-trellis in your prompt.

---

Workflow Tracks

The plugin provides three standard tracks mapped to the task stage (work.stage):

Track	Naming Pattern	Stage Progression	Description
Feature (feat)	feat-MM-DD-name	prd → design → design-review → impl → review → check	For new feature development or major functionality changes
Issue (issue)	issue-MM-DD-name	report → analyze → fix → fix-note	For bug diagnosis, fixing anomalies, and regression testing
Refactor (refactor)	refactor-MM-DD-name	scan → design → apply → done	For behavior-preserving optimizations and cleanups

---

Key Mechanisms

1. Step State Machine & Verification Gates

The steps array in task.json serves as the execution list and supports 5 states:

• pending: Waiting to be worked on;
• in_progress: Actively working on the step;
• verifying: Implementation done, awaiting verification;
• blocked: Blocked by external causes (requires blockedReason);
• completed: Verified and closed.

Verification Modes:

• Automated Verification (verification: 'ai'): The model must run test commands and record verified: true with verificationNotes evidence via trellis_task_update in an initial call before the step can be marked completed in a subsequent call.
• Human Approval Gate (verification: 'human'): Reserved for critical or high-risk changes. The step cannot be marked completed unless confirmed by the user and saved with verifiedBy: 'human'.
• Completion Audit: When closing or archiving a task, the plugin validates that all steps are completed and verified, and that the Git working tree is clean.

2. Read-Only Planning (Optional Enforcement)

When enforceReadonlyPlanning: true is configured, the plugin TRIMS ONLY the specified tools based on the current workflow state (denylist semantics — every other tool, including tools registered by other plugins, is kept):

Authorization State	Condition	Trimmed Tools	Description
undecided	In allowlist, no active task, not skipped	write / edit + trellis_task_update / trellis_artifact_update / trellis_task_archive / trellis_ui_update	Removes code-write and task-write tools to avoid blindly rewriting source; trellis_task_create / trellis_task_skip and all other tools (including other plugins') are kept
planning	Task is in planning stages (prd, design, scan, report)	write / edit + trellis_task_create / trellis_task_skip / trellis_task_archive / trellis_ui_update	Removes generic write / edit tools and task-lifecycle tools; deliverables can only be updated through the artifact tool; trellis_task_update / trellis_artifact_update and all other tools are kept
authorized	Task is in implementation stages (impl, fix, apply) or skipped	None (no trimming)	Restores the full tool surface

Note: trellis_artifact_update only permits writing whitelisted documentation inside the active task directory (.trellis/tasks/<slug>/), preventing path traversal.

---

Provided Tools

The plugin registers the following specialized tools:

• trellis_task_create: Creates a new task with initial task.json, seeds templates, and binds to the current session.
• trellis_task_update: Advances task stages, updates step progress, records verification evidence, or modifies task metadata.
• trellis_artifact_update: Safely updates task planning documents (such as prd.md, design.md, check.md), restricted by path and filename whitelists.
• trellis_task_archive: Archives a completed task to .trellis/tasks/archive/YYYY-MM/ and unbinds the session.
• trellis_task_skip: Skips the Trellis workflow for the active session upon user approval, unlocking write tools.
• trellis_state: Inspects and reports Trellis runtime state and task information for the current workspace.
• trellis_ui_update: Manually refreshes the web header phase chip.

---

Configuration Reference

Configure via the Web UI (Settings → Plugins → Trellis Workflow) or in ~/.dsh/settings.yaml:

Key	Type	Default	Description
allowlist	string[]	[]	Project Allowlist: Absolute paths of enabled workspace roots. Empty disables interception
enforceReadonlyPlanning	boolean	false	Read-Only Planning: Strips code modification tools during planning stages when enabled
skipKeywords	string[]	['no-trellis']	Skip Keywords: Suppresses workflow interception for turns containing these words
injectStep	number	1	Breadcrumb prompt injection step index (default: first step of turn)
inline	boolean	false	Enables codex-inline style phase dispatch

---

Repository Structure

dsh-trellis/
├── lib/
│   ├── index.js            # Plugin entry: registers pre-step hooks, tool filtering, and API routes
│   ├── task.js             # Task engine: step state machine, verification gates, and audits
│   ├── skills.js           # Skills provider: provisions standard workflow skills into workspace
│   ├── breadcrumb.js       # Context builder: extracts focused steps and formats prompts
│   ├── readonly.js         # Authorization logic: undecided / planning / authorized states
│   ├── state.js            # State resolution: stage inference, session pointers, slug checks
│   ├── artifact.js         # Sandboxed writes: whitelisted artifact updates and security checks
│   ├── archive.js          # Archiving logic: completion validation, directory migration, Git checks
│   ├── board.js            # Kanban data: aggregates active tasks and archive buckets
│   ├── client.js           # Web client: phase badge, mini kanban, and settings panel
│   └── types/index.d.ts    # TypeScript type definitions
├── skills/                 # Bundled workflow skills and markdown templates
├── docs/images/            # Screenshots and architecture diagrams
└── test/                   # Automated unit test suite

---

License & Acknowledgements

• Licensed under the MIT License;
• Thanks to Trellis (Mindfold) for the conceptual foundation of stage specifications and breadcrumb injection;
• Thanks to CodeStable for the three standard workflow track classifications;
• Thanks to DeepSeek Harness for the modern, extensible agent runtime.