diff --git a/docs/index.mdx b/docs/index.mdx index c0c8e1b..04b9f66 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -25,6 +25,7 @@ sidebar: | --- | --- | | Install skills and open a first verified session | [Quickstart](/quickstart) | | Bootstrap a new iOS/macOS SwiftUI app | [Bootstrap](/skills/bootstrap) · `$apple-development-foundation` → `$codex-bootstrap` | +| Add agent rules to my Swift app | [AGENTS.md template](/workflow/agents-md-template) | | Follow the full agent session loop | [Session workflow](/workflow) | | Choose the right skill for a task | [Skill routing](/workflow/skill-routing) · `$apple-development-foundation` | | Run a common scenario end-to-end | [Task recipes](/workflow/task-recipes) | @@ -63,7 +64,7 @@ Always-on rules for work **in this repository**: root `AGENTS.md`. | Section | Contents | | --- | --- | | [Quickstart](/quickstart) | Install, MCP, first session | -| [Workflow](/workflow) | Loop, routing, consumer workspace, recipes | +| [Workflow](/workflow) | Loop, routing, consumer workspace, [AGENTS.md template](/workflow/agents-md-template), recipes | | [Skills](/skills) | Inventory and major flows | | [Tools](/tools) | XcodeBuildMCP, Maestro, scripts | | [Reference](/reference/prompts) | Prompts, verification matrix, troubleshooting, external skills | diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx index 7457332..08ef1c5 100644 --- a/docs/quickstart.mdx +++ b/docs/quickstart.mdx @@ -79,7 +79,8 @@ Customize the template's project/workspace, scheme, configuration, platforms, deployment versions, simulator/config, repository-native verification commands, and Apple verification policy knobs (XcodeBuildMCP CLI fallback and raw `xcodebuild`/`xcrun`/`simctl`: `require-approval` by default, or `allowed` / -`denied`). +`denied`). Copy-paste the same contract from [AGENTS.md template](/workflow/agents-md-template) +when you prefer not to run the script. 1. Add XcodeBuildMCP to Codex’s MCP server list using current Codex and XcodeBuildMCP documentation. 2. In the **consumer** (or monorepo) workspace root, create project-local config when you need more than the default simulator tools: diff --git a/docs/reference/prompts.mdx b/docs/reference/prompts.mdx index a4cda6b..1bc5c9b 100644 --- a/docs/reference/prompts.mdx +++ b/docs/reference/prompts.mdx @@ -5,22 +5,41 @@ description: Structured, scenario-based prompts for routing skills, bootstrap, v # Copy-paste prompts -Each prompt is an **agent contract**: goal, constraints, inputs, done definition, verification. Replace `/path/to/…` and task specifics. `$skill-name` is the verified Codex invocation; other hosts require a manually verified equivalent described in [Agent host support](/reference/host-support). +Each prompt is an **agent contract**: goal, constraints, inputs, done definition, verification, stop, handoff. Paste one block into a new session, then replace every `<…>` placeholder. `$skill-name` is the verified Codex invocation; other hosts need a manually verified equivalent — see [Agent host support](/reference/host-support). + +## How to use + +1. Pick the scenario that matches the request (or start with **Point a session** for a new chat). +2. Fill placeholders before sending. Leave a field as `unknown` only when the agent must discover it — never invent paths, schemes, or policy values. +3. Prefer one prompt per session goal. Chain a second prompt only after the first handoff. +4. Pair with the matching [task recipe](/workflow/task-recipes) when you need the skill/tool table, not a pasteable contract. + +**Common placeholders** + +| Token | Meaning | +| --- | --- | +| `` | Active app/package workspace (not this foundation repo unless skill maintenance) | +| `` | Absolute path to `AppleDevelopmentFoundation/.agents/skills` | +| `` | e.g. iOS 17+, macOS 14+, or both | +| `` / `` | Exact Xcode scheme and one pinned simulator UUID | ## Point a session at these skills ```text Goal: Use Apple Development Foundation skills for Apple-platform work in this session. Constraints: -- Work only in the consumer workspace unless the user asked for foundation skill maintenance. -- Follow the Apple verification capability ladder: MCP tools; explicitly permitted XcodeBuildMCP CLI; authorized repository-native tools; otherwise report blocked. +- Work only in unless the user asked for foundation skill maintenance. +- Read root and scoped consumer AGENTS.md before acting on verification policy or editing guidance. +- Follow the Apple verification capability ladder: MCP tools → explicitly permitted XcodeBuildMCP CLI → authorized repository-native tools → otherwise report blocked. Never infer permission from tool availability. - Do not expand AppleDevelopmentFoundation `archive/Sources/`, `archive/Website/`, or package modules. - Ordinary routing is not an audit, install, or full-repo scan. Inputs: -- Skills path: /path/to/AppleDevelopmentFoundation/.agents/skills +- Skills path: - Task: Done when: Correct skills shortlisted and applied; implementation matches the task; verification reported. Verification: session_show_defaults before first build/run/test; MCP build/test as applicable; residual risk listed. +Stop when: Consumer path unclear; policy would require unauthorized fallback; task is foundation package work without explicit ask. +Handoff: skills used, project/workspace + scheme + configuration + destination, what ran, residual risk, next skill if any. ``` Start with `$apple-development-foundation` when the task is broad or the chat is new; otherwise invoke the matching skill directly. @@ -32,17 +51,45 @@ Goal: Bootstrap a new iOS (or macOS) SwiftUI app in the consumer workspace. Constraints: - Entry point: $apple-development-foundation → $codex-bootstrap (or $codex-bootstrap if already selected). - Prefer foundation routing over generic host-local macOS/iOS skills. +- Before writing project files: inspect consumer AGENTS.md; preserve existing instructions; create or merge from the consumer-AGENTS template only with explicit authorization. Never edit ~/.codex/AGENTS.md. +- Set or review Apple verification policy knobs (XcodeBuildMCP CLI fallback and repository-native raw xcodebuild/xcrun/simctl): keep require-approval unless the user authorizes allowed or denied. - If multiple peer destinations: $swiftui-tab-navigation for native primary navigation. - Design system: reuse consumer tokens or create a minimal neutral system in the consumer repo. - No invented business domain; no edits to AppleDevelopmentFoundation archived package. Inputs: -- Platforms / min OS: <…> +- Consumer path: +- Platforms / min OS: - Navigation shape: -- Consumer path: <…> -Done when: App skeleton builds; skill chain applied or explicitly skipped with reason; handoff lists next skills. +- Peer destinations (if any): +- Project-local AGENTS.md: +Done when: App skeleton builds; AGENTS.md created/preserved/proposed as authorized; skill chain applied or explicitly skipped with reason; handoff lists next skills. Verification: -- iOS: session_show_defaults → build_run_sim → test_sim if present → optional screenshot/snapshot_ui -- macOS: enable macos workflow → build_run_macos (or at least build_macos if no launch/tests) → test_macos if present (no ui-automation) +- session_show_defaults (session_set_defaults if needed); discover_projs only if defaults still wrong +- iOS: one exact → build_run_sim → wait for same-project test runners → test_sim if present (extraArgs: ["-parallel-testing-enabled", "NO"]) → optional screenshot/snapshot_ui +- macOS: enable macos workflow → build_run_macos (or at least build_macos if no launch/tests) → test_macos if present (extraArgs: ["-parallel-testing-enabled", "NO"]; no ui-automation / test_sim — iOS-simulator-only) +- Both platforms: verify each platform on its own tool path above +Stop when: No clear consumer workspace; AGENTS.md create/merge requested but unauthorized; planning-only request (use Plan only prompt); request is a single screen (use $swiftui-component-author instead). +Handoff: structure created; AGENTS.md status; skills applied/next; project/workspace, scheme, configuration, destination, tools, residual risk. +``` + +## Plan only (no implementation) + +```text +Goal: Produce an implementation plan and skill shortlist for without writing product code. +Constraints: +- Entry: $apple-development-foundation and/or $apple-platform-planner as appropriate. +- Do not create/edit app sources, project files, or AGENTS.md unless the user separately authorizes guidance edits. +- Prefer foundation skills over generic host-local Apple skills. +- Call out platform split, navigation, design-system needs, and review skills that will apply later. +Inputs: +- Consumer path: +- Platforms / min OS: +- Acceptance criteria: <…> +- Known constraints: <…> +Done when: Ordered plan, skill chain, verification plan, and open questions are written; no unauthorized file changes. +Verification: N/A for code — state what would run after implementation authorization. +Stop when: User asks to implement (switch to bootstrap or ship-feature prompt) or consumer path is unclear. +Handoff: plan, shortlist, blockers/questions, residual unknowns. ``` ## Ship a feature @@ -53,9 +100,15 @@ Constraints: - Plan with $apple-platform-planner only if multi-feature or multi-platform; otherwise implement. - Use design/component/platform skills only when the change needs them. - Shared UI: $apple-accessibility-review before calling done. Async: $swift-concurrency-review. Files/logging/permissions: $apple-security-privacy-review. -Inputs: Consumer project path, acceptance criteria, any existing patterns to match. -Done when: Feature matches criteria; reviews applied where relevant; no unrelated refactors. +- Match existing consumer patterns; no unrelated refactors. +Inputs: +- Consumer path: +- Acceptance criteria: <…> +- Patterns to match: +Done when: Feature matches criteria; reviews applied where relevant; verification executed. Verification: $swift-testing-verification + XcodeBuildMCP build/test; Maestro for critical UI paths if needed. +Stop when: Criteria conflict with existing architecture and need a product decision; required MCP path blocked by policy. +Handoff: files touched, reviews run, scheme/destination/results, residual risk, follow-ups. ``` ## Author reusable UI (tabs / tokens / components) @@ -68,9 +121,26 @@ Constraints: - Components: $swiftui-component-author on the consumer design system. - Platform divergence only when needed: $ios-macos-platform-adaptation. - Do not land code in AppleDevelopmentFoundation `archive/Sources/`. -Inputs: Consumer path, existing design system (if any), peer destinations list if tabs. +Inputs: Consumer path: ; existing design system (if any); peer destinations list if tabs. Done when: Shared UI builds; a11y review on reusable surfaces; handoff lists residual risk. Verification: session_show_defaults → MCP build; $apple-accessibility-review; $swift-testing-verification if APIs/logic changed. +Stop when: Request is a one-off screen with no reuse intent (implement locally instead of extracting). +Handoff: tokens/components/tabs added, a11y notes, build target, residual risk. +``` + +## Add a shared module or extract reusable code + +```text +Goal: . +Constraints: +- New module in the active workspace: $swift-package-module-author. +- Extract from an existing app: $reusable-code-extractor into the consumer shared module — not into AppleDevelopmentFoundation `archive/Sources/`. +- Keep public API minimal; update app imports; no branding or secrets in the shared layer. +Inputs: Consumer path: ; module name; code to extract or API sketch; app targets that will import it. +Done when: Module builds and is importable from the consumer app; extraction callers updated if applicable. +Verification: Package/app build via authorized XcodeBuildMCP (or swift_package_* tools); $swift-testing-verification for public API/logic. +Stop when: User asks to land the module in the foundation archived package without explicit package-work authorization. +Handoff: module path/products, import sites, verification results, residual risk. ``` ## Fix a bug @@ -81,9 +151,15 @@ Constraints: - Prefer the smallest failing test or Maestro flow first. - No broad cleanup unrelated to the bug. - If UI flake: $maestro-apple-app-testing diagnosis loop (hierarchy → classify → reproduce once → fix). -Inputs: Repro steps, logs/screenshots if any, consumer project path. +Inputs: +- Consumer path: +- Repro steps: <…> +- Logs/screenshots if any: <…> +- Scheme / destination: ; exact or macOS destination Done when: Repro fails before fix and passes after; residual risk stated. -Verification: Re-run the same unit/UI check via XcodeBuildMCP / Maestro; report scheme and simulator ID. +Verification: Re-run the same unit/UI check via XcodeBuildMCP / Maestro; report and exact or macOS destination. +Stop when: Cannot reproduce; fix would require speculative multi-area rewrite — report findings instead. +Handoff: root cause, diff summary, before/after check, residual risk. ``` ## Review before ship @@ -95,23 +171,37 @@ Constraints: - $apple-security-privacy-review for storage, files, logging, permissions, imports, sensitive data. - $apple-accessibility-review for reusable SwiftUI (not non-UI services). - Do not claim automated a11y proof for semantics the environment cannot test. -Inputs: Changed files / PR scope. +- Fix findings only when the user authorized fixes; otherwise report only. +Inputs: Changed files / PR scope: <…> Done when: Severity-ranked findings (and fixes if authorized); manual checks listed. -Verification: Strict concurrency build when relevant; then verification matrix for the change type. +Verification: Strict concurrency build when relevant; then docs/reference/verification-matrix.mdx for the change type. +Stop when: Scope is unclear (ask for PR/diff bounds) or review would require editing without authorization. +Handoff: findings by severity, fixes applied or deferred, manual checks, residual risk. ``` ## Verify after bootstrap or feature work ```text Goal: Prove the consumer target builds and tests on the intended device class. -Constraints: Follow active policy: XcodeBuildMCP MCP tools first; CLI only when explicitly permitted; repository-native raw Xcode tools only when authorized; otherwise report blocked. -Inputs: Project/workspace, scheme, simulator or macOS target. -Done when: Defaults shown; build and tests executed; outcomes and next tool call on failure reported. +Constraints: +- Follow active consumer AGENTS.md Apple verification policy: XcodeBuildMCP MCP tools first; CLI only when explicitly permitted; repository-native raw Xcode tools only when authorized; otherwise report blocked. +- Never infer fallback permission from shell access or an installed binary. +- Pin one exact for iOS; do not use OS=latest. +- Serialize same-project simulator tests; default extraArgs: ["-parallel-testing-enabled", "NO"]. +Inputs: +- Consumer path: +- Project/workspace: <…> +- Scheme: +- Destination: exact or macOS target +Done when: Defaults shown; build and tests executed (or compile-only when no tests); outcomes and next tool call on failure reported. Verification: 1. session_show_defaults (session_set_defaults if needed) 2. discover_projs only if defaults still wrong/missing -3. iOS: build_run_sim → test_sim; macOS: enable macos workflow → build_run_macos (or at least build_macos if no launch/tests) → test_macos if present (no ui-automation) -Never claim pass without running an authorized tool. Report project/workspace, scheme, configuration, exact destination, command/tool, and residual risk. +3. iOS: build_run_sim → test_sim if present (extraArgs: ["-parallel-testing-enabled", "NO"]); optional screenshot/snapshot_ui +4. macOS: enable macos workflow → build_run_macos (or at least build_macos if no launch/tests) → test_macos if present (extraArgs: ["-parallel-testing-enabled", "NO"]; no ui-automation / test_sim) +Never claim pass without running an authorized tool. Report project/workspace, scheme, configuration, exact destination, command/tool, skipped checks, and residual risk. +Stop when: No authorized capability remains — report blocked with policy values in force. +Handoff: context, commands/tools, pass/fail, skips, residual risk, next action. ``` ## Maestro UI regression @@ -120,12 +210,19 @@ Never claim pass without running an authorized tool. Report project/workspace, s Goal: Author or stabilize Maestro coverage for . Constraints: - Use $maestro-apple-app-testing with XcodeBuildMCP for build/install/sim control. -- One exact simulator ID; do not use OS=latest. +- One exact ; do not use OS=latest. - If maestro CLI missing: report blocker before writing speculative flows. - MCP for inspect/debug; maestro test for regression YAML. -Inputs: App identifier, existing .maestro/ conventions, flows to cover. +- After each flow or journey change, run only the edited or directly affected flow(s). If a shared UI or navigation change genuinely affects several journeys, run all of those directly affected flows and state why. Do not run tagged or full-suite runs unless the user or a documented release/CI gate requires them. +Inputs: +- Consumer path: +- App identifier: <…> +- Scheme / simulator: ; exact +- Existing .maestro/ conventions; flows to cover: <…> Done when: Flows run; flakes classified; pass/fail counts and artifacts reported. -Verification: Run only the single smallest relevant flow after each flow or journey change. Do not add tagged or complete-suite runs unless the user explicitly requests them or a documented release/CI gate requires them. +Verification: Targeted maestro test on the edited/affected flow(s); report and artifacts. +Stop when: CLI missing, simulator ambiguous, or flake class needs product decision (timing vs selector vs app bug). +Handoff: flows added/changed, results, flake classification, residual risk. ``` ## Foundation skill maintenance @@ -137,22 +234,30 @@ Constraints: - Follow docs/skills/skill-authoring-guide.mdx. - Keep skills neutral (no branding, secrets, user-specific paths, hidden network). - Update canonical manifest.json metadata and run ./Scripts/generate-skill-catalog.py; do not edit generated inventories directly. -Inputs: Skill change request. +Inputs: Skill change request: <…> Done when: Contracts pass and generated catalog projections are current. Verification: ./Scripts/verify-skills.sh; ./Scripts/test-install-skills.sh if installer behavior changed; install --dry-run. +Stop when: Change would bake consumer branding or secrets into a shared skill. +Handoff: skills touched, verify script results, catalog regeneration note, residual risk. ``` ## Explicit foundation audit (only when requested) ```text -Goal: Run an explicit Apple Development Foundation skill inventory audit. +Goal: Run an explicit Apple Development Foundation audit for the selected scope (inventory comparison and/or installer verification). Constraints: -- Invoke $apple-development-foundation in audit mode using master-skill.json classifications. +- Invoke $apple-development-foundation in audit mode. - Do not treat ordinary routing as an audit. -- Run foundation verification scripts only if this repo or its installer is in scope. -Inputs: Audit scope (inventory comparison, installer, both). -Done when: Classifications and comparison reported; verification outcomes only if in scope. -Verification: Per master-skill.json verification commands when applicable. +- Inventory comparison or both: use master-skill.json classifications and compare inventories. +- Installer or both: run foundation verification scripts for this repo or its installer. +- Installer-only: do not run or invent an inventory comparison. +Inputs: Audit scope: +Done when: +- inventory comparison or both: classifications and comparison reported +- installer or both: foundation verification script outcomes reported +Verification: Per master-skill.json verification commands when installer is in scope; otherwise N/A for installer scripts. +Stop when: User only asked for routing/shortlist — do not escalate into audit mode. +Handoff: residual risk always; classifications and diffs vs expected inventory only when inventory is in scope; verification outcomes only when installer is in scope. ``` ## Related diff --git a/docs/reference/troubleshooting.mdx b/docs/reference/troubleshooting.mdx index bb42fc1..d34cf04 100644 --- a/docs/reference/troubleshooting.mdx +++ b/docs/reference/troubleshooting.mdx @@ -26,7 +26,7 @@ Installer **never** overwrites conflicting names. Details: [Scripts](/tools/scri | Symptom | Likely cause | Next step | | --- | --- | --- | | `An explicit --target is required` | Consumer repository was not selected | Re-run `./Scripts/init-consumer-guidance.sh --target /path/to/consumer --dry-run` | -| `Conflict; leaving existing consumer instructions untouched` | Consumer already owns an `AGENTS.md` | Keep it unchanged; compare `.agents/skills/codex-bootstrap/assets/consumer-AGENTS.md.template`, propose specific missing sections, and merge only with explicit authorization | +| `Conflict; leaving existing consumer instructions untouched` | Consumer already owns an `AGENTS.md` | Keep it unchanged; compare `.agents/skills/codex-bootstrap/assets/consumer-AGENTS.md.template` or [AGENTS.md template](/workflow/agents-md-template), propose specific missing sections, and merge only with explicit authorization | | Foundation repository target is refused | Initializer was pointed at this skills repository | Select the actual consumer app/package root explicitly | | `install-global-instructions.sh is retired` | Legacy global behavior was invoked | Use the project-local initializer; global `~/.codex/AGENTS.md` is never modified | | Generated guidance still contains `<...>` | Required customization is incomplete | Fill project/workspace, scheme, configuration, platforms, deployment versions, simulator/config, and repository-native check commands from checked-in consumer configuration | diff --git a/docs/skills/bootstrap.mdx b/docs/skills/bootstrap.mdx index 2defd30..8e779e1 100644 --- a/docs/skills/bootstrap.mdx +++ b/docs/skills/bootstrap.mdx @@ -41,8 +41,9 @@ Extraction of proven app code → `$reusable-code-extractor` into the **consumer - Inspect root and scoped consumer `AGENTS.md` files before writing - Preserve existing instructions; propose a merge and wait for explicit authorization - If no file exists and creation is authorized, initialize from the portable - `assets/consumer-AGENTS.md.template` skill asset or preview with - `./Scripts/init-consumer-guidance.sh --target --dry-run` + `assets/consumer-AGENTS.md.template` skill asset, preview with + `./Scripts/init-consumer-guidance.sh --target --dry-run`, or copy from + [AGENTS.md template](/workflow/agents-md-template) - Never modify global `~/.codex/AGENTS.md` - SwiftUI `@main` entry with a single root shell - Native primary navigation only when the user listed multiple peer destinations diff --git a/docs/tools/scripts.mdx b/docs/tools/scripts.mdx index 35e4edb..383c2f2 100644 --- a/docs/tools/scripts.mdx +++ b/docs/tools/scripts.mdx @@ -65,7 +65,8 @@ Required tools: `awk`, `python3`, `readlink`. Missing `manifest.json` fails the one explicitly selected consumer repository. The asset travels with the installed bootstrap skill. The initializer requires `--target`, supports `--dry-run`, refuses this foundation repository, and treats any existing `AGENTS.md` path as a conflict. It never reads -or writes global `~/.codex/AGENTS.md`. +or writes global `~/.codex/AGENTS.md`. The same contract is published for copy-paste on +[AGENTS.md template](/workflow/agents-md-template). The former `install-global-instructions.sh` entry point is a retired compatibility stub that exits with migration instructions and performs no writes. diff --git a/docs/workflow/agents-md-template.mdx b/docs/workflow/agents-md-template.mdx new file mode 100644 index 0000000..65c3754 --- /dev/null +++ b/docs/workflow/agents-md-template.mdx @@ -0,0 +1,223 @@ +--- +title: AGENTS.md template +description: Copy-paste the project-local consumer AGENTS.md contract for SwiftUI and Apple-platform repos. +--- + +# AGENTS.md template + +SwiftUI and other Apple-platform **consumer** repos that use Apple Development Foundation skills should have a root `AGENTS.md`. If yours is missing, copy the template below. If one already exists, preserve it and merge only with explicit authorization. + +This contract is **project-local**. Paste it into `/AGENTS.md`. Do **not** paste it into global `~/.codex/AGENTS.md`. + +## How to install + +1. **Copy/paste** — Create `/AGENTS.md` from the template on this page when the file is missing. +2. **Initializer** — From this foundation repo: + ```bash + ./Scripts/init-consumer-guidance.sh --target /path/to/consumer --dry-run + ./Scripts/init-consumer-guidance.sh --target /path/to/consumer + ``` +3. **Bootstrap** — `$codex-bootstrap` (via `$apple-development-foundation` when routing) may propose create or merge; it waits for authorization and never overwrites silently. + +The initializer refuses this foundation repository and any existing `AGENTS.md` path. Details: [Scripts](/tools/scripts) · [Bootstrap](/skills/bootstrap) · [Troubleshooting](/reference/troubleshooting). + +## Customize before relying on it + +Fill every `<…>` placeholder from checked-in project configuration. Do not invent schemes, destinations, or policy values. + +| Fill in | Examples | +| --- | --- | +| Project or workspace | `App.xcodeproj`, `App.xcworkspace` | +| Scheme / configuration | scheme name, `Debug` | +| Platforms and min OS | iOS 17+, macOS 14+, or both | +| Destinations | exact `simulatorId`; macOS arch or `n/a` | +| Formatter / linter / checks | repo-native commands or `not configured` | +| Targeted and full tests | repo-native or MCP test scope | +| Apple verification policy | XcodeBuildMCP CLI and raw `xcodebuild`/`xcrun`/`simctl`: keep `require-approval` unless you authorize `allowed` or `denied` | + +Scoped `AGENTS.md` files in subdirectories refine this root contract for their trees; keep them when present. + +## Canonical source + +The bootstrap skill asset is the source of truth: + +`.agents/skills/codex-bootstrap/assets/consumer-AGENTS.md.template` + +This page mirrors that file for website copy-paste. Prefer the skill asset when scripting installs. + +## Template + +Copy everything inside the fence into `/AGENTS.md`: + +```markdown +# Consumer Apple-platform engineering contract + +This file governs work in this repository. Customize every value in angle +brackets before relying on project-specific build or test instructions. Preserve +more-specific `AGENTS.md` files in subdirectories; their instructions refine +this contract for files in their scope. + +## Project configuration + +- Project or workspace: `` +- Scheme: `` +- Build configuration: `` +- Target platforms: `` +- Minimum deployment versions: `` +- Destination: + - iOS / simulator targets: `` or project-local defaults in + `.xcodebuildmcp/config.yaml` + - macOS targets: `` (enable the XcodeBuildMCP + `macos` workflow); leave as `n/a` when the repo is iOS-only + - Shared iOS + macOS: fill both of the above +- Formatter: `` +- Linter: `` +- Additional type or build checks: + `` +- Targeted tests: `` +- Full tests: `` + +## Apple verification policy + +Fill these before relying on fallback behavior. Shell access or an installed +binary is never permission by itself. + +- XcodeBuildMCP CLI fallback: `require-approval` + (allowed values: `require-approval` | `allowed` | `denied`) +- Repository-native raw `xcodebuild` / `xcrun` / `simctl`: `require-approval` + (allowed values: `require-approval` | `allowed` | `denied`) + +Interpret as: + +- `allowed` — the matching ladder step may run without asking again +- `require-approval` — ask the user before that step when MCP tools cannot + complete the needed action +- `denied` — never use that step; report blocked when MCP cannot complete it + +Do not guess missing values. Inspect checked-in project configuration and scripts, +then ask before choosing among materially different targets or workflows. Keep +machine-specific simulator IDs and Mac destinations in project-local configuration +only when the team intentionally shares them. + +## Engineering lifecycle + +Use an inspect → implement → verify → handoff lifecycle, scaled to the task. + +### Inspect + +- Read every `AGENTS.md` from the repository root through the files in scope. +- Inspect `git status` and relevant diffs before editing. Treat existing changes + as user-owned and preserve unrelated work. +- Read relevant manifests, project settings, package definitions, task runners, + and repository scripts. Prefer documented repository commands. +- Identify the smallest coherent file and target scope that satisfies the task. + +### Implement + +- Make the smallest cohesive change that satisfies the request. Avoid unrelated + cleanup and preserve established architecture unless the task changes it. +- Use Swift 6 for new Swift code. If an existing target is not configured for + Swift 6, report the compatibility constraint and request authorization before + changing project-wide language settings. Prefer structured concurrency, + explicit state ownership, native observation, and initializer or environment + dependency injection. Do not introduce a view model without a state-ownership + or testability reason. +- Do not add, remove, or upgrade dependencies, change lockfiles, or run data + migrations unless explicitly authorized. +- Do not deploy, publish, push, create a pull request, cut a release, or change + external systems unless explicitly authorized. +- Never use destructive Git operations or blanket staging. Stage only explicit + paths when a commit is requested or otherwise authorized by repository policy. + +### Verify + +- Start with the narrowest relevant formatter, linter, build, and tests from the + project configuration above. Broaden verification according to risk. +- Treat failures as work to investigate. Do not silently ignore a failed or + unavailable check. +- Do not modify code merely to make unrelated pre-existing failures disappear. + +### Handoff + +- Summarize what changed and why. +- Report every verification command or MCP action and its outcome. +- Report the active project/workspace, scheme, configuration, platform, and exact + destination (simulatorId and/or macOS) used. +- Identify skipped or failed checks, remaining risks, and preserved unrelated + working-tree changes. + +## XcodeBuildMCP workflow + +Use XcodeBuildMCP first for Apple-platform builds, tests, and runs. Do not +silently fall back to raw `xcodebuild`, `xcrun`, or `simctl`. Branch by the +**Target platforms** value above — do not use iOS simulator tools for a +macOS-only app, and do not skip the `macos` workflow when macOS is in scope. + +1. Before the first build, run, or test action in a session, call + `session_show_defaults`. Report the active project/workspace, scheme, + configuration, and platform destination. +2. If defaults are missing or incorrect, use `session_set_defaults`; use project + discovery only when the correct path is not already known. +3. **iOS (simulator) targets:** + - Prefer one exact `simulatorId` over name-only or `OS=latest` destinations. + - Reuse an already-booted simulator. For a manual launch, use `build_run_sim`; + do not separately build, boot, install, and launch for the same operation. + - Use `test_sim` as the complete simulator test workflow. Do not build + immediately before it unless a separate compile-only build was requested. + - Before simulator tests, check for another active `xcodebuild`, `xctest`, or + project test-runner process. Wait rather than starting a concurrent run for + the same project. + - Run simulator tests serially with + `extraArgs: ["-parallel-testing-enabled", "NO"]` unless the project + explicitly requires and has verified parallel workers. + - Optional: `screenshot` / `snapshot_ui` when the `ui-automation` workflow is + enabled (iOS simulator only). +4. **macOS targets:** + - Enable and use the XcodeBuildMCP `macos` workflow. + - Prefer `build_run_macos` for a launch smoke. + - Use `test_macos` when a test target exists; default + `extraArgs: ["-parallel-testing-enabled", "NO"]`. + - If neither launch smoke nor `test_macos` runs, require at least + `build_macos` so the target is compiled. + - Do **not** call `build_run_sim`, `test_sim`, or ui-automation + screenshot/hierarchy tools for macOS — those are iOS-simulator-only. + - If no test target exists yet, report that `test_macos` was skipped and the + residual risk only after `build_run_macos` or `build_macos` succeeds. +5. **Shared iOS + macOS:** verify each platform with its branch above. +6. If an MCP capability is unavailable, apply **Apple verification policy** + above for XcodeBuildMCP CLI. Use CLI only when that policy is `allowed`, or + when it is `require-approval` and the user has just approved this step. If the + policy is `denied`, skip CLI and evaluate the next ladder step. +7. Use repository-native raw `xcodebuild`, `xcrun`, or `simctl` only when the + raw-tooling policy is `allowed`, or `require-approval` with fresh user + approval. Preserve the same project/workspace, scheme, configuration, exact + destination, serialized execution, and test scope. For macOS fallbacks, state + destination architecture explicitly (for example `platform=macOS,arch=arm64`). +8. If no authorized path exists, report blocked with the exact unavailable + capability, policy value in force, checks not run, next action, and residual + risk. + +For Swift packages without an Xcode project, prefer the XcodeBuildMCP Swift +package workflow when available, then use configured repository-native commands +only when active policy authorizes them, with the same inspect and reporting discipline. + +## Accessibility, privacy, and security + +- SwiftUI must support Dynamic Type, VoiceOver, keyboard access where applicable, + sufficient contrast, Reduce Motion, and Differentiate Without Color. +- Give every icon-only control a descriptive accessibility label. Preserve native + controls and platform conventions unless a custom interaction is justified and + equivalently accessible. +- Request only necessary entitlements and permissions. Explain user-data impact + when changing persistence, imports/exports, permissions, or file access. +- Never log credentials, tokens, private content, raw imported data, complete + sensitive paths, or security-scoped URLs. Redact diagnostics and keep secrets + out of source control, fixtures, screenshots, and handoff text. +``` + +## Related + +- [Consumer workspace](/workflow/consumer-workspace) +- [Bootstrap](/skills/bootstrap) +- [Scripts](/tools/scripts) +- [Troubleshooting](/reference/troubleshooting) diff --git a/docs/workflow/consumer-workspace.mdx b/docs/workflow/consumer-workspace.mdx index 5e6e372..94003d8 100644 --- a/docs/workflow/consumer-workspace.mdx +++ b/docs/workflow/consumer-workspace.mdx @@ -40,7 +40,8 @@ When the user wants a new app: 2. Inspect existing consumer `AGENTS.md` files and preserve them. 3. With authorization, preview or create a missing root contract from the `codex-bootstrap/assets/consumer-AGENTS.md.template` skill asset using - `./Scripts/init-consumer-guidance.sh --target --dry-run`. + `./Scripts/init-consumer-guidance.sh --target --dry-run`, or + copy from [AGENTS.md template](/workflow/agents-md-template). 4. Invoke `$apple-development-foundation` so it routes to `$codex-bootstrap` against the **consumer** path (use `$codex-bootstrap` directly only when already selected). 5. Chain sibling skills as needed (tabs, design system, components, reviews). @@ -53,7 +54,7 @@ or merging the consumer contract, set the **Apple verification policy** knobs (XcodeBuildMCP CLI fallback and raw Xcode tooling: default `require-approval`) so agents do not invent fallback permission. -Details: [Bootstrap](/skills/bootstrap). +Details: [Bootstrap](/skills/bootstrap) · [AGENTS.md template](/workflow/agents-md-template). ## Skill maintenance (this repo only) diff --git a/docs/workflow/index.mdx b/docs/workflow/index.mdx index 45d0068..da2f730 100644 --- a/docs/workflow/index.mdx +++ b/docs/workflow/index.mdx @@ -10,7 +10,7 @@ A reliable agent session follows a fixed loop. Skip steps only when the task is ## Loop 1. **Orient** - - Read always-on rules: repo `AGENTS.md` (when working in this foundation repo) or the consumer app’s agent instructions. + - Read always-on rules: repo `AGENTS.md` (when working in this foundation repo) or the consumer app’s agent instructions ([AGENTS.md template](/workflow/agents-md-template) if missing). - Identify the **active workspace** (consumer app vs this skills reference). - See [Consumer workspace](/workflow/consumer-workspace). diff --git a/docs/workflow/meta.ts b/docs/workflow/meta.ts index 07b2320..3b92d0c 100644 --- a/docs/workflow/meta.ts +++ b/docs/workflow/meta.ts @@ -4,6 +4,12 @@ export default defineMeta({ title: "Workflow", icon: "git-branch", order: 2, - pages: ["index", "task-recipes", "skill-routing", "consumer-workspace"], + pages: [ + "index", + "task-recipes", + "skill-routing", + "consumer-workspace", + "agents-md-template", + ], });