dsh-spec-loop

Spec-driven development loop for DeepSeek Harness (dsh): a /spec command family drives propose → approve → implement → verify → archive, with change directories compatible with the OpenSpec layout under <workspace>/openspec/.

The harness is in developer preview and iterates quickly — expect compatibility-breaking changes.

中文说明见 README.zh.md。

Features

• /spec command family — init · new <goal> · status · list · show <id> · approve <id> · implement <id> · verify <id> [--deep] · archive <id> · validate [id] · edit <id>. Commands orchestrate and touch the filesystem only; proposal and implementation content is generated by the agent's main model through agent.steer with the full tool set.
• Clarification on /spec new — up to three built-in choice questions (scope / constraints / acceptance), in the language of the goal; answered through the harness question UI. Subagent sessions and missing UI providers fall back to proceeding without clarification.
• OpenSpec-compatible layout — openspec/project.md, openspec/specs/<capability>/spec.md, openspec/changes/<change-id>/{proposal.md,tasks.md,design.md,verify.md,specs/<cap>/spec.md}, archived to changes/archive/YYYY-MM-DD-<id>/. Spec deltas use ## ADDED|MODIFIED|REMOVED Requirements with #### Scenario: per requirement.
• Built-in validator — the plugin ships the same core rules as the OpenSpec CLI (sections, requirements, scenarios, change-id shape) and runs them automatically after proposal generation: on failure it steers a correction request back to the agent (bounded retries). approve refuses changes that do not validate; archive refuses missing changes.
• Approval gate — implement refuses changes whose state is not approved (or later in the implementation chain). The gate reads the same durable projection the panel renders, so display state and behavior state can never disagree.
• Per-scenario verification — verify judges every Requirement/Scenario against the workspace with a bounded judge call (flash by default, main model with --deep), runs ```bash verification commands declared in proposal.md, and writes verify.md with a ✅/❌ table plus the raw judge output.
• Durable state machine — proposed → approved → implemented → verified → archived (any stage can edit back to proposed) is a session projection folded from standard events (command/run/command/done pairs + the agent's machine-readable markers), so the change card, stage, and gate survive restarts. No custom event types are appended to the log.
• Change card in the composer dock — a full-width row above the input card (conversation.input.dock) shows the current change-id, stage, task progress x/y, and the next command to run. Task progress reads the standard todos projection (the implement prompt mirrors tasks.md into todo_write) — zero RPC. UI strings are localized through the harness locale service (zh/en).

Install

Prerequisites

The dsh CLI must be on your PATH. If you only ever ran the harness through npx, dsh is not installed and you will get zsh: command not found: dsh — install it globally first:

npm install -g @deepseek-ai/dsh

pnpm add -g @deepseek-ai/dsh also works if your pnpm global bin dir is on PATH (otherwise pnpm asks you to run pnpm setup first). Alternatively skip the global install and prefix the commands below with npx @deepseek-ai/dsh ….

Add the bundle

# 1. add the bundle to your web profile (pnpm-backed; the built lib/ artifacts
#    are committed in this repo, so no build script runs at install time).
#    Prefer a release tag (#v0.1.2); #main tracks the latest commit.
dsh plugin --profile web add "github:tianji-qingtian/dsh-spec-loop#v0.1.2"

# 2. restart the harness with that profile — `add` only edits the profile
#    files; a running instance does not hot-load the new bundle
dsh --profile web

After the restart the 📐 Spec card appears above the composer in the Web UI and the /spec command is registered once the host half loads. Verify under Settings → Plugins that dsh-spec-loop is listed.

Usage

/spec init                          # create openspec/project.md + directory layout
/spec new 用户登录功能               # clarify → agent writes proposal/tasks/deltas → auto-validate
/spec status                        # read-only card: current change-id, stage, x/y progress
/spec list                          # active changes (x/y tasks) + capability specs
/spec show add-user-login           # read a proposal (plus design.md when present)
/spec approve add-user-login        # approve → implementation gate opens
/spec implement add-user-login      # agent implements tasks.md in order, ticks checkboxes
/spec verify add-user-login         # per-scenario judge (flash); --deep for the main model
/spec verify add-user-login --deep
/spec archive add-user-login        # merge deltas into specs/, move to changes/archive/
/spec validate [id]                 # OpenSpec format check (auto-run after /spec new)
/spec edit add-user-login           # revise a proposal, back to proposed

The change card above the input shows the current change-id, stage, and x/y progress, plus the next command to run.

How it works

Piece	Mechanism
Commands	commands.register — one /spec command with a subcommand router. Handlers orchestrate and touch the filesystem (ctx.fs); generation is steered to the agent (agent.steer with a plugin-sourced UserMessage).
State machine	A session projection (specLoop) folds standard events: command/run+command/done pairs transition on success only, and the agent's reply markers (SPEC_CHANGE_ID: <id>, SPEC_IMPLEMENTED) complete the async stages. implement gates on the same projection.
Task progress	The implement prompt mirrors tasks.md into the todo_write tool; the panel reads the shipped todos projection.
Verification	Handler-side bounded judge call (ctx.llm.stream, reasoningEffort: 'off', flash by default); ```bash blocks from proposal.md run first via ctx.shell and their output is included in the judge prompt.
Archive merge	Deltas are merged requirement-by-requirement into specs/<cap>/spec.md (ADDED append, MODIFIED replace, REMOVED drop), then the change dir moves with one mv (ctx.shell).
UI	conversation.input.dock slot entry; reads useProjection('specLoop') + useProjection('todos'); locale service for zh/en strings.

Compatibility notes

• No custom session event types. Out-of-repo plugins cannot register new SessionEventMap members safely (the persistence read path refuses unknown non-ignorable types), so every state transition rides standard events. This keeps session logs readable even if the plugin is later removed.
• ctx.fs has no move/delete, so archive uses ctx.shell (mkdir && mv) for the physical move; the workspace sandbox allows it because openspec/ lives inside the workspace.
• Approval state is per-session, folded from that session's command log — approving in one session does not approve in another.

Development

pnpm install
pnpm build      # tsdown: lib/index.js (host) + lib/client.js (client bundle)
pnpm test       # three suites: mock-runtime unit tests, real-filesystem smoke,
                # and a real-composition integration test (cordis + real
                # fs/commands/session-projection/llm services)

Requirements baseline: REQUIREMENTS.md.

License

MIT