{"id":"ef212082-a772-4155-af97-ef0451fb7f78","slug":"swiftkeystone","kind":"skill","name":"swiftkeystone","summary":"A workflow framework for Swift apps with Codex: onboard, plan, build, and verify.","owner":"TensaiSolutions","repoUrl":"https://github.com/TensaiSolutions/swiftkeystone","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-10-22T17:33:07.000Z","addedAt":"2026-11-01T02:05:17.071Z","logoUrl":"https://avatars.githubusercontent.com/u/4450081?u=acb0158bfe4cb652801d829eb2c59b8af1aebed1&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["writing"],"tags":["codex","developer-tools","ios","swift","swiftui"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-11-01T02:19:40.270Z","sample":false,"url":"https://conduits.dev/tools/swiftkeystone","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# SwiftKeystone\n\nA reusable development workflow framework for Swift apps with Codex: onboard an app, plan a feature,\nimplement a bounded change, and collect honest verification evidence.\n\n**v0.4.0 — Baseline Expectations Preview.** Four installable skills and a dependency-free Python helper.\nThe latest published release is [v0.4.0](https://github.com/TensaiSolutions/swiftkeystone/releases/tag/v0.4.0).\nIt adds optional baseline expectations and test-count change reporting to the existing audit,\nevidence comparison, PR-summary and safe update-staging workflows.\nNo account, service, API key, or global configuration change is required by SwiftKeystone itself.\nYou use it within your existing Codex environment.\n\nThe name reflects the goal: connect planning, implementation, and verification into a dependable\npattern for Swift app development. This preview covers iOS and native macOS workflows;\nsee the validation record for the actual environments, pilot corrections, and results.\nSupport and validation for additional Apple platforms remain future work.\n\nThe project was previously called iOS Forge. For compatibility, the framework keeps the `forge.py` entry point,\n`.ios-forge/app.json` profile, and `$ios-*` skill names. Existing profiles need no migration.\nUpdated skill bundles still require manual review when they differ from an installed copy;\nthe installer will not overwrite them.\n\nThe published archive is `swiftkeystone-0.4.0.zip`, containing a `swiftkeystone-0.4.0/` directory.\n\n## Start here\n\nDownload `swiftkeystone-0.4.0.zip` and `swiftkeystone-0.4.0.zip.sha256` from the\n[v0.4.0 release](https://github.com/TensaiSolutions/swiftkeystone/releases/tag/v0.4.0).\nUse those named assets, rather than GitHub's automatically generated source archives, for these steps.\nIn the download directory on macOS, verify and extract:\n\n```sh\nshasum -a 256 -c swiftkeystone-0.4.0.zip.sha256\nunzip swiftkeystone-0.4.0.zip\ncd swiftkeystone-0.4.0\n```\n\nStop if the checksum does not match. Keep the extracted directory in a stable location.\nCloning this repository is an alternative; it gives you the current branch rather than necessarily v0.4.0.\nCommands below run from that SwiftKeystone directory. Python 3.10+ is required.\nCheck `python3 --version` before setup. macOS `/usr/bin/python3` may be older; select an\nalready installed Python 3.10+ interpreter and use that same executable for every command below.\nIf none is installed, stop and arrange installation explicitly. SwiftKeystone does not install Python\nor change your system interpreter. The original v0.3.0 helper does not enforce this minimum at startup;\nv0.4.0 rejects older interpreters before dispatching commands.\nApp builds need macOS and full Xcode. iOS simulator runs also need a compatible installed runtime.\nXcode 16 or newer is required to read test-result summaries.\n\nPreview installation into your app:\n\n```sh\npython3 forge.py install --app \"/path/to/MyApp\" --dry-run\npython3 forge.py install --app \"/path/to/MyApp\"\n```\n\nThis copies only SwiftKeystone's four skills into the app's `.agents/skills/` directory.\nIt preserves `AGENTS.md`, unrelated skills, and global settings. An identical installation is a no-op;\na differing existing skill stops installation before any copying. v0.3.0 includes reviewed\n[three-way update staging](docs/skill-updates.md); activation remains explicit and preserves originals.\nDo not install skills into repositories you do not trust without reading them.\n\nOpen your app in Codex and ask:\n\n> Use $ios-onboard to discover this app's configuration and establish a verification baseline. The SwiftKeystone helper is at /absolute/path/to/swiftkeystone-0.4.0/forge.py.\n\nReplace that helper path with the location you extracted. Installation copies skills, not the Python\nhelper, into the app. If a skill is not discovered, reopen the app's Codex chat and confirm its\n`.agents/skills/ios-onboard/SKILL.md` exists; you can also ask Codex to read that file explicitly.\n\nThe onboarding skill discovers the real project/workspace, scheme, and available destination.\nFor reproducible team/CI use, share the intended scheme in Xcode and commit its scheme file;\nlocally generated schemes can work without being portable to another checkout.\nYou can also create the configuration yourself after inspecting those values:\n\n```sh\npython3 forge.py init --app \"/path/to/MyApp\" \\\n  --name \"MyApp\" --project \"MyApp.xcodeproj\" --scheme \"MyApp\" \\\n  --destination \"platform=iOS Simulator,id=YOUR_AVAILABLE_SIMULATOR_UUID\"\npython3 forge.py validate \"/path/to/MyApp/.ios-forge/app.json\"\npython3 forge.py doctor --app \"/path/to/MyApp\"\n```\n\nReplace the sample values; SwiftKeystone does not choose an arbitrary simulator or scheme.\n`doctor` discovers executable prerequisites and a valid profile; it does not certify Xcode health.\nSee the [profile contract](docs/profile.md) and [example profile](examples/app-profile.json).\n\n### Apps without tests\n\n`init` starts with `\"checks\": [\"build\", \"test\"]`. Inspect the scheme's test action before running it.\nIf the app has no test target, record that coverage gap. For an explicitly build-only baseline, edit\n`.ios-forge/app.json` to use `\"checks\": [\"build\"]`, validate it, and then run verification.\nA passing build-only baseline proves compilation, not tested behavior. Do not remove existing tests\nfrom a profile to hide failures. Add or restore tests as a separate, scoped task.\n\nThe profile contains a machine-specific destination. Review your app's ignore policy before committing\nit; the installer does not edit `.gitignore`. Installed skills may be committed for the team or kept local.\n\n### Permissions and baseline scope\n\nCodex may require normal approval to write project-local `.agents/skills/` or access Xcode and\nCoreSimulator beyond its sandbox. If installation reports `Operation not permitted`, use the normal\napproval flow for that scoped write. Simulator discovery can exit successfully while its output reports\nCoreSimulator connection or permission errors and lists only placeholder destinations. Treat that output\nas blocked discovery; retry with normal approved Xcode access before choosing an actual available device.\nDo not disable sandboxing, plugin validation, or authentication, or change global settings to get past it.\n\nCompare the selected scheme's enabled tests with the app's documented CI command. This preview cannot\nexpress `-only-testing`, custom configurations, or arbitrary build-setting overrides. A full-scheme local\nbaseline can therefore include tests that CI excludes; record that difference instead of claiming CI parity\nor silently dropping tests. A baseline failure is a finding, not permission to rewrite the app or tests.\nThe `summary` command can successfully generate text for a failed run; inspect its reported status and\ncounts rather than treating summary exit code 0 as a passing verification.\n\n## Everyday workflow\n\n1. **`$ios-onboard`** discovers the app's conventions and baseline.\n2. **`$ios-plan-feature`** defines acceptance criteria, affected components, and verification.\n3. **`$ios-build-feature`** implements authorized work using the app's existing architecture.\n4. **`$ios-verify`** gathers build/test evidence and relevant simulator or device observations.\n\nFor example:\n\n> Use $ios-plan-feature to plan offline favourites. Preserve this app's architecture and deployment target.\n\n> Use $ios-build-feature to implement the agreed favourites feature, then use $ios-verify to check it.\n\nPlanning does not automatically start implementation. Already-authorized implementation does not need\nanother ceremonial approval. The workflows preserve the user's scope and existing app instructions.\n\n## Collect build and test evidence\n\n```sh\npython3 forge.py verify --app \"/path/to/MyApp\" \\\n  --output-dir \"/path/to/private-forge-evidence\" --dry-run\npython3 forge.py verify --app \"/path/to/MyApp\" \\\n  --output-dir \"/path/to/private-forge-evidence\"\n```\n\nChoose an output directory **outside the app checkout**. Each run gets its own build output,\nlogs, JSON report, and Xcode test result bundle when produced. A failed check stops later checks;\ntimeouts terminate the launched process group. Nonzero exit codes make failures usable in CI.\nReports include Xcode version, source/profile fingerprints, actual test counts and destinations,\nand bounded failure diagnostics. Tests with no executed cases or unreadable result evidence cannot pass.\nReading test summaries requires Xcode 16 or newer.\n\n`passed` means the configured commands and test-result evidence passed. UI journeys and automated\naccessibility audits can run through the app's XCTest UI tests; inspect those tests for actual coverage.\nPhysical-device behaviour, manual accessibility, and release readiness require their own evidence.\nSwiftKeystone's CLI does not directly drive the simulator UI.\nSee [verification and evidence handling](docs/verification.md).\n\n## Native macOS projects\n\nThe four workflows also cover native macOS projects; the `ios-*` skill names are\ncompatibility aliases. Use an actual Mac scheme and a discovered macOS destination, rather than an\niOS simulator. See [macOS verification](docs/macos.md) and the\n[example Mac profile](examples/macos-app-profile.json). Native macOS guidance and the example\nare included starting with v0.2.0; the original v0.1.0 assets remain unchanged.\n\n## Baseline audit, evidence comparison, and updates (v0.3.0)\n\n- [`audit`](docs/baseline-audit.md) inspects local Xcode test wiring and earlier evidence against current source/profile hashes, without building or fetching remotes.\n- [`compare` and `summary`](docs/evidence-comparison.md) compare completed reports, qualify restoration checks, and draft bounded PR evidence text without private diagnostics.\n- [`update`](docs/skill-updates.md) stages a three-way skill candidate, backup, and conflict inventory; it never replaces installed skills or profiles.\n\nThese commands are included in v0.4.0 and were introduced in v0.3.0. Use the verified download above;\ninstallation copies skills into the app, while these commands run from the extracted distribution.\nA static audit, staged update, or generated summary does not establish native behavior or grant merge approval.\n\n## Baseline expectations (v0.4.0)\n\nThe helper accepts optional required test targets and a minimum executed-test count;\nsee the [profile contract and adoption checklist](docs/profile.md#optional-baseline-expectations-v040).\nExisting profiles need no migration. These fields require the v0.4.0 helper; older helpers reject them.\nUse the verified v0.4.0 download above and keep previous distributions available during an upgrade.\nCount decreases and changed contracts require review in comparisons and PR summaries. Neither counts\nnor target names establish behavioral acceptance. Skill activation remains explicit and preserves originals.\n\n## Specialist skills\n\nSwiftKeystone works without third-party skills. The [candidate registry](upstream/registry.json) identifies\nSwiftUI, concurrency, testing, and simulator projects worth evaluating. Nothing is bundled or installed\nfrom these projects in this release. A profile's `specialist_skills` field is advisory.\n\nBefore adding a dependency, inspect its instructions/scripts, check its license and compatibility,\nand record an exact revision. Load only skills relevant to the task. Preserve existing UIKit, XCTest,\nCore Data, toolchain, deployment target, and architecture decisions.\n\n## Development and validation\n\n```sh\npython3 -m unittest discover -s tests -v\npython3 scripts/check_distribution.py\npython3 scripts/package_release.py\n```\n\nTests use temporary projects and a fake `xcodebuild` process to exercise the runner, failure paths,\ntimeouts, argument handling, and installation boundaries. They do **not** demonstrate an app building\nin Xcode. CI is configured for Linux/macOS and Python 3.10/3.13; the [hosted checks](https://github.com/TensaiSolutions/swiftkeystone/actions) report toolkit results. See the [validation record](docs/validation.md) and\n[evaluation scenarios](docs/evaluations.md) for real Codex/app pilots.\n\n## Boundaries of this release\n\n- Skills are prompt workflows; code provides deterministic setup and command execution.\n- No unattended sweeps, issue filing, PR creation, auto-merge, signing changes, or App Store submission.\n- No crash provider, App Store Connect, simulator interaction, or scheduling integration yet.\n- No automatic upstream installation, in-place skill replacement, uninstall, custom shell commands, archive/export, or test-plan flags.\n- Install preflight prevents known conflicts; it is not a transactional updater and concurrent installations are unsupported.\n- Evidence retention is manual. Logs and test bundles are private until explicitly reviewed for sharing.\n- Validation covers Forge Notes and LaRecette on iOS simulators, plus a native CotEditor macOS pilot. The Mac pilot passed app tests and four XCTest UI cases after explicit local test corrections, including document save/reopen. The earlier automation-startup timeout did not recur; its cause and reboot persistence remain unproven. iPhone/iPad hardware and broader compatibility remain outstanding.\n\nFor new projects, follow the [project creation and first-baseline workflow](docs/new-project.md).\nReal-app pilot results and remaining validation limits are recorded in [validation](docs/validation.md).\n\n## Publishing and attribution\n\nSee [GitHub publishing](docs/publishing.md), [contributing](CONTRIBUTING.md),\n[changelog](CHANGELOG.md), and [acknowledgements](ACKNOWLEDGEMENTS.md).\nOriginal SwiftKeystone material is MIT licensed. Third-party candidate projects retain their own licenses.\n"}