Swain Doctor

Runs at every session start to validate your swain project setup: governance blocks in instructions, tool availability, memory directories, ticket structure, script permissions, and the .agents directory. It auto-migrates legacy .beads directories to .tickets, repairs stale artifact indexes, and fixes broken worktree layouts that don't match ADR conventions. The detection logic lives in a consolidated bash script that outputs structured JSON, then remediation happens selectively based on what actually failed. It's idempotent and safe to run manually whenever something feels off. If you're jumping between worktrees or onboarding to an existing swain repo, this is what catches configuration drift before it bites you mid-session.

skills.sh installs: 123
GitHub stars: 2
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add cristoslc/swain --skill swain-doctor --agent claude-code

Installs into .claude/skills of the current project.

Files

Doctor

Session-start health checks for swain projects. The consolidated script is authoritative for all detection. This skill file defines how to run the script and how to remediate each check.

Running the script

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/.agents/bin/swain-doctor.sh"

The script outputs structured JSON with { checks: [...], summary: {...} }. Each check has name, status, message, and optional detail. Parse it and present the summary table to the operator. Then use the remediation sections below only for checks that reported warning or advisory status — do not re-run detection.

To auto-fix flat-file artifacts: bash "$REPO_ROOT/.agents/bin/swain-doctor.sh" --fix-flat-artifacts

If the script is unavailable (e.g., .agents/bin/ symlinks not yet bootstrapped), fall back to running checks from the script source at skills/swain-doctor/scripts/swain-doctor.sh. Run checks sequentially (one Bash call at a time), never in parallel — parallel tool calls cascade-cancel on first error.