When developing multi-repository projects in a DSH environment, agents can easily write code to the wrong location by forgetting to switch directories or branches. This plugin builds a multi-repository feature workspace to ensure that each feature runs in an isolated directory and that all component repositories stay synchronized on the same feature branch.

Plugin Introduction

This is a DSH plugin for multi-repository feature workspace orchestration, maintained by TY-ang. It binds a group of repositories into a “Set”, stored at $DSH_HOME/worktree-flow/sets/<name>.json. When creating a feature, the plugin creates a git worktree for each component repository, with all worktrees sharing the same feature branch. The feature root directory is automatically registered as a DSH workspace, so the session sandbox is precisely scoped to that feature.

Core Features

  • Multi-repository feature workspaces: Each feature corresponds to a directory, and each component repository corresponds to a git worktree.
  • Shared feature branch: All component worktrees reuse the same feature branch, avoiding branch confusion.
  • Automatic registration as a DSH workspace: The feature root directory is registered automatically, and sessions can operate within that scope.
  • Sandbox isolation: Sessions can only write to the feature root directory and cannot touch the main repository or other feature directories.
  • Pre-created branches: When creating a feature, the plugin checks out the designated branch, so writes land in the correct location by default.
  • Identity description injection: At session startup, the current feature layout and branch constraints are injected automatically.
  • Environment doctor: Diagnoses environment integrity, including directory ownership, Git ownership, branch references, and more.
  • Automatic discovery: Scans for Git repositories near the reference directory and supports bulk binding of components.
  • Real-time shared documentation: Supports configuring project-level documentation sources that sessions can read directly and keep up to date.
  • Custom branch types: Supports custom branch naming rules (such as Bugfix/feature/release).

Installation and Activation

Use the following command to install the plugin (profile must be specified):

dsh plugin --profile web add github:TY-ang/dsh-worktree-flow

After installation, restart dsh web. The package declares dsh.bundle, so it is automatically added to the configuration file stack. This is a private package and is not published to the npm registry.

Typical Usage

Configuration

Open the Settings → Worktree Flow page. Create a “Set” on the configuration page and bind component paths. Non-Git directories can be selected and initialized as repositories. The configuration includes shared documentation sources, branch type definitions, and more.

Command Operations

# 查看功能状态
/worktree status [feature]

# 创建新功能
/worktree create [name] --branch <full-branch> [--components a,b] [--base ref] [--set name] [--dry-run] [--register-components]

# 诊断环境
/worktree doctor [--set name]

# 同步现有功能，迁移旧版清单
/worktree sync

# 打开指定功能（确保已注册）
/worktree open <feature>

# 完成并归档功能
/worktree finish <feature> [--cleanup] [--force] [--keep-registered]

# 显示当前配置
/worktree config show [--set name]

Applicable Scenarios and Notes

Applicable scenarios: Multi-repository front-end/back-end/API co-development where strict feature isolation and branch management are required.

Notes:
* Node.js >= 22 is required.
* Worktree-root and component paths must be absolute paths; ~ is supported.
* There are strict restrictions in Windows environments:
* The DSH process must not be at High Integrity or system level; it must run under a regular user account.
* Component creation relies on native git worktree add, so ensure Git validation passes.
* The plugin does not modify global git config, change Owner/ACL, or switch Windows users.
* Ensure that DSH, Codex, and the IDE run under the same Windows account.
* The environment doctor provides read-only diagnostics only and does not automatically repair environment or trust issues.
* Archiving (finish) only removes the registration record; it does not delete files or branches.

By using physical isolation and pre-configured branches, this plugin resolves path and branch confusion in multi-repository development. It suits development workflows that require strict feature isolation. For more details, visit GitHub or SkillHub.