ios-audit
Comprehensive iOS audit for Swift and SwiftUI apps. Runs deterministic collectors for Code Health, UX, Runtime Quality, and Release & Compliance, then synthesizes a complete fresh docs tree plus `audi
SKILL.mdagent-marketplace/src/ios/skills/ios-audit/SKILL.md
GitHubiOS Audit
Use this skill to create a reproducible engineering baseline for a Swift or SwiftUI app. The audit runs four pillars through four phases:
- COLLECT deterministic evidence from source, tools, and optionally a simulator.
- ANALYZE that evidence and author current-run docs and findings for each pillar.
- RENDER a complete docs tree,
audit.json, andaudit.html. - DIFF the new baseline against an earlier one when available.
The outputs are a replacement documentation tree covering architecture, UX,
operations, quality, and release; a JSON baseline with findings, severity,
priority, evidence, and RICE scores; a self-contained HTML report; and, when a
prior baseline exists, audit-diff.md with changes since that run. Use it for
refactor baselines, release reviews, recurring health checks, onboarding, and
auditing drift between runs. Use a focused review when the user needs only a
single question answered.
Choose the run
- With a booted simulator and a UX workflow YAML, run all four pillars.
- Without either UX prerequisite, pass
--no-ux; Code Health, Runtime Quality, and Release & Compliance still run. - If this is the first run, omit DIFF. The new
audit.jsonbecomes the baseline. - Write docs to the app's
docs/only when the user wants to replace that tree. Otherwise use--docs-dir .audit/docs-preview/to keep the output isolated.
The CLI is scripts/audit.py. Its subcommands are collect, analyze,
render, and diff; all runs the sequence and pauses after COLLECT so you
can perform ANALYZE. It prints the raw-input and prompt paths, then waits on
STDIN.
Run the audit
1. Prepare inputs
Install uv. swiftlint and periphery are optional, recommended collectors.
For UX flows, prepare a workflow file in the app repository, a booted simulator,
and the ios-simulator-skill in the rendered ios plugin. Start from
examples/movies-do.yaml or examples/silly-tavern.yaml; see
references/authoring-workflows.md for
workflow syntax and selectors.
Use helper-owned simulator UDIDs when available. In a scaffolded project:
make run-iphone run-ipad
export IOS_AUDIT_IPHONE_UDID="$(jq -er .udid build/simulators/iphone.json)"
export IOS_AUDIT_IPAD_UDID="$(jq -er .udid build/simulators/ipad.json)"
Set each device_matrix lane's udid to the matching environment variable.
For a single lane without device_matrix, pass --udid "$IOS_AUDIT_IPHONE_UDID".
Use explicitly assigned simulators in an unscaffolded project; never rely on
whichever simulator happens to be booted.
Workflow credentials must use environment-variable references. Never commit
plaintext credentials. The collector expands ${VAR} values at runtime and
fails before the flow starts if a referenced variable is unset. For Xcode UI
tests, forward credentials with the TEST_RUNNER_ prefix (Xcode 15.3+):
TEST_RUNNER_MY_APP_TEST_USERNAME="$MY_APP_TEST_USERNAME" \
xcodebuild test -workspace MyApp.xcworkspace -scheme MyApp ...
2. Collect
Run collectors against the app repository. --output is disposable generated
state: each collection removes and regenerates the entire audit root.
~/.agents/plugins/plugins/ios/skills/ios-audit/scripts/audit.py collect \
--repo ~/code/my-app \
--workflows ~/code/my-app/.audit/workflows.yaml \
--output ~/code/my-app/.audit
Omit --workflows when UX is not being collected and pass --no-ux when
required. Collectors write JSON under .audit/raw/: meta.json,
code_health.json, ux.json, runtime.json, and release.json. Missing
optional tools are recorded as tool_missing where supported; they do not
silently produce equivalent evidence.
3. Analyze
For every pillar that ran, follow its prompt and create all required outputs:
- Read
.audit/raw/<pillar>.jsonand inspect the current source needed to verify its claims. - Read
scripts/analyze/prompts/<pillar>.mdbefore authoring that pillar. - Write authored Markdown under
.audit/docs/in the structure required by the prompt. Treat every listed document as required. - Write
.audit/findings/<pillar>.jsonas an array matching thefindingsschema inaudit-schema.json. Includeid,pillar,severity,priority,title,summary,evidence,recommendation,rice, andtagsfor each finding.
The pillar names are code_health, ux, runtime, and release; their
prompts are under scripts/analyze/prompts/. Back every claim with the current
raw inputs and source. Author a fresh docs tree for every run: do not reuse
prior audit prose, findings, screenshots, or thumbnails. Include only
current-run UX screenshots and copy every referenced screenshot into
.audit/docs/ where the UX prompt requires it.
4. Render
~/.agents/plugins/plugins/ios/skills/ios-audit/scripts/audit.py render \
--audit ~/code/my-app/.audit \
--docs-dir ~/code/my-app/docs
Rendering merges .audit/docs/, .audit/findings/*.json, and
.audit/raw/meta.json. It writes audit.json, audit.html, and copies the
freshly authored Markdown into <docs-dir>/. Rendering fails if required docs,
findings files, or current-run UX screenshots are missing. Resolve those gaps
before proceeding; a partial report is not a completed audit.
5. Diff
~/.agents/plugins/plugins/ios/skills/ios-audit/scripts/audit.py diff \
--current ~/code/my-app/.audit/audit.json
DIFF uses docs/audit.json as the default previous baseline, or accepts
--baseline PATH. It writes audit-diff.md with fixed, new, regressed, and
demoted findings plus the net RICE change. With no previous baseline, it prints
First audit — no baseline and exits successfully.
To run the phases together, use all with the same project inputs and desired
docs target:
~/.agents/plugins/plugins/ios/skills/ios-audit/scripts/audit.py all \
--repo ~/code/my-app \
--workflows ~/code/my-app/.audit/workflows.yaml \
--docs-dir ~/code/my-app/docs
Python entrypoints include uv script metadata and can run directly or through
uv run path/to/script.py.
Pillars and analysis guides
| Pillar | Evidence and focus | Main docs |
|---|---|---|
| Code Health | SwiftLint, Periphery, Tuist graph, file inventory, state/config provenance, layer hierarchies, concurrency and error-handling smells | docs/architecture/*.md, docs/quality/*.md |
| UX | Screenshots, accessibility trees, navigation, components, gestures, repeated semantic surfaces, workflow and device-lane coverage | docs/ux/ |
| Runtime Quality | Logging, errors, retries, timeouts, caches, network resilience, storage placement and cleanup | docs/operations/ |
| Release & Compliance | Privacy manifests, plist and entitlement settings, localization, signing, risky APIs, Fastlane | docs/release/ |
Read the relevant guide in references/pillars/ for that pillar's evidence,
tool requirements, output list, and common finding patterns. Read its analysis
prompt for the exact document outline and finding rules. The prompt is the
required authoring contract; the guide explains the collector and pillar.
Each finding carries three separate assessments:
severity:critical,major,moderate, orminordescribes the harm.priority:must,should,could, orwontdescribes when to address it.rice:{reach, impact, confidence, effort, score}estimates work value;score = (reach * impact * confidence) / effort.
Use all three. They can disagree, and that disagreement can be informative.
See references/priority-model.md for scales
and scoring guidance.
Project files
UX workflow YAML belongs to the app repository, typically at
.audit/workflows.yaml or .audit/flows/*.yaml. workflow-schema.yaml defines
its format, and examples/ contains full examples. Keep audit-generated files
out of Git except for .audit/audit.json when the project intentionally
checks in a baseline. In that case, ignore .audit/raw/ and .audit/docs/.
Store non-audit notes outside a docs tree that the audit will replace. Run
separate audit output roots for separate device or appearance variants.
The analysis prompts define required documentation and finding outputs. The
schema files define their machine-readable formats. The main implementation
lives in scripts/collect/, scripts/render/, scripts/diff/, and
scripts/ux/; Python entrypoints are self-contained scripts. See
references/migration-from-ios-flow-audit.md
when moving an existing caller from the former ios-flow-audit skill.