Initial commit

Author: kylehughes

.claude-plugin/marketplace.json

@@ -0,0 +1,21 @@
+{
+  "name": "apple-platform-build-tools",
+  "owner": {
+    "name": "Kyle Hughes",
+    "email": "kyle@kylehugh.es"
+  },
+  "metadata": {
+    "description": "Build, test, and archive Swift packages and Xcode projects for Apple platforms.",
+    "version": "0.1.0"
+  },
+  "plugins": [
+    {
+      "name": "apple-platform-build-tools",
+      "description": "Reference documentation for xcodebuild and swift build, plus an autonomous build agent that absorbs verbose logs and preserves your context window.",
+      "source": "./",
+      "strict": false,
+      "skills": ["./skills/building-apple-platform-products"],
+      "agents": ["./agents/apple-platform-builder.md"]
+    }
+  ]
+}

.github/workflows/release.yml

@@ -0,0 +1,15 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - '*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: softprops/action-gh-release@v2

.gitignore

@@ -0,0 +1 @@
+.claude/settings.local.json

CLAUDE.md

@@ -0,0 +1,62 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Repository Contains
+
+This repository contains an **Agent Skill** and **Subagent** for Claude Code called `building-apple-platform-products`.
+
+- **Skill**: Teaches Claude the xcodebuild and swift build command patterns (reference documentation)
+- **Agent**: Executes build commands autonomously, discovering schemes and destinations as needed
+
+## Repository Structure
+
+```
+skills/
+└── building-apple-platform-products/
+    ├── SKILL.md          # Entry point with YAML frontmatter
+    └── references/       # Detailed documentation loaded on-demand
+
+agents/
+└── apple-platform-builder.md   # Autonomous build executor
+```
+
+**Skill components**:
+- **SKILL.md**: Quick reference tables and links to reference files
+- **references/**: Progressive disclosure—Claude loads these only when needed
+
+**Agent**: Discovers project structure, constructs correct commands, executes autonomously
+
+## Key Design Principles
+
+1. **Reference manual style**: Use tables and clear categories, not decision trees
+2. **Standalone Swift packages only**: `swift build`/`swift test` do NOT work for Swift Package Manager submodules in Xcode projects—must use `xcodebuild` with the appropriate scheme
+3. **Simulator name volatility**: Device names change with Xcode releases; always document `xcrun simctl list devices available`
+4. **No code signing complexity**: Scope is Build, Test & Archive; distribution/signing is out of scope
+
+## File Organization
+
+Every reference file follows this structure:
+
+1. **Title** — H1 with one-line purpose
+2. **Important note** — `**Important**:` callout for critical constraints
+3. **Core content** — Topic-specific sections
+4. **Quick Reference** — Table with Goal | Command columns
+5. **Complete Example** — Minimal example + Full CI example
+6. **Troubleshooting** — Cause/Solution format for topic-specific errors
+
+Conventions:
+- Emphasis markers use `**Keyword**:` format (e.g., `**Important**:`, `**Cause**:`)
+- Tables use Goal | Command format (what you want → how to get it)
+- Code blocks have no trailing blank lines
+- `troubleshooting.md` is an index pointing to other files' Troubleshooting sections
+
+## Installation
+
+```bash
+# Install skill (reference documentation)
+cp -r skills/building-apple-platform-products ~/.claude/skills/
+
+# Install agent (autonomous executor)
+cp agents/apple-platform-builder.md ~/.claude/agents/
+```

LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 Kyle Hughes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,126 @@
+# Apple Platform Build Tools Claude Code Plugin
+
+[![Agent Skill](https://img.shields.io/badge/Claude_Code_Plugin-555?logo=claude)](https://code.claude.com/docs/en/plugins)
+[![Latest Release](https://img.shields.io/github/v/release/kylehughes/apple-platform-build-tools-claude-code-plugin)](https://github.com/kylehughes/apple-platform-build-tools-claude-code-plugin/releases)
+
+*Build, test, and archive Swift packages and Xcode projects for Apple platforms with Claude Code.*
+
+## About
+
+Apple Platform Build Tools Claude Plugin is a Claude Code plugin containing an Agent Skill and a Subagent for building Apple platform products.
+
+- **Agent Skill**: Reference documentation for `xcodebuild` and `swift build` command patterns.
+- **Subagent**: Autonomous executor that discovers schemes, runs builds, and returns concise results. Uses the Agent Skill.
+
+## Usage
+
+The Subagent is useful for delegating build and test commands from your main programming agent. It can report the results of these commands without exposing the build logs. This keeps the main agent on track and prevents its context window from being polluted.
+
+The Agent Skill is useful for understanding `xcodebuild` and `swift` options, debugging build failures, or constructing complex commands manually or by an agent when more control is needed than the Subagent provides.
+
+### Automatic
+
+The Agent Skill and Subagent are both exposed to Claude Code, along with descriptions about when to use them. Theoretically, Claude should know to read the Agent Skill when composing a complex `xcodebuild` command, or to invoke the Subagent when a build needs to be run. This is nondeterministic in practice and may change with Claude models and Claude Code versions.
+
+### Manual
+
+To explicitly invoke the Agent Skill or Subagent, use natural language in Claude Code.
+
+e.g.
+
+> use the builder agent to build the app
+
+> check with the builder agent that the tests pass
+
+> use the build skill to help me write an xcodebuild command for CI
+
+## What's Included
+
+### Agent Skill: `building-apple-platform-products`
+
+Quick-reference tables and detailed documentation for:
+
+- Project discovery (schemes, targets, configurations)
+- Swift Package Manager commands
+- `xcodebuild` commands (build, test, archive)
+- Destination specifiers for all Apple platforms
+- Test filtering, parallel execution, coverage
+- CI configuration and code signing
+- Troubleshooting common errors
+
+### Subagent: `apple-platform-builder`
+
+Autonomous build executor that:
+
+- Discovers project structure automatically
+- Constructs correct commands for the project type
+- Handles errors using troubleshooting guidance
+- Returns success/failure with only relevant details
+- Uses the `building-apple-platform-products` skill
+
+## Installation
+
+### Claude Code
+
+#### Personal Usage
+
+To install this plugin for your personal use in Claude Code:
+
+1. Add the marketplace:
+   ```bash
+   /plugin marketplace add kylehughes/apple-platform-build-tools-claude-code-plugin
+   ```
+
+2. Install the plugin:
+   ```bash
+   /plugin install apple-platform-build-tools@apple-platform-build-tools-claude-code-plugin
+   ```
+
+#### Project Configuration
+
+To automatically provide this plugin to everyone working in a repository, configure the repository's `.claude/settings.json`:
+
+```json
+{
+  "enabledPlugins": {
+    "apple-platform-build-tools@apple-platform-build-tools-claude-code-plugin": true
+  },
+  "extraKnownMarketplaces": {
+    "apple-platform-build-tools-claude-code-plugin": {
+      "source": {
+        "source": "github",
+        "repo": "kylehughes/apple-platform-build-tools-claude-code-plugin"
+      }
+    }
+  }
+}
+```
+
+When team members open the project, Claude Code will prompt them to install the plugin.
+
+### Manual Installation
+
+The raw Agent Skill and Subagent content is available in this repository's `skills/` and `agents/` directories.
+
+## Contributions
+
+Apple Platform Build Tools Claude Code Plugin is not accepting source contributions at this time. Bug reports will be considered.
+
+## Author
+
+[Kyle Hughes](https://kylehugh.es)
+
+[![Bluesky][bluesky_image]][bluesky_url]  
+[![LinkedIn][linkedin_image]][linkedin_url]  
+[![Mastodon][mastodon_image]][mastodon_url]
+
+[bluesky_image]: https://img.shields.io/badge/Bluesky-0285FF?logo=bluesky&logoColor=fff
+[bluesky_url]: https://bsky.app/profile/kylehugh.es
+[linkedin_image]: https://img.shields.io/badge/LinkedIn-0A66C2?logo=linkedin&logoColor=fff
+[linkedin_url]: https://www.linkedin.com/in/kyle-hughes
+[mastodon_image]: https://img.shields.io/mastodon/follow/109356914477272810?domain=https%3A%2F%2Fmister.computer&style=social
+[mastodon_url]: https://mister.computer/@kyle
+
+## License
+
+Apple Platform Build Tools Claude Code Plugin is available under the **MIT License**. See `LICENSE` for details.

agents/apple-platform-builder.md

@@ -0,0 +1,52 @@
+---
+name: apple-platform-builder
+description: "STRONGLY PREFER to delegate Apple platform builds and tests to this agent to preserve your context window. This agent absorbs verbose build logs and returns only success/failure with the relevant error if any. Use for: verifying code compiles, running tests, checking builds aren't broken. Discovers schemes and simulators automatically."
+color: red
+tools: Bash, Read, Glob, Grep
+model: sonnet
+skills: building-apple-platform-products
+---
+
+You execute Apple platform build commands autonomously, shielding the caller from verbose build output.
+
+**Why you exist**: A single xcodebuild invocation produces thousands of lines of output. Running builds directly in the main conversation pollutes the context window with noise. You absorb that noise and return only the signal.
+
+## Workflow
+
+### Step 1: Classify the Request
+
+**Specific request** (user provides scheme, destination, or command):
+→ Validate the inputs exist, then execute.
+
+**Ambiguous request** (user says "build this", "run tests", etc.):
+→ Run discovery first.
+
+### Step 2: Discover (if needed)
+
+Run in sequence, stopping when you have enough information:
+
+1. Find project files: `ls Package.swift *.xcworkspace *.xcodeproj 2>/dev/null`
+2. Determine tool:
+   - Standalone `Package.swift` (no .xcodeproj) → `swift build`
+   - `.xcodeproj` → `xcodebuild` (handles SPM dependencies automatically)
+   - `.xcworkspace` → `xcodebuild -workspace` (only for CocoaPods/multi-project)
+3. List schemes: `xcodebuild -list` or `swift package describe` (local package targets appear as individual schemes)
+4. Get simulators (if needed): `xcrun simctl list devices available`
+
+### Step 3: Execute
+
+Construct the command using patterns from the skill. Run it.
+
+### Step 4: Handle Errors
+
+If a command fails, consult the skill's troubleshooting guidance and retry with the suggested fix.
+
+## Output Format
+
+Return a concise summary for the caller:
+
+1. **What you did**: The command executed (e.g., "Built MyApp scheme for iOS Simulator")
+2. **Result**: Success or failure
+3. **If failed**: The key error message and what fix was attempted
+
+Keep output brief. The caller doesn't need full build logs—just whether it worked and why if it didn't.

release.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+set -euo pipefail
+
+# Release script for Apple Platform Build Tools Claude Code Plugin
+#
+# Usage: ./scripts/release.sh <version>
+# Example: ./scripts/release.sh 1.0.1
+
+if [ $# -ne 1 ]; then
+    echo "Usage: $0 <version>"
+    echo "Example: $0 1.0.1"
+    exit 1
+fi
+
+VERSION="$1"
+MARKETPLACE_JSON=".claude-plugin/marketplace.json"
+
+# Validate version format (basic semver)
+if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+    echo "Error: Version must be in format X.Y.Z (e.g., 1.0.1)"
+    exit 1
+fi
+
+# Check for uncommitted changes
+if ! git diff --quiet || ! git diff --cached --quiet; then
+    echo "Error: You have uncommitted changes. Please commit or stash them first."
+    exit 1
+fi
+
+# Check we're on main branch
+BRANCH=$(git branch --show-current)
+if [ "$BRANCH" != "main" ]; then
+    echo "Warning: You're on branch '$BRANCH', not 'main'. Continue? (y/N)"
+    read -r response
+    if [[ ! "$response" =~ ^[Yy]$ ]]; then
+        exit 1
+    fi
+fi
+
+# Update version in marketplace.json
+echo "Updating version to $VERSION in $MARKETPLACE_JSON..."
+sed -i '' "s/\"version\": \"[^\"]*\"/\"version\": \"$VERSION\"/" "$MARKETPLACE_JSON"
+
+# Commit
+echo "Committing..."
+git add "$MARKETPLACE_JSON"
+git commit -m "Release $VERSION"
+
+# Tag
+echo "Creating tag $VERSION..."
+git tag "$VERSION"
+
+# Push
+echo "Pushing to origin..."
+git push
+git push --tags
+
+echo ""
+echo "Released $VERSION"
+echo "GitHub Action will create the release at:"
+echo "https://github.com/kylehughes/apple-platform-build-tools-claude-code-plugin/releases/tag/$VERSION"