From f0c8b806427daa014bfdd68ec81827e89d796938 Mon Sep 17 00:00:00 2001 From: Ewan Croft Date: Tue, 4 Aug 2026 05:22:17 +0100 Subject: [PATCH] Move .claude/skills to .agents/skills convention Symlink .claude/skills -> ../.agents/skills so skill content is shared across agent-specific config dirs. Co-Authored-By: Claude Sonnet 5 --- .agents/skills/desloppify/SKILL.md | 345 +++++++++++++++++++++++++++++ 1 file changed, 345 insertions(+) create mode 100644 .agents/skills/desloppify/SKILL.md diff --git a/.agents/skills/desloppify/SKILL.md b/.agents/skills/desloppify/SKILL.md new file mode 100644 index 0000000..45b13ea --- /dev/null +++ b/.agents/skills/desloppify/SKILL.md @@ -0,0 +1,345 @@ +--- +name: desloppify +description: > + Multi-language codebase health scanner. Use when the user explicitly asks + to run desloppify, scan for technical debt, get a health score, or create + a cleanup plan. Do NOT trigger for general code review, renaming, or + fixing individual bugs. +--- + + + + +# Desloppify + +## 1. Your Job + +Maximise the **strict score** honestly. Your main cycle: **scan → plan → execute → rescan**. Follow the scan output's **INSTRUCTIONS FOR AGENTS** — don't substitute your own analysis. + +**Don't be lazy.** Do large refactors and small detailed fixes with equal energy. If it takes touching 20 files, touch 20 files. If it's a one-line change, make it. No task is too big or too small — fix things properly, not minimally. + +## 2. The Workflow + +Three phases, repeated as a cycle. + +### Monorepos and multi-project directories + +If the workspace contains multiple programs (e.g., frontend + backend in sibling folders), scan each one separately — do not scan the parent directory: + +```bash +desloppify --lang typescript scan --path ./frontend +desloppify --lang python scan --path ./backend +``` + +Each `--path` target should be a single coherent project. Scanning a parent that contains multiple programs mixes state and path context, producing unreliable results. + +### Phase 1: Scan and review — understand the codebase + +```bash +desloppify scan --path . # analyse the codebase +desloppify status # check scores — are we at target? +``` + +After scanning, **always run `desloppify next`** — it tells you exactly what to do, in order. Don't interpret the scan output yourself or ask the user what to do. Just run `next` and follow its instructions. + +The scan will tell you if subjective dimensions need review. Follow its instructions. To trigger a review manually: + +```bash +desloppify review --prepare # then follow your runner's review workflow +``` + +### Phase 2: Plan — decide what to work on + +After reviews, triage stages and plan creation appear in the execution queue surfaced by `next`. Complete them in order — `next` tells you what each stage expects in the `--report`: + +```bash +desloppify next # shows the next execution workflow step +desloppify plan triage --stage observe --report "themes and root causes..." +desloppify plan triage --stage reflect --report "comparison against completed work..." +desloppify plan triage --stage organize --report "summary of priorities..." +desloppify plan triage --complete --strategy "execution plan..." +``` + +For automated triage: `desloppify plan triage --run-stages --runner codex` (Codex), `--runner claude` (Claude), or `--runner rovodev` (Rovo Dev). Options: `--only-stages`, `--dry-run`, `--stage-timeout-seconds`. + +Then shape the queue. **The plan shapes everything `next` gives you** — `next` is the execution queue, not the full backlog. Don't skip this step. + +```bash +desloppify plan # see the living plan details +desloppify plan queue # compact execution queue view +desloppify plan reorder top # reorder — what unblocks the most? +desloppify plan cluster create # group related issues to batch-fix +desloppify plan focus # scope next to one cluster +desloppify plan skip # defer — hide from next +``` + +### Phase 3: Execute — grind the queue to completion + +Trust the plan and execute. Don't rescan mid-queue — finish the queue first. + +**Branch first.** Create a dedicated branch — never commit health work directly to main: + +```bash +git checkout -b desloppify/code-health # or desloppify/ +desloppify config set commit_pr 42 # link a PR for auto-updated descriptions +``` + +**The loop:** + +```bash +# 1. Get the next item from the execution queue +desloppify next + +# 2. Fix the issue in code + +# 3. Resolve it (next shows the exact command including required attestation) + +# 4. When you have a logical batch, commit and record +git add && git commit -m "desloppify: fix 3 deferred_import findings" +desloppify plan commit-log record # moves findings uncommitted → committed, updates PR + +# 5. Push periodically +git push -u origin desloppify/code-health + +# 6. Repeat until the queue is empty +``` + +Score may temporarily drop after fixes — cascade effects are normal, keep going. +If `next` suggests an auto-fixer, run `desloppify autofix --dry-run` to preview, then apply. + +**When the queue is clear, go back to Phase 1.** New issues will surface, cascades will have resolved, priorities will have shifted. This is the cycle. + +## 3. Reference + +### Key concepts + +- **Tiers**: T1 auto-fix → T2 quick manual → T3 judgment call → T4 major refactor. +- **Auto-clusters**: related findings are auto-grouped in `next`. Drill in with `next --cluster `. +- **Zones**: production/script (scored), test/config/generated/vendor (not scored). Fix with `zone set`. +- **Wontfix cost**: widens the lenient↔strict gap. Challenge past decisions when the gap grows. + +### Scoring + +Overall score = **25% mechanical** + **75% subjective**. + +- **Mechanical (25%)**: auto-detected issues — duplication, dead code, smells, unused imports, security. Fixed by changing code and rescanning. +- **Subjective (75%)**: design quality review — naming, error handling, abstractions, clarity. Starts at **0%** until reviewed. The scan will prompt you when a review is needed. +- **Strict score** is the north star: wontfix items count as open. The gap between overall and strict is your wontfix debt. +- **Score types**: overall (lenient), strict (wontfix counts), objective (mechanical only), verified (confirmed fixes only). + +### Reviews + +Four paths to get subjective scores: + +- **Local runner (Codex)**: `desloppify review --run-batches --runner codex --parallel --scan-after-import` — automated end-to-end. +- **Local runner (Claude)**: `desloppify review --prepare` → launch parallel subagents → `desloppify review --import merged.json` — see skill doc overlay for details. +- **Local runner (Rovo Dev)**: `desloppify review --run-batches --runner rovodev --parallel --scan-after-import` — automated end-to-end via `acli rovodev run` subprocesses. +- **Cloud/external**: `desloppify review --external-start --external-runner claude` → follow session template → `--external-submit`. +- **Manual path**: `desloppify review --prepare` → review per dimension → `desloppify review --import file.json`. + +**Batch output vs import filenames:** Individual batch outputs from subagents must be named `batch-N.raw.txt` (plain text/JSON content, `.raw.txt` extension). The `.json` filenames in `--import merged.json` or `--import findings.json` refer to the final merged import file, not individual batch outputs. Do not name batch outputs with a `.json` extension. + +**Subagent parallelism limit:** Do not launch every review batch at once. Run subagents in small waves, usually **3-5 concurrent agents**, and wait for a wave to finish before starting the next. If agents return empty, partial, or rate-limit-shaped results, reduce the wave size and retry only failed batches. Launching 20+ subagents at once can exhaust API quota and produce no usable review output. + +- Import first, fix after — import creates tracked state entries for correlation. +- Target-matching scores trigger auto-reset to prevent gaming. Use the blind-review workflow described in your agent overlay doc (e.g. `docs/CLAUDE.md`, `docs/HERMES.md`). +- Even moderate scores (60-80) dramatically improve overall health. +- Stale dimensions auto-surface in `next` — just follow the queue. + +**Integrity rules:** Score from evidence only — no prior chat context, score history, or target-threshold anchoring. When evidence is mixed, score lower and explain uncertainty. Assess every requested dimension; never drop one. + +#### Review output format + +Return machine-readable JSON for review imports. For `--external-submit`, include `session` from the generated template: + +```json +{ + "session": { + "id": "", + "token": "" + }, + "assessments": { + "": 0 + }, + "findings": [ + { + "dimension": "", + "identifier": "short_id", + "summary": "one-line defect summary", + "related_files": ["relative/path/to/file.py"], + "evidence": ["specific code observation"], + "suggestion": "concrete fix recommendation", + "confidence": "high|medium|low" + } + ] +} +``` + +`findings` MUST match `query.system_prompt` exactly (including `related_files`, `evidence`, and `suggestion`). Use `"findings": []` when no defects found. Import is fail-closed: invalid findings abort unless `--allow-partial` is passed. Assessment scores are auto-applied from trusted internal or cloud session imports. Legacy `--attested-external` remains supported. + +#### Import paths + +- Robust session flow (recommended): `desloppify review --external-start --external-runner claude` → use generated prompt/template → run printed `--external-submit` command. +- Durable scored import (legacy): `desloppify review --import findings.json --attested-external --attest "I validated this review was completed without awareness of overall score and is unbiased."` +- Findings-only fallback: `desloppify review --import findings.json` + +#### Reviewer agent prompt + +Runners that support agent definitions (Cursor, Copilot, Gemini) can create a dedicated reviewer agent. Use this system prompt: + +``` +You are a code quality reviewer. You will be given a codebase path, a set of +dimensions to score, and what each dimension means. Read the code, score each +dimension 0-100 from evidence only, and return JSON in the required format. +Do not anchor to target thresholds. When evidence is mixed, score lower and +explain uncertainty. +``` + +See your editor's overlay section below for the agent config format. + +### Plan commands + +```bash +desloppify plan reorder top # move all cluster members at once +desloppify plan reorder top # mix clusters + findings in one reorder +desloppify plan reorder before -t X # position relative to another item/cluster +desloppify plan cluster reorder a,b top # reorder multiple clusters as one block +desloppify plan resolve # mark complete +desloppify plan reopen # reopen +desloppify backlog # broader non-execution backlog +``` + +### Commit tracking + +```bash +desloppify plan commit-log # see uncommitted + committed status +desloppify plan commit-log record # record HEAD commit, update PR description +desloppify plan commit-log record --note "why" # with rationale +desloppify plan commit-log record --only "smells::*" # record specific findings only +desloppify plan commit-log history # show commit records +desloppify plan commit-log pr # preview PR body markdown +desloppify config set commit_tracking_enabled false # disable guidance +``` + +After resolving findings as `fixed`, the tool shows uncommitted work, committed history, and a suggested commit message. After committing externally, run `record` to move findings from uncommitted to committed and auto-update the linked PR description. + +### Agent directives + +Directives are messages shown to agents at lifecycle phase transitions — use them to switch models, set constraints, or give context-specific instructions. + +```bash +desloppify directives # show all configured directives +desloppify directives set execute "Switch to claude-sonnet-4-6. Focus on speed." +desloppify directives set triage "Switch to claude-opus-4-6. Read carefully." +desloppify directives set review "Use blind packet. Do not anchor on previous scores." +desloppify directives unset execute # remove a directive +``` + +Available phases: `execute`, `review`, `triage`, `workflow`, `scan` (and fine-grained variants like `review_initial`, `triage_postflight`, etc.). + +### Quick reference + +```bash +desloppify next --count 5 # top 5 execution items +desloppify next --cluster # drill into a cluster +desloppify backlog --count 5 # top 5 backlog items outside execution +desloppify show # filter by file/detector/ID +desloppify show --status open # all open findings +desloppify plan skip --permanent "" --note "reason" --attest "..." # accept debt +desloppify exclude # exclude a directory from scanning +desloppify config show # show all config including excludes +desloppify scan --path . --reset-subjective # reset subjective baseline to 0 +``` + +## 4. Fix Tool Issues Upstream + +When desloppify itself appears wrong or inconsistent — a bug, a bad detection, a crash, confusing output — **fix it and open a PR**. If you can't confidently fix it, file an issue instead. + +### Fix and PR (preferred) + +Clone the tool repo to a temp directory, make the fix there, and verify it works against the project you're scanning before pushing. + +```bash +git clone https://github.com/peteromallet/desloppify.git /tmp/desloppify-fix +cd /tmp/desloppify-fix +git checkout -b fix/ +``` + +Make your changes, then run the test suite and verify the fix against the original project: + +```bash +python -m pytest desloppify/tests/ -q +python -m desloppify scan --path # the project you were scanning +``` + +Once it looks good, push and open a PR: + +```bash +git add && git commit -m "fix: " +git push -u origin fix/ +gh pr create --title "fix: " --body "$(cat <<'EOF' +## Problem + + +## Fix + +EOF +)" +``` + +Clean up after: `rm -rf /tmp/desloppify-fix` + +### File an issue (fallback) + +If the fix is unclear or the change needs discussion, open an issue at `https://github.com/peteromallet/desloppify/issues` with a minimal repro: command, path, expected output, actual output. + +## Prerequisite + +`command -v desloppify >/dev/null 2>&1 && echo "desloppify: installed" || echo "NOT INSTALLED — run: uvx --from git+https://github.com/peteromallet/desloppify.git desloppify"` + +If `uvx` is not available: `pip install desloppify[full] && desloppify setup` + + + +## Claude Code Overlay + +Use Claude subagents for subjective scoring work. **Do not use `--runner codex`** — use Claude subagents exclusively. + +### Review workflow + +Run `desloppify review --prepare` first to generate review data, then use Claude subagents: + +1. **Prepare**: `desloppify review --prepare` — writes `query.json` and `.desloppify/review_packet_blind.json`. +2. **Launch subagents**: Split the review across N parallel Claude subagents (one message, multiple Task calls). Each agent reviews a subset of dimensions. +3. **Merge & import**: Merge agent outputs, then `desloppify review --import merged.json --manual-override --attest "Claude subagents ran blind reviews against review_packet_blind.json" --scan-after-import`. + +#### How to split dimensions across subagents + +- Read `dimension_prompts` from `query.json` for dimensions with definitions and seed files. +- Read `.desloppify/review_packet_blind.json` for the blind packet (no score targets, no anchoring data). +- Group dimensions into 3-4 batches by theme (e.g., architecture, code quality, testing, conventions). +- Launch one Task agent per batch with `subagent_type: "general-purpose"`. Each agent gets: + - The codebase path and list of dimensions to score + - The blind packet path to read + - Instruction to score from code evidence only, not from targets +- Each agent writes output to `results/batch-N.raw.txt` (matching the batch index). Merge assessments (average overlapping dimension scores) and concatenate findings. + +### Subagent rules + +1. Each agent must be context-isolated — do not pass conversation history or score targets. +2. Agents must consume `.desloppify/review_packet_blind.json` (not full `query.json`) to avoid score anchoring. + +### Triage workflow + +Orchestrate triage with per-stage subagents: + +1. `desloppify plan triage --run-stages --runner claude` — prints orchestrator instructions +2. For each stage (observe → reflect → organize → enrich): + - Get prompt: `desloppify plan triage --stage-prompt ` + - Launch a subagent with that prompt + - Verify: `desloppify plan triage` (check dashboard) + - Confirm: `desloppify plan triage --confirm --attestation "..."` +3. Complete: `desloppify plan triage --complete --strategy "..." --attestation "..."` + + + -- 2.51.2