# Skill 2 Execute Manual Flows > Runtime/manual-flow execution workflow for proving app behavior in simulators, emulators, browsers, devices, or GUI apps. Use when Codex should launch the relevant target, perform a user-facing or integration flow, collect stdout/stderr/logs/screenshots, inspect failures, retry with a better hypothesis, and hand back exact manual reproduction instructions. Especially useful after skill-1 implementation when build/tests pass but runtime behavior still needs evidence. - Skill: `careylzh/skill-2-execute-manual-flows` (Agent Skill) - Install (CLI): `npx skillmds@latest add careylzh/skill-2-execute-manual-flows` - Raw SKILL.md: https://api.skillmd.com/api/skills/careylzh/skill-2-execute-manual-flows/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: careylzh (https://skillmd.com/u/careylzh) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/careylzh/skill-2-execute-manual-flows --- # Skill 2 Execute Manual Flows Use this skill to execute and verify runtime behavior that cannot be proven by compile checks alone. It is a companion to autonomous coding workflows: after code builds, run the app or simulator path, capture evidence, and either confirm the acceptance criteria or feed concrete failures back into debugging. ## Operating Contract At the start, derive a short runtime contract: - Flow under test: the exact user journey, command path, device interaction, or integration behavior. - Targets: app names, schemes, destinations, simulators, devices, browsers, services, or ports. - Inputs: launch arguments, group keys, accounts, URLs, payloads, fixtures, permissions, or network assumptions. - Evidence required: logs, stdout/stderr, screenshots, process exit codes, UI state, server traces, network output, or generated artifacts. - Pass/fail criteria: observable result that proves the flow worked, plus known limitations. If details are missing, infer conservative defaults from the repo docs and recent commands. Ask only when guessing would exercise the wrong product path. ## Workflow 1. Identify the runnable surface. - Read project docs, scripts, package files, schemes, and prior command history. - Prefer documented commands over inventing new ones. - Check for existing smoke-test, e2e, simulator, or harness entry points. 2. Prepare the runtime environment. - Build the target first if the flow depends on fresh code. - Boot or select the needed simulator/device/browser. - Install the app if required. - Terminate stale app instances when they could hold ports, listeners, windows, or simulator state. - Request escalated permission for GUI, simulator, device, or log commands when sandboxing requires it. 3. Execute the flow. - Use command-line launch arguments when available so the run is repeatable. - For GUI flows, open the app and use the app's own controls or documented automation hooks. - Capture stdout/stderr to files when the launcher detaches from the terminal. - For multi-client or concurrency flows, run the expected number of clients concurrently and keep separate logs. 4. Collect evidence. - Read captured stdout/stderr files. - Inspect simulator/device/app logs with targeted predicates. - Capture screenshots when visual state matters. - Record process IDs, exit codes, selected simulator IDs, ports, service names, and key log lines. - Use concise excerpts; do not dump noisy framework logs unless they contain the relevant failure. 5. Interpret honestly. - Distinguish build success, app launch success, network connection, protocol acknowledgement, and UI confirmation. - Treat a clean exit without expected evidence as inconclusive. - Treat framework-level network logs as supporting evidence, but prefer app-level pass/fail logs or protocol acknowledgements. - If the flow fails, form a new hypothesis from the evidence and retry after a small targeted fix or environment adjustment. 6. Clean up. - Stop long-running log streams, dev servers, simulator app instances, and temporary clients when no longer needed. - Leave useful captured logs in `/private/tmp` or the repo only when they are intentionally part of the handoff. - Do not commit generated logs, DerivedData, simulator state, or user-local IDE metadata. 7. Report and hand off. - State pass/fail for each runtime criterion. - Include exact commands that were run, with placeholders for machine-specific IDs. - Include expected output snippets and where to find logs. - If physical devices or human interaction are still required, give step-by-step manual instructions and ask for the specific evidence needed if it fails. ## Common Command Patterns Use these as patterns, adapting to the repository and platform. ### Xcode / Apple Simulator Discover destinations: ```sh xcodebuild -showdestinations -project .xcodeproj -scheme xcrun simctl list devices available ``` Build: ```sh xcodebuild build -project .xcodeproj -scheme -destination 'id=' -derivedDataPath .DerivedData CODE_SIGNING_ALLOWED=NO xcodebuild build -project .xcodeproj -scheme -destination 'platform=macOS' -derivedDataPath .DerivedData CODE_SIGNING_ALLOWED=NO ``` Install and launch a simulator app: ```sh xcrun simctl terminate xcrun simctl install .DerivedData/Build/Products/-/.app xcrun simctl launch --example-flag VALUE ``` Launch a macOS `.app` with captured output: ```sh open -W -n .DerivedData/Build/Products/Debug/.app \ --stdout /private/tmp/-flow.out \ --stderr /private/tmp/-flow.err \ --args --example-flag VALUE ``` Read logs: ```sh xcrun simctl spawn log stream --predicate 'process == ""' --style compact log show --last 5m --style compact --predicate 'process == ""' ``` ### Browser / Web App - Start the documented dev server. - Open the local URL. - Use Playwright or browser automation when available. - Capture screenshots and console/network errors for UI assertions. - Stop the server after verification unless the user asked to keep it running. ### Multi-Client Flows - Give each client a separate stdout/stderr file. - Run clients concurrently when simultaneity is part of the requirement. - Verify every client reached the pass condition, not only that the server stayed alive. - Confirm the host/server saw all expected peers or commands when host-side evidence is available. ## Failure Handling When runtime execution fails: 1. Preserve the command, exit code, and log excerpt. 2. Decide whether the failure is environment/setup, permissions, lifecycle, network/service discovery, protocol, UI state, or test harness. 3. Retry only after changing one meaningful variable. 4. If a code fix is needed, return to the implementation workflow, validate the build, then rerun this manual flow. 5. If blocked by hardware, credentials, signing, or an external service, report the blocker and give the user the shortest manual test that can close the gap. ## macOS to visionOS Bubble Example For this repo's AVP-host/macOS-controller flow, the repeatable simulator proof is: ```sh xcrun simctl list devices available xcodebuild build -project mac2visionOS.xcodeproj -scheme mac2visionOS -destination 'id=' -derivedDataPath .DerivedData CODE_SIGNING_ALLOWED=NO xcodebuild build -project mac2visionOS.xcodeproj -scheme mac2visionOS -destination 'platform=macOS' -derivedDataPath .DerivedData CODE_SIGNING_ALLOWED=NO xcrun simctl install .DerivedData/Build/Products/Debug-xrsimulator/mac2visionOS.app xcrun simctl launch com.i3d.mac2visionOS --bubble-smoke-host AVP1 open -W -n .DerivedData/Build/Products/Debug/mac2visionOS.app --stdout /private/tmp/mac2vision-smoke.out --stderr /private/tmp/mac2vision-smoke.err --args --bubble-smoke-client AVP1 ``` Passing evidence includes: ```text [BubbleSmoke] Found mac2visionOS-AVP1; connecting [BubbleSmoke] Decoded ack(true, Accepted Ping) [BubbleSmoke] Smoke connection passed: Accepted Ping ``` For the four-controller requirement, launch four macOS smoke clients concurrently and verify all four output files contain the pass line.