--- name: wayfare-setup-dev # prettier-ignore description: "Check local tools and credentials against HERO.md, or set up a whole machine from the fleet's .fleet/setup.yaml when run at the fleet root. Guide git config, CLI sign-ins and missing dependencies. Never change shared files. Use on a fresh machine or clone, or when a tool or login is missing." argument-hint: "[--check | recalibrate]" compatibility: "Requires the complete Wayfare plugin and access to the developer machine whose local tools and credentials are being checked." disable-model-invocation: true --- # Setup: get a developer's machine ready Guide one developer through local setup using the team's `HERO.md` configuration. Keep developer-specific setup out of repository commits. Run at a fleet root, it sets up the whole machine instead: the fleet's `.fleet/setup.yaml`, the repos the person picks, their local-only files from an old machine, then this procedure in each repo. Read [WORKFLOW.md](WORKFLOW.md) in full before doing anything at a fleet root. ## Arguments - `recalibrate` - Tune the `HERO.md` fields this skill reads, then stop (see below). Matched before every other form. - `$ARGUMENTS`: - (none) - Full guided setup - `--check` - Only verify the current setup and report what is missing ## Prerequisites At a fleet root, wayfare must already be installed and the register cloned as `.fleet/`; on a clean machine that is the bootstrap in [docs/SETUP-YAML.md](../../docs/SETUP-YAML.md), done by a person. In a repo, `HERO.md` must exist. If it doesn't, tell the user: ``` No HERO.md found. Run wayfare:wayfare-init-repo first to configure the project. ``` ## `recalibrate` `wayfare:wayfare-setup-dev recalibrate` tunes this skill's config. It stops after tuning and does not run the main procedure. Check for `recalibrate` before you parse other arguments. If the first token of `$ARGUMENTS` is exactly `recalibrate`, print `wayfare-setup-dev: running recalibrate`, follow the four phases in [docs/RECALIBRATE.md](../../docs/RECALIBRATE.md): report, ask, write, commit. Use the table below as the report. Stop after these phases. ```bash WAYFARE_ROOT="${CLAUDE_PLUGIN_ROOT:-${WAYFARE_ROOT:-$HOME/.claude/plugins/wayfare-skills}}" "$WAYFARE_ROOT/scripts/hero-fields.sh" wayfare-setup-dev ``` Ask only about rows whose CURRENT value is `(unset)`, `(no-section)`, `(refused)`, `(absent)`, or `(no-file)`. Also ask about rows the user identifies as wrong. Do not ask about a row that already has the correct value. ## Instructions ### Step 1: Read HERO.md **If the first token of `$ARGUMENTS` is exactly `recalibrate`, run the `recalibrate` section above and stop.** Do this before the missing-HERO.md check below, which would otherwise send the user to `wayfare-init-repo` for the very file the verb exists to fill in. ```bash ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd) WAYFARE_ROOT="${CLAUDE_PLUGIN_ROOT:-${WAYFARE_ROOT:-$HOME/.claude/plugins/wayfare-skills}}" . "$WAYFARE_ROOT/scripts/hero-lib.sh" || { echo "wayfare: cannot load hero-lib.sh from $WAYFARE_ROOT, export WAYFARE_ROOT as the plugin root"; exit 1; } hero_config_show "$ROOT" hero_fleet_step0 || exit 1 ``` If the command prints `FLEET_ROOT`, stop this repo procedure. Read [WORKFLOW.md](WORKFLOW.md) in full and follow it instead. Parse the `## Developer Setup` section for required tools, recommended tools, and MCP servers. Also read other sections for implicit requirements (e.g., CI platform → `gh`, deployment platform → `kubectl`). ### Step 2: Check Git Configuration ```bash # Local git config git config --local user.name git config --local user.email # Global fallback git config --global user.name git config --global user.email # Signing git config --local commit.gpgsign git config --global commit.gpgsign git config --local gpg.format # Remote git remote -v ``` **Present findings:** ``` GIT CONFIGURATION ───────────────── [OK] user.name: "Jane Doe" (global) [OK] user.email: "jane@company.com" (global) [--] No local git config — using global values → Set local config for this repo? (useful if you use a different email for work vs personal projects) [--] Commit signing: not configured → Set up GPG/SSH signing? (recommended for verified commits) ``` **If local config is missing**, offer to set it: ```bash git config --local user.name "USER_NAME" git config --local user.email "USER_EMAIL" ``` Ask the user. Never auto-set identity config without confirmation. ### Step 3: Check Required CLI Tools For each tool in HERO.md `## Developer Setup → Required Tools`: ```bash which TOOL_NAME 2>/dev/null && TOOL_NAME --version 2>/dev/null ``` **Present findings:** ``` REQUIRED TOOLS ────────────── [OK] node: v20.11.0 (required: >=20) ✓ [OK] pnpm: 9.1.0 ✓ [OK] docker: 24.0.7 ✓ [!!] gh: not installed → Required for PR workflows. Install: brew install gh [!!] tofu: not installed → Required for infrastructure. Install: brew install opentofu ⚠ Do NOT install terraform — this project uses OpenTofu ``` For missing tools, provide **platform-appropriate install commands**: - macOS: `brew install TOOL_NAME` - Linux: distro-appropriate (apt, dnf, pacman) or official install script - Suggest the user's package manager if detectable ### Step 4: Check Authentication & Access For each installed CLI tool that requires auth: ```bash # GitHub gh auth status 2>&1 # AWS aws sts get-caller-identity 2>&1 # GCP gcloud auth list 2>&1 # kubectl kubectl cluster-info 2>&1 # Docker registry docker info 2>&1 | grep -i registry # Linear linear whoami 2>&1 || linear auth status 2>&1 ``` **Present findings:** ``` AUTHENTICATION ────────────── [OK] gh: authenticated as jane-doe (github.com) [!!] aws: not authenticated → Run: aws configure (or aws sso login) [OK] kubectl: connected to staging-cluster [--] linear: CLI not installed (recommended, not required) ``` Only check auth for tools that are actually installed AND relevant to HERO.md. ### Step 5: Check Recommended Tools Run Step 3's checks for `## Developer Setup → Recommended Tools`. Report missing recommended tools with `[--]` instead of `[!!]`. These tools do not block setup. ``` RECOMMENDED TOOLS ───────────────── [OK] pre-commit: 3.6.0 ✓ [--] linear: not installed → Optional CLI for issue management. Install: npm i -g @linear/cli ``` ### Step 6: Check MCP Servers If HERO.md lists MCP servers: ``` MCP SERVERS ─────────── [??] linear (mcp__linear): listed in HERO.md → Is the Linear MCP server configured in the active client? → This is needed for wayfare:wayfare-build-task to fetch issues [??] slack (mcp__slack): listed in HERO.md → Is the Slack MCP server configured in the active client? ``` MCP server setup happens in the client's settings, not on the command line. Tell the user what is expected and why. ### Step 7: Summary & Next Steps **If `--check` was passed**, just show the summary and exit. **For full setup**, after each section offer to fix what's missing. Then show final summary: ``` SETUP SUMMARY ═════════════ Git config: ✓ local user.name and user.email set Required tools: ✓ all 5 installed Authentication: ⚠ 1 issue — aws not authenticated Recommended: ✓ 2/2 installed MCP servers: ? 1 to verify — linear Remaining action items: 1. Run: aws sso login 2. Verify the Linear MCP server is configured in the active client Your environment is ready for development! 🎉 Run wayfare:wayfare-init-repo recalibrate if the project setup has changed. Next step: wayfare:wayfare-check-preflight — sanity-check tooling, .env, ports before starting (print only — model-invocation-restricted, cannot auto-run) ``` Do not also print `wayfare:wayfare-build-task`. Follow `wayfare-check-preflight`'s next steps after it passes. ## Key Principles - **Never modify shared files.** In a repo, this skill only touches local git config and suggests installs. At a fleet root it installs what `.fleet/setup.yaml` names, after asking. It never writes to HERO.md, CLAUDE.md, `setup.yaml`, or any committed file. - **Always ask before changing config.** Git identity, signing keys, and auth are personal. Confirm before setting any of them. - **Platform-aware.** Detect macOS vs Linux and suggest the right install commands. - **Idempotent.** Running `wayfare:wayfare-setup-dev` twice should be safe. Skip whatever is already done. - **Reference HERO.md.** Every check should tie back to why it's needed: "Required by HERO.md for wayfare:wayfare-push-pr" or "Used by CI (GitHub Actions)". ## Examples ``` wayfare:wayfare-setup-dev # Full guided setup (the whole machine at a fleet root) wayfare:wayfare-setup-dev --check # Just verify, don't change anything ```