dh

SAM-style feature initiation workflow — discovery through codebase analysis, architecture spec, task decomposition, validation, and context manifest. Use when a user asks to add a feature, plan a feature, or convert an idea into an executable SAM plan.

Use when analyzing failing test cases to determine whether failures indicate genuine bugs or test implementation issues. Activates on "analyze failing tests", "debug test failures", "investigate test errors", or when provided with specific failing test names or output. Applies balanced investigative reasoning — does not auto-fix tests without establishing root cause.

Fetch and report current API syntax, changelog entries, and breaking changes for a specific library or protocol version. One research angle within a parallel technical-research set — runs independently and returns a structured cited report. Invoke when a specific library name and version are the target.

How to determine which backlog backend a project is configured to use, and what to do with the answer. Use when about to call a backend-specific tool, choosing between a GitHub-only and a Beads-native operation, or reporting which store a result came from.

Use when orchestration or planning agents are producing task plans, task prompts, or TASK.md instructions that must be unambiguous, verifiable, and resistant to hallucination. Applies CLEAR (Concise, Logical, Explicit, Adaptive, Reflective) to structure and write agent task prompts, then adds CoVe (Chain of Verification) checks where accuracy risk is meaningful. Activates on draft task prompts, swarm plans, migration tasks, and multi-step plans requiring independently executable steps.

Use when a task asks for architecture review, dependency graph visualization, module coupling analysis, or circular dependency detection. Auto-detects scope (git diff → PR diff → full project). Reads project config (pyproject.toml, tsconfig.json, go.mod, Cargo.toml) to establish the intra-project module namespace before parsing imports. Builds a module-dependency graph across Python, TypeScript, JavaScript, Go, Rust, and Java. Detects cycles via graphify output or an executable Python script. Checks Conway's Law alignment against CODEOWNERS and directory structure. For Claude plugin repos, also traces cross-language chains: hook configs → hook scripts, SKILL.md/agent docs → node/uv-run scripts, PEP 723 inline deps, and MCP tool calls. Emits Mermaid flowcharts with severity color-coding (red = circular dep, yellow = high-coupling, green = clean, blue = Conway violation). Applies recursive semantic partitioning for graphs > 40 nodes. Registers each diagram as a codebase-analysis artifact.

Loaded automatically when reviewing Claude skills or agent definitions — covers SKILL.md structure, frontmatter validity, token budget, description quality, and agent contract compliance.

Reviews CLI application code for correctness and quality. Use when reviewing tools that use argparse, click, typer, commander.js, or similar argument parsers — covers exit codes, help flags, stdin/stdout/stderr separation, non-interactive operation, signal handling, argument validation, ANSI color safety, and dry-run support for destructive operations.

Use when reviewing AI/ML code or LLM integration — activates on prompt templates, model selection logic, token budget concerns, or evaluation harness code. Enforces prompt hygiene, model tier matching, context window management, token economics, structured output validation, temperature settings, retry logic, streaming error handling, and PII/safety rules.

Applies Node.js-specific code review patterns for async I/O, streams, security, process management, and dependency hygiene. Use when reviewing Node.js server code, route handlers, middleware, or any JavaScript file alongside package.json without TypeScript. Triggers on sync I/O in request paths, missing stream backpressure, process.exit misuse, eval/exec injection risks, wildcard version ranges, missing lockfiles, EventEmitter cleanup gaps, and unvalidated environment variables at startup.

Provides Python-specific code review rules for the dh code-reviewer agent. Activates on pyproject.toml or *.py file detection — enforces uv, ruff, ty, pytest, type annotation, error handling, and Python 3.11+ idioms including pathlib, match statements, and modern union syntax.

Provides TypeScript-specific code review patterns covering strict mode, ESM, type safety, branded types, discriminated unions, async patterns, runtime safety, and common anti-patterns. Activates on detection of tsconfig.json, *.ts, or *.tsx files during code review — loaded automatically by dh:code-reviewer.

Use when reviewing web frontend code — HTML, CSS, JSX, or browser-targeted JavaScript. Enforces accessibility (WCAG AA, aria labels, focus management), XSS prevention (innerHTML, dangerouslySetInnerHTML), performance (layout thrash, CLS, lazy loading), CSS design tokens, form labeling, and event listener cleanup. Loaded by dh:code-reviewer on *.html, *.css, *.jsx detection.

Local codebase analysis research angle — derives behavioral contracts, coding conventions, SKILL.md flow insertion points, and agent data availability maps from actual source files. Use when the blocking question is answered by reading the repository: what does this function actually do, what pattern does the codebase use for X, where in this workflow does a new step go, or what data does this agent already have.

Execute large-scale automated code transformations safely and idempotently. Use when renaming symbols across a codebase, migrating API call-sites, enforcing new patterns at scale, or applying structural edits to many files at once. Triggers on: 'codemod', 'mass rename', 'migrate all usages', 'transform codebase', 'apply pattern at scale', AST-based refactoring, or any task requiring consistent edits across 10 or more files.

Use when all tasks for a feature are marked COMPLETE — runs holistic quality gates including code review, feature verification, integration check, documentation drift audit and update, and context refinement. Creates follow-up plans when issues are found.

Close a completed GitHub milestone. Args: {milestone-number}. Audits open and closed issues, offers to carry forward open items to a new or existing milestone, closes the GitHub milestone, updates Project V2 Status to Done for closed issues, and generates a completion summary. Use when a sprint or release is finished and needs to be officially closed.

Use when reviewing test suites for coverage, isolation, mock usage, naming conventions, or completeness. Activates on "review test coverage", "audit test quality", or "check tests for completeness" requests. Performs thorough checklist-driven review covering test isolation, mock correctness, AAA pattern adherence, and naming standards.

Use when the PLAN artifact from SAM Stage 2 needs contextualization against actual codebase state — grounds the design plan in reality by performing scope analysis (NEW/MODIFY/COMPLETE classification), conflict detection between plan assumptions and codebase patterns, and resource mapping to concrete file paths and integration points. Produces an updated ARTIFACT:PLAN registered via MCP with a Contextualization section appended.

Register a plan artifact via the MCP backlog server. Use when you produce a document or report that downstream agents or worktree-isolated environments need to retrieve — feature-context, codebase-analysis, architect, T0-baseline, TN-verification, or research artifacts. Triggers include "store an artifact", "register a plan artifact", "write a report to the backlog", "upload artifact content".

Routes to the correct dh skill entry point by intent. Use when unsure which development-harness skill to invoke, starting a development workflow, or invoking /dh directly. Covers capture, groom, plan, execute, single task, quality gates, and milestone routing.

Gives the dh CLI command and the directory of dh's scripts, both resolved from this skill's own directory. Use before running a dh plan, backlog, artifact or dispatch command, or a script from dh's scripts directory, and when an mcp__plugin_dh_* server failed to connect.

One-line definitions of development-harness (dh) plugin terminology — RT-ICA, ARL, SAM, the S1-S7 pipeline stage names, Impact Radius — each with a pointer to its canonical source file. Use when a dh skill, agent, or workflow step references a term without defining it, before guessing what the term means from its observed outputs, or when asked what a dh concept or acronym stands for.

Development harness plugin documentation index. Use when looking up SAM pipeline, backlog lifecycle, SDLC layers, task/plan schema, plan artifacts, quality gates, impact analysis, or dispatch schema documentation.

Use when starting a new feature, gathering requirements for an unfamiliar domain, refining a vague idea into actionable scope, or when a user request is ambiguous or underspecified. Conducts SAM Stage 1 discovery — structured requirements gathering through user discussion, asking WHO/WHAT/WHEN/WHY and never HOW. Produces the ARTIFACT:DISCOVERY document containing feature requirements, NFRs, goals, anti-goals, references, and resolved questions. Supports backlog item self-initialization via a

Orchestrate parallel agent dispatch as a manager — not a micromanager. Use when coordinating 2+ independent workers, running SAM task waves, relaying discoveries between worker waves, handling blockers, or synthesizing results. Covers both SAM structured dispatch (the task does the work) and ad-hoc dispatch (reference agent-orchestration for prompt template).

Which agent a dh workflow dispatches, and the artifact consumer invariant.

Research community usage patterns, real-world gotchas, and client compatibility for a specific known library, tool, or protocol feature. Use when a technical-researcher orchestrator needs community-sourced evidence about a named library or feature — bug reports, workarounds, compatibility gaps, and patterns from issue trackers and discussions. Distinct from the broad ecosystem-researcher agent — this skill targets a KNOWN entity and mines what real users have actually experienced, not what exists in a domain.

Evaluate and iterate on the SDLC Layer Separation Architecture implementation. Runs validation checks (cross-references, doc completeness, layer metadata, integration points), produces a findings report, and supports iterative fixes. Use when validating first-pass implementation, before claiming layer work is complete, or when improving layer docs/schema.

Executes SAM Stage 5 — opens an attempt on a single ARTIFACT:TASK, dispatches it to a fresh stateless agent session, runs quality gates, and records an ARTIFACT:EXECUTION with implementation results and verification output on the task. Use when Stage 4 Task Decomposition is complete and tasks are ready for execution, when re-executing a task after Stage 6 returns NEEDS_WORK, or when dispatching a task to a language-appropriate specialist agent via the development harness pipeline.

Verify claims in backlog items, skill documentation, or plugin content against primary sources. Spawns parallel @dh:fact-checker agents using mcp__Ref, mcp__exa, mcp__context7 as primary tools — training data recall is rejected as evidence. WebFetch/WebSearch are last-resort fallbacks. Produces VERIFIED/REFUTED/INCONCLUSIVE verdicts with citations. Triggers on "fact check", "verify claims", "check against primary sources", or when backlog items are marked UNVERIFIED.

Classify changed prose files into review tiers before deciding SKIP. Use when reviewing a diff containing prose files.

Certifies that a feature achieves its original objectives via goal-backward verification (SAM Stage 7). Use when all tasks pass forensic review — starts from expected outcomes, works backwards to verify each was achieved, and returns CERTIFIED or NOT_CERTIFIED with specific gaps.

Investigate why something happens — confirm the question and success criteria with you, then trace the root cause with an evidence chain.

Use when SAM Stage 5 Execution has completed and task results need independent verification against acceptance criteria. Dispatches a separate reviewer agent to fact-check implementation outputs and returns COMPLETE or NEEDS_WORK with specific findings and remediation tasks.

Single-verb branch-to-PR quality gate pipeline. Use when the user wants to gate, push, and open a PR for a branch in one command.

Generates one worker task prompt conforming to the CLEAR + selective CoVe task design standard and swarm-task-planner structure. Use when creating or rewriting a single task entry or task block inside a plan — providing a title and brief description as input.

Grooms a GitHub milestone for parallel execution — batch-grooms ungroomed items, assesses scope gaps, analyzes cross-item dependencies via Impact Radius overlap, builds conflict groups, assigns items to execution waves, and persists the dispatch plan via dispatch_create_plan MCP tool. Calls dispatch_wave_start per wave to register state. Use when preparing a milestone for /work-milestone execution. Pass the milestone number as the first argument. Requires milestone items assigned via /group-items-to-milestone.

Use when assigning backlog items to a GitHub milestone. Args: {milestone-number} [P0|P1|P2|title-filter]. Uses backlog list to load items, shows items with GitHub Issue status, lets user select which to assign. Creates missing GitHub Issues for selected P0/P1 items, assigns all to the milestone, updates Project V2 Status to Backlog. Use after create-milestone to populate a sprint or release.

Quantitative cost measurement for technical research — token injection costs, payload sizes, context window consumption, and file-level counts from actual repo files. Use when a technical-researcher orchestrator needs the cost dimension of adding or changing something: how many tokens will it inject, how big are the artifacts, what is the context window impact? This is NOT blast-radius analysis (which files break) — it covers size, tokens, and performance cost only.

Use when the plan_ref returned by add-new-feature is provided. Executes the SAM implementation loop — opens an attempt per ready task, dispatches each to a specialist agent in parallel, settles and judges what comes back, manages bookend tasks (T0 baseline capture and TN verification), and tracks concerns and contract violations per task. Drives task state through the work ledger via the SAM CLI.

Manages feature implementation task state via SAM MCP tools. Use when querying task status, listing ready tasks, dispatching tasks for execution, updating task timestamps, or coordinating multi-task feature rollout. Activated by the /dh:execution orchestrator to track progress — also activates directly when managing tasks.

Routes a Superpowers plan file through the /work-backlog-item pipeline and writes SAM task back-references and chunk annotations into the original plan. Use when given a path to a Superpowers plan file via $ARGUMENTS and needing to create a linked backlog item plus SAM task plan.

Spawn and manage persistent interactive Claude Code CLI sessions with bidirectional communication via tmux. Provides spawn, send, read, status, list, and kill subcommands for orchestrating parallel peer sessions. Uses built-in --worktree and --tmux flags. Sessions stay alive for multi-turn steering. Triggers on "spawn claude session", "launch separate claude", "peer session", "inter-session communication", "shadow clone", "kage bunshin".

Entry point for refreshing the DH workflow graph. Use when skills, agents, Mermaid flowcharts, MCP tools, or artifact flows change and docs/dh-workflow-graph.json must remain current.

Use when a diff needs four parallel perspective reviewers (Security, Performance, Quality, Accessibility). Creates an ephemeral SAM plan, collects structured verdicts, synthesizes them into one deduplicated cross-referenced punch list, prints one summary line per perspective, and exits non-zero if any perspective returns REJECT. SKIP is a passing outcome.

Same reverse-thinking method as dh:rt-ica (see dh:rt-ica or dh-glossary for the definition), but localizes any MISSING input to the affected task only, as a non-blocking information-completeness pre-pass before task decomposition and plan generation. Use when grooming backlog items, generating plans, decomposing tasks under uncertainty, or working in brownfield and refactor scenarios. Produces completeness summary (APPROVED-FOR-PLANNING, APPROVED-WITH-GAPS, or BLOCKED-FOR-PLANNING), missing input report with dependency mapping, required unblock actions, and planning annotations for downstream tasks. Use dh:rt-ica instead at the S2 implementation gate where missing inputs must halt execution.

Use when Stage 1 Discovery is complete and design must begin — transforms the ARTIFACT:DISCOVERY into an actionable ARTIFACT:PLAN via RT-ICA prerequisite verification. Produces approach, components, success criteria, acceptance tests, and risks. Blocks on missing prerequisites before design proceeds.

Synthesis step in the multi-angle technical research pipeline. Receives structured outputs from all four research angles (api-state, ecosystem-research, impact-measurement, codebase-auditor), applies cross-angle signal weighting and conflict resolution, and produces a single synthesized Research section. Invoked by the technical-researcher orchestrator after all angle skills complete. Returns content to the orchestrator — does not write to the backlog.

Load the shared verdict, punch-list, SKIP, and gate schema used by the dh multi-perspective review orchestrator, reviewers, and synthesizer. Use only when one of those components must produce, parse, validate, or gate review results.