Plan Before Code

Use this workflow for controlled iOS development instead of direct

implementation. Keep the work grounded in the repository's real iOS architecture,

Xcode schemes, simulator/device constraints, and documented harness. Apply the

workflow as three distinct intents:

1. Establish an implementation plan without editing files.
2. Assess whether iOS work can be split safely across agents.
3. Execute only after the user gives explicit approval for the current plan.

Stage 1: Plan Only

When the user asks to determine the development plan first:

• Do not create, modify, or delete files; run migrations; create commits; or

start implementation.

• Read the repo's local rules first: AGENTS.md, iOS architecture docs,

reliability or harness docs, relevant execution plans, Xcode scheme notes,

Maestro flows, and verification scripts.

• Use read-only inspection only: rg, find, sed, git status, `git diff

--stat, xcodebuild -list`, XcodeBuildMCP discovery, and file reads are OK.

Do not run formatters, generators, migrations, app-changing scripts, or

commands that mutate DerivedData/results unless the user has approved

execution.

• Inspect only the code needed to understand the requested change.
• Explain the recommended implementation approach, affected areas, expected

file ownership, harness/verification commands, risks, and open questions.

• If the repo requires an execution plan for non-trivial work, say where it

should be created or updated during execution.

• Ask at most one blocking question if the plan cannot be made safely from local

context. Otherwise make a reasonable recommendation.

The output should be a concrete plan, not a proposal to start coding. Use this

shape unless the user asks for something shorter:

Recommended approach:
Affected iOS areas:
File ownership:
Harness and verification:
Risks:
Open questions:
Agent split recommendation:

Mention exact commands when known, such as the relevant xcodebuild command,

XcodeBuildMCP build/test action, Maestro flow, snapshot/visual review command,

or project-specific harness script. If the command is unknown, name the file or

directory to inspect during execution instead of inventing one.

Stage 2: Agent Split Assessment

When the user asks whether the work can be split across multiple agents:

• Assess coupling, shared files, dependency order, and verification bottlenecks.
• Recommend one agent when the work is tightly coupled, has one critical file

cluster, or would create merge conflicts.

• Recommend multiple agents only when tasks have clear, disjoint ownership and

can run in parallel without blocking each other.

• If recommending multiple agents, define each agent's responsibility, write

scope, expected output, integration order, and what must stay serial.

• Respect repo harness constraints. For example, if flows share one simulator,

verification must remain serial even if implementation work is parallel.

• Use this iOS split checklist:
• Shared files: view controller, SwiftUI view, coordinator, model, project

file, asset catalog, localization, build settings, and generated files.

• Dependency order: API/model changes before UI, routing before screen flows,

project settings before build validation, fixture updates before Maestro.

• Verification bottlenecks: one simulator, one physical device, single Xcode

scheme, shared DerivedData, or long-running UI flows.

• Merge risk: .pbxproj, shared snapshots, storyboard/xib, package files,

generated screenshots, and global test fixtures.

Do not spawn subagents during this assessment unless the user has explicitly

asked for delegation or parallel agent work and approved execution.

Recommending multiple agents is only an assessment; actual subagent spawning

waits until the user approves execution.

Stage 3: Execute After Approval

When the user explicitly approves executing the recommended plan:

• If no concrete plan has been presented in the current thread, first summarize

or rebuild the intended plan and ask for confirmation before editing files.

• Treat approval as sufficient only when the user clearly instructs you to begin

implementing the current plan or a named option.

• Do not treat status checks, feasibility questions, requests for reassurance,

or requests for your opinion as approval. Answer them directly and continue

planning unless the user then gives a clear execution instruction.

• Implement according to the approved plan and the repo's local rules.
• Use subagents only if the user explicitly asked for multi-agent/delegated work

and the approved plan recommended it.

• Give each subagent a concrete, bounded task with disjoint write ownership.
• Keep urgent, tightly coupled, or integration-critical work in the main agent.
• Run the repo's relevant verification gates and record any blocker with exact

commands and artifacts.

• If behavior changes and tests or flows are missing, update the appropriate

tracker or execution plan according to repo rules.

Harness Engineering

"参考项目的 harness engineering" means:

• Treat the repository's documented harness as the source of truth.
• Prefer existing verification scripts over ad hoc commands.
• Do not add fake app states, private launch routes, fake stores, or test-only

runtime paths just to make implementation or visual review easier.

• Prefer XcodeBuildMCP or the repo's documented xcodebuild wrapper for build,

test, install, launch, screenshots, and simulator logs. Check session defaults

before the first XcodeBuildMCP build/run/test call.

• For iOS Maestro flows, prefer launchApp.permissions or setPermissions to

preconfigure system permissions instead of making smoke flows tap permission

alerts. Keep ATT/usertracking prompt taps optional when the local

Maestro/Xcode/iOS Simulator stack still shows the alert after

usertracking: allow.

• Follow the repo's harness rules for generated verification artifacts such as

screenshots, visual review captures, build logs, DerivedData, result bundles,

and simulator output; keep them local, ignored, or cleaned up unless the repo

explicitly requires preserving them.

Behavior Checks

Use these examples to keep the skill honest:

• User intent: requests an iOS implementation plan and says not to edit yet.

Expected: read only the relevant iOS files and harness docs, then return a

plan with affected areas, verification commands, risks, and agent split. Make

no edits.

• User intent: asks whether the iOS work can be split across multiple agents.

Expected: assess file ownership, simulator bottlenecks, .pbxproj risk, and

UI flow verification. Do not spawn subagents unless execution is approved.

• User intent: asks you to execute the current recommendation.

Expected: execute only if a concrete plan exists in the current thread. If the

plan is missing or stale, restate it and ask for confirmation before editing.