apple-dev-loop

An evidence-driven Apple-platform development Skill for AI coding agents. It selects the smallest validation loop that can prove a change across SwiftPM, Xcode, XCTest, Simulator, signed macOS apps, physical-device tooling, UI observation, and Instruments.

The Skill does not replace repository rules or Apple specialist guidance. It owns tool routing, bounded execution, private artifact handling, failure attribution, and honest closure claims.

Repository layout

skills/apple-dev-loop/
├── SKILL.md
├── agents/openai.yaml
├── references/
├── scripts/
└── tests/

The installable Skill is entirely self-contained under skills/apple-dev-loop. Repository-level files provide GitHub documentation and CI only.

Install

Choose exactly one installation form for a given agent. The plugin is recommended for Codex or Claude Code; use the standalone Skill only for agents without compatible plugin discovery. Installing both forms in the same agent can create duplicate routing entries.

Standalone Skill

Clone the repository using GitHub's Code menu, enter the checkout, then copy or symlink skills/apple-dev-loop into the Skill discovery directory used by your agent:

cd apple-dev-loop
ln -s "$PWD/skills/apple-dev-loop" /path/to/agent-skills/apple-dev-loop

Other agents can consume the same SKILL.md, references, and executable scripts when they support directory-based Skills; agent-specific discovery, namespacing, and tool names remain adapter concerns.

Plugin distribution

The repository also contains native plugin metadata for both Codex and Claude Code:

• .codex-plugin/plugin.json packages the Skill as a Codex plugin;
• .agents/plugins/marketplace.json makes this repository a local Codex marketplace;
• .claude-plugin/plugin.json packages the Skill as a Claude Code plugin;
• .claude-plugin/marketplace.json makes this repository a one-plugin Claude marketplace.

Keep the version in both plugin manifests and the Claude marketplace entry aligned when publishing a release.

Codex

Test the repository marketplace locally:

codex plugin marketplace add .

Then open /plugins in Codex, install Apple Development Loop, and start a new session before using the plugin-qualified Skill name. Reinstalling a development build requires a new manifest cachebuster and another new session.

Claude Code

Validate and test the plugin directly:

claude plugin validate --strict .
claude --plugin-dir .

To exercise the marketplace flow from this checkout:

claude plugin marketplace add .
claude plugin install apple-dev-loop@apple-dev-loop

After installation, run /reload-plugins or restart Claude Code. When the repository is public on GitHub, users can replace . with the repository identifier. Check the current Codex or Claude Code documentation before publishing because marketplace submission and discovery rules are external contracts that can change independently of this bundle.

Requirements

• macOS and Xcode for real build, Simulator, device, signing, UI, or Instruments work;
• Python 3.9 or newer and a POSIX shell for bundled runners;
• repository-specific build and test commands remain authoritative.

Contract tests use fake Apple tools and can run without Xcode. They do not replace a real forward-test on the relevant Apple environment.

Preflight and UI runners place raw logs and supported caches in unique mode-0700 children under the selected artifact parent. Preflight cleans its owned child by default and supports explicit retention for diagnosis. A successful UI start retains its session child until stop; any runner retains an artifact for recovery when process or ownership checks cannot prove cleanup is safe. Xcode enumeration inherits a task-local DEVELOPER_DIR; the runners never change global xcode-select, HOME, or CFFIXED_USER_HOME.

Validate

sh scripts/validate.sh

The validator checks Skill metadata and links, shell and Python syntax, executable contracts, unresolved placeholders, whitespace, and repository diffs.

Privacy boundary

Raw .xcresult, .trace, build logs, device data, credentials, URLs, and account content must stay in private temporary or artifact storage. In particular, an Instruments trace can contain process environment data even when its summarized JSON is sanitized.

License

MIT