Skip to content

Make doctor portable via graceful degradation: single-source check procedures, Workflow fast path on Claude #57

Description

@TBarregren

Why

doctor was marked Claude-only because its documentation-vs-code verification runs through doctor.workflow.js via Claude Code's Workflow tool. But the skill is two separable halves: doctor.py (deterministic checks: git state, .gitignore coverage, coding-standard home/sync, licence/NOTICE pairing) is plain Python and portable today, and the Workflow engine's read-only verification passes are markdown-expressible instructions. This ticket makes doctor capability-aware: Workflow-driven fan-out on Claude Code, sequential inline verification elsewhere, with one source of truth for what gets checked.

Do this after the restructuring in #56 is merged (this ticket assumes its layout — doctor.py in skills/doctor/scripts/ — and its boilerplate blocks).

Changes

1. Extract check procedures

Extract the verification instructions currently embedded in doctor.workflow.js (the agent prompts that verify AGENTS.md, agents.d/ files, and README against the real code) into skills/doctor/checks/<name>.md, one file per verification dimension. Each file states: what to read, what to compare it against, and the finding format to return. doctor.workflow.js is rewritten to load its agent prompts from these files (or, if the Workflow sandbox cannot read files at script-build time, the SKILL.md instructs Claude to inline the file contents into the workflow's args — pick whichever the Workflow tool supports; the invariant is that the procedural text exists in exactly one place, the checks/ files).

2. Capability-aware execution in skills/doctor/SKILL.md

Replace the hard-wired Workflow invocation with:

If you are running in Claude Code (the Workflow tool is available): run scripts/doctor.py, then launch the workflow engine doctor.workflow.js (absolute path of this skill's directory + /doctor.workflow.js) exactly as before. Otherwise: run scripts/doctor.py, then perform each file under checks/ yourself, sequentially and strictly read-only, and merge your findings with the script's output into the same report format.

The report format (sections, severity vocabulary, fix proposals, the --yes apply behavior) must be identical regardless of path, so downstream expectations hold.

3. Unhide and polish

4. README, audit, tests

Acceptance criteria

  • grep -rn 'CLAUDE_PLUGIN_ROOT' skills/doctor/ returns nothing.
  • Copy skills/doctor/ (plus its library-skill dependencies per Make skills self-contained for standalone distribution: dissolve lib/ and scripts/ into owning skills #56, if any) into an empty directory and verify every path its SKILL.md and check files mention resolves.
  • On Claude Code, doctor produces the same report as before this change (spot-check on one repo).
  • uv run scripts/audit.py and pytest pass.
  • CHANGELOG.md gets an entry per the repo's convention.
  • No version bump, no tag, no release — leave that to the maintainer.

Deliver as a PR against the default branch.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    ready-for-agentFully specified, ready for an AFK agent

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions