Preface¶

DeepSeek Harness (CLI name: dsh) is an agent runtime open-sourced by DeepSeek AI, designed under the principle of “everything is a plugin”: models, tools, skills, sessions, and interfaces can all be assembled via plugins. The official repository is currently marked as developer preview, and compatibility may change at any time.

There is also an independent community plugin directory deepseek-harness-plugin.com for searching third-party plugins. It has no official affiliation with DeepSeek / Hypermind and is not an official app store.

A common pain point when modifying code in a repository is jumping straight into coding based on a one-sentence requirement, only to realize halfway through that the scope is incorrect, acceptance criteria are vague, or reviewer feedback arrives too late. dsh-plans targets this exact scenario: first organize rough changes into a traceable Markdown plan in the workspace, refine it via reviewer/criticizer sub-agents, and only proceed to execution after explicit handoff from a human.

This article is compiled after cross-checking with the community directory details page, GitHub repository README, preset.yml / agent.cordis.yml, and bundled skill documentation.

What is this¶

dsh-plans is a human-machine collaborative planning preset (agent preset) for DeepSeek Harness maintained by Optim-Agent, licensed under MIT. The community directory categorizes it under the “Interface Enhancement” section. As of 2026-08-17, the GitHub repository shows 22 stars (the directory page listed 12 at the time; refer to the repository page for the latest count).

The repository description states that this project ports the planning workflow from prime-plans. The same maintainer also has optim-plans for Claude / Codex, which has five skill names that correspond one-to-one with this project; dsh-plans adapts this workflow to DSH’s native mechanisms — ask_user_question, sub-agents, goal loops, and bundled skills — without building a separate execution engine.

The problems it solves can be summarized in three steps:
1. Read-only access to the target repository, then write the change requirements into a plan under ./dsh-plans/ with a stable ID and Verifier Checklist.
2. Polish the plan iteratively via a reviewer/criticizer sub-agent; before each round, ask the user (or use Auto-complete) to select this role.
3. After the plan is accepted, ask a final handoff question with no auto-complete option: execute now as a DSH goal, or stop at the planning stage.

The preset disables DSH’s built-in plan mode. The agent.cordis.yml specifies that the built-in plan mode’s “single plan, write-protected” loop conflicts with the practice of writing PLAN_vN.md during the planning phase, so the preset’s own handoff question is used as the gatekeeper instead.

Core Features¶

How a full run works¶

The README outlines a complete workflow in six steps:
1. The agent reads the target repository in read-only mode, then asks for the language setting for this workspace (asked once per workspace, reused afterwards).
2. Only one planning question is asked at a time, with a fixed option order: recommended items first, Other second-to-last, and Auto-complete last. Questions and answers are written to DECISIONS.md and the run ledger.
3. Scope confirmation must be completed first before drafting the first version of dsh-plans/YYYY-MM-DD-topic/PLAN_v1.md. The plan must include a stable ID, evidence, and a ## Verifier Checklist.
4. After each version of the plan, ask how to refine it. The reviewer/criticizer will not start automatically without user selection. These two roles use the preset’s own run_plan_subagent tool: they are read-only by design, and the model for each role is selected when the role is first actually used.
5. After the refinement converges, ask a final execution handoff question without Auto-complete: execute now as a DSH goal, or end the planning here.
6. After approval, execution runs as a DSH goal, targeting the accepted plan and its Verifier Checklist. Implementation follows the ponytail simplification discipline and MVP minimal test set mentioned in the repository; only when every item on the checklist passes will update_goal complete be called.

Five bundled skills¶

The agent selects skills based on requests, rather than running the same full set every time:

diagnose-before-plan first performs RCA based on the repository, logs, tests, and user-provided symptoms (up to 5 Whys; mark unknown if there is insufficient evidence, do not fabricate causes), then asks whether to proceed to bug-fixing planning. Only after selecting to continue will PROBLEM_ANALYSIS.md be written.

reference-before-plan requires downloading at least 3 credible references before writing PLAN_v1.md. Large files are stored by default in ~/.cache/dsh-plans/refs/ outside the repository, and REF_ANALYSIS.md is written. For each reference, at least 3 adoption questions must be asked first, and their answers must be recorded before their ideas can be included in the plan.

Workspace artifacts¶

Files that can be submitted externally are left in the workspace:

dsh-plans/YYYY-MM-DD-topic/
  DECISIONS.md
  PROBLEM_ANALYSIS.md     # Only for diagnose-before-plan
  REF_ANALYSIS.md         # Only for reference-before-plan
  PLAN_v1.md
  PLAN_v1_reviewer_comments.md
  PLAN_v2.md

Machine state is stored alongside the artifacts, and is not committed by default (a helper will write .state/ to .gitignore):

dsh-plans/.state/
  config.json             # Language + models for each role
  active.json
  runs/<run-id>/

Each workspace remembers the language; the models for the reviewer, criticizer, and executor are asked once and persisted when the role is first actually used. The executor is the goal loop of the current session, and the confirmed model is the session model.

Security boundaries¶

The README limits the supported scope to planning discipline, persistent state, and explicit handoff. Before handoff, the workflow only writes to dsh-plans/.state/ and artifacts under dsh-plans/, and does not touch the target source code, configuration, or tests.

run_plan_subagent will block sub-agents from using tools like write, goal, ask user, and re-delegation; reviewers and critics can only report via final output. Auto-complete can answer planning and refinement questions, but cannot approve goal execution, installation, deployment, merging, pushing, using credentials, or any operation that changes external state.

Installation and activation¶

The installation command given on the community directory page is:

dsh plugin add github:Optim-Agent/dsh-plans

For reproducible installations, the directory page recommends pinning a commit hash:

dsh plugin add github:Optim-Agent/dsh-plans#commit

Replace #commit with the specific hash. The directory page also reminds users that the plugin runs with the permissions of the current dsh process, and may execute code during installation.

The repository itself does not have a package.json. The README describes installation as cloning to the user’s preset directory, where it will be scanned by the roster and appear in the preset selector:

mkdir -p ~/.dsh/.agent-presets
git clone https://github.com/Optim-Agent/dsh-plans.git ~/.dsh/.agent-presets/dsh-plans

The roster scans the root directory each time it loads, so new presets will appear immediately. Select dsh-plans for a new session, and there is no need to restart the entire dsh service. To update an existing installation:

git -C ~/.dsh/.agent-presets/dsh-plans pull

The two installation methods come from different sources: the former is from the directory page, and the latter is from the repository README. Verify against your installed dsh version before executing, and do not assume consistent results from mixing the two.

Code Mode prerequisites¶

dsh-plans exposes all tools via DSH Code Mode (run_code plus the generated TypeScript SDK). The README explains that this avoids issues where some models fill every optional Bash parameter in the function schema, while retaining the original Bash implementation, sandbox upgrade checks, approval, background tasks, and cancellation behavior.

The host must provide a codeRuntime. The DSH Web profile already loads dsh-code-runtime-worker-thread. Profiles without a code runtime will fail explicitly when mounting the preset, rather than falling back to incompatible Native tool rendering. Tool rendering is fixed when composing the agent, and a new dsh-plans session is required after updating; there is generally no need to restart the entire DSH service, and existing sessions will not be hot-migrated.

Typical usage¶

After selecting the preset, you can directly say this in any directory:

Create a plan for <your change>

Replace <your change> with your specific modification, such as adding an interface to a module, fixing a CI failure, or evaluating a dependency upgrade. The agent will select one of the five skills above based on the request, first read the repository in read-only mode, then proceed according to the question count and refinement rounds for that skill.

A medium-scale change (corresponding to create-a-plan) will roughly go through:
1. Workspace language (if not already recorded).
2. 5-10 planning questions, one multiple-choice question at a time.
3. Final scope confirmation, then write PLAN_v1.md.
4. By default, one round of reviewer, then one round of criticizer; ask for refinement method before and after each round.
5. After accepting the plan, ask “Execute now as a DSH goal” or “End planning here”.

For large plans, the reviewer round will concurrently launch three read-only reviewers in the same assistant message, and the main agent will deduplicate and write to PLAN_vN_reviewer_comments.md, showing up to 5 high-priority comments to the user per round. The criticizer will ask up to 5 follow-up questions per round; record the answers to these questions before revising the plan.

The repository also provides self-test commands (which do not modify the target repository):

node --test scripts/test_plan_subagents.js
python3 scripts/validate_preset.py
python3 scripts/dsh_plans_state.py init --workdir /tmp/dsh-plans-smoke

Applicable scenarios and notes¶

Good fits include:
- Changes spanning multiple files, modules, external APIs, or dependency upgrades, where you need to clarify scope and acceptance criteria first.
- Tasks that require RCA or external document review before deciding how to modify code.
- Teams that want plans, decisions, and refinement feedback stored in the repository and submitted for review together.

Cases that are not a good fit, or require a different approach:
- Explicit user requests to skip planning and make changes directly. The skill documentation excludes these requests.
- Pure factual Q&A, one-off commands, or explanatory questions without repository changes.
- Host profiles without codeRuntime: the preset will fail to mount.
- Expecting it to replace the built-in DSH plan mode’s “write-protected” behavior: this preset writes artifacts to dsh-plans/ during the planning phase and disables the built-in plan mode.

Important notes for installation and usage:
- The plugin/preset runs with the permissions of the current dsh process, and may execute code during installation. Before installing, check the source repository and license (this repository is MIT licensed).
- The community directory is not an official DeepSeek store; stars, categories, and installation commands are subject to the currently open page, and cross-check with GitHub whenever possible.
- Auto-complete cannot approve execution. The handoff question has no auto-complete option, which is intentional.
- The execution phase follows the ponytail discipline to minimize implementation, and tests only retain the minimal set that validates core logic. The goal will not be marked complete until all checklist items pass.

Summary¶

dsh-plans turns “plan first, then modify code” into a storable DSH preset: plans are versioned in ./dsh-plans/, reviewers/critics polish in read-only mode, execution requires an explicit handoff without auto-complete, and DSH’s native goal loop ensures the Verifier Checklist is fully passed.

Directory page: https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-plans/

GitHub: https://github.com/Optim-Agent/dsh-plans