dx-harness

DX Harness

Audits, scaffolds, and maintains the developer-experience harness of a repository. The harness is the meta-tooling that makes a dev loop fast: one-command bootstrap, one-command reset, one-command seed, discoverable conventions, agent-friendly entry points.

This skill exists because dev-experience attrition is real: harnesses rot, manual steps creep back in, conventions drift, and the cost is paid in micro-friction every day. The skill detects attrition systematically and applies canonical fixes.

When to Apply

Trigger this skill when:

• A user describes a repeated manual chore ("every time I reset the db I have to re-register", "I always run these three commands before working")
• A user mentions slow onboarding or asks "how do I get this running"
• A new repo is being bootstrapped and needs a harness from day one
• A user explicitly asks to audit DX or measure time-to-first-commit (TTFC)
• A user asks to fix missing bootstrap/reset/seed scripts or AGENTS.md
• A periodic maintenance pass is needed (e.g., after a release, after onboarding a new engineer)

Workflow Overview

┌────────────────────────────────────────────────────────────┐
│  1. DISCOVER     scripts/discover.sh → repo-fingerprint    │
│  2. AUDIT        scripts/audit.sh    → dx-audit.json       │
│  3. PRIORITIZE   scripts/prioritize.sh → ranked findings   │
│  4. SCAFFOLD     scripts/scaffold-*.sh → scratch dir       │
│  5. CONFIRM      show diff to user; user picks what to apply│
│  6. VERIFY       scripts/verify.sh → assertions + timing   │
│  7. TRACK        scripts/track-attrition.sh → audit log    │
└────────────────────────────────────────────────────────────┘

All scaffolded edits land in a scratch directory first (${TMPDIR}/dx-harness-<timestamp>/). The user reviews the diff and chooses what to copy back into the repo. No surprise writes to the working tree.

Tool Requirements

Required: bash, git, node, jq.

Detected at runtime (the skill adapts — it never forces a migration):

Toolchain	Detection signal
npm/pnpm/yarn/bun	package.json, pnpm-lock.yaml, yarn.lock, bun.lockb
cargo	Cargo.toml
go modules	go.mod
Python (uv/poetry/pip)	pyproject.toml, uv.lock, poetry.lock, requirements.txt
just	Justfile or justfile
make	Makefile
docker compose	docker-compose.yml, compose.yaml
database (postgres)	docker-compose.yml services, DATABASE_URL env reference

Risk Level

Write. The skill writes files but does not delete user data, force-push, or run destructive ops. Default mode stages everything in a scratch directory; the user explicitly approves each application. Verification runs in a separate git worktree so timing measurements never touch the working tree.

Setup

On first invocation, the skill checks config.json and prompts via AskUserQuestion for any empty required fields. See config.json for fields and defaults.

Key defaults:

• ttfc_target_seconds: 60 — the time-to-first-commit goal in seconds
• apply_mode: "scratch" — scaffolded edits go to scratch dir first; user copies in
• audit_log_path: "${CLAUDE_PLUGIN_DATA}/dx-harness/audits.log" — persistent attrition history

Quick Reference

Run a full audit + scaffold pass

bash scripts/discover.sh > /tmp/fingerprint.json
bash scripts/audit.sh /tmp/fingerprint.json > /tmp/audit.json
bash scripts/prioritize.sh /tmp/audit.json

Scaffold one specific harness piece

bash scripts/scaffold-bootstrap.sh   /tmp/fingerprint.json
bash scripts/scaffold-reset.sh       /tmp/fingerprint.json
bash scripts/scaffold-seed.sh        /tmp/fingerprint.json
bash scripts/scaffold-agents-md.sh   /tmp/fingerprint.json
bash scripts/scaffold-justfile.sh    /tmp/fingerprint.json

Verify the harness works end-to-end

bash scripts/verify.sh
# runs bootstrap in a scratch worktree, times it, asserts TTFC < target

Track attrition over time

bash scripts/track-attrition.sh /tmp/audit.json
# appends to audits.log, prints diff vs previous run

How to Use

The workflow scripts produce JSON between steps so they compose. The agent should read references/workflow.md for full step-by-step orchestration, including error handling and when to stop and ask the user.

For deeper context:

File	Read When
references/workflow.md	Executing the workflow (always start here)
references/audit-checklist.md	Understanding what audit.sh checks and why
references/fix-recipes.md	Choosing which scaffold script applies for a finding
references/attrition-patterns.md	Reading git history for DX-rot signals

Gotchas

See gotchas.md — accumulated failure points discovered over time. Always append new ones rather than rewriting.

Related Skills

• dev-skill:* — for creating new agent-friendly skills (often the output of an AGENTS.md scaffolding pass references skills)
• bug-review — pairs naturally: bad DX often surfaces as repeat bug categories