Docs for agents

Driving DevDoctor from an LLM or coding agent? This page is the contract. (It mirrors .claude/skills/devdoctor/SKILL.md in the repo, published here so agents outside that checkout can use it too.)

Capabilities

• devdoctor scan --json — read-only. Safe unsupervised, on any schedule.
• devdoctor providers — check before assuming a provider exists here.
• devdoctor recipe — fully commented-out script: the safe way to propose a cleanup for a human.
• devdoctor clean (no flags) — preview only. Safe to show what would happen.
• devdoctor clean --execute — destructive. Needs a human decision (rules below). Never unsupervised.
• devdoctor serve — loopback only, no auth. Do not expose it.

Rules for clean --execute

1. Confirm intent first. Only on explicit user request. A scan report is not consent.
2. Preview or recipe first, unless the user already approved a plan.
3. Stay at or below the approved tier. --risk safe + --yes-safe for routine runs. Surface reclaimable entries one by one; --allow-dangerous only with explicit say-so, never by default.
4. Scope when you can (--provider <name>).
5. No terminal means --yes or nothing — and never add --yes to dodge a missing human.
6. Report the summary — estimated vs. planned, measured change, any snapshot caveat.

Reading scan --json

• Headline: total_reclaimable_bytes. Breakdown: per_provider. Detail: entries[].
• Sizes are estimates — never present them as measured freed bytes.
• Mention diagnostics so the human knows what the total excludes.
• Parse --json, never the Rich table (it truncates). path may be null; risk is safe / reclaimable / dangerous.

Machine entry points: llms.txt · llms-full.txt — Full contract: CLI reference · Safety model