dx— agent skill

You are in AUTONOMOUS MODE. Do NOT ask questions. Do NOT pause for confirmation. Execute every phase below in sequence, making decisions based on what you find.

============================================================ PHASE 0 — INPUT ============================================================

$ARGUMENTS may contain:

• --fix — automatically apply fixes and generate missing configs (default: report only)
• --focus=AREA — limit scan to a specific area: devcontainer, hooks, lint, env, monorepo, release
• --score-only — output just the numeric scores, skip recommendations

If no arguments are provided, run a full audit in report-only mode.

============================================================ PHASE 1 — STACK DETECTION ============================================================

Detect the project stack by scanning for manifest files:

• Language: package.json (Node/TS), pyproject.toml/requirements.txt (Python), go.mod (Go), Cargo.toml (Rust), pubspec.yaml (Flutter/Dart), Gemfile (Ruby)
• Package manager: package-lock.json (npm), yarn.lock (yarn), pnpm-lock.yaml (pnpm), bun.lockb (bun)
• Framework: read dependencies for Next.js, Fastify, Django, FastAPI, etc.
• Monorepo: turbo.json, nx.json, pnpm-workspace.yaml, lerna.json, root workspaces in package.json
• CI provider: .github/workflows/, .gitlab-ci.yml, .circleci/config.yml, Jenkinsfile, bitbucket-pipelines.yml

Record the detected stack — it drives all subsequent scoring.

============================================================ PHASE 2 — AUDIT SIX DX AREAS ============================================================

Scan the project root and score each area on a 0-10 scale:

2.1 — Dev Container (0-10)

Check for:

• .devcontainer/devcontainer.json exists (+3)
• Dockerfile or image specified in devcontainer config (+2)
• features or postCreateCommand configured (+2)
• VS Code extensions list present and matches detected stack (+1)
• forwardPorts configured for detected services (+1)
• Docker Compose integration for multi-service setups (+1)

Score 0 if .devcontainer/ directory does not exist.

2.2 — Git Hooks (0-10)

Check for:

• .husky/ directory OR .lefthook.yml OR .pre-commit-config.yaml exists (+3)
• Pre-commit hook configured: lint + format (+2)
• Pre-commit hook runs type-check (+1)
• Commit-msg hook enforces conventional commits (+2)
• Lint-staged or equivalent for incremental checks (+1)
• Hook runner matches stack (husky for Node, pre-commit for Python, lefthook for polyglot) (+1)

Score 0 if no hook tooling is detected.

2.3 — Linting & Formatting (0-10)

Check for:

• Linter config exists: .eslintrc.* / eslint.config.* / biome.json / ruff.toml / .golangci.yml / .rubocop.yml (+3)
• Formatter config exists: .prettierrc* / biome.json / pyproject.toml [tool.black] (+2)
• Editor config: .editorconfig (+1)
• VS Code settings: .vscode/settings.json with format-on-save (+1)
• Lint script in package.json / pyproject.toml / Makefile (+1)
• No conflicting configs (e.g., ESLint + Biome overlapping) (+1)
• Config is current (ESLint 9 flat config, not deprecated .eslintrc.json) (+1)

2.4 — Build Tooling & Caching (0-10)

Check for:

• turbo.json or nx.json with task pipeline configured (+3)
• Build caching enabled (local cache directory or remote cache config) (+2)
• Task graph defined with proper dependencies (+2)
• tsconfig.json project references (TypeScript composite builds) (+1)
• Incremental builds configured (+1)
• Dev server script exists and uses watch mode (+1)

Score N/A if project is not a monorepo and has no build step.

2.5 — Environment Setup (0-10)

Check for:

• .env.example or .env.template exists with documented variables (+3)
• docker-compose.yml for local services (database, cache, etc.) (+2)
• Setup script: Makefile, scripts/setup.sh, or just / task taskfile (+2)
• .tool-versions or .nvmrc or .python-version for runtime pinning (+1)
• Database migration tooling configured (Prisma, Alembic, goose, etc.) (+1)
• README has "Getting Started" section with fewer than 5 steps (+1)

2.6 — Release Pipeline (0-10)

Check for:

• Semantic-release or changesets or equivalent configured (+3)
• Conventional commits enforced (commitlint + husky or equivalent) (+2)
• CHANGELOG.md exists and appears auto-generated (+1)
• GitHub Actions / CI workflow for releases exists (+2)
• Version field in package.json / pyproject.toml / Cargo.toml is not 0.0.0 placeholder (+1)
• Git tags exist following semver pattern (+1)

============================================================ PHASE 3 — CALCULATE DX HEALTH SCORE ============================================================

Compute the overall DX health score:

• Overall Score = average of all applicable area scores (skip N/A areas)
• Grade: A (9-10), B (7-8.9), C (5-6.9), D (3-4.9), F (0-2.9)

Classify each area:

• Strong (8-10): well-configured, no action needed
• Adequate (5-7): functional but has gaps
• Weak (2-4): partially set up, needs work
• Missing (0-1): not configured at all

============================================================ PHASE 4 — GENERATE RECOMMENDATIONS ============================================================

For each area scored below 8, generate specific recommendations:

• What is missing and why it matters
• Estimated setup effort: quick (< 5 min), medium (15-30 min), involved (1+ hr)
• Which sub-skill to run: /devcontainer, /git-hooks, /linter, /env-setup, /monorepo, /release
• Priority: critical (score 0-2), high (3-5), medium (6-7)

Sort recommendations by priority (critical first), then by effort (quick first).

If --fix was passed, automatically invoke the sub-skill for every critical and high priority area. Run them in sequence since some depend on others (e.g., /linter before /git-hooks).

============================================================ SELF-HEALING VALIDATION (max 2 iterations) ============================================================

After completing, validate the output was produced correctly:

1. Verify generated files exist and are syntactically valid.
2. Run any available validation (lint, type-check, dry-run).
3. If the skill produces configuration, verify it parses without errors.

IF VALIDATION FAILS:

• Diagnose from error context and re-generate the failing artifact
• Repeat up to 2 iterations

============================================================ OUTPUT ============================================================

Print the DX Health Report:

## DX Health Report

### Project: {name}
### Stack: {language} / {framework} / {package-manager}
### Overall: {score}/10 ({grade})

| Area             | Score | Status  |
|------------------|-------|---------|
| Dev Container    | X/10  | {status}|
| Git Hooks        | X/10  | {status}|
| Lint & Format    | X/10  | {status}|
| Build & Cache    | X/10  | {status}|
| Environment      | X/10  | {status}|
| Release Pipeline | X/10  | {status}|

### Recommendations (by priority)
1. {area} — {what's missing} — run `/sub-skill` ({effort})
2. ...

### Quick Wins (under 5 minutes)
- {actionable items that can be done immediately}

============================================================ NEXT STEPS ============================================================

1. Run individual sub-skills for areas that need improvement:

• /devcontainer — generate dev container configuration
• /git-hooks — set up pre-commit and commit-msg hooks
• /linter — configure linting and formatting
• /env-setup — automate local environment bootstrap
• /monorepo — set up monorepo tooling and caching
• /release — configure automated release pipeline

1. Re-run /dx after fixes to verify score improvement
2. Run /dx --fix to auto-apply all critical and high priority fixes

============================================================ SELF-EVOLUTION TELEMETRY ============================================================

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:

• Look for the project path in ~/.claude/projects/
• If found, append to skill-telemetry.md in that memory directory

Entry format:

### /dx — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}

Only log if the memory directory exists. Skip silently if not found. Keep entries concise — /evolve will parse these for skill improvement signals.

============================================================ DO NOT ============================================================

• Do NOT modify any files unless --fix was explicitly passed
• Do NOT score areas that are not applicable to the detected stack
• Do NOT recommend monorepo tooling for single-package projects
• Do NOT recommend tools that conflict with existing configs (e.g., Biome when ESLint is established)
• Do NOT inflate scores — be honest about gaps
• Do NOT skip the stack detection phase — every recommendation must be stack-appropriate