pproenca 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 secondsapply_mode: "scratch"— scaffolded edits go to scratch dir first; user copies inaudit_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