swain-doctor

name	swain-doctor
description	Auto-invoked at session start when swain-preflight detects issues. Also user-invocable for on-demand health checks. Validates project health: governance rules, tool availability, memory directory, settings files, script permissions, .agents directory, and .tickets/ validation. Auto-migrates stale .beads/ directories to .tickets/ and removes them. Remediates issues across all swain skills. Idempotent — safe to run any time.
user-invocable	true
license	MIT
allowed-tools	Bash, Read, Write, Edit, Grep, Glob
metadata	{"short-description":"Session-start health checks and repair","version":"2.6.0","author":"cristos","source":"swain"}

Doctor

Session-start health checks for swain projects. Validates and repairs health across all swain skills — governance, tools, directories, settings, scripts, caches, and runtime state. Auto-migrates stale .beads/ directories to .tickets/ and removes them. Idempotent — run it every session; it only writes when repairs are needed.

Run checks in the order listed below. Collect all findings into a summary table at the end.

Preflight integration

A lightweight shell script (skills/swain-doctor/scripts/swain-preflight.sh) performs quick checks before invoking the full doctor. If preflight exits 0, swain-doctor is skipped for the session. If it exits 1, swain-doctor runs normally.

The preflight checks are a subset of this skill's checks — governance files, .agents directory, .tickets health, script permissions. It runs as pure bash with zero agent tokens. See AGENTS.md § Session startup for the invocation flow.

When invoked directly by the user (not via the auto-invoke flow), swain-doctor always runs regardless of preflight status.

Trunk branch detection

Detect the trunk branch once at the start. Use it for all branch-relative checks (worktree staleness, merge-base):

REPO_ROOT=$(git rev-parse --show-toplevel)
TRUNK=$(bash "$REPO_ROOT/scripts/swain-trunk.sh")

Session-start governance check

1. Detect the agent platform and locate the context file:

   Platform	Context file	Detection
   Claude Code	CLAUDE.md (project root)	Default — use if no other platform detected
   Cursor	.cursor/rules/swain-governance.mdc	.cursor/ directory exists

2. Check whether governance rules are already present:

   grep -l "swain governance" CLAUDE.md AGENTS.md .cursor/rules/swain-governance.mdc 2>/dev/null
   

   If any file matches, governance is installed. Check freshness (step 3), then proceed to Legacy skill cleanup.

3. If governance markers found, check freshness:

   Extract the block between <!-- swain governance and <!-- end swain governance --> from the installed context file. Compare against the canonical source at skills/swain-doctor/references/AGENTS.content.md (same extraction, excluding marker lines).

   extract_gov() { awk '/<!-- swain governance/{f=1;next}/<!-- end swain governance/{f=0}f' "$1"; }
   INSTALLED_HASH=$(extract_gov "$GOV_FILE" | shasum -a 256 | cut -d' ' -f1)
   CANONICAL_HASH=$(extract_gov "skills/swain-doctor/references/AGENTS.content.md" | shasum -a 256 | cut -d' ' -f1)
   

   • ok — hashes match. Governance is current. Proceed to Legacy skill cleanup.
   • stale — hashes differ. Proceed to Governance replacement before Legacy skill cleanup.

4. If no marker match in step 2 (governance missing), run Legacy skill cleanup, then proceed to Governance injection.

Legacy skill cleanup

Clean up renamed and retired skill directories using fingerprint checks. Read references/legacy-cleanup.md for the full procedure. Data source: skills/swain-doctor/references/legacy-skills.json.

Platform dotfolder cleanup

Remove dotfolder stubs (.windsurf/, .cursor/, etc.) for agent platforms that are not installed. Read references/platform-cleanup.md for the detection and cleanup procedure. Requires jq.

Governance injection

Inject governance rules into the platform context file when missing. Read references/governance-injection.md for Claude Code and Cursor injection procedures. Source: skills/swain-doctor/references/AGENTS.content.md.

Governance replacement

Replace a stale governance block with the current canonical version. Read references/governance-injection.md § Stale governance replacement for the replacement procedure. This runs when freshness check (step 3) detects a hash mismatch.

Tickets directory validation

Validates .tickets/ health — YAML frontmatter, stale locks. Skip if .tickets/ does not exist. Read references/tickets-validation.md for the full procedure.

Stale .beads/ migration and cleanup

Auto-migrates .beads/ → .tickets/ if present. Skip if .beads/ does not exist. Read references/beads-migration.md for the migration procedure.

Governance content reference

The canonical governance rules live in skills/swain-doctor/references/AGENTS.content.md. Both swain-doctor and swain-init read from this single source of truth. If the upstream rules change in a future swain release, update that file and bump the skill version. The freshness check (step 3 of the governance check) will automatically detect the mismatch and offer replacement on the next session.

Tool availability

Check required (git, jq) and optional (tk, uv, gh, tmux, fswatch) tools. Never install automatically. Read references/tool-availability.md for the check commands, degradation notes, and reporting format.

Runtime checks

Memory directory, settings validation, script permissions, .agents directory, status cache bootstrap, and SSH alias readiness. Read references/runtime-checks.md for the full procedures and bash commands.

tk health (extended .tickets checks)

Verify vendored tk is executable at skills/swain-do/bin/tk and check for stale lock files. Skip if .tickets/ does not exist. See references/tickets-validation.md for details.

swain-box symlink

Ensure ./swain-box exists as a symlink to the installed swain-box script so operators can launch Docker Sandboxes from the project root. The script is distributed inside the swain skill tree at */swain/scripts/swain-box. Skip if the script cannot be found.

Detection

SWAIN_BOX_SCRIPT=$(find . .claude .agents -path '*/swain/scripts/swain-box' -print -quit 2>/dev/null)
if [ -n "$SWAIN_BOX_SCRIPT" ]; then
  # Get relative path from project root
  SWAIN_BOX_REL=$(python3 -c "import os,sys; print(os.path.relpath(sys.argv[1]))" "$SWAIN_BOX_SCRIPT" 2>/dev/null || echo "$SWAIN_BOX_SCRIPT")
  if [ -L swain-box ] && [ "$(readlink swain-box)" = "$SWAIN_BOX_REL" ]; then
    echo "ok"
  elif [ -e swain-box ] && [ ! -L swain-box ]; then
    echo "conflict"  # a real file named swain-box exists — do not overwrite
  else
    echo "missing"
  fi
fi

Remediation

• ok — silent, no output.
• missing — create the symlink automatically:

  ln -sf "$SWAIN_BOX_REL" swain-box
  

  Report: swain-box symlink created (./swain-box → $SWAIN_BOX_REL)
• conflict — warn: ./swain-box exists but is not a symlink — skipping. To fix manually: rm swain-box && ln -sf <path> swain-box

Status values

• ok — symlink present and correct
• repaired — symlink created
• warning — conflict (real file); manual action needed

Lifecycle directory migration

Detect old phase directories from before ADR-003's three-track normalization. Old directory names: Draft/, Planned/, Review/, Approved/, Testing/, Implemented/, Adopted/, Deprecated/, Archived/, Sunset/, Validated/.

Detection

OLD_PHASES="Draft Planned Review Approved Testing Implemented Adopted Deprecated Archived Sunset Validated"
for dir in docs/*/; do
  for phase in $OLD_PHASES; do
    if [[ -d "${dir}${phase}" ]]; then
      # Check for non-empty (ignore hidden files)
      if find "${dir}${phase}" -maxdepth 1 -not -name '.*' -print -quit 2>/dev/null | grep -q .; then
        echo "  Old directory: ${dir}${phase}"
      fi
    fi
  done
done

Remediation

1. List each old directory and its artifact count.
2. Explain: "ADR-003 normalized artifact lifecycle phases into three tracks. Old phase directories need migration."
3. Check for the migration script: $(find "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" -path '*/swain-design/scripts/migrate-lifecycle-dirs.py' -print -quit 2>/dev/null)
   • If available: offer to run uv run python3 "$(find "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" -path '*/swain-design/scripts/migrate-lifecycle-dirs.py' -print -quit 2>/dev/null)" --dry-run first, then the real migration.
   • If unavailable: provide manual git mv instructions using the phase mapping from ADR-003.
4. After migration, clean up empty old directories.

Status values

• ok — no old directories found
• repaired — migration script ran successfully
• warning — old directories found, user chose not to migrate now

Superpowers detection

Check whether superpowers skills are installed:

SUPERPOWERS_SKILLS="brainstorming writing-plans test-driven-development verification-before-completion subagent-driven-development executing-plans"
found=0
missing=0
missing_names=""
for skill in $SUPERPOWERS_SKILLS; do
  if ls .agents/skills/$skill/SKILL.md .claude/skills/$skill/SKILL.md 2>/dev/null | head -1 | grep -q .; then
    found=$((found + 1))
  else
    missing=$((missing + 1))
    missing_names="$missing_names $skill"
  fi
done

Status values and response

• ok — all superpowers skills detected. No output.
• partial — some skills present, some missing. List the missing ones, then prompt (see below). A partial install may indicate a failed update — note this in the prompt.
• missing — no superpowers skills found. Prompt the user.

When status is missing or partial, ask:

Superpowers (obra/superpowers) is not installed [or: partially installed — N of 6 skills missing]. It provides TDD, brainstorming, plan writing, and verification skills that swain chains into during implementation and design work.

Install superpowers now? (yes/no)

If the user says yes:

npx skills add obra/superpowers

Report success or failure. On success, update status to ok.

If the user says no, note "Superpowers: skipped" and continue. They can install later: npx skills add obra/superpowers.

Superpowers is strongly recommended but not required. Declining is always allowed.

Stale worktree detection

Enumerate all linked worktrees and classify their health. Skip if the repo has no linked worktrees (i.e., git worktree list --porcelain returns only the main worktree entry) — this check produces no output in a clean repo.

Detection

git worktree list --porcelain

Parse each linked worktree (exclude the main worktree — the first entry in the output):

git worktree list --porcelain | awk '
  /^worktree / { path=$2 }
  /^branch /   { branch=$2 }
  /^$/         { if (path != "") print path, branch; path=""; branch="" }
' | tail -n +2

For each linked worktree:

1. Orphaned — directory does not exist on disk ([ ! -d "$path" ]):

   • WARN: "Orphaned worktree: <path> (directory missing). Clean up with: git worktree prune"

2. Stale (merged) — directory exists and branch is fully merged into the trunk branch ($TRUNK):

   git merge-base --is-ancestor "$branch" "origin/$TRUNK"
   

   • WARN: "Stale worktree: <path> (branch <branch> already merged into $TRUNK). Safe to remove: git worktree remove <path> && git branch -d <branch>"

3. Active (unmerged) — directory exists and branch has commits not in $TRUNK:

   • INFO: "Active worktree: <path> (branch <branch>, N commits ahead of $TRUNK). Do not remove — work in progress."

Do not remove any worktree automatically. All output is advisory.

Status values

• ok — no linked worktrees, or all are active
• warning — one or more stale or orphaned worktrees found (provide cleanup commands per item)

Trunk/release branch model check (ADR-013)

Non-blocking advisory check. Verifies that the trunk+release branch model is properly configured.

Detection

1. Check that scripts/swain-trunk.sh exists and is executable
2. Run it and verify the detected trunk branch has a remote counterpart on origin
3. Check whether a release branch exists (required by ADR-013)

Response

• If scripts/swain-trunk.sh is missing: WARN — "Trunk detection script not found. EPIC-029 may not be installed."
• If the detected trunk branch has no remote: WARN — "Trunk branch <name> has no remote counterpart on origin."
• If no release branch exists: INFO — "No release branch found. The trunk+release model (ADR-013) is not configured. To adopt it, run: bash scripts/migrate-to-trunk-release.sh --dry-run"

Status values

• ok — trunk detected, remote exists, release branch exists
• info — trunk works but release branch not configured (project hasn't adopted ADR-013 yet)
• warning — trunk detection fails or remote is missing

Epics without parent-initiative (migration advisory)

This is a non-blocking advisory check. It does not gate any other checks.

Detection

# Find Active EPICs that have a parent-vision but no parent-initiative field
grep -rl "parent-vision:" docs/epic/ 2>/dev/null | while read f; do
  if ! grep -q "parent-initiative:" "$f"; then
    echo "$f"
  fi
done

Response

If any EPICs are found without parent-initiative:

Advisory: N Epic(s) have a parent-vision but no parent-initiative. The INITIATIVE artifact type is now available as a mid-level container between Vision and Epic. Adding parent-initiative links is optional but recommended for projects using prioritization features (specgraph recommend, specgraph decision-debt).

To add the link, edit each Epic's frontmatter and add:

parent-initiative: INITIATIVE-NNN

This check is informational — no action required. To run the guided migration, ask: "how do I fix the initiative migration?" or "run the initiative migration".

Guided migration workflow

When the operator asks to run the migration (or says "how do I fix the initiative migration?"), guide them through these steps:

Step 1: Scan and group

Run the scan helper to list all epics without parent-initiative, grouped by parent-vision:

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

Analyze the output and propose initiative clusters. For example:

"Under VISION-001, you have 8 epics. I'd suggest grouping them into 2-3 initiatives based on theme:

• Security Hardening: EPIC-017, EPIC-023 (both security-related)
• Developer Experience: EPIC-016, EPIC-019, EPIC-022 (workflow improvements)
• Product Design: EPIC-021 (standalone strategic bet)

Does this grouping work, or would you like to adjust?"

Proposals are suggestions, not commitments. Base clustering on epic titles, descriptions, and shared themes visible in the scan output.

Step 2: Operator decides

The operator approves, adjusts, or rejects each proposed cluster. This is a vision-mode decision — don't rush it. Present one vision's worth of clusters at a time if there are many.

Step 3: Create initiatives

For each approved cluster, invoke swain-design to create an Initiative artifact:

• Set parent-vision to the vision these epics belong to
• Set priority-weight if the operator specifies one (otherwise omit — it inherits from the vision)
• List the child epics in the "Child Epics" section of the initiative document

Step 4: Re-parent epics

For each epic in an approved cluster, add parent-initiative: INITIATIVE-NNN to its frontmatter. During the migration period, parent-vision can remain alongside parent-initiative — specgraph accepts both and resolves the vision ancestor through whichever path exists.

# Before
parent-vision: VISION-001

# After (during migration — both fields coexist)
parent-vision: VISION-001
parent-initiative: INITIATIVE-001

Step 5: Set vision weights

Prompt the operator to set priority-weight on their visions if not already set:

priority-weight: high    # active strategic focus
priority-weight: medium  # maintained, progressing (default if omitted)
priority-weight: low     # parked, not abandoned

They can defer — everything defaults to medium and the system works without weights.

Step 6: Verify

Run specgraph to verify the new hierarchy looks correct:

bash "$(find "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" -path '*/swain-design/scripts/chart.sh' -print -quit 2>/dev/null)"
bash "$(find "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" -path '*/swain-design/scripts/chart.sh' -print -quit 2>/dev/null)" recommend

Check that initiatives appear in the tree and that recommendations reflect the new structure.

Migration is incremental. The operator can migrate one vision's epics at a time. Unmigrated epics continue to work — they just show this advisory on each session start.

Status values

• ok — all Active EPICs already have parent-initiative, or no EPICs exist
• advisory — one or more Active EPICs lack parent-initiative (non-blocking)

Evidence Pool → Trove Migration

Detect unmigrated evidence pools:

• If docs/evidence-pools/ exists: warn and offer to run migration
• If any artifact frontmatter contains evidence-pool:: warn and offer migration
• If both docs/troves/ and docs/evidence-pools/ exist: warn about incomplete migration

Migration script: bash "$(find "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" -path '*/swain-search/scripts/migrate-to-troves.sh' -print -quit 2>/dev/null)" Dry run first: bash "$(find "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" -path '*/swain-search/scripts/migrate-to-troves.sh' -print -quit 2>/dev/null)" --dry-run

Summary report

After all checks complete, output a concise summary table:

swain-doctor summary:
  Governance ......... ok
  Legacy cleanup ..... ok (nothing to clean)
  Platform dotfolders  ok (nothing to clean)
  .tickets/ .......... ok
  Stale .beads/ ...... ok (not present)
  Tools .............. ok (1 optional missing: fswatch)
  Memory directory ... ok
  Settings ........... ok
  Script permissions . ok
  .agents directory .. ok
  Status cache ....... seeded
  tk health .......... ok
  Lifecycle dirs ..... ok
  Epics w/o initiative advisory (3 epics — see note below)
  Worktrees .......... ok
  Superpowers ........ ok (6/6 skills detected)

3 checks performed repairs. 0 issues remain.

Use these status values:

• ok — nothing to do
• repaired — issue found and fixed automatically
• warning — issue found, user action recommended (give specifics)
• skipped — check could not run (e.g., jq missing for JSON validation)

If any checks have warnings, list them below the table with remediation steps.