diff --git a/plugins/agent-plugin-skills/.codex-plugin/plugin.json b/plugins/agent-plugin-skills/.codex-plugin/plugin.json index 03d5bb9a..54dfc707 100644 --- a/plugins/agent-plugin-skills/.codex-plugin/plugin.json +++ b/plugins/agent-plugin-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agent-plugin-skills", - "version": "6.7.14", + "version": "6.7.15", "description": "Installable maintainer skills for skills-export repositories.", "author": { "name": "Gale", diff --git a/plugins/agent-plugin-skills/pyproject.toml b/plugins/agent-plugin-skills/pyproject.toml index f4078393..1b2a7fca 100644 --- a/plugins/agent-plugin-skills/pyproject.toml +++ b/plugins/agent-plugin-skills/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "agent-plugin-skills-maintenance" -version = "6.7.14" +version = "6.7.15" description = "Maintainer-only Python tooling baseline for agent-plugin-skills." requires-python = ">=3.11" dependencies = [] diff --git a/plugins/agent-plugin-skills/uv.lock b/plugins/agent-plugin-skills/uv.lock index cc139f7c..a65145fc 100644 --- a/plugins/agent-plugin-skills/uv.lock +++ b/plugins/agent-plugin-skills/uv.lock @@ -4,7 +4,7 @@ requires-python = ">=3.11" [[package]] name = "agent-plugin-skills-maintenance" -version = "6.7.14" +version = "6.7.15" source = { virtual = "." } [package.dev-dependencies] diff --git a/plugins/apple-dev-skills/.codex-plugin/plugin.json b/plugins/apple-dev-skills/.codex-plugin/plugin.json index fe0643d8..e343b2a6 100644 --- a/plugins/apple-dev-skills/.codex-plugin/plugin.json +++ b/plugins/apple-dev-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "apple-dev-skills", - "version": "6.7.14", + "version": "6.7.15", "description": "Apple development workflows for Codex, including SwiftUI architecture and DocC authoring guidance.", "author": { "name": "Gale", diff --git a/plugins/apple-dev-skills/ROADMAP.md b/plugins/apple-dev-skills/ROADMAP.md index 689bab4d..0440f84b 100644 --- a/plugins/apple-dev-skills/ROADMAP.md +++ b/plugins/apple-dev-skills/ROADMAP.md @@ -202,6 +202,7 @@ Planned - [ ] Decide which implementation surface should own the offload path. - [ ] Define the input and output contract for the offload path so verification work can be delegated without losing decision-useful detail. - [ ] Cover the highest-value offload cases first, including `swift build`, `swift test`, `xcodebuild`, preview refresh, diagnostics refresh, and noisy failure summarization. +- [ ] Cover performance-sensitive Apple silicon package and Xcode workflows, including `OSSignposter`, `xctrace`, Time Profiler, Metal System Trace, Allocations, VM Tracker, Audio, MLX, local AI, and trace artifact reporting. - [ ] Document when the main agent should stay local versus when it should hand verification work to the offload path. - [ ] Add validation or smoke-test coverage once the implementation surface is chosen. diff --git a/plugins/apple-dev-skills/pyproject.toml b/plugins/apple-dev-skills/pyproject.toml index b834ef46..a7a61f16 100644 --- a/plugins/apple-dev-skills/pyproject.toml +++ b/plugins/apple-dev-skills/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "apple-dev-skills-maintainer" -version = "6.7.14" +version = "6.7.15" description = "Maintainer tooling for the apple-dev-skills repository" requires-python = ">=3.9" dependencies = [] diff --git a/plugins/apple-dev-skills/skills/swift-package-testing-workflow/SKILL.md b/plugins/apple-dev-skills/skills/swift-package-testing-workflow/SKILL.md index d2ed3726..dcd9999b 100644 --- a/plugins/apple-dev-skills/skills/swift-package-testing-workflow/SKILL.md +++ b/plugins/apple-dev-skills/skills/swift-package-testing-workflow/SKILL.md @@ -7,7 +7,7 @@ description: Guide Swift Testing, XCTest holdouts, xctestplan handoff conditions ## Purpose -Use this skill as the primary execution workflow for test-focused work in existing Swift Package Manager repositories. Keep it focused on Swift Testing, XCTest holdouts, `.xctestplan` handoff conditions, async-test guidance, semantic accessibility-test boundaries, filters, retries, fixtures, and package-level test diagnosis instead of broad manifest and build/run work. `scripts/run_workflow.py` is the runtime entrypoint for repo-shape checks, test-surface command planning, and clean handoff to the build/run or Xcode-oriented surfaces when the request drifts. +Use this skill as the primary execution workflow for test-focused work in existing Swift Package Manager repositories. Keep it focused on Swift Testing, XCTest holdouts, `.xctestplan` handoff conditions, async-test guidance, semantic accessibility-test boundaries, performance-sensitive package workload profiling, filters, retries, fixtures, and package-level test diagnosis instead of broad manifest and build/run work. `scripts/run_workflow.py` is the runtime entrypoint for repo-shape checks, test-surface command planning, and clean handoff to the build/run or Xcode-oriented surfaces when the request drifts. ## When To Use @@ -15,6 +15,7 @@ Use this skill as the primary execution workflow for test-focused work in existi - Use this skill for Swift Testing-first package work, XCTest holdouts, async-test design, semantic accessibility-test boundaries, and test-fixture organization. - Use this skill for package-level `.xctestplan` execution when the package surface needs Xcode test-plan follow-through. - Use this skill when the request is about test selection, filtering, retries, failures, flaky tests, or test-only Debug/Release validation. +- Use this skill when the request is about package-first performance-sensitive testing, signpost placement, Release workload harnesses, or profiling-ready package test design for Audio, Metal, MLX, local AI, streaming, or other Apple silicon-sensitive workloads. - Do not use this skill for broad manifest edits, dependency work, package resources, plugin flows, or ordinary build and run work. - Do not use this skill for brand-new package bootstrap from nothing. - Do not use this skill for repo-guidance alignment in an existing package repo. @@ -47,8 +48,9 @@ Use this skill as the primary execution workflow for test-focused work in existi - preserve its package-appropriate logging, telemetry, structured-concurrency, and Swift Testing guidance 4. Run `scripts/run_workflow.py` to resolve repo shape, confirm the request stays on the testing surface, and plan the package-testing command path. 5. Use `references/package-resources-testing-and-builds.md` when the request touches Swift Testing, XCTest, `.xctestplan`, accessibility-related semantic tests, fixtures, async test discipline, or test-related Debug/Release validation. -6. If the repo root is ambiguous because Xcode-managed markers are present at the same root, use `references/xcode-handoff-conditions.md` and hand off cleanly to `xcode-testing-workflow`. -7. Report which parts were agent-executed, the docs relied on, the repo-shape result, and any required next step or handoff. +6. Use `references/performance-sensitive-testing-and-profiling.md` when the request touches package-first instrumentation, `OSSignposter`, `xctrace`, Time Profiler, Metal System Trace, Allocations, VM Tracker, Audio, MLX, local AI, streaming, or other performance-sensitive Apple silicon workloads. +7. If the repo root is ambiguous because Xcode-managed markers are present at the same root, use `references/xcode-handoff-conditions.md` and hand off cleanly to `xcode-testing-workflow`. +8. Report which parts were agent-executed, the docs relied on, the repo-shape result, and any required next step or handoff. ## Inputs @@ -100,6 +102,7 @@ Use this skill as the primary execution workflow for test-focused work in existi - Xcode MCP mutation tools - `.xctestplan` execution or package test behavior that is more authoritative through Xcode-managed Apple SDK integration - direct test execution through Xcode-native destinations, UI testing, or `.xctestplan` handling inside an Xcode-managed workspace + - Instruments UI inspection, `.trace` artifact interpretation, or `xctrace` capture that depends on Xcode-managed schemes, destinations, app hosts, or test plans - Recommend `apple-ui-accessibility-workflow` when the user is really asking how the UI should expose semantics to assistive technologies instead of how a package-side test should be organized. - Hand off to `xcode-build-run-workflow` when package test work instead crosses into direct changes inside `.xcodeproj`, `.xcworkspace`, or `.pbxproj` managed scope. - Recommend `sync-swift-package-guidance` when the request is really about repo guidance instead of execution. @@ -120,6 +123,7 @@ Use this skill as the primary execution workflow for test-focused work in existi - `references/workflow-policy.md` - `references/repo-shape-detection.md` - `references/package-resources-testing-and-builds.md` +- `references/performance-sensitive-testing-and-profiling.md` - `references/xcode-handoff-conditions.md` ### Contract References diff --git a/plugins/apple-dev-skills/skills/swift-package-testing-workflow/references/cli-command-matrix.md b/plugins/apple-dev-skills/skills/swift-package-testing-workflow/references/cli-command-matrix.md index b0dde2dd..fef046aa 100644 --- a/plugins/apple-dev-skills/skills/swift-package-testing-workflow/references/cli-command-matrix.md +++ b/plugins/apple-dev-skills/skills/swift-package-testing-workflow/references/cli-command-matrix.md @@ -35,3 +35,14 @@ - `xcrun --find swift` when Apple toolchain location matters - `xcodebuild -version` when Apple-managed SDK or Xcode component state matters - `xcodebuild -showComponent metalToolchain` when Metal toolchain availability is relevant +- `xcrun --find xctrace` when Instruments trace capture or export is relevant +- `xcrun xctrace version` when the active Instruments command-line tool version matters +- `xcrun xctrace list templates` before assuming an Instruments template exists on the current Xcode version + +## Performance profiling + +- `swift build -c release --product ` before profiling an optimized package executable +- `xcrun xctrace record --template 'Time Profiler' --output traces/.trace --launch -- .build/release/ ` for CPU profile capture +- `xcrun xctrace record --template 'Metal System Trace' --time-limit 30s --output traces/.trace --launch -- .build/release/ ` for Metal CPU/GPU timeline capture +- `xcrun xctrace record --template 'Allocations' --output traces/.trace --launch -- .build/release/ ` for allocation capture +- Prefer profiling the built executable over profiling `swift run` when the measurement target is runtime behavior rather than build or package-driver overhead. diff --git a/plugins/apple-dev-skills/skills/swift-package-testing-workflow/references/package-resources-testing-and-builds.md b/plugins/apple-dev-skills/skills/swift-package-testing-workflow/references/package-resources-testing-and-builds.md index d93b9c46..662a2fb5 100644 --- a/plugins/apple-dev-skills/skills/swift-package-testing-workflow/references/package-resources-testing-and-builds.md +++ b/plugins/apple-dev-skills/skills/swift-package-testing-workflow/references/package-resources-testing-and-builds.md @@ -44,3 +44,9 @@ - Use `xcodebuild` when schemes, destinations, configurations, test plans, or Apple-managed SDK and toolchain behavior matter. - Validate Release builds intentionally when optimization or packaging can change behavior. - Treat tagged releases as a cue to verify both the everyday Debug path and the Release artifact path before publishing. + +## Performance-sensitive package workloads + +- Use `performance-sensitive-testing-and-profiling.md` when a package test or executable workload needs repeatable timing, allocation, VM, CPU, GPU, Audio, Metal, MLX, local AI, streaming, or Apple silicon performance evidence. +- Keep ordinary correctness tests in Swift Testing or XCTest, but do not treat passing package tests as proof that performance-sensitive workloads have been profiled. +- Prefer package-owned signposts and Release executable harnesses before handing off to Xcode-managed Instruments or `xctrace` interpretation. diff --git a/plugins/apple-dev-skills/skills/swift-package-testing-workflow/references/performance-sensitive-testing-and-profiling.md b/plugins/apple-dev-skills/skills/swift-package-testing-workflow/references/performance-sensitive-testing-and-profiling.md new file mode 100644 index 00000000..342acf3d --- /dev/null +++ b/plugins/apple-dev-skills/skills/swift-package-testing-workflow/references/performance-sensitive-testing-and-profiling.md @@ -0,0 +1,137 @@ +# Performance-Sensitive Testing and Profiling + +Use this reference when a Swift package contains performance-sensitive Apple-platform work, especially Audio, Metal, MLX, local AI models, streaming generation, real-time rendering, or large memory-mapped resources. + +## Apple Documentation Anchors + +- [`OSSignposter`](https://developer.apple.com/documentation/os/ossignposter) records signposted intervals and events through the unified logging system so Instruments can show package-defined phases on a trace timeline. +- [Xcode command-line tool reference](https://developer.apple.com/documentation/xcode/xcode-command-line-tool-reference) documents `xctrace` as the command-line tool for recording, importing, exporting, and symbolicating Instruments `.trace` files. +- [Installing the command-line tools](https://developer.apple.com/documentation/xcode/installing-the-command-line-tools) states that `xcodebuild` and `xctrace` ship with full Xcode, not the standalone Command Line Tools for Xcode package. +- [Metal developer workflows](https://developer.apple.com/documentation/xcode/metal-developer-workflows) describes Metal System Trace as the Instruments tool for CPU/GPU timeline and Metal memory analysis. +- [Analyzing the performance of your Metal app](https://developer.apple.com/documentation/xcode/analyzing-the-performance-of-your-metal-app) describes the Instruments Game Performance template and its included instruments, including Points of Interest, Time Profiler, Virtual Memory Trace, Metal Resource Events, Metal Application, and GPU. +- [Gathering information about memory use](https://developer.apple.com/documentation/xcode/gathering-information-about-memory-use) describes the Allocations instrument for heap and anonymous virtual memory allocations. + +## Apple Silicon Baseline + +- Treat Apple silicon Macs as the default profiling target for current and forward-looking Swift package performance guidance. +- Do not add Intel-specific tuning, benchmark interpretation, architecture switches, or fallback expectations unless the target repository explicitly declares Intel Mac support. +- Record the Apple silicon device class, chip family when known, macOS version, Xcode version, Swift version, package resolved versions, model identifier, model dtype or quantization, and workload fixture before comparing trace results. +- For Metal, MLX, and Audio workloads, treat unified memory, GPU scheduling, thermal state, and model/resource residency as first-class evidence instead of CPU time alone. +- Prefer measuring on a quiet machine. Do not run heavy package tests, model loads, build jobs, or trace captures concurrently with other expensive validation. + +## Decision Model + +- Use ordinary `swift test` for correctness, small unit coverage, fixture validation, and regression checks that do not depend on runtime performance. +- Use package-level performance tests or executable harnesses when the package needs repeatable timing, allocation, or resource-pressure evidence. +- Use `xctrace` or Instruments when the question is where CPU time is spent, how CPU and GPU work overlap, where heap or virtual memory grows, or how package-defined phases align with system behavior. +- Use Xcode-managed test plans when sanitizers, runtime API checking, destinations, or named test configurations are part of the repeatable performance contract. +- Use an app host when the package behavior depends on app lifecycle, audio session behavior, UI event loops, display timing, sandboxing, entitlements, or simulator/device state. + +## Package Workload Shape + +- Build before profiling so the trace captures the workload, not package resolution or compilation. +- Profile Release builds when optimization, inlining, specialization, ARC behavior, or Metal/MLX performance is the question. +- Keep Debug traces only when diagnosing debug-only assertions, sanitizer failures, or development-time runtime warnings. +- Prefer a dedicated executable target or test harness that performs one workload at a time with deterministic fixtures. +- Separate cold model load, warmup, steady-state execution, streaming or chunk generation, audio rendering, and teardown into distinct phases. +- For MLX and large local model work, run one heavy workload at a time unless the test is explicitly about concurrent model pressure. +- For Audio work, capture sample rate, buffer size, channel count, device or route assumptions, and whether playback is live, synthetic, or file-backed. +- For benchmark-style tests, keep fixture inputs stable and report whether results are wall-clock timings, CPU samples, GPU timeline evidence, allocation counts, resident memory, or virtual memory activity. + +## Signpost Contract + +- Use `OSSignposter` for durable package-defined trace intervals when profiling will be repeated or compared across runs. +- Keep signpost names stable, short, and phase-oriented so traces from different branches can be compared. +- Prefer one subsystem per package or executable harness and categories that describe the workload family, such as `audio`, `mlx`, `inference`, `streaming`, or `benchmark`. +- Avoid signposting every low-level helper call. Mark phases that a maintainer can interpret in Time Profiler, Points of Interest, Metal System Trace, Allocations, or VM views. +- Recommended interval names for Audio and MLX packages: + - `model.load` + - `model.warmup` + - `audio.decode` + - `audio.render` + - `inference.prefill` + - `inference.generate` + - `stream.chunk` + - `resource.teardown` +- Recommended event names: + - `fixture.ready` + - `first.audio.buffer` + - `first.token` + - `first.chunk` + - `playback.started` + - `playback.completed` + +## Instrument Selection + +- Use Time Profiler when the question is CPU call stacks, Swift runtime overhead, actor or task scheduling overhead, lock contention symptoms, expensive decoding, or non-GPU model-preparation work. +- Use Metal System Trace when the question is CPU/GPU overlap, command buffer timing, GPU scheduling, Metal resource events, GPU workload gaps, or whether compute work is actually reaching the GPU as expected. +- Use Allocations when the question is heap growth, allocation churn, retained object graphs, unexpected bridging, autorelease-like spikes, or per-phase allocation deltas. +- Use VM Tracker or Virtual Memory Trace when the question is mapped model weights, dirty memory growth, resident memory pressure, memory-mapped files, or large region behavior that heap allocation summaries do not explain. +- Use Points of Interest or signpost views to align package-defined phases with the system timeline. +- Use Processor Trace only when supported by the active Xcode/Instruments version and the user specifically needs lower-overhead Apple-silicon CPU execution evidence beyond Time Profiler. + +## Command Guidance + +- Verify full Xcode is active before relying on `xctrace`: + +```bash +xcode-select -p +xcrun --find xctrace +xcrun xctrace version +``` + +- Inspect available trace templates on the current machine: + +```bash +xcrun xctrace list templates +``` + +- Build the package workload before recording: + +```bash +swift build -c release --product +``` + +- Record a built executable with Time Profiler: + +```bash +xcrun xctrace record --template 'Time Profiler' --output traces/.trace --launch -- .build/release/ +``` + +- Record a bounded run when the workload would otherwise continue indefinitely: + +```bash +xcrun xctrace record --template 'Time Profiler' --time-limit 30s --output traces/.trace --launch -- .build/release/ +``` + +- Record Metal work when the package executable or host app exercises GPU-backed work: + +```bash +xcrun xctrace record --template 'Metal System Trace' --time-limit 30s --output traces/.trace --launch -- .build/release/ +``` + +- Record allocation behavior: + +```bash +xcrun xctrace record --template 'Allocations' --output traces/.trace --launch -- .build/release/ +``` + +- Redirect target output when the harness prints structured workload metadata: + +```bash +xcrun xctrace record --template 'Time Profiler' --target-stdout traces/.stdout.txt --output traces/.trace --launch -- .build/release/ +``` + +## Artifact Expectations + +- Preserve `.trace` artifacts when they justify a performance fix, tuning decision, or regression report. +- Keep trace artifacts out of git unless the repository explicitly tracks performance evidence fixtures or release artifacts. +- Report the workload command, build configuration, hardware, OS, Xcode, Swift version, model/resource versions, trace path, and the specific question the trace answered. +- Do not pretend text export replaces opening Instruments for timeline-heavy Metal, GPU, or memory-pressure investigation. +- If a trace cannot be captured because `xctrace` is unavailable, Xcode is not active, privacy prompts block recording, or the template is missing, report that exact blocker. + +## Handoff Rules + +- Stay in `swift-package-testing-workflow` when the work is package workload design, Swift Testing/XCTest organization, signpost placement, Release package builds, or executable-harness profiling. +- Hand off to `xcode-testing-workflow` when the next step depends on Instruments UI, `.xctestplan` configurations, Xcode destinations, app-hosted test execution, or interpretation of `.trace` timelines. +- Hand off to `xcode-build-run-workflow` when the work becomes Metal toolchain setup, shader compilation, app launch profiling, entitlements, project membership, scheme configuration, or Xcode-managed build settings. diff --git a/plugins/apple-dev-skills/skills/xcode-testing-workflow/SKILL.md b/plugins/apple-dev-skills/skills/xcode-testing-workflow/SKILL.md index eabb5b20..d060ead1 100644 --- a/plugins/apple-dev-skills/skills/xcode-testing-workflow/SKILL.md +++ b/plugins/apple-dev-skills/skills/xcode-testing-workflow/SKILL.md @@ -7,12 +7,13 @@ description: Guide Swift Testing, XCTest, XCUITest, XCUIAutomation-oriented mech ## Purpose -Use this skill as the primary execution workflow for test-focused work in or around Xcode-managed projects and workspaces. Keep it focused on Swift Testing, XCTest, XCUITest, XCUIAutomation-oriented mechanics, `.xctestplan`, destinations, launch arguments, interruption handling, attachments, accessibility-verification follow-through, filters, retries, diagnostics, and test-specific Debug/Release validation instead of broad build/run or toolchain work. `scripts/run_workflow.py` is the runtime entrypoint for MCP-first test execution, official CLI fallback planning, and the remaining `.pbxproj` warning boundary when mutation enters project-file territory. +Use this skill as the primary execution workflow for test-focused work in or around Xcode-managed projects and workspaces. Keep it focused on Swift Testing, XCTest, XCUITest, XCUIAutomation-oriented mechanics, `.xctestplan`, destinations, launch arguments, interruption handling, attachments, accessibility-verification follow-through, Instruments profiling, `xctrace` trace capture, filters, retries, diagnostics, and test-specific Debug/Release validation instead of broad build/run or toolchain work. `scripts/run_workflow.py` is the runtime entrypoint for MCP-first test execution, official CLI fallback planning, and the remaining `.pbxproj` warning boundary when mutation enters project-file territory. ## When To Use - Use this skill for Xcode test execution, test diagnosis, test filtering, retries, destination selection, and test-plan work. - Use this skill for Swift Testing, XCTest, XCUITest, XCUIAutomation-oriented mechanics, `.xctestplan`, flaky-test diagnosis, accessibility-verification follow-through, and test-only configuration validation. +- Use this skill for Instruments and `xctrace` follow-through when performance-sensitive tests need Time Profiler, Metal System Trace, Allocations, VM Tracker, Points of Interest, signpost-aligned traces, or `.trace` artifact interpretation. - Use this skill for Xcode MCP operations and official Apple CLI fallback when the work is primarily about tests rather than build/run. - Use this skill when direct filesystem mutation around tests or test plans may be required. - Do not use this skill as the default path for ordinary build, run, preview, archive, or general project-integrity work. @@ -42,6 +43,7 @@ Use this skill as the primary execution workflow for test-focused work in or aro - `references/xctestplan-configurations-and-matrix.md` for `.xctestplan`, launch-argument matrices, named configurations, and Debug/Release test coverage - `references/xcuitest-and-xcuiautomation.md` for UI automation mechanics, waits, interruption handling, activities, and attachments - `references/ui-accessibility-verification.md` for accessibility-specific runtime verification expectations and coordination with `apple-ui-accessibility-workflow` + - `references/instruments-performance-profiling.md` for Instruments, `xctrace`, Time Profiler, Metal System Trace, Allocations, VM Tracker, Points of Interest, and signpost-aligned trace evidence - `references/testing-plans-file-membership-and-configurations.md` for the condensed cross-cutting summary and file-membership reminder 6. Use `references/xcodegen-project-maintenance.md` when the repo is XcodeGen-backed and the task touches generated test targets, scheme test actions, test-plan references, launch arguments, environment variables, or test bundle membership. 7. If MCP fails, use the structured fallback output from `scripts/run_workflow.py` together with `references/cli-fallback-matrix.md`. @@ -93,7 +95,7 @@ Use this skill as the primary execution workflow for test-focused work in or aro - Use `references/allowlist-guidance.md` when a safe official CLI fallback is blocked by local rules. - Hand off to `xcode-build-run-workflow` when the request becomes primarily about build, run, previews, archives, file membership, or toolchains. - Recommend `explore-apple-swift-docs` directly when the task becomes Apple or Swift docs exploration work. -- Recommend `swift-package-testing-workflow` directly when the task becomes package-first test execution. +- Recommend `swift-package-testing-workflow` directly when the task becomes package-first test execution, package workload design, signpost placement, or SwiftPM-first profiling harness work. - Recommend `apple-ui-accessibility-workflow` directly when the task is primarily about accessibility semantics or review rather than runtime test execution. - Recommend `format-swift-sources` directly when the task becomes SwiftLint or SwiftFormat setup, config export, or style-tooling maintenance work. - Recommend `structure-swift-sources` directly when the task becomes structural source cleanup work. @@ -118,6 +120,7 @@ Use this skill as the primary execution workflow for test-focused work in or aro - `references/xctestplan-configurations-and-matrix.md` - `references/xcuitest-and-xcuiautomation.md` - `references/ui-accessibility-verification.md` +- `references/instruments-performance-profiling.md` - `references/testing-plans-file-membership-and-configurations.md` - `references/xcodegen-project-maintenance.md` - `references/mutation-risk-policy.md` diff --git a/plugins/apple-dev-skills/skills/xcode-testing-workflow/references/cli-fallback-matrix.md b/plugins/apple-dev-skills/skills/xcode-testing-workflow/references/cli-fallback-matrix.md index 7e11cdf0..03e9ee80 100644 --- a/plugins/apple-dev-skills/skills/xcode-testing-workflow/references/cli-fallback-matrix.md +++ b/plugins/apple-dev-skills/skills/xcode-testing-workflow/references/cli-fallback-matrix.md @@ -13,6 +13,14 @@ - Tool lookup: - `xcrun --find swift` - `xcrun --find xcodebuild` + - `xcrun --find xctrace` +- Instruments: + - `xcrun xctrace version` + - `xcrun xctrace list templates` + - `xcrun xctrace record --template 'Time Profiler' --time-limit 30s --output traces/.trace --launch -- ` + - `xcrun xctrace record --template 'Metal System Trace' --time-limit 30s --output traces/.trace --launch -- ` + - `xcrun xctrace record --template 'Allocations' --output traces/.trace --launch -- ` + - `xcrun xctrace record --template 'Time Profiler' --time-limit 30s --output traces/.trace --attach ` - Simulator-related tools: - `xcrun simctl list` diff --git a/plugins/apple-dev-skills/skills/xcode-testing-workflow/references/instruments-performance-profiling.md b/plugins/apple-dev-skills/skills/xcode-testing-workflow/references/instruments-performance-profiling.md new file mode 100644 index 00000000..f88b7f79 --- /dev/null +++ b/plugins/apple-dev-skills/skills/xcode-testing-workflow/references/instruments-performance-profiling.md @@ -0,0 +1,105 @@ +# Instruments Performance Profiling + +Use this reference when Xcode-managed testing or diagnostics crosses into Instruments, `xctrace`, or trace artifact interpretation for performance-sensitive Apple-platform work. + +## Apple Documentation Anchors + +- [Xcode command-line tool reference](https://developer.apple.com/documentation/xcode/xcode-command-line-tool-reference) documents `xctrace` as the command-line tool for Instruments `.trace` files. +- [Installing the command-line tools](https://developer.apple.com/documentation/xcode/installing-the-command-line-tools) states that `xcodebuild` and `xctrace` require full Xcode rather than only the standalone Command Line Tools for Xcode package. +- [`OSSignposter`](https://developer.apple.com/documentation/os/ossignposter) records intervals and events that Instruments can display on a trace timeline. +- [Metal developer workflows](https://developer.apple.com/documentation/xcode/metal-developer-workflows) describes Metal System Trace as the Instruments timeline for CPU/GPU work and Metal memory usage. +- [Analyzing the performance of your Metal app](https://developer.apple.com/documentation/xcode/analyzing-the-performance-of-your-metal-app) describes the Game Performance template and its timeline instruments. +- [Gathering information about memory use](https://developer.apple.com/documentation/xcode/gathering-information-about-memory-use) describes the Allocations instrument and generation-based memory investigation. + +## Apple Silicon Baseline + +- Treat Apple silicon as the default architecture for current Xcode and Instruments performance guidance. +- Do not add Intel Mac-specific profiling branches unless the target repository explicitly declares Intel support. +- Record chip family, macOS version, Xcode version, destination, build configuration, thermal state when relevant, workload fixture, and package resolved versions before comparing traces. +- For Metal, MLX, Audio, and local AI work, interpret CPU samples, GPU timelines, unified-memory pressure, and model/resource residency together. + +## Instrument Selection + +- Time Profiler: use for CPU call stacks, Swift runtime overhead, expensive decoding, actor or queue overhead, thread contention symptoms, and CPU-bound model preparation. +- Metal System Trace: use for CPU/GPU overlap, command buffer timing, GPU scheduling, Metal resource events, GPU gaps, and Metal-backed ML or compute workloads. +- Allocations: use for heap growth, allocation churn, retained object growth, bridging overhead, and per-phase allocation deltas. +- VM Tracker or Virtual Memory Trace: use for mapped model weights, dirty memory growth, resident memory pressure, mapped files, and large memory regions that Allocations does not explain clearly. +- Points of Interest: use with `OSSignposter` intervals and events to align package-defined workload phases with the trace timeline. +- Processor Trace: use only when the active Apple silicon hardware and Xcode/Instruments version support it and the user needs lower-overhead CPU execution evidence beyond Time Profiler. + +## Trace Capture Flow + +1. State the performance question before recording. +2. Confirm the active Xcode and `xctrace` availability. +3. Choose the narrowest template that answers the question. +4. Prefer Release builds when optimization affects the behavior under investigation. +5. Use signposts or stable workload output to mark phases before recording long-running or multi-phase workloads. +6. Save `.trace` artifacts outside tracked source unless the repository explicitly owns trace evidence. +7. Report the trace path, template, target command or scheme, duration, build configuration, hardware, and the decision the trace supports. + +## Command Guidance + +- Verify tool availability: + +```bash +xcode-select -p +xcrun --find xctrace +xcrun xctrace version +``` + +- List templates before assuming a template exists on the current Xcode version: + +```bash +xcrun xctrace list templates +``` + +- Record an app, tool, or package executable: + +```bash +xcrun xctrace record --template 'Time Profiler' --output traces/.trace --launch -- +``` + +- Bound recordings that might otherwise run too long: + +```bash +xcrun xctrace record --template 'Time Profiler' --time-limit 30s --output traces/.trace --launch -- +``` + +- Attach to a running app or helper only when launch would hide the issue: + +```bash +xcrun xctrace record --template 'Time Profiler' --time-limit 30s --output traces/.trace --attach +``` + +- Capture Metal timeline evidence: + +```bash +xcrun xctrace record --template 'Metal System Trace' --time-limit 30s --output traces/.trace --launch -- +``` + +- Capture allocation evidence: + +```bash +xcrun xctrace record --template 'Allocations' --output traces/.trace --launch -- +``` + +- Redirect workload output into the trace evidence directory: + +```bash +xcrun xctrace record --template 'Time Profiler' --target-stdout traces/.stdout.txt --output traces/.trace --launch -- +``` + +## Trace Interpretation Expectations + +- Summarize what the trace shows, what it does not show, and whether the evidence is enough for the decision being made. +- For Time Profiler, report the hot stack or subsystem, whether samples are on the expected threads, and whether signposted intervals line up with the hot work. +- For Metal System Trace, report CPU/GPU overlap, command buffer gaps, GPU occupancy symptoms when visible, Metal memory/resource events, and whether the workload appears GPU-bound, CPU-bound, synchronization-bound, or memory-bound. +- For Allocations, report per-phase growth, allocation categories, churn versus retained growth, and whether generation marks or signposts isolate the feature under investigation. +- For VM Tracker or Virtual Memory Trace, report mapped regions, dirty memory growth, resident pressure, and whether model/resource residency matches expectations. +- Do not overstate trace results. If Instruments UI inspection is required and only a command-line capture was performed, say that the trace was captured but not fully interpreted. + +## Xcode Testing Handoffs + +- Use this workflow when traces are tied to schemes, destinations, `.xctestplan` configurations, runtime diagnostics, app-hosted package tests, or Instruments UI inspection. +- Hand off to `swift-package-testing-workflow` when the remaining work is package workload design, test harness shape, signpost placement, or SwiftPM-first Release validation. +- Hand off to `xcode-build-run-workflow` when scheme mutation, file membership, Metal build settings, shader compilation, app launch behavior, entitlements, or other project-integrity work becomes central. diff --git a/plugins/apple-dev-skills/skills/xcode-testing-workflow/references/testing-plans-file-membership-and-configurations.md b/plugins/apple-dev-skills/skills/xcode-testing-workflow/references/testing-plans-file-membership-and-configurations.md index b30998c1..9d68dbb2 100644 --- a/plugins/apple-dev-skills/skills/xcode-testing-workflow/references/testing-plans-file-membership-and-configurations.md +++ b/plugins/apple-dev-skills/skills/xcode-testing-workflow/references/testing-plans-file-membership-and-configurations.md @@ -40,3 +40,9 @@ - Use Debug builds for the normal edit-build-run loop. - Validate Release builds explicitly when optimization, launch behavior, watchdog timing, or packaging can change runtime behavior. - Treat tagged releases as a signal to build and validate both Debug and Release paths, and when shipping artifacts verify the Release behavior without relying on a debugger attachment. + +## Instruments and performance profiling + +- Use `instruments-performance-profiling.md` when Xcode-managed tests or diagnostics need Time Profiler, Metal System Trace, Allocations, VM Tracker, Points of Interest, `OSSignposter`, `xctrace`, or `.trace` artifact interpretation. +- Keep package-owned workload design and signpost placement in `swift-package-testing-workflow` unless the next step depends on schemes, destinations, app hosts, test plans, or Instruments UI inspection. +- Prefer Apple silicon as the baseline profiling architecture unless the target repository explicitly declares Intel Mac support. diff --git a/plugins/apple-dev-skills/uv.lock b/plugins/apple-dev-skills/uv.lock index a61bfd8d..ee998c88 100644 --- a/plugins/apple-dev-skills/uv.lock +++ b/plugins/apple-dev-skills/uv.lock @@ -8,7 +8,7 @@ resolution-markers = [ [[package]] name = "apple-dev-skills-maintainer" -version = "6.7.14" +version = "6.7.15" source = { virtual = "." } [package.dev-dependencies] diff --git a/plugins/cardhop-app/.codex-plugin/plugin.json b/plugins/cardhop-app/.codex-plugin/plugin.json index c08d7cd2..ba1c5409 100644 --- a/plugins/cardhop-app/.codex-plugin/plugin.json +++ b/plugins/cardhop-app/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "cardhop-app", - "version": "6.7.14", + "version": "6.7.15", "description": "Cardhop.app workflow guidance plus a bundled local MCP server for contact capture and updates on macOS.", "author": { "name": "Gale", diff --git a/plugins/cardhop-app/mcp/pyproject.toml b/plugins/cardhop-app/mcp/pyproject.toml index 5a7a52bf..bd76b698 100644 --- a/plugins/cardhop-app/mcp/pyproject.toml +++ b/plugins/cardhop-app/mcp/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "cardhop-app-mcp" -version = "6.7.14" +version = "6.7.15" requires-python = ">=3.13" dependencies = [ "fastmcp>=3.0.2", diff --git a/plugins/cardhop-app/mcp/uv.lock b/plugins/cardhop-app/mcp/uv.lock index d8c34491..765fda45 100644 --- a/plugins/cardhop-app/mcp/uv.lock +++ b/plugins/cardhop-app/mcp/uv.lock @@ -93,7 +93,7 @@ wheels = [ [[package]] name = "cardhop-app-mcp" -version = "6.7.14" +version = "6.7.15" source = { virtual = "." } dependencies = [ { name = "fastmcp" }, diff --git a/plugins/dotnet-skills/.codex-plugin/plugin.json b/plugins/dotnet-skills/.codex-plugin/plugin.json index 300754a1..b21bb31f 100644 --- a/plugins/dotnet-skills/.codex-plugin/plugin.json +++ b/plugins/dotnet-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "dotnet-skills", - "version": "6.7.14", + "version": "6.7.15", "description": "Standalone plugin repository for future .NET-focused Codex skills.", "author": { "name": "Gale", diff --git a/plugins/productivity-skills/.codex-plugin/plugin.json b/plugins/productivity-skills/.codex-plugin/plugin.json index 916a4172..4a7c4d02 100644 --- a/plugins/productivity-skills/.codex-plugin/plugin.json +++ b/plugins/productivity-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "productivity-skills", - "version": "6.7.14", + "version": "6.7.15", "description": "Broadly useful productivity workflows for Codex.", "author": { "name": "Gale", diff --git a/plugins/productivity-skills/pyproject.toml b/plugins/productivity-skills/pyproject.toml index 5a5d4ddc..7b9289b4 100644 --- a/plugins/productivity-skills/pyproject.toml +++ b/plugins/productivity-skills/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "productivity-skills-maintenance" -version = "6.7.14" +version = "6.7.15" description = "Maintainer-only Python tooling baseline for productivity-skills." requires-python = ">=3.11" dependencies = [] diff --git a/plugins/productivity-skills/uv.lock b/plugins/productivity-skills/uv.lock index 96fdad2d..e2357ac3 100644 --- a/plugins/productivity-skills/uv.lock +++ b/plugins/productivity-skills/uv.lock @@ -40,7 +40,7 @@ wheels = [ [[package]] name = "productivity-skills-maintenance" -version = "6.7.14" +version = "6.7.15" source = { virtual = "." } [package.dev-dependencies] diff --git a/plugins/python-skills/.codex-plugin/plugin.json b/plugins/python-skills/.codex-plugin/plugin.json index 7e9fdf98..da66796b 100644 --- a/plugins/python-skills/.codex-plugin/plugin.json +++ b/plugins/python-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "python-skills", - "version": "6.7.14", + "version": "6.7.15", "description": "Bundled Python-focused Codex skills for uv bootstrapping, FastAPI and FastMCP scaffolding, FastAPI/FastMCP integration, and pytest workflows.", "author": { "name": "Gale", diff --git a/plugins/python-skills/pyproject.toml b/plugins/python-skills/pyproject.toml index 6055d763..b1144e6d 100644 --- a/plugins/python-skills/pyproject.toml +++ b/plugins/python-skills/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "python-skills-maintainer" -version = "6.7.14" +version = "6.7.15" description = "Maintainer tooling for the python-skills repository" requires-python = ">=3.11" dependencies = [] diff --git a/plugins/python-skills/uv.lock b/plugins/python-skills/uv.lock index 9e2d5b77..b941477e 100644 --- a/plugins/python-skills/uv.lock +++ b/plugins/python-skills/uv.lock @@ -206,7 +206,7 @@ wheels = [ [[package]] name = "python-skills-maintainer" -version = "6.7.14" +version = "6.7.15" source = { virtual = "." } [package.dev-dependencies] diff --git a/plugins/rust-skills/.codex-plugin/plugin.json b/plugins/rust-skills/.codex-plugin/plugin.json index 0a6855e0..780e6ac9 100644 --- a/plugins/rust-skills/.codex-plugin/plugin.json +++ b/plugins/rust-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "rust-skills", - "version": "6.7.14", + "version": "6.7.15", "description": "Standalone plugin repository for future Rust-focused Codex skills.", "author": { "name": "Gale", diff --git a/plugins/spotify/.codex-plugin/plugin.json b/plugins/spotify/.codex-plugin/plugin.json index 64a3715b..aed1a6dd 100644 --- a/plugins/spotify/.codex-plugin/plugin.json +++ b/plugins/spotify/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "spotify", - "version": "6.7.14", + "version": "6.7.15", "description": "Placeholder plugin repository for future Spotify-focused Codex workflows.", "author": { "name": "Gale", diff --git a/plugins/swiftasb-skills/.codex-plugin/plugin.json b/plugins/swiftasb-skills/.codex-plugin/plugin.json index 36e5e7c7..e182ff4e 100644 --- a/plugins/swiftasb-skills/.codex-plugin/plugin.json +++ b/plugins/swiftasb-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "swiftasb-skills", - "version": "6.7.14", + "version": "6.7.15", "description": "Codex skills for explaining SwiftASB and building SwiftUI, AppKit, and Swift package integrations on top of it.", "author": { "name": "Gale", diff --git a/plugins/things-app/.codex-plugin/plugin.json b/plugins/things-app/.codex-plugin/plugin.json index 2e2a6a2d..5b3d6478 100644 --- a/plugins/things-app/.codex-plugin/plugin.json +++ b/plugins/things-app/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "things-app", - "version": "6.7.14", + "version": "6.7.15", "description": "Things.app skills and a bundled local MCP server for reminders, planning digests, and structured task workflows.", "author": { "name": "Gale", diff --git a/plugins/things-app/mcp/pyproject.toml b/plugins/things-app/mcp/pyproject.toml index 2f7bd860..473dab01 100644 --- a/plugins/things-app/mcp/pyproject.toml +++ b/plugins/things-app/mcp/pyproject.toml @@ -7,7 +7,7 @@ packages = ["app"] [project] name = "things-mcp" -version = "6.7.14" +version = "6.7.15" requires-python = ">=3.13" dependencies = [ "fastmcp>=3.0.2", diff --git a/plugins/things-app/mcp/uv.lock b/plugins/things-app/mcp/uv.lock index edf09d54..8708e600 100644 --- a/plugins/things-app/mcp/uv.lock +++ b/plugins/things-app/mcp/uv.lock @@ -1118,7 +1118,7 @@ wheels = [ [[package]] name = "things-mcp" -version = "6.7.14" +version = "6.7.15" source = { editable = "." } dependencies = [ { name = "fastmcp" }, diff --git a/plugins/things-app/pyproject.toml b/plugins/things-app/pyproject.toml index a20d55d1..f1dddb78 100644 --- a/plugins/things-app/pyproject.toml +++ b/plugins/things-app/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "things-app-maintenance" -version = "6.7.14" +version = "6.7.15" description = "Maintainer-only Python tooling baseline for things-app skills and plugin packaging." requires-python = ">=3.11" dependencies = [] diff --git a/plugins/things-app/uv.lock b/plugins/things-app/uv.lock index 18cbfea3..adf1c39e 100644 --- a/plugins/things-app/uv.lock +++ b/plugins/things-app/uv.lock @@ -120,7 +120,7 @@ wheels = [ [[package]] name = "things-app-maintenance" -version = "6.7.14" +version = "6.7.15" source = { virtual = "." } [package.dev-dependencies] diff --git a/plugins/web-dev-skills/.codex-plugin/plugin.json b/plugins/web-dev-skills/.codex-plugin/plugin.json index 70fed203..999c4e5e 100644 --- a/plugins/web-dev-skills/.codex-plugin/plugin.json +++ b/plugins/web-dev-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "web-dev-skills", - "version": "6.7.14", + "version": "6.7.15", "description": "Standalone plugin repository for future web-focused Codex skills.", "author": { "name": "Gale", diff --git a/pyproject.toml b/pyproject.toml index 93e56ac5..69cbb63a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "socket-maintenance" -version = "6.7.14" +version = "6.7.15" description = "Root uv tooling baseline for the socket superproject." requires-python = ">=3.11" dependencies = [] diff --git a/uv.lock b/uv.lock index 3510e414..7b75b07a 100644 --- a/uv.lock +++ b/uv.lock @@ -286,7 +286,7 @@ wheels = [ [[package]] name = "socket-maintenance" -version = "6.7.14" +version = "6.7.15" source = { virtual = "." } [package.dev-dependencies]