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:
   bash

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

   If any file matches, governance is already installed. Proceed to Legacy skill cleanup.
3. If no match, run Legacy skill cleanup, then proceed to Governance injection.

renamed

1. Check whether

   .claude/skills/<old-name>/

   exists.
2. If it does NOT exist, skip (nothing to clean).
3. If it exists, check whether

   .claude/skills/<new-name>/

   also exists. If the replacement is missing, skip and warn — the update may not have completed:

   Skipping cleanup of

   <old-name>

   — its replacement

   <new-name>

   is not installed.

4. If both exist, fingerprint check: read

   .claude/skills/<old-name>/SKILL.md

   and check whether its content matches ANY of the fingerprints listed in

   legacy-skills.json

   . Specifically, grep the file for each fingerprint string — if at least one matches, the skill is confirmed to be a swain skill.
5. If no fingerprint matches, skip and warn — this may be a third-party skill with the same name:

   Skipping cleanup of

   .claude/skills/<old-name>/

   — it does not appear to be a swain skill (no fingerprint match). If this is a stale swain skill, delete it manually.

6. If fingerprint matches and replacement exists, delete the old directory:
   bash

   rm -rf .claude/skills/<old-name>

   Tell the user:

   Removed legacy skill

   .claude/skills/<old-name>/

   (replaced by

   <new-name>

   ).

retired

1. Check whether

   .claude/skills/<old-name>/

   exists.
2. If it does NOT exist, skip (nothing to clean).
3. If it exists, fingerprint check: same as for renamed skills — read

   .claude/skills/<old-name>/SKILL.md

   and check whether its content matches ANY fingerprint in

   legacy-skills.json

   .
4. If no fingerprint matches, skip and warn:

   Skipping cleanup of

   .claude/skills/<old-name>/

   — it does not appear to be a known pre-swain skill (no fingerprint match). Delete manually if stale.

5. If fingerprint matches, delete the old directory:
   bash

   rm -rf .claude/skills/<old-name>

   Tell the user:

   Removed retired pre-swain skill

   .claude/skills/<old-name>/

   (functionality now in

   <absorbed-by>

   ).

<!-- swain governance -->

<!-- end swain governance -->

renamed

platforms

1. If the entry has a

   command

   field → run

   command -v <command> &>/dev/null

   .
2. If the entry has a

   detection

   field → expand the path (replace

   ~

   with

   $HOME

   , evaluate env var defaults like

   ${CODEX_HOME:-~/.codex}

   ) and check whether the directory exists.

.claude

jq

jq

installed_dotfolders=(".claude")
while IFS= read -r entry; do
  dotfolder=$(echo "$entry" | jq -r '.project_dotfolder')
  cmd=$(echo "$entry" | jq -r '.command // empty')
  det=$(echo "$entry" | jq -r '.detection // empty')

  found=false
  if [[ -n "$cmd" ]] && command -v "$cmd" &>/dev/null; then
    found=true
  fi
  if [[ -n "$det" ]] && ! $found; then
    det_expanded=$(echo "$det" | sed "s|~|$HOME|g")
    det_expanded=$(eval echo "$det_expanded" 2>/dev/null)
    [[ -d "$det_expanded" ]] && found=true
  fi

  $found && installed_dotfolders+=("$dotfolder")
done < <(jq -c '.platforms[]' "SKILL_DIR/references/platform-dotfolders.json")

SKILL_DIR

1. Check whether the directory exists in the project root.
2. If it does NOT exist, skip.
3. If it exists, verify it is installer-generated — the directory should contain only a

   skills/

   subdirectory (possibly with symlinks or further subdirectories). Check:
   bash

   # Count top-level entries (excluding . and ..)
   entries=$(ls -A "<dotfolder>" 2>/dev/null | wc -l)
   # Check if the only entry is "skills"
   if [[ "$entries" -le 1 ]] && [[ -d "<dotfolder>/skills" || "$entries" -eq 0 ]]; then
     # Safe to remove — installer-generated stub
   fi

   • If the directory is empty OR contains only a

     skills/

     subdirectory → remove it:
     bash

     rm -rf <dotfolder>

   • If the directory contains other files or directories besides

     skills/

     → skip and warn:

     Skipping

     <dotfolder>

     — contains user content beyond installer symlinks. Remove manually if unused.

4. After processing all entries, report:

   Removed N platform dotfolder(s) created by

   npx skills add

   (installer stubs for unused agent platforms).

   If none were found, this step is silent.

1. If

   CLAUDE.md

   exists and its content is just

   @AGENTS.md

   (the include pattern set up by swain-init), inject into

   AGENTS.md

   instead.
2. Otherwise, inject into

   CLAUDE.md

   (create it if it doesn't exist).

references/AGENTS.content.md

Governance rules installed in

<file>

. These ensure swain-design, swain-do, and swain-release skills are routable. You can customize the rules — just keep the

<!-- swain governance -->

markers so this skill can detect them on future sessions.

references/.beads-gitignore

dolt/
dolt-access.lock
bd.sock
bd.sock.startlock
sync-state.json
last-touched
.local_version
redirect
.sync.lock
export-state/
ephemeral.sqlite3
ephemeral.sqlite3-journal
ephemeral.sqlite3-wal
ephemeral.sqlite3-shm
dolt-server.pid
dolt-server.log
dolt-server.lock
dolt-server.port
dolt-server.activity
dolt-monitor.pid
backup/
*.db
*.db?*
*.db-journal
*.db-wal
*.db-shm
db.sqlite
bd.db
.beads-credential-key

1. If

   .beads/.gitignore

   does not exist, create it from the reference file (

   references/.beads-gitignore

   ) and skip to Step 2.
2. Read

   .beads/.gitignore

   . For each canonical pattern above, check whether it appears as a non-comment line in the file.
3. Collect any missing patterns. If none are missing, this step is silent — move to Step 2.
4. If patterns are missing, append them to

   .beads/.gitignore

   :

   
   # --- swain-managed entries (do not remove) ---
   <missing patterns, one per line>

5. Tell the user:

   Patched

   .beads/.gitignore

   with N missing entries. These entries prevent runtime and database files from being tracked by git.

cd "$(git rev-parse --show-toplevel)" && git ls-files --cached .beads/ | while IFS= read -r f; do
  if git check-ignore -q "$f" 2>/dev/null; then
    echo "$f"
  fi
done

1. Remove them from the index (this untracks them without deleting from disk):
   bash

   git rm --cached <file1> <file2> ...

2. Tell the user:

   Untracked N file(s) from git that are now covered by

   .beads/.gitignore

   . These files still exist on disk but will no longer be committed. You should commit this change.

if [[ ! -d "$MEMORY_DIR" ]]; then
  mkdir -p "$MEMORY_DIR"
fi

Created memory directory at

$MEMORY_DIR

. This is where swain-status, swain-session, and swain-stage store their caches.

swain.settings.json

jq empty swain.settings.json 2>/dev/null

swain.settings.json

contains invalid JSON. Skills will fall back to defaults. Fix the file or delete it to use defaults.

${XDG_CONFIG_HOME:-$HOME/.config}/swain/settings.json

jq empty "${XDG_CONFIG_HOME:-$HOME/.config}/swain/settings.json" 2>/dev/null

User settings file contains invalid JSON. Skills will fall back to project defaults. Fix the file or delete it.

jq

find skills/*/scripts/ -type f \( -name '*.sh' -o -name '*.py' \) ! -perm -u+x

chmod +x <files...>

Fixed executable permissions on N script(s).

.agents/

• execution-tracking.vars.json

  — swain-do first-run config

• specwatch.log

  — swain-design stale reference log

• evidencewatch.log

  — swain-search pool refresh log

if [[ ! -d ".agents" ]]; then
  mkdir -p ".agents"
fi

Created

.agents/

directory for skill configuration storage.

status-cache.json

STATUS_SCRIPT="skills/swain-status/scripts/swain-status.sh"
if [[ -f "$STATUS_SCRIPT" && ! -f "$MEMORY_DIR/status-cache.json" ]]; then
  bash "$STATUS_SCRIPT" --json > /dev/null 2>&1 || true
fi

Seeded initial status cache. The MOTD and status dashboard now have data.

swain-status

for f in .beads/bd.sock .beads/bd.sock.startlock .beads/dolt-server.pid .beads/dolt-server.lock .beads/.sync.lock; do
  if [[ -f "$f" ]]; then
    echo "stale: $f"
  fi
done

Found stale bd runtime files. If bd is not currently running (

pgrep -f "bd serve"

shows nothing), these can be safely removed. Remove them? (list the files)

swain-doctor summary:
  Governance ......... ok
  Legacy cleanup ..... ok (nothing to clean)
  Platform dotfolders  ok (nothing to clean)
  .beads/.gitignore .. ok
  Tools .............. ok (1 optional missing: fswatch)
  Memory directory ... ok
  Settings ........... ok
  Script permissions . ok
  .agents directory .. ok
  Status cache ....... seeded
  bd health .......... ok

3 checks performed repairs. 0 issues remain.

• 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)