AGENTS.md · conorluddy/ios-simulator-skill

Sections

1. Project Overview
2. Principles
3. Project Structure
4. Architecture Patterns
5. Script Categories
6. Shared Utilities
7. Quality Standards
8. Contributing
9. Release Process

First lines (shown under the repo's MIT license)

# AGENTS.md - Developer Guide

Canonical guidance for AI coding agents (Codex, Claude Code, and others) and developers working
with this repository. `CLAUDE.md` only imports this file - edit here, not there.

## Project Overview

iOS Simulator Skill is a production-ready Agent Skill providing 30 scripts for iOS app building, testing, and automation. It wraps Apple's `xcrun simctl` and Facebook's `idb` tools with semantic interfaces designed for AI agents and developers.

**Key Statistics:**
- 30 production scripts
- 7 script categories (Build, Device State, Navigation, Testing, Permissions, Simulator Discovery, Lifecycle)
- 7 shared utility modules (~2,400 lines)
- 100% token-optimized default output
- Unit tests under `tests/` (run `pytest tests/`)

## Principles

Every script is a tool an agent calls in a loop, so these rules beat convenience. New code and
reviews are checked against them.

1. **Low noise, high signal.** An agent-facing message is one line that says what happened and,
   on failure, what to do next. No usage dumps, tracebacks or prose. Default output is 3-5 lines;
   `--verbose` and `--json` give more. Cap lists (`IOS_SIM_MAX_ELEMENTS`) and end them with
   "... and N more".
2. **Never claim an effect you didn't get.** Say how an action was done ("(accessibility press)")
   and warn when its effect can't be confirmed, e.g. a coordinate tap on a toggle. A wrong "Tapped"
   costs an agent more than an honest failure.
3. **Act only on an unambiguous target.** idb markers are substring, first-match: only use one when
   nothing else on screen contains it, otherwise fall back to the safer path.
4. **Verify against a live simulator before relying on idb behaviour.** Upstream publishes no
   changelog and the docs drift from reality. Ship only what you saw working, and record what you
   dropped and why.
5. **Gate features by trying, not by version.** Run the command and fall back (or hint at an
   upgrade) on failure. Don't add `--help` probes to hot paths: each costs ~0.35s.
6. **simctl first.** It's Apple-maintained, with no companion to break. Use idb only for what simctl
   can't do (UI interaction, notification list/clear, photos clear).
7. **Don't change the device silently.** Device-wide side effects (e.g. axbridge's automation mode)
   sit behind an explicit flag like `--deep`, and tests restore whatever they change.
8. **Semantic over pixels.** Find elements by meaning via the accessibility tree; coordinates are
   the last resort.
9. **One helper per repeated agent-facing message.** Shared wording lives in `common/` (e.g.
   `with_idb_upgrade_hint`) once it appears a third time (AHA), so messages can't drift apart.
10. **Destructive operations need `--yes`.** Anything that deletes data the user can't easily
    recreate (erasing or deleting a simulator, uninstalling an app, clearing the photo library)
    refuses without `--yes` in one line that says what would be lost, so the agent asks the user
    first. Never prompt interactively: an agent has no one to answer.

## Project Structure

```
ios-simulator-skill/            # Repository root
├── .claude-plugin/marketplace.json  # Claude Code marketplace
├── .agents/plugins/marketplace.json # Codex marketplace
├── ios-simulator-skill/        # Distributable package
│   ├── .claude-plugin/
│   │   └── plugin.json        # Claude Code plugin manifest
│   ├── .codex-plugin/
│   │   └── plugin.json        # Codex plugin manifest (keep version in sync)
│   ├── assets/icon.svg        # Codex plugin icon
│   └── skills/
│       └── ios-simulator-skill/
│           ├── SKILL.md       # Entry point (table of contents)
│           ├── agents/openai.yaml  # Codex skill UI metadata
│           └── scripts/       # 30 production scripts
│               ├── build_and_test.py
│               ├── xcode/     # Xcode integration module
│               ├── log_monitor.py
│               ├── hang_watcher.py    # HangBuster session recorder + legacy stream
│               ├── screen_mapper.py
│               ├── navigator.py
│               ├── gesture.py
│               ├── keyboard.py
│               ├── app_launcher.py
│               ├── accessibility_audit.py
│               ├── visual_diff.py
│               ├── test_recorder.py
│               ├── app_state_capture.py
│               ├── clipboard.py
│               ├── status_bar.py
│               ├── push_notification.py
│               ├── privacy_manager.py
│               ├── simctl_boot.py
│               ├── simctl_shutdown.py
│               ├── simctl_create.py
│               ├── simctl_delete.py
│               ├── simctl_erase.py
│               ├── sim_health_check.sh
│               └── common/    # Shared utilities
│                   ├── hang_pipeline.py   # HangBuster filter pipeline (pure fns)
│                   └── hang_sessions.py   # HangBuster session storage
├── .github/workflows/
├── pyproject.toml
└── README.md
```

## Architecture Patterns

### Pattern 1: Class-Based Script Design

All scripts use class-based architecture for testability:

```python
class DeviceManager:
    def __init__(self, udid: str | None = None):
        self.udid = udid

    def execute(self, **kwargs) -> tuple[bool, str]:
        # Return (success, message) tuple
        pass

def main():
    parser = argparse.ArgumentParser()
    manager = DeviceManager(args.udid)
    success, message = manager.execute()
    print(message)
    sys.exit(0 if success else 1)
```

### Pattern 2: Auto-UDID Detection

All scripts support optional `--udid` with auto-detection:

```python
try:
    udid = resolve_device_identifier(args.udid)  # May be None
except RuntimeError as e:
    print(f"Error: {e}", file=sys.stderr)
    sys.exit(1)
```

### Pattern 3: Output Formatting

Consistent format across all scripts:

```
# Default (3-5 lines)
Device booted: iPhone 16 Pro (ABC123) [2.1s]

# --verbose (50+ lines)
Device booted successfully.
Device UDID: ABC123DEF456...
Boot time: 2.1 seconds

# --json (20-30 lines)
{"action": "boot", "udid": "ABC123", "success": true}
```

### Pattern 4: Batch Operations

Most scripts support batch operations:

```bash
python scripts/simctl_boot.py --all
python scripts/simctl_boot.py --type iPhone
```

## Script Categories

### Build & Development (2)