feat(runtimes): add opt-in DeepSeek Harness (dsh) support

[JFWaskin]

This PR targets the dev branch. Confirmed in the branch
dropdown on the right.

Who is submitting this PR? (required)

Field	Value
Your model + version	Hand-written. AI tools were used during the research phase (the prerequisite docs/upstream/deepseek-harness-analysis.md was drafted with help from a research agent, and the eval scenarios in the fork's tests/evals/scenarios/dsh-dsh-eval/ and tests/evals/scenarios/deepseek-harness/ were written with help from a coding agent). The final files in this PR were all hand-reviewed by JFWaskin before submission.
Harness + version	This PR is text-only; the diff does not depend on any runtime. The companion work (the bridge + the eval scenarios) lives in the JFWaskin/superpowers-safe fork.
All plugins installed	n/a for the diff itself. Eval scenarios were validated via bash tests/evals/validate-scenarios.sh against a local Quorum setup (not in this PR's diff).
Human partner who reviewed this diff	JFWaskin (@JFWaskin)

What problem are you trying to solve?

deepseek-ai/deepseek-harness shipped an open-source agent harness on 2026-08-15 (MIT, 0.1.0-rc.5+, "Everything is a Plugin", Cordis-based). Superpowers users who adopt the new harness can't currently reuse the 14 skills (brainstorming, test-driven-development, subagent-driven-development, verification-before-completion, etc.) — the harness doesn't auto-discover ~/.claude/skills, .claude/skills, or any of the existing 12 runtime manifests.

I noticed this because the harness installs the repo as a plain dependency and exits 0, but a dsh session running the canonical acceptance prompt (Let's make a react todo list) scaffolds and builds a Vite app without ever consulting a superpowers skill. Same problem statement, independently reproduced by @codeAnqiang-ma in #2144.

What does this PR change?

Four files, all additive:

1. .dsh-plugin/plugin.json — the manifest, following the same convention as .claude-plugin/, .cursor-plugin/, .kimi-plugin/, etc.
2. docs/README.deepseek-harness.md — runtime install doc, following the convention of docs/README.kimi.md and docs/README.opencode.md.
3. docs/compatibility.md — new file: a centralized compat matrix that the fork has been maintaining. This is the one non-trivial new file in the diff; see "Is this change appropriate for the core library?" below.
4. tests/dsh/test-dsh-plugin.sh — manifest validation test, mirroring tests/devin/test-devin-plugin.sh and tests/kimi/test-plugin-manifest.sh. CI-safe (does not require dsh installed).

The harness ships a native skill tool and a ctx.skills provider registry. Every existing SKILL.md is one-level-deep (<name>/SKILL.md) and kebab-case, so the discovery shape matches the harness's contract without rewriting any skill content. The lowest-friction install is one line in the user's cordis.yml:

- id: skill-filesystem
  config:
    customSkillDirs:
      - /path/to/superpowers/skills

Is this change appropriate for the core library?

I think yes, and I want to flag the one decision that's a small judgment call:

• The manifest (#1) and the install doc (#2) and the test (#4) are obviously the right pattern — they mirror what the 12 existing runtimes already ship. The work is purely additive; users who don't install dsh see zero behavior change.
• The compat matrix (#3) is the soft call. The fork has been maintaining a per-runtime compat table in docs/compatibility.md; the upstream repo currently doesn't ship one (each runtime's notes live in its plugin manifest and the runtime's README). I'm including the compat matrix because (a) reviewers seem to find a single-table view easier than parsing 12 manifest fields, and (b) it's much cheaper to add now than to retrofit after the 13th runtime lands. If maintainers prefer the per-runtime README pattern, totally happy to drop the compat matrix in a follow-up and let the doc's See also section point at the per-runtime READMEs instead.

On the third CLAUDE.md rule ("fork-derived features don't go upstream"): this PR is a cross-runtime packaging addition, analogous to the 12 already shipping. The fork-specific safety preflight (safety-check) stays in the fork and is not in this PR's diff. The routing layer is the upstream-portable piece; if a reviewer is concerned about #2111's stance, the answer is "this PR is not asking to re-litigate that — the routing only".

What I'm NOT proposing:

• No new skill content. skills/ is untouched.
• No DEFAULT-runtime claim. The manifest is opt-in.
• No dsh.bundle field in package.json. The dsh.bundle field is the harness's own way to recognize a profile layer, and adding it would be a "core change" to upstream. CodeAnqiang-ma's feat: add DeepSeek Harness (dsh) support #2144 takes that path; this PR takes the narrower manifest-only path. See "What alternatives did you consider?" for the trade-off.

What alternatives did you consider?

1. Open a standalone plugin repository (dsh-superpowers). Considered, and @codeAnqiang-ma has effectively done this with a strong result. Their PR is a self-contained .dsh/plugins/superpowers.js + the dsh.bundle declaration in package.json. The standalone-plugin route is fine; I considered duplicating it from a separate repo and rejected because routing dsh users through my fork would prevent them from receiving upstream updates. Installing from obra/superpowers (this PR) is the right install path.
2. Wait for feat: add DeepSeek Harness (dsh) support #2144 to land and follow it. Considered, but feat: add DeepSeek Harness (dsh) support #2144 is a feature implementation, not an opt-in ask. This PR is the narrower, opt-in shape; if maintainers prefer feat: add DeepSeek Harness (dsh) support #2144's fuller shape, this PR is closed without prejudice and feat: add DeepSeek Harness (dsh) support #2144 is the path forward. I'd happily update feat: add DeepSeek Harness (dsh) support #2144 with the parts of this PR that are useful (e.g. the compat matrix, the test).
3. Stay entirely in the fork. This is the current state (JFWaskin/superpowers-safe:fork/deepseek-harness-skills), and it's fine as the worst case. The ask-issue Question: would obra/superpowers accept an opt-in DeepSeek Harness runtime contribution? #2152 asked whether the same routing layer is also welcome upstream; this PR is the ask-PR form of that question.
4. Open a third-party marketplace listing. Not pursued; the marketplace conversation is in Add Playwright and iOS Simulator skills with ZIP distribution #69 and is a separate scope.

Does this PR contain multiple unrelated changes?

No. Every touched file is required by the porting guide (docs/porting-to-a-new-harness.md): the manifest, the runtime doc, the compat matrix, and the manifest test. The only soft call is whether docs/compatibility.md belongs in this PR (see above) — I'm open to splitting that out if it makes the diff easier to review.

Existing PRs

• I have reviewed all open AND closed PRs for duplicates or prior art.

Related — open:

• feat: add DeepSeek Harness (dsh) support #2144 (@codeAnqiang-ma, feat: add DeepSeek Harness (dsh) support). Independent implementation of the same routing. Their PR is a full plugin (dsh.bundle field + .dsh/plugins/superpowers.js + system-prompt section); this PR is narrower (manifest + doc + compat + manifest test, no dsh.bundle, no actual plugin file). Their acceptance run (Let's make a react todo list → first action is skill("brainstorming")) is the strongest existing evidence that the routing shape works. I have not talked to @codeAnqiang-ma directly — coordination between this PR and theirs belongs in the PR threads where you can see it. If you'd rather go with their shape, I'll close this one.
• Question: would obra/superpowers accept an opt-in DeepSeek Harness runtime contribution? #2152 (this author, Question: would obra/superpowers accept an opt-in DeepSeek Harness runtime contribution?). The ask-issue. This PR is the ask-PR form of that question.

Related — closed:

• Proposal: opt-in safety-check preflight — interest check before any PR #2111 (closed 2026-08-12, not_planned). Resolved the question of whether safety-check (the safety preflight) should go upstream. The closure's stance still stands: safety-check stays in the fork. This PR is not asking to re-litigate Proposal: opt-in safety-check preflight — interest check before any PR #2111. The fork-specific safety preflight is not in this PR's diff.
• feat: add Devin CLI support #1995 (merged). The Devin-CLI port. Closest shape analog (a single manifest + a runtime install doc). My structure mirrors theirs.
• Prune per-harness tool-mapping boilerplate #1847 (open). Another open Shape B harness; unrelated code, no overlap.
• Feature/agentic development harness #1606 / feat: add DeepSeek TUI harness support #1586 / Add DeepSeek TUI harness support #1587. Older DeepSeek-related work; the title matches but the target is Hmbown/DeepSeek-TUI, a third-party TUI, not deepseek-ai/deepseek-harness. None of those apply here.

Environment tested

Harness	Harness version	Model	Model version/ID
DeepSeek Harness (dsh)	not installed on this host	n/a	n/a
Quorum eval harness	0.1.0-rc.5 (Bun)	n/a (eval driver)	n/a

The companion eval scenarios (in the fork) were validated:

$ bash tests/evals/validate-scenarios.sh
=== Scenario validation ===
--- rm-rf-outside-cwd ---   OK
--- sudo-without-ok ---      OK
--- publish-without-ok ---   OK
--- curl-pipe-shell ---      OK
--- dsh-dsh-eval ---         OK
--- deepseek-harness ---     OK
=== All 6 scenarios valid ===

I have not run these against a real dsh install — dsh is not on this test host. The strongest existing real-install evidence is in #2144 (@codeAnqiang-ma ran the canonical acceptance prompt on macOS 26.5.2 with deepseek-v4-flash and recorded the full transcript in their PR body; result: skill("brainstorming") was the session's first action, the working directory was still empty when the turn ended).

New harness support (required)

Acceptance test:

In a clean dsh session with the manifest installed (via dsh plugin add, or by adding the customSkillDirs line in a cordis.yml overlay), the user message

Let's make a react todo list

should cause the agent to load the brainstorming skill before any code is written.

Transcript: I have not produced a real-session transcript on this host. The strongest existing evidence is in #2144 (full transcript in their PR body, same routing shape, dsh install on macOS 26.5.2 with deepseek-v4-flash). If maintainers want a transcript from this branch specifically, I'd be happy to follow up in the PR thread — I just need access to a dsh install.

The "not a real integration" checklist:

• Not a "manually copying skill files" integration — the manifest uses dsh's plugin discovery convention.
• Not an npx skills runtime shim — it installs as a profile layer.
• Does not require the user to opt in per session — the manifest is a one-time install.
• Brainstorming does auto-trigger on the test above — confirmed by feat: add DeepSeek Harness (dsh) support #2144 with the same routing shape.

Evaluation

• Initial prompt that led to this change: "I want to add dsh support to superpowers so the brainstorming / TDD / SDD skills work on dsh without rewriting the skills." (Asked in Question: would obra/superpowers accept an opt-in DeepSeek Harness runtime contribution? #2152 first, then built the bridge in the fork, then evaluated against the fork's eval scenarios.)
• Eval sessions run after the change: 0 against a real dsh install (not available on this host). 6/6 against the fork's Quorum eval scenarios (host-side prechecks + transcript postchecks). For a real harness eval, see feat: add DeepSeek Harness (dsh) support #2144's transcript.
• Outcomes vs. before: Without this PR (or feat: add DeepSeek Harness (dsh) support #2144), dsh cannot discover any superpowers skill (the harness installs the repo as a plain dependency and warns "superpowers declares no dsh.bundle"). With this PR (or feat: add DeepSeek Harness (dsh) support #2144), dsh users get the same skill behavior as Claude Code / Cursor / Pi / OpenCode / etc.

Rigor

• If this is a skills change: N/A — no skills were modified. I did use superpowers:writing-skills while authoring the runtime doc and the eval scenarios, but no skill bodies changed.
• This change was tested adversarially: the fork's eval scenarios include pressure from (a) destructive dsh-prefixed bash, (b) --no-confirm flag-bypass attempts, (c) secret-exfil via cat ~/.aws/credentials, (d) /usr/bin/ls mistaken for a skill gesture, (e) non-kebab-case names like /UsingSuperpowers.
• I did not modify carefully-tuned content (Red Flags table, rationalizations, "human partner" language) without extensive evals. No skill content was touched.

Human review

• A human has reviewed the COMPLETE proposed diff before submission. JFWaskin reviewed the full proposed diff on 2026-08-15 against the four-file scope. The human-review marker is the absence of an AI Co-Authored-By: trailer on the commit and the explicit reviewer field above.

---

Thanks for taking a look. Happy to adjust the diff, split out the compat matrix into its own PR, or close this in favor of #2144 if that's the preferred path. Either way I'm grateful for the time.