Project Onboarding One-time setup for adopting swain in a project. This skill is not idempotent — it migrates files and installs tools. For per-session health checks, use swain-doctor. Run all phases in order. If a phase detects its work is already done, skip it and move to the next. Phase 1: CLAUDE.md → AGENTS.md migration Goal: establish the @AGENTS.md include pattern so project instructions live in AGENTS.md (which works across Claude Code, GitHub, and other tools that read AGENTS.md natively). Step 1.1 — Survey existing files cat CLAUDE.md 2

/dev/null ; echo "---SEPARATOR---" ; cat AGENTS.md 2

/dev/null Classify the current state: CLAUDE.md AGENTS.md State Missing or empty Missing or empty Fresh — no migration needed Contains only @AGENTS.md Any Already migrated — skip to Phase 2 Has real content Missing or empty Standard — migrate CLAUDE.md → AGENTS.md Has real content Has real content Split — needs merge (ask user) Step 1.2 — Migrate Fresh state: Create both files.

CLAUDE.md

@AGENTS.md

AGENTS.md

(empty — governance will be added in Phase 3) Already migrated: Skip to Phase 2. Standard state: Copy CLAUDE.md content to AGENTS.md (preserve everything). If CLAUDE.md contains a

block, strip it from the AGENTS.md copy — it will be re-added cleanly in Phase 3. Replace CLAUDE.md with: @AGENTS.md Tell the user: Migrated your CLAUDE.md content to AGENTS.md and replaced CLAUDE.md with @AGENTS.md . Your existing instructions are preserved — Claude Code reads AGENTS.md via the include directive. Split state: Both files have content. Ask the user: Both CLAUDE.md and AGENTS.md have content. How should I proceed? Merge — append CLAUDE.md content to the end of AGENTS.md, then replace CLAUDE.md with @AGENTS.md Keep AGENTS.md — discard CLAUDE.md content, replace CLAUDE.md with @AGENTS.md Abort — leave both files as-is, skip migration If merge: append CLAUDE.md content (minus any

block) to AGENTS.md, replace CLAUDE.md with @AGENTS.md . Phase 2: Verify dependencies Goal: ensure uv is available and the vendored tk script is accessible. Step 2.1 — Check uv availability command -v uv If uv is found, skip to Step 2.2. If missing, install: curl -LsSf https://astral.sh/uv/install.sh | sh If installation fails, tell the user: uv installation failed. You can install it manually ( https://docs.astral.sh/uv/getting-started/installation/ ) — swain scripts require uv for Python execution. Then skip the rest of Phase 2 (don't block init on uv, but warn that scripts will not function without it). Step 2.2 — Verify vendored tk tk (ticket) is vendored in the swain skill tree — no external installation is needed. TK_PATH = " $( find . .claude .agents -path '*/swain-do/bin/tk' -print -quit 2

/dev/null ) " test -x " $TK_PATH " && echo "tk found at $TK_PATH " || echo "tk not found" If found, verify it runs: " $TK_PATH " help

/dev/null 2

&1 && echo "tk works" || echo "tk broken" If tk is not found or broken, tell the user: The vendored tk script was not found at skills/swain-do/bin/tk . This usually means the swain-do skill was not fully installed. Try running /swain update to reinstall skills. Step 2.3 — Migrate from beads (if applicable) Check if this project has existing beads data: test -d .beads && echo "beads found" || echo "no beads" If .beads/ exists: Check for backup data: ls .beads/backup/issues.jsonl 2>/dev/null If backup exists, offer migration: Found existing .beads/ data. Migrate tasks to tk? This will convert .beads/backup/issues.jsonl to .tickets/ markdown files. If user agrees, run migration: TK_BIN = "$(cd " $( dirname " $TK_PATH " ) " && pwd ) " export PATH=" $TK_BIN : $PATH " cp .beads/backup/issues.jsonl .beads/issues.jsonl 2

/dev/null

migrate-beads expects this location

ticket-migrate-beads Verify: ls .tickets/*.md 2>/dev/null | wc -l Tell the user the results and that .beads/ can be removed after verification. If .beads/ does not exist, skip this step. tk creates .tickets/ on first tk create . Phase 3: Pre-commit security hooks Goal: configure pre-commit hooks for secret scanning so credentials are caught before they enter git history. Default scanner is gitleaks; additional scanners (TruffleHog, Trivy, OSV-Scanner) are opt-in. Step 3.1 — Check for existing .pre-commit-config.yaml test -f .pre-commit-config.yaml && echo "exists" || echo "missing" If exists: Present the current config and ask: Found existing .pre-commit-config.yaml . How should I proceed? Merge — add swain's gitleaks hook alongside your existing hooks Skip — leave pre-commit config unchanged Replace — overwrite with swain's default config (your existing hooks will be lost) If user chooses Skip, skip to Phase 4. If missing: Proceed to Step 3.2. Step 3.2 — Check pre-commit framework command -v pre-commit && pre-commit --version If pre-commit is not found, install it: uv tool install pre-commit If uv is unavailable or installation fails, warn: pre-commit framework not available. You can install it manually ( uv tool install pre-commit or pip install pre-commit ). Skipping hook setup. Skip to Phase 4 if pre-commit cannot be installed. Step 3.3 — Create or update .pre-commit-config.yaml The default config enables gitleaks: repos : - repo : https : //github.com/gitleaks/gitleaks rev : v8.21.2 hooks : - id : gitleaks If the user requested additional scanners (via --scanner flags or when asked), add their hooks: TruffleHog (opt-in): - repo : https : //github.com/trufflesecurity/trufflehog rev : v3.88.1 hooks : - id : trufflehog args : [ '--results=verified,unknown' ] Trivy (opt-in): - repo : https : //github.com/cebidhem/pre - commit - trivy rev : v1.0.0 hooks : - id : trivy - fs args : [ '--severity' , 'HIGH,CRITICAL' , '--scanners' , 'vuln,license' ] OSV-Scanner (opt-in): - repo : https : //github.com/nicjohnson145/pre - commit - osv - scanner rev : v0.0.1 hooks : - id : osv - scanner Write the config file. If merging with an existing config, append the new repo entries to the existing repos: list. Step 3.4 — Install hooks pre-commit install Step 3.5 — Update swain.settings.json Read the existing swain.settings.json (if any) and add the sync.scanners key: { "sync" : { "scanners" : { "gitleaks" : { "enabled" : true } , "trufflehog" : { "enabled" : false } , "trivy" : { "enabled" : false , "scanners" : [ "vuln" , "license" ] , "severity" : "HIGH,CRITICAL" } , "osv-scanner" : { "enabled" : false } } } } Set enabled: true for any scanners the user opted into. Merge with existing settings — do not overwrite other keys. Tell the user: Pre-commit hooks configured with gitleaks (default). Scanner settings saved to swain.settings.json . To enable additional scanners later, edit swain.settings.json and re-run /swain-init . Phase 4: Swain governance Goal: add swain's routing and governance rules to AGENTS.md. Step 4.1 — Check for existing governance grep -l "swain governance" AGENTS.md CLAUDE.md 2

/dev/null If found in either file, governance is already installed. Tell the user and skip to Phase 5. Step 4.2 — Ask permission Ask the user: Ready to add swain governance rules to AGENTS.md. These rules: Route artifact requests (specs, stories, ADRs, etc.) to swain-design Route task tracking to swain-do (using tk) Enforce the pre-implementation protocol (plan before code) Prefer swain skills over built-in alternatives Add governance rules to AGENTS.md? (yes/no) If no, skip to Phase 5. Step 4.3 — Inject governance Read the canonical governance content from skills/swain-doctor/references/AGENTS.content.md . Locate it by searching for the file relative to the installed skills directory: find .claude/skills .agents/skills skills -path '*/swain-doctor/references/AGENTS.content.md' -print -quit 2

/dev/null Append the full contents of that file to AGENTS.md. Tell the user: Governance rules added to AGENTS.md. These ensure swain skills are routable and conventions are enforced. You can customize anything outside the

markers. Phase 5: Finalize Step 5.1 — Create .agents directory mkdir -p .agents This directory is used by swain-do for configuration and by swain-design scripts for logs. Step 5.2 — Run swain-doctor Invoke the swain-doctor skill. This validates .tickets/ health, checks stale locks, removes legacy skill directories, and ensures governance is correctly installed. Step 5.3 — Onboarding Invoke the swain-help skill in onboarding mode to give the user a guided orientation of what they just installed. Step 5.4 — Summary Report what was done: swain init complete. CLAUDE.md → @AGENTS.md include pattern: [done/skipped/already set up] tk (ticket) verified: [done/not found] Beads migration: [done/skipped/no beads found] Pre-commit security hooks: [done/skipped/already configured] Swain governance in AGENTS.md: [done/skipped/already present] Re-running init If the user runs /swain init on a project that's already set up, each phase will detect its work is done and skip. The only interactive phase is governance injection (Phase 3), which checks for the

marker before asking. To force a fresh governance block, delete the

...

section from AGENTS.md and re-run.