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:

xcodebuild -showdestinations -project <Project>.xcodeproj -scheme <Scheme>
xcrun simctl list devices available

Build:

xcodebuild build -project <Project>.xcodeproj -scheme <Scheme> -destination 'id=<DEVICE_ID>' -derivedDataPath .DerivedData CODE_SIGNING_ALLOWED=NO
xcodebuild build -project <Project>.xcodeproj -scheme <Scheme> -destination 'platform=macOS' -derivedDataPath .DerivedData CODE_SIGNING_ALLOWED=NO

Install and launch a simulator app:

xcrun simctl terminate <DEVICE_ID> <BundleID>
xcrun simctl install <DEVICE_ID> .DerivedData/Build/Products/<Config>-<sdk>/<App>.app
xcrun simctl launch <DEVICE_ID> <BundleID> --example-flag VALUE

Launch a macOS .app with captured output:

open -W -n .DerivedData/Build/Products/Debug/<App>.app \
  --stdout /private/tmp/<app>-flow.out \
  --stderr /private/tmp/<app>-flow.err \
  --args --example-flag VALUE

Read logs:

xcrun simctl spawn <DEVICE_ID> log stream --predicate 'process == "<ProcessName>"' --style compact
log show --last 5m --style compact --predicate 'process == "<ProcessName>"'

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:

xcrun simctl list devices available
xcodebuild build -project mac2visionOS.xcodeproj -scheme mac2visionOS -destination 'id=<DEVICE_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 <DEVICE_ID> .DerivedData/Build/Products/Debug-xrsimulator/mac2visionOS.app
xcrun simctl launch <DEVICE_ID> 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:

[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.