SAXEM1997/specpowers

English | 简体中文

specpowers

SDD + TDD engineering development methodology — DeepSeek Harness plugin + Claude Code skill group

specpowers blends OpenSpec (spec-driven development) with Superpowers (test-driven discipline), bridging the two into a complete Phase 0→4 development workflow through a set of adapter instructions. It prevents requirement drift (building things nobody needs) and implementation defects (building the needed things wrong), and its stage-by-stage review Gates across the whole workflow guard against context rot and deliverable-quality decay.

flowchart LR
    classDef src fill:#ddf4ff,stroke:#0969da,stroke-width:2px,color:#0a3069
    classDef dsh fill:#ddf4ff,stroke:#0969da,stroke-width:2px,color:#0a3069
    classDef cc fill:#fff8c5,stroke:#9a6700,stroke-width:2px,color:#7d4e00
    classDef cx fill:#f6f8fa,stroke:#8c959f,stroke-width:2px,color:#57606a,stroke-dasharray:6 4

    SRC["skills/ — single source of truth<br/>6 skills · refs/ · scripts/"]:::src

    SRC ==> DSH["DeepSeek Harness"]:::dsh
    SRC ==> CC["Claude Code"]:::cc
    SRC -.->|reserved · unverified| CX["Codex CLI"]:::cx

    DSH --> D["package.json · cordis.patch.yml<br/>lib/index.js → ctx.skills<br/>the skill tool · bare names"]:::dsh
    CC --> C[".claude-plugin/plugin.json<br/>skills: ./skills<br/>the Skill tool · bare names + plugin-prefix fallback"]:::cc
    CX --> X["target location<br/>.agents/skills/ · one dir per skill"]:::cx

Skill Group Architecture

specpowers (entry — decision tree + routing + state machine)
  ├── specpowers-design  Phase 0+1: requirements clarification → OpenSpec format conversion
  ├── specpowers-plan    Phase 2: OpenSpec → TDD plan bridging
  ├── specpowers-apply   Phase 3: subagent-driven TDD implementation + Gate 3 review
  ├── specpowers-review  review system: two-tier routing (critical/full) / final read-through
  └── specpowers-archive Phase 4: hard Gate chain verification + archiving

Skill	Phase	Responsibility
specpowers	Global	Execution-mode decision (tiny/medium/complex/large-scale) + routing + state machine
specpowers-design	0+1	brainstorming → OpenSpec format conversion + Gate 0/1
specpowers-plan	2	writing-plans bridging + Gate 2
specpowers-apply	3	subagent-driven TDD, one task at a time + code-review + spec-compliance-check
specpowers-review	Cross-cutting	Two-tier routing (auto-decided by rounds × size: critical/full review) / anti-degradation mechanisms
specpowers-archive	4	Full test suite → openspec validate → archive → integrity verification

Installation

Prerequisites

Tool	Purpose	Installation check
DeepSeek Harness or Claude Code	Runtime environment	dsh --version / claude --version
superpowers-dsh (DSH) or Superpowers (Claude Code)	TDD skill group (hard dependency)	see Dependency Setup below
OpenSpec CLI	SDD spec management (hard dependency)	openspec --version
CodeGraph (optional)	Code knowledge graph	.codegraph/ directory at repo root / MCP codegraph_explore
Graphify (optional)	Multimodal knowledge graph (architecture understanding)	/graphify command

Install in DeepSeek Harness

Simplest — run from any directory:

npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/specpowers

To pin a reproducible version, append a tag after # (recommended for production):

npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/specpowers#v1.0.0

Without #, the current main HEAD is installed — what you get today may differ from what you get later. dsh plugin is backed by pnpm, so a commit SHA works after # too.

After installation, restart the profile (stop it and run dsh web / npx @deepseek-ai/dsh web again), then refresh the browser.

You can also let DeepSeek Harness install it itself — open a new conversation and send it this message:

Please install the plugin from this link: https://github.com/SAXEM1997/specpowers

Restart and verify the layer has been composed:

dsh --profile web --dump-config     # a specpowers line must appear

Afterwards the 6 skills appear in the agent skill catalog (specpowers is the entry skill) and can be loaded with the skill tool.

To uninstall:

dsh plugin --profile web remove specpowers
# restarting the profile is likewise required after uninstalling

You must use the dsh plugin form — a plain npm install specpowers only installs the package as an ordinary library into the current directory and never registers it into any profile, so the skills would never be loaded.

Install in Claude Code

Option 1: Plugin Marketplace (recommended)

/plugin marketplace add https://github.com/SAXEM1997/specpowers.git
/plugin install specpowers@specpowers-marketplace

Option 2: Manual installation

git clone https://github.com/SAXEM1997/specpowers.git
cp -r specpowers/skills/* ~/.claude/skills/
cp -r specpowers/commands/* ~/.claude/commands/

Dependency Setup

specpowers itself ships only the workflow skills; two dependency groups must be installed separately. The .claude/ directory is user-local generated content — it is not distributed with this repository and must be regenerated by the steps below.

1. OpenSpec CLI (required)

npm install -g @fission-ai/openspec
openspec init --tools claude     # Claude Code: generates .claude/skills/openspec-*/ and .claude/commands/opsx/
openspec init --tools codex      # Codex: generates .agents/skills/openspec-*/

The openspec-* skills and /opsx:* commands generated by openspec init are owned by OpenSpec and refreshed by openspec update — do not hand-edit them.

2. Superpowers skill group (required)

DSH users:

npx @deepseek-ai/dsh plugin --profile web add superpowers-dsh

Claude Code users: install the superpowers plugin.

specpowers hard-depends on 8 upstream skills; when one is missing, the corresponding Phase cannot run:

brainstorming, writing-plans, subagent-driven-development, test-driven-development, systematic-debugging, requesting-code-review, verification-before-completion, finishing-a-development-branch

3. CodeGraph / Graphify (optional) — affects architecture-understanding capability only, not workflow execution.

Project Initialization

To enable specpowers in a target project:

□ Run openspec init (generates the openspec/ directory and tool integrations)
□ Install the superpowers skill group (see above)
□ Create the docs/superpowers/ directory structure
□ Configure TEST_COMMAND (full test command, optional)

See skills/specpowers/refs/project-template.md for the project template.

Quick Start

Trigger it in natural language:

• "Start the specpowers workflow"
• "Develop this feature with SDD+TDD"
• "Begin the specpowers workflow for this new feature"

Claude Code users can also use the /specpowers slash command. DSH users simply load the entry skill directly: skill(name: "specpowers").

Execution Modes

The entry skill decides automatically by file count + complexity:

Mode	Files	Phase flow	Review
Tiny	1-3	Light exploration → subagent execution → done	Auto-decided by two-tier routing
Medium	4-19	Full Phase 0→1→2→3→4 pipeline	Auto-decided by two-tier routing
Complex	20-49	Phase 2 enables UltraPlan	Auto-decided by two-tier routing
Large-scale	50+	Phase 2 enables Workflow	Auto-decided by two-tier routing

Phase Workflow

Phase 0: requirements clarification + approach design (brainstorming)
  ├── explore project context
  ├── ask clarifying questions in sequence
  ├── approach discussion + design presentation (section-by-section approval)
  ├── write the design doc + self-review
  └── approval Gate → Gate 0 review
       ↓
Phase 1: OpenSpec format conversion + cross-check verification
  ├── design doc → OpenSpec four-piece set (proposal/design/specs/tasks)
  ├── mandatory cross-check verification (vs original requirements)
  └── manual review → Gate 1 review
       ↓
Phase 2: bridging stage (writing-plans)
  ├── OpenSpec artifacts → Superpowers TDD plan
  ├── granularity conversion + scenario→test mapping
  └── Gate 2 review
       ↓
Phase 3: subagent-driven TDD implementation
  ├── each task executed by an independent sub-agent (fresh context)
  ├── RED-GREEN-REFACTOR-COMMIT executed per task
  ├── code-review + spec-compliance-check
  └── Gate 3 review
       ↓
Phase 4: verification + archiving
  ├── full test suite Gate
  ├── openspec validate Gate
  ├── /opsx:archive Gate
  └── integrity verification Gate

Review System

The review tier is decided automatically by the two-tier routing matrix inside specpowers-review (review rounds × artifact size × line-count floor + the ★ convergence gate); users can override manually:

• Critical: tiny tasks end-to-end, medium tasks from round 2 on (alignment + supervision, 2 agents, ~0.4x tokens); ★ convergence gate: medium tasks from round 2 on upgrade to Full when the previous round had p0_raw>0 (conservative raw caliber)
• Full: first-round reviews, complex/large-scale tasks; code artifacts fork into bucket sub-paths — reinforced review (<10 files: code-review + single alignment pass) / UltraReview (≥10 files: 6-agent team); document artifacts use a 3-agent multi-model progressive review

All anti-degradation mechanisms are preserved, with additional guards for tier routing.

Multi-Model Progressive Review

Three agents review independently in parallel, each on a different model: structure agent (completeness/redundancy/consistency, strong-reasoning model), grounding agent (executability/compatibility/edge cases, fast model), alignment agent (alignment with original requirements/omission detection/ambiguity identification, a model different from the other two).

UltraReview

A 6-agent team review (build/code/specs/docs/deps/alignment) with a Step A-F per-finding analysis protocol.

Convergence Check

Issue counts use five calibers (authoritative definition: see the review skill's issue-count caliber section): p*_raw audit baseline (not used in trigger computation), p*_merged verdict caliber, p*_rejected not-included count, p*_supplement supervisor-added count, and post-fix remaining p0/p1/p2 (used solely for the P0 blocking verdict). After every Gate review a convergence verdict is emitted (marked [CONVERGENCE_CHECK]), computed from this round's merged issue counts p*_merged (post-dedup, post-noise-filter issue counts — so multi-agent duplicate reports cannot inflate the totals into a needless extra round) against 5 trigger conditions (any one met → continue another round by default): ① p0_merged > 1; ② p1_merged > 5; ③ P0+P1+P2 combined > 10; ④ all levels combined > 20; ⑤ this round's p1_merged grew by more than 3 versus the previous round (when either round has caliber=raw, both rounds are compared on p1_raw). Exit happens only when none are met or the user explicitly terminates (action=exit), followed by the final read-through. Anti-laziness companions: RAW_COUNT structured counting + a merge-table sources conservation equation (Σ(source entries) + Σp*_rejected == Σp*_raw + Σp*_supplement, exact arithmetic; p*_supplement counts only finding-type additions from the supervisor's cross-verification — adopted ones count into p*_merged, rejected ones into p*_rejected; correction-type items are not counted, they are recorded only in the audit notes) + forced independent verification on abnormal rejection rates (agent_rejected + user_rejected > 3 items, or > 30% of Σp*_raw; including the reinforced-review path, which then no longer skips Step 3) (with one exception: at N==0 the check moves to an independent Step 5 review instead of Step 3) + severity-calibration sampling whenever p0_raw ≥ 1 or p0_rejected ≥ 1 or agent_rejected ≥ 1 or user_rejected ≥ 1. Verification-intensity decisions (Step 3 supervisor deployment and the tier convergence gate) deliberately keep the conservative raw counts — Step 3 deploys in three tiers by issue count N (raw caliber): p0_raw≥3 or N>15 → standalone supervisor, all 4 dimensions; N∈[1,15] with p0_raw≤2 → absorbed into Step 5; N==0 → trivial; the reinforced-review path has no independent verifier for the merge table, so its convergence check falls back to the merge-table-independent raw counts (not an extra safeguard, see the review skill's authoritative caliber definition).

Platform Adaptation

Platform	Skill invocation form	Skill source path	Status
DeepSeek Harness	skill(name: "specpowers")	plugin package skills/, registered into the host skill registry by the lib/index.js provider	✅ Implemented
Claude Code	bare name when available: Skill({skill: "specpowers"}); falls back to Skill({skill: "specpowers:specpowers"}) when the skill registry requires a plugin namespace	skills: "./skills" in .claude-plugin/plugin.json	✅ Implemented
Codex CLI	skill called by bare name (skills-only tooling)	.agents/skills/<name>/SKILL.md	🔲 Reserved · Unverified

For the full mapping of platform differences (tool correspondence, degradation paths when hooks or slash commands are missing) see skills/specpowers/refs/platform-tools.md.

Repository Layout

specpowers/
├── package.json                       # DSH plugin manifest (dsh.bundle.patch)
├── cordis.patch.yml                   # DSH bundle-layer patch
├── lib/index.js                       # DSH skill provider (ctx.skills)
├── scripts/verify-dsh-provider.mjs    # packaging self-check (zero dependencies)
├── .claude-plugin/                    # Claude Code manifests
│   ├── marketplace.json
│   └── plugin.json
├── skills/                            # ★ the single source of truth for skills on both platforms
│   ├── specpowers/SKILL.md            # entry skill
│   │   ├── refs/                      # getting-started guide, project template, UltraPlan prompt, platform adaptation
│   │   └── scripts/                   # state machine / guard / hook validation (zero dependencies)
│   ├── specpowers-design/SKILL.md     # Phase 0+1
│   ├── specpowers-plan/SKILL.md       # Phase 2
│   ├── specpowers-apply/SKILL.md      # Phase 3
│   ├── specpowers-review/SKILL.md     # review system
│   └── specpowers-archive/SKILL.md    # Phase 4
├── commands/specpowers.md             # Claude Code /specpowers command
├── static/logo.png                    # hero image (text-to-image generated)
├── docs/superpowers/{specs,plans}/    # this project's designs and plans (development history)
├── AGENTS.md                          # vendor-neutral project instructions (source of truth)
├── CLAUDE.md                          # Claude Code entry (imports AGENTS.md)
├── README.md / README.en.md
├── NOTICE
└── LICENSE

.claude/ (OpenSpec-generated) and .superpowers/ (runtime state) are user-local content, excluded via .gitignore.

Development

Skill files are Markdown + YAML frontmatter. After editing, make sure the frontmatter name and description are well-formed, cross-skill reference names match reality, and required sub-skill paths are correct.

Run the packaging self-check (zero dependencies; validates manifest validity + the provider list()/get() contract + relative-resource reachability):

node scripts/verify-dsh-provider.mjs

A second zero-dependency check guards against leaking internal or credential material:

node scripts/verify-no-internal-refs.mjs

It scans tracked files and commit messages for internal TLDs, private IPv4 ranges, credential prefixes and private keys; project-specific hostnames come from the gitignored .internal-refs.txt, so the script itself is safe to publish. Wire it into a pre-push hook or CI.

Required reading before changing the frontmatter parser: DSH routes skills solely by description. The parser in this repo's lib/index.js supports 4 scalar forms (single-line, folded blocks >/>-, literal blocks |/|-, and multi-line plain continuations). If it degrades to single-line scalars only, the description of specpowers and specpowers-review collapses to the literal strings ">"/">-", and the description of specpowers-design and specpowers-plan gets truncated — the skills become visible but never selectable. Always run node scripts/verify-dsh-provider.mjs after changing the parser.

The skill eval suite lives in skills/*/evals/: declarative YAML cases plus rule-based assertions. The runner is the open-source skill-up project (Alibaba, Apache-2.0); this repo's eval.yaml (schema_version: v1alpha1) and cases/*.yaml are its eval format.

curl -fsSL https://raw.githubusercontent.com/alibaba/skill-up/main/install.sh | bash

skill-up validate <path>
skill-up run <path>

<path> is the skill directory (a skill's evals/ sits next to its SKILL.md); validate checks the cases and run executes the suite, writing output to <skill>-workspace/ in that directory (e.g. iteration-1/result.json), which .gitignore already excludes. skill-up ships four built-in Agent Engines — claude_code / codex / qodercli / qwen_code — plus custom engines via engine.custom; DeepSeek Harness is not a built-in engine, so the suite must run under one of those built-in engines or a custom engine. See the upstream docs for authoring new cases.

See AGENTS.md for the development workflow and key design decisions.

License

MIT, see LICENSE. Upstream skill content is adapted from Superpowers (MIT, Copyright (c) 2025 Jesse Vincent) and OpenSpec (MIT, Copyright (c) 2024 OpenSpec Contributors); the full upstream copyright notices are in NOTICE.