Agent Scenario Loop

Agent Scenario Loop is an evidence-first scenario orchestration layer for agent-driven mobile development.

It lets teams define durable app scenarios once, run them through whichever agent, device, and profiling runners fit the job, collect stable evidence artifacts, compare before/after behavior, and give coding agents proof of improvement or regression.

Execution tools can change. The scenario and evidence contract should not.

Bring your own runner. Keep your scenarios. Keep your evidence.

Start Here

| If you want to... | Read this | | --- | --- | | Understand the idea in plain language | Concepts | | Understand the project doctrine | Principles | | Understand why ASL is a protocol, not a TypeScript-only library | Architecture | | Implement or evaluate an out-of-process adapter in any language | External Adapter Protocol | | Inspect artifacts, schemas, and supported surfaces | Contracts | | Write your first scenario | Scenario Authoring | | Add a runner or evidence provider | Adapter Onboarding | | Rehearse adoption in an existing app | Consumer App Rehearsal | | Run fixture, Android, or iOS proofs | Live Proofs | | Use the package from code | Public API | | Inspect runner behavior and limits | Runner docs | | Explore the neutral dogfood app | examples/mobile-app | | See runner and provider fixtures | examples/runners |

The Model

Agent Scenario Loop keeps four things separate:

1. Scenario: the application behavior that matters, such as opening a feed, joining a livestream, uploading media, completing checkout, or loading a conversation.
2. Runner: the tool that executes or observes part of the scenario, such as adb, simctl, Agent Device, Argent, accessibility tooling, profilers, or internal scripts.
3. Evidence: the durable output from a run, including logs, metrics, traces, screenshots, accessibility results, budget verdicts, and custom signals.
4. History: trusted prior runs that let agents and humans compare whether behavior improved, regressed, or stayed inconclusive.

The scenario is the asset. Runners can change. Instrumentation can change. The app behavior remains.

Quick Start

Install or use the package, then scaffold a first scenario inside an app:

asl-init --out . --scenario first-journey

Add the optional repository-scoped agent skill when you want Codex to load ASL operating guidance from the consuming app:

asl-init --out . --scenario first-journey --with-agent-skill

Wire the generated app helper, emit truth events around one real journey, merge the generated asl:* scripts intentionally, then validate the project:

asl-validate-project --root . --platform all --out artifacts/asl/project-validation

Use --config <file> when a mature app keeps its ASL config outside the root asl.config.json.

Before runtime execution, validate a scenario and runner plan:

asl-check-plan \
  --scenario scenarios/mobile/first-journey.json \
  --runner runner-manifests/primary-runner.json \
  --platform android \
  --out artifacts/asl/plan/first-journey-android

No simulator or device available yet? Run the fixture loop:

pnpm demo:loop -- --out artifacts/demo-loop

Package Surface

The root package exports stable core contracts:

const {
  createArtifactLayout,
  evaluateRunnerCompatibility,
  buildScenarioExecutionPlan,
  buildRunIndex,
  findLatestTrustedRun,
} = require('agent-scenario-loop');

Installed CLIs include:

• project setup and validation: asl-init, asl-validate-project, asl-check-plan
• profile and comparison pipelines: asl-profile-android, asl-profile-ios, asl-compare, asl-compare-latest
• generic mobile live proofs: asl-host-doctor, asl-live-android, asl-live-ios, asl-live-proof
• runner-specific helpers: asl-android-adb, asl-ios-simctl, asl-agent-device, asl-argent (asl-agent-device --check --out <dir> and asl-argent --check --out <dir> verify configured external tool surfaces and preserve availability artifacts)
• dogfood and fixture helpers: asl-demo-loop, asl-example-android-live, asl-example-ios-live

Read Public API for imports and Contracts for artifact layout, schemas, and supported runner surfaces.

What It Is Not

Agent Scenario Loop is not:

• an end-to-end UI test framework
• a generic mobile automation stack
• a replacement for Codex, Argent, Agent Device, adb, XcodeBuildMCP, Maestro, Detox, Appium, accessibility tooling, or profilers
• an agent evaluation framework

Those tools can still execute or observe the work. Agent Scenario Loop gives the scenario, evidence, and history a stable home.

Package Guarantees

Current package guarantees are tracked in Contracts, Runner docs, and the release checks exercised by:

pnpm release:check

The package should remain product-neutral. Product-specific selectors, routes, auth assumptions, accounts, and scenario data belong in the consuming app, not in this repository.

Read next

• Concepts for the plain-language model