| name | vp-build |
| description | Use when editing VP's macOS Swift agent code (apple/VantagePointAgent). Triggers an xcodegen + xcodebuild rebuild of VantagePointAgent.app with log monitoring, so the user doesn't need to run it in a separate terminal. Examples: edited apple/VantagePointAgent/Sources/*.swift, changed apple/VantagePointAgent/project.yml, or changed the club-unison Swift client (../club-unison/clients/swift) the agent depends on. |
VP Build Workflow（VantagePointAgent / pure Swift）
VP の macOS surface は apple/VantagePointAgent（doc 25 Model D の Swift menu bar agent、LSUIElement）。
pure Apple-native（Rust を一切リンクしない・FFI 無し）で、club-unison の native Swift Unison client
（../club-unison/clients/swift）越しに Mac daemon と喋る。Swift コードを編集したら、Claude が
xcodegen → xcodebuild でリビルド・再起動し、ログをモニタして成功/失敗を判定・報告する。
⚠️ 旧アーキは退役済み。apple/VantagePoint（Rust-tao app）/ crates/vp-bridge（FFI）/ mr mac
task はもう存在しない。vp-bridge FFI も ARCHS=arm64 リンクも mr mac も出てこない ── これらは
doc 25 の Swift-first 転換で消えた。本 skill は新 VantagePointAgent（xcodebuild）専用。
リビルドが必要な編集パス
| パターン | 理由 |
|---|
apple/VantagePointAgent/Sources/**.swift | agent UI / ロジック（AgentMenuView / AgentModel / CoreMIDIWatcher / DaemonClient / InstanceScanner / VPProtocol …） |
apple/VantagePointAgent/project.yml | XcodeGen プロジェクト定義（target / Info.plist properties / 依存）→ xcodegen 再生成が必須 |
../club-unison/clients/swift/**（UnisonClient SDK） | agent が SPM local path で依存。SDK 変更は agent ビルドに波及 |
リビルドしないケース
docs/**, README.md, CLAUDE.md, AGENTS.md 等のドキュメントcrates/vantage-point/** / crates/vp-cli/**（Rust サーバ/CLI 側 → cargo install --path crates/vp-cli --force）crates/vp-app/**（旧 webview app。frontend は別 dev loop = mr dev:web esbuild watch）- ユーザーが「build するな」と明示したとき
- 既に他の xcodebuild / cargo が走っている（直列化、
Resolve Package Graph 競合回避）
標準手順
0. 前提（fresh checkout / sibling 依存）
../club-unison/clients/swift が存在すること（project.yml の UnisonClient local path 依存）。
無ければ club-unison を sibling に clone（new-machine-setup memory: creoui と同じ sibling 前提）。.xcodeproj と Generated/Info.plist は gitignore された生成物。fresh checkout や project.yml
変更後は 必ず xcodegen generate を先に走らせる（無いと does not exist で xcodebuild 失敗）。
1. リビルド実行（バックグラウンド）
( cd apple/VantagePointAgent && xcodegen generate ) 2>&1 | tee /tmp/vp_agent_build.log
xcodebuild \
-project apple/VantagePointAgent/VantagePointAgent.xcodeproj \
-scheme VantagePointAgent \
-configuration Debug \
-derivedDataPath apple/VantagePointAgent/DerivedData \
build 2>&1 | tee -a /tmp/vp_agent_build.log
run_in_background: true で Bash tool 発火、tee で stdout/stderr 保存、2>&1 必須。- ビルド成果物 =
apple/VantagePointAgent/DerivedData/Build/Products/Debug/VantagePointAgent.app。
mr agent task があればそれを優先（rig wrapper が kill→xcodegen→xcodebuild→launch を束ねる）。
2. Monitor で完了判定
until grep -qE "\*\* BUILD SUCCEEDED \*\*|\*\* BUILD FAILED \*\*|error: |The following build commands failed" /tmp/vp_agent_build.log; do sleep 3; done
grep -E "\*\* BUILD (SUCCEEDED|FAILED) \*\*|error: |warning: .*Sendable|ld: " /tmp/vp_agent_build.log | tail -15
Monitor tool の command にそのまま渡す。persistent: false、timeout_ms: 600000（10 分）で十分。
3. 結果判定
| ログパターン | 判定 | アクション |
|---|
** BUILD SUCCEEDED ** | 成功 | agent を再起動（手順 4）→「再起動済、menu bar を確認してください」と報告 |
** BUILD FAILED ** | 失敗 | error: 行（Swift type / concurrency / missing member）を抽出して原因報告 |
error: no such module 'UnisonClient' | 依存欠落 | ../club-unison/clients/swift の存在 + xcodebuild -resolvePackageDependencies を確認 |
scheme ... does not contain / .xcodeproj does not exist | 生成漏れ | xcodegen generate を先に走らせていない → 手順 1 の xcodegen から |
CoreSimulator is out of date | 無視 | macOS target には無関係 |
4. 再起動（LSUIElement = menu bar）
pkill -x VantagePointAgent 2>/dev/null; sleep 0.3
open apple/VantagePointAgent/DerivedData/Build/Products/Debug/VantagePointAgent.app
agent は dock icon を持たない（LSUIElement: true）。起動確認は menu bar アイコン or pgrep -x VantagePointAgent。
既知のハマりどころ
xcodegen を飛ばす事故
.xcodeproj は gitignore。project.yml を変えたのに xcodebuild だけ回すと古い project graph でビルド
され、新しい Info.plist / 依存 / source が反映されない。project.yml 変更時は必ず xcodegen generate。
SPM local path 依存（club-unison）
UnisonClient は remote URL ではなく sibling repo の local path（../../../club-unison/clients/swift）。
sibling が無い / branch がズレていると no such module 'UnisonClient'。VP と club-unison は併せて更新する。
codesign（cp 禁止は Rust 側の話）
Swift agent は xcodebuild が自動署名（CODE_SIGN_STYLE: Automatic）。.app を cp で別所へ運ぶと
署名が剥がれ macOS に kill されるので、open で DerivedData の成果物を直接起動する。CLI（vp）側は
従来どおり cargo install --path crates/vp-cli --force（cp は厳禁、CLAUDE.md feedback）。
Swift 6 concurrency
SWIFT_VERSION: "6.0"（strict concurrency）。Sendable / actor-isolation の error が出やすい。
error: が concurrency 系なら、該当型に @MainActor or Sendable 整合を促す形で報告する。
CLI / daemon 側のインストール（別系統）
Swift agent ではなく Rust（crates/vantage-point/ / crates/vp-cli/）を触ったとき:
cargo install --path crates/vp-cli --force
daemon の再起動は vp restart-all or vp daemon stop && vp daemon start。
やらない判断（ユーザー確認を挟む）
project.yml の target/署名設定を大きく変えたとき（動作が不確定）- club-unison SDK 側の破壊的変更を伴うとき（VP/unison の両 repo 整合が要る）
- 同時並行で複数編集 → まとめて確認したいとき
- ユーザーが「しばらく build するな」「貯めてからやる」と指示したとき
