dsh-plans

Human-in-the-loop planning preset for the DeepSeek Harness (DSH): researched, refined Markdown plans before any code changes, then goal-driven execution after an explicit handoff.

Turn a rough repository-change request into a traceable plan under ./dsh-plans/, refine that plan with reviewer or criticizer subagent rounds, and hand the accepted plan to a persistent DSH goal that drives implementation until the plan's Verifier Checklist passes. Everything runs on DSH's native mechanisms — ask_user_question, subagents, the goal loop, and bundled skills — with no separate execution engine.

How a run goes

1. The agent inspects the target repository read-only, then asks the workspace's language setting once (persisted for every later run in that workspace).
2. Planning questions come one at a time, in a standard choice format (recommended option first, Other second-last, Auto-complete last); every question and answer is recorded in DECISIONS.md and the run ledgers.
3. A mandatory final scope confirmation gates the first draft: dsh-plans/YYYY-MM-DD-topic/PLAN_v1.md, with stable IDs, evidence, and a ## Verifier Checklist.
4. After every plan version, a refinement mode question — a reviewer or criticizer never runs without the user (or Auto-complete) selecting it. Reviewer and criticizer subagents run through the preset's own run_plan_subagent tool: read-only by construction, with the model chosen for that role at its first use.
5. After refinement converges, an explicit execution handoff question with no auto-complete: execute the plan now as a DSH goal, or stop after planning.
6. On approval, execution runs as a DSH goal whose objective points at the accepted plan and its Verifier Checklist. Implementation follows ponytail simplification discipline and the MVP minimum-test set, and update_goal complete is called only when every checklist box passes.

Bundled skills

Five skills, chosen by the agent for each request:

Skill	Use it when
create-a-small-plan	A small scoped repo change needs 1 to 3 planning questions. Recommended refinement: one criticizer round, then accept for execution.
create-a-plan	A broad or risky change needs 5 to 10 planning questions and web research. Recommended refinement: one reviewer round, then one criticizer round, then accept for execution.
create-a-big-plan	An open-ended or high-risk effort needs 10 or more planning questions and web research. Recommended refinement: one round of three concurrent reviewers consolidated by the main agent, then one criticizer round, then accept for execution.
diagnose-before-plan	A bug, CI failure, regression, incident, RCA, or broken behavior needs diagnosis before planning.
reference-before-plan	Downloaded projects, articles, papers, or docs must be analyzed before planning choices are safe.

Workflow guarantees:

• Per workspace, the language setting is asked once before the first planning question, and persisted.
• Per role, the model for reviewer / criticizer / executor is asked once, at that role's first actual use, and persisted. Reviewer and criticizer children run through the preset's own run_plan_subagent tool (runtime model selection; write tools, goal tools, user questions, and delegation tools are denied to the child). The executor is the current session's goal loop, so its confirmed model is the session model.
• One planning question at a time; the final scope confirmation gates PLAN_v1.md.
• After every plan version, a refinement mode question — a reviewer or criticizer never runs without it.
• After refinement, an explicit execution handoff question with no auto-complete: execute the plan now as a DSH goal, or stop after planning.
• Execution runs as a DSH goal with ponytail simplification discipline and the MVP minimum-test set, so token cost stays proportional to the work.

Install

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

The roster re-scans its roots on every read, so the new preset appears in the preset picker immediately — select dsh-plans for a new session (no restart needed). Then from any directory ask:

Create a plan for <your change>

Update an existing install with git -C ~/.dsh/.agent-presets/dsh-plans pull.

Code Mode requirement

dsh-plans presents all tools through DSH Code Mode (run_code plus the generated TypeScript SDK). This avoids native function-schema incompatibilities in models that populate every optional Bash argument, while leaving the original Bash implementation, sandbox escalation checks, approvals, background jobs, and cancellation behavior unchanged.

The host must provide codeRuntime; the DSH Web profile already loads dsh-code-runtime-worker-thread. Profiles without a code runtime fail clearly while mounting the preset instead of falling back to the incompatible Native tool presentation. Presentation is fixed when an agent is composed, so open a new dsh-plans session after updating. Restarting the whole DSH service is not normally required, and existing sessions are not hot-migrated.

Runtime layout

Public artifacts stay in the workspace, ready to commit:

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

Machine state stays private beside the artifacts, never committed:

dsh-plans/.state/         # .gitignore contains ".state/" (created by the helper)
  config.json             # language + per-role model settings
  active.json
  runs/<run-id>/          # run.json, decisions.jsonl, subagents.jsonl, refs.jsonl

Large downloaded references live outside the repository by default, under ~/.cache/dsh-plans/refs/.

Preset layout

agent.cordis.yml                  The composition: standard agent + dsh-plans rows
preset.yml                        Display metadata
lib/plan-subagents.js             Local host plugin: run_plan_subagent tool
skills/                           The five bundled skills + shared references
scripts/dsh_plans_state.py        State helper CLI (stdlib only)

The composition registers its own skills/ directory through the loader's baseUrl, so the preset is relocatable: clone it anywhere under a preset root and it still finds its skills and its local plugin.

Safety model

The supported boundary is planning discipline, durable state, and explicit handoff. Before the handoff, the workflow writes only dsh-plans/.state/ and dsh-plans/ artifacts — never target source, configs, or tests. Reviewer and criticizer subagents are read-only structurally (run_plan_subagent denies file-write, goal, user-question, and delegation tools) and report back through their final output. Auto-complete may answer planning and refinement questions; it never approves goal execution, installs, deploys, merges, pushes, credential use, or anything that changes external state.

Verify

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

License

MIT. See LICENSE.