build-afm - SKILL.md Agent Skill

name: build-afm description: Build AFM from scratch — submodules, patches, webui, and Swift build. Use when user types /build-afm, asks to build afm, or needs a fresh build from a clean clone. user_invocable: true

Build AFM

Build the afm binary from scratch, suitable for a fresh clone or a full rebuild.

Usage

/build-afm — release build (default)
/build-afm debug — debug build
/build-afm release — explicit release build

Instructions

Step 0: Validate Prerequisites

Before building, check that all required tools and environment are present. Run these checks and collect results:

# 1. Apple Silicon check (MLX requires arm64)
uname -m   # must be "arm64"

# 2. macOS version (Package.swift requires macOS 26+)
sw_vers -productVersion   # must be 26.0 or higher

# 3. Homebrew (must come before brew-installed tools)
brew --version

# 4. Xcode (full install — mlx-swift uses Metal framework SDK, not available in standalone CLI Tools)
xcode-select -p           # must point to Xcode.app, NOT /Library/Developer/CommandLineTools
swift --version           # needs Swift 5.9+ (swift-tools-version: 5.9)

# 5. Git (for submodule operations — installed via brew or Xcode)
git --version

# 6. Node.js + npm (for llama.cpp webui build — Svelte/Vite frontend)
node --version            # Node 18+ recommended
npm --version

Present results as a checklist to the user in dependency order (install top-to-bottom). For each item, show pass/fail, reason, and install command (even on pass, for copy-paste on other machines):

#	Prerequisite	Check	Status	Reason	Install
1	Apple Silicon	`uname -m` = arm64	pass/fail	MLX framework requires ARM64 GPU	N/A (hardware requirement)
2	macOS 26+ (Tahoe)	`sw_vers` >= 26.0	pass/fail	Foundation Models backend + SDK APIs	System Settings > Software Update
3	Homebrew	`brew --version`	pass/fail	Package manager — Git, Node.js depend on it	`/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`
4	Xcode (full)	`xcode-select -p` points to Xcode.app	pass/fail	mlx-swift uses Metal SDK (not in standalone CLI Tools)	Install from App Store → search "Xcode"
5	Swift 5.9+	`swift --version`	pass/fail	swift-tools-version: 5.9 in Package.swift	Included with Xcode
6	Git	`git --version`	pass/fail	Submodule init (mlx-swift-lm, llama.cpp)	`brew install git`
7	Node.js 18+	`node --version`	pass/fail	llama.cpp webui build (Svelte/Vite)	`brew install node`
8	npm	`npm --version`	pass/fail	`npm install` + `npm run build` for webui	Included with Node.js

Important Xcode notes:

Standalone CLI Tools (xcode-select --install) are NOT sufficient — mlx-swift imports the Metal framework which requires the full Xcode SDK
If xcode-select -p returns /Library/Developer/CommandLineTools, switch to Xcode: sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
After installing Xcode, accept the license: sudo xcodebuild -license accept

If anything is missing, present the failing items with install commands and ask the user to confirm when ready. Alternative Node.js install:

Node.js + npm (via nvm instead of Homebrew): curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash && nvm install 22

Do NOT proceed with the build until all prerequisites pass.

Step 1: Build

Parse the argument: if the user passes debug, use --debug. Otherwise default to release.

Run the full build script with NO skip flags:

./Scripts/build-from-scratch.sh        # release (default)
./Scripts/build-from-scratch.sh --debug # debug

IMPORTANT: Never add --skip-submodules, --skip-patches, or --skip-webui. The point of this skill is a complete from-scratch build.

Step 2: Monitor

The script already handles:

git submodule update --init --recursive
Scripts/apply-mlx-patches.sh (apply + verify)
llama.cpp webui build (npm install + build)
Swift package resolve + clean + build
Version injection: writes the git commit SHA into BuildInfo.swift (then restores it after build)
Strip symbols for release builds
Metallib bundle verification
Info.plist embedding verification — fails the build if the __TEXT,__info_plist section is missing or doesn't contain NSSpeechRecognitionUsageDescription. Required by Sources/MacLocalAPI/Info.plist + Package.swift linker flags (-Xlinker -sectcreate -Xlinker __TEXT -Xlinker __info_plist -Xlinker …). Without this, macOS 26 SIGABRTs any Speech Recognition / microphone / camera call.

Step 3: Report Results

After the build succeeds, report to the user:

The build configuration (debug or release)
The full absolute path to the compiled afm binary (from the script output)
The version string by running: <binary-path>/afm --version

Do NOT add example run commands, CLI options, or environment variables. Just report the binary path and version — the user knows how to run it.

Step 4: Handle Failures

If the build fails, show the error output and suggest checking:

Xcode Command Line Tools are installed (xcode-select -p)
Node.js/npm available for webui build
Submodules initialized properly
Re-run Step 0 prerequisite checks to catch environment issues