agent-scenario-loop 0.1.0 → 0.1.2

package/README.md

@@ -43,6 +43,12 @@ 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:
+
+```bash
+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:
 
 ```bash

package/dist/runner/demo-loop.d.ts

@@ -10,6 +10,12 @@ type DemoLoopResult = {
     outputDir: string;
     preflightDir: string;
 };
+/**
+ * Resolves files shipped with the installed package.
+ *
+ * @returns {string}
+ */
+declare function resolvePackageRoot(): string;
 /**
  * Prints CLI usage.
  *
@@ -41,5 +47,5 @@ declare function runDemoLoop({ outputDir }?: {
  * @returns {Promise<void>}
  */
 declare function main(): Promise<void>;
-export { main, parseArgs, runDemoLoop, usage, };
+export { main, parseArgs, runDemoLoop, resolvePackageRoot, usage, };
 export type { CliArgs, DemoLoopResult, };

package/dist/runner/demo-loop.js

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.main = main;
 exports.parseArgs = parseArgs;
 exports.runDemoLoop = runDemoLoop;
+exports.resolvePackageRoot = resolvePackageRoot;
 exports.usage = usage;
 const path = require('node:path');
 const { buildAgentSummaryMarkdown } = require('../core/agent-summary');
@@ -15,6 +16,14 @@ const { buildPlanArtifacts } = require('./check-plan');
 const { hasHelpFlag, writeUsage } = require('./cli');
 const { compareLatestTrustedRun } = require('./compare-latest');
 const { runProfileIos } = require('./profile-ios');
+/**
+ * Resolves files shipped with the installed package.
+ *
+ * @returns {string}
+ */
+function resolvePackageRoot() {
+    return path.resolve(__dirname, '..', '..');
+}
 /**
  * Prints CLI usage.
  *
@@ -60,16 +69,16 @@ function parseArgs(argv) {
  * @returns {Promise<DemoLoopResult>}
  */
 async function runDemoLoop({ outputDir = path.resolve('artifacts/demo-loop') } = {}) {
-    const root = process.cwd();
+    const packageRoot = resolvePackageRoot();
     const resolvedOutputDir = path.resolve(outputDir);
     const preflightDir = path.join(resolvedOutputDir, 'preflight', 'app-startup');
     const profileRoot = path.join(resolvedOutputDir, 'profile-runs');
-    const configPath = path.join(root, 'core/config-template.json');
-    const profileScenarioPath = path.join(root, 'examples/scenarios/ios/app-startup.json');
-    const mobileScenarioPath = path.join(root, 'examples/scenarios/mobile/app-startup.json');
-    const runnerPath = path.join(root, 'examples/runners/xcodebuildmcp-ios.json');
-    const baselineLogPath = path.join(root, 'examples/event-logs/app-startup-baseline.log');
-    const currentLogPath = path.join(root, 'examples/event-logs/app-startup-current.log');
+    const configPath = path.join(packageRoot, 'core/config-template.json');
+    const profileScenarioPath = path.join(packageRoot, 'examples/scenarios/ios/app-startup.json');
+    const mobileScenarioPath = path.join(packageRoot, 'examples/scenarios/mobile/app-startup.json');
+    const runnerPath = path.join(packageRoot, 'examples/runners/xcodebuildmcp-ios.json');
+    const baselineLogPath = path.join(packageRoot, 'examples/event-logs/app-startup-baseline.log');
+    const currentLogPath = path.join(packageRoot, 'examples/event-logs/app-startup-current.log');
     const preflight = await buildPlanArtifacts({
         scenarioPath: mobileScenarioPath,
         runnerPath,

package/dist/runner/init-project.d.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 type CliArgs = {
     'dry-run'?: string | boolean;
+    'with-agent-skill'?: string | boolean;
     force?: string | boolean;
     out?: string | boolean;
     scenario?: string | boolean;
@@ -18,6 +19,7 @@ type InitProjectOptions = {
     outDir?: string;
     packageRoot?: string;
     scenarioId?: string;
+    withAgentSkill?: boolean;
 };
 type InitProjectResult = {
     created: string[];
@@ -59,10 +61,11 @@ declare function normalizeScenarioId(value: string | undefined): string;
  * @param {{packageRoot: string, scenarioId: string, targetDir: string}} options
  * @returns {ScaffoldFile[]}
  */
-declare function buildScaffoldFiles({ packageRoot, scenarioId, targetDir, }: {
+declare function buildScaffoldFiles({ packageRoot, scenarioId, targetDir, withAgentSkill, }: {
     packageRoot: string;
     scenarioId: string;
     targetDir: string;
+    withAgentSkill?: boolean;
 }): ScaffoldFile[];
 /**
  * Scaffolds Agent Scenario Loop starter files into a consuming app directory.

package/dist/runner/init-project.js

@@ -14,6 +14,9 @@ const fsp = require('node:fs/promises');
 const path = require('node:path');
 const { hasHelpFlag, writeUsage } = require('./cli');
 const TEMPLATE_FILES = {
+    agentSkillAdoptionChecklist: path.join('skills', 'agent-scenario-loop', 'references', 'adoption-checklist.md'),
+    agentSkillArtifactInterpretation: path.join('skills', 'agent-scenario-loop', 'references', 'artifact-interpretation.md'),
+    agentSkillReadme: path.join('skills', 'agent-scenario-loop', 'SKILL.md'),
     config: 'project.config.json',
     evidenceProvider: 'evidence-provider.json',
     gitignoreSnippet: 'gitignore-snippet',
@@ -32,7 +35,7 @@ const TEMPLATE_FILES = {
  */
 function usage(output = process.stderr) {
     writeUsage([
-        'Usage: asl-init [--out <dir>] [--scenario <id>] [--force] [--dry-run]',
+        'Usage: asl-init [--out <dir>] [--scenario <id>] [--with-agent-skill] [--force] [--dry-run]',
         '',
         'Copies public Agent Scenario Loop templates into a consuming app layout.',
         'Refuses to overwrite existing files unless --force is provided.',
@@ -103,9 +106,9 @@ function normalizeScenarioId(value) {
  * @param {{packageRoot: string, scenarioId: string, targetDir: string}} options
  * @returns {ScaffoldFile[]}
  */
-function buildScaffoldFiles({ packageRoot, scenarioId, targetDir, }) {
+function buildScaffoldFiles({ packageRoot, scenarioId, targetDir, withAgentSkill = false, }) {
     const templatesRoot = path.join(packageRoot, 'templates');
-    return [
+    const files = [
         {
             source: path.join(templatesRoot, TEMPLATE_FILES.config),
             destination: path.join(targetDir, 'asl.config.json'),
@@ -153,6 +156,19 @@ function buildScaffoldFiles({ packageRoot, scenarioId, targetDir, }) {
             destination: path.join(targetDir, 'src', 'devtools', 'profile-session.ts'),
         },
     ];
+    if (withAgentSkill) {
+        files.push({
+            source: path.join(templatesRoot, TEMPLATE_FILES.agentSkillReadme),
+            destination: path.join(targetDir, '.agents', 'skills', 'agent-scenario-loop', 'SKILL.md'),
+        }, {
+            source: path.join(templatesRoot, TEMPLATE_FILES.agentSkillArtifactInterpretation),
+            destination: path.join(targetDir, '.agents', 'skills', 'agent-scenario-loop', 'references', 'artifact-interpretation.md'),
+        }, {
+            source: path.join(templatesRoot, TEMPLATE_FILES.agentSkillAdoptionChecklist),
+            destination: path.join(targetDir, '.agents', 'skills', 'agent-scenario-loop', 'references', 'adoption-checklist.md'),
+        });
+    }
+    return files;
 }
 /**
  * Copies one scaffold template unless it already exists and overwrite is disabled.
@@ -194,7 +210,12 @@ async function initProject(options = {}) {
     const packageRoot = options.packageRoot ?? defaultPackageRoot();
     const targetDir = path.resolve(options.outDir ?? process.cwd());
     const scenarioId = normalizeScenarioId(options.scenarioId);
-    const files = buildScaffoldFiles({ packageRoot, scenarioId, targetDir });
+    const files = buildScaffoldFiles({
+        packageRoot,
+        scenarioId,
+        targetDir,
+        withAgentSkill: Boolean(options.withAgentSkill),
+    });
     const created = [];
     const skipped = [];
     for (const file of files) {
@@ -252,6 +273,7 @@ async function main() {
         force: isEnabled(args.force),
         ...(typeof args.out === 'string' ? { outDir: args.out } : {}),
         ...(typeof args.scenario === 'string' ? { scenarioId: args.scenario } : {}),
+        withAgentSkill: isEnabled(args['with-agent-skill']),
     });
     process.stdout.write(`${formatResult(result)}\n`);
 }

package/docs/api.md

@@ -74,7 +74,7 @@ The package intentionally ships schemas and examples:
 - `agent-scenario-loop/examples/*`
 - `agent-scenario-loop/templates/*`
 
-These are public fixtures and contract references. Templates are safe starting points to copy into a consuming app and adapt.
+These are public fixtures and contract references. Templates are safe starting points to copy into a consuming app and adapt. The optional `templates/skills/agent-scenario-loop/` folder teaches Codex when and how to operate ASL from a repository-scoped skill without making the skill part of ASL runtime truth.
 
 For concrete runner and evidence-provider integration steps, see [Adapter Onboarding](adapters.md).
 

package/docs/authoring.md

@@ -51,6 +51,8 @@ You can also copy these files manually and rename them as needed:
 | `templates/scripts/asl-capture-profiler-provider.mjs` | Runnable starter provider command for deterministic profiler, memory, and network evidence |
 | `templates/integration-readme.md` | Consumer-app wiring guide generated into `asl/README.md` |
 | `templates/package-scripts.json` | Package-script snippets generated into `asl/package-scripts.json`; project validation also checks that required scripts exist in app `package.json` and direct installed-bin scripts have not drifted |
+| `templates/skills/agent-scenario-loop/SKILL.md` | Optional repository-scoped Codex skill generated into `.agents/skills/agent-scenario-loop/SKILL.md` by `asl-init --with-agent-skill` |
+| `templates/skills/agent-scenario-loop/references/*.md` | Optional skill references for artifact interpretation and adoption checks |
 
 The JSON templates are schema-checked, and every shipped template is checked by package smoke. They intentionally use neutral placeholder names.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-scenario-loop",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
   "description": "Scenario orchestration and evidence collection for agent-driven software development. Bring your own runner. Keep your scenarios. Keep your evidence.",
   "license": "MIT",
@@ -55,95 +55,141 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "require": "./dist/index.js"
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
     },
     "./runner/android-adb": {
       "types": "./dist/runner/android-adb.d.ts",
-      "require": "./dist/runner/android-adb.js"
+      "import": "./dist/runner/android-adb.js",
+      "require": "./dist/runner/android-adb.js",
+      "default": "./dist/runner/android-adb.js"
     },
     "./runner/android-adb-driver": {
       "types": "./dist/runner/android-adb-driver.d.ts",
-      "require": "./dist/runner/android-adb-driver.js"
+      "import": "./dist/runner/android-adb-driver.js",
+      "require": "./dist/runner/android-adb-driver.js",
+      "default": "./dist/runner/android-adb-driver.js"
     },
     "./runner/agent-device-driver": {
       "types": "./dist/runner/agent-device-driver.d.ts",
-      "require": "./dist/runner/agent-device-driver.js"
+      "import": "./dist/runner/agent-device-driver.js",
+      "require": "./dist/runner/agent-device-driver.js",
+      "default": "./dist/runner/agent-device-driver.js"
     },
     "./runner/argent-driver": {
       "types": "./dist/runner/argent-driver.d.ts",
-      "require": "./dist/runner/argent-driver.js"
+      "import": "./dist/runner/argent-driver.js",
+      "require": "./dist/runner/argent-driver.js",
+      "default": "./dist/runner/argent-driver.js"
     },
     "./runner/agent-device": {
       "types": "./dist/runner/agent-device.d.ts",
-      "require": "./dist/runner/agent-device.js"
+      "import": "./dist/runner/agent-device.js",
+      "require": "./dist/runner/agent-device.js",
+      "default": "./dist/runner/agent-device.js"
     },
     "./runner/argent": {
       "types": "./dist/runner/argent.d.ts",
-      "require": "./dist/runner/argent.js"
+      "import": "./dist/runner/argent.js",
+      "require": "./dist/runner/argent.js",
+      "default": "./dist/runner/argent.js"
     },
     "./runner/check-plan": {
       "types": "./dist/runner/check-plan.d.ts",
-      "require": "./dist/runner/check-plan.js"
+      "import": "./dist/runner/check-plan.js",
+      "require": "./dist/runner/check-plan.js",
+      "default": "./dist/runner/check-plan.js"
     },
     "./runner/compare": {
       "types": "./dist/runner/compare.d.ts",
-      "require": "./dist/runner/compare.js"
+      "import": "./dist/runner/compare.js",
+      "require": "./dist/runner/compare.js",
+      "default": "./dist/runner/compare.js"
     },
     "./runner/compare-latest": {
       "types": "./dist/runner/compare-latest.d.ts",
-      "require": "./dist/runner/compare-latest.js"
+      "import": "./dist/runner/compare-latest.js",
+      "require": "./dist/runner/compare-latest.js",
+      "default": "./dist/runner/compare-latest.js"
     },
     "./runner/demo-loop": {
       "types": "./dist/runner/demo-loop.d.ts",
-      "require": "./dist/runner/demo-loop.js"
+      "import": "./dist/runner/demo-loop.js",
+      "require": "./dist/runner/demo-loop.js",
+      "default": "./dist/runner/demo-loop.js"
     },
     "./runner/example-android-live": {
       "types": "./dist/runner/example-android-live.d.ts",
-      "require": "./dist/runner/example-android-live.js"
+      "import": "./dist/runner/example-android-live.js",
+      "require": "./dist/runner/example-android-live.js",
+      "default": "./dist/runner/example-android-live.js"
     },
     "./runner/example-ios-live": {
       "types": "./dist/runner/example-ios-live.d.ts",
-      "require": "./dist/runner/example-ios-live.js"
+      "import": "./dist/runner/example-ios-live.js",
+      "require": "./dist/runner/example-ios-live.js",
+      "default": "./dist/runner/example-ios-live.js"
     },
     "./runner/host-doctor": {
       "types": "./dist/runner/host-doctor.d.ts",
-      "require": "./dist/runner/host-doctor.js"
+      "import": "./dist/runner/host-doctor.js",
+      "require": "./dist/runner/host-doctor.js",
+      "default": "./dist/runner/host-doctor.js"
     },
     "./runner/init-project": {
       "types": "./dist/runner/init-project.d.ts",
-      "require": "./dist/runner/init-project.js"
+      "import": "./dist/runner/init-project.js",
+      "require": "./dist/runner/init-project.js",
+      "default": "./dist/runner/init-project.js"
     },
     "./runner/ios-simctl": {
       "types": "./dist/runner/ios-simctl.d.ts",
-      "require": "./dist/runner/ios-simctl.js"
+      "import": "./dist/runner/ios-simctl.js",
+      "require": "./dist/runner/ios-simctl.js",
+      "default": "./dist/runner/ios-simctl.js"
     },
     "./runner/ios-simctl-driver": {
       "types": "./dist/runner/ios-simctl-driver.d.ts",
-      "require": "./dist/runner/ios-simctl-driver.js"
+      "import": "./dist/runner/ios-simctl-driver.js",
+      "require": "./dist/runner/ios-simctl-driver.js",
+      "default": "./dist/runner/ios-simctl-driver.js"
     },
     "./runner/live-android": {
       "types": "./dist/runner/live-android.d.ts",
-      "require": "./dist/runner/live-android.js"
+      "import": "./dist/runner/live-android.js",
+      "require": "./dist/runner/live-android.js",
+      "default": "./dist/runner/live-android.js"
     },
     "./runner/live-ios": {
       "types": "./dist/runner/live-ios.d.ts",
-      "require": "./dist/runner/live-ios.js"
+      "import": "./dist/runner/live-ios.js",
+      "require": "./dist/runner/live-ios.js",
+      "default": "./dist/runner/live-ios.js"
     },
     "./runner/live-proof": {
       "types": "./dist/runner/live-proof.d.ts",
-      "require": "./dist/runner/live-proof.js"
+      "import": "./dist/runner/live-proof.js",
+      "require": "./dist/runner/live-proof.js",
+      "default": "./dist/runner/live-proof.js"
     },
     "./runner/profile-ios": {
       "types": "./dist/runner/profile-ios.d.ts",
-      "require": "./dist/runner/profile-ios.js"
+      "import": "./dist/runner/profile-ios.js",
+      "require": "./dist/runner/profile-ios.js",
+      "default": "./dist/runner/profile-ios.js"
     },
     "./runner/profile-android": {
       "types": "./dist/runner/profile-android.d.ts",
-      "require": "./dist/runner/profile-android.js"
+      "import": "./dist/runner/profile-android.js",
+      "require": "./dist/runner/profile-android.js",
+      "default": "./dist/runner/profile-android.js"
     },
     "./runner/validate-project": {
       "types": "./dist/runner/validate-project.d.ts",
-      "require": "./dist/runner/validate-project.js"
+      "import": "./dist/runner/validate-project.js",
+      "require": "./dist/runner/validate-project.js",
+      "default": "./dist/runner/validate-project.js"
     },
     "./schemas/*": "./schemas/*",
     "./examples/*": "./examples/*",

package/templates/skills/agent-scenario-loop/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: agent-scenario-loop
+description: Use Agent Scenario Loop when implementing, debugging, optimizing, or validating mobile app behavior through durable scenarios, Android or iOS live proofs, evidence artifacts, health checks, budgets, or before-and-after comparisons. Do not use for ordinary unit-test-only changes or work unrelated to observable app behavior.
+---
+
+# Agent Scenario Loop
+
+Use ASL to establish trustworthy evidence about changes to this mobile app.
+
+## Discover The Project Contract
+
+1. Inspect `package.json` for installed ASL commands and project-owned `asl:*` scripts.
+2. Locate `asl.config.json` or the configured alternative.
+3. Inspect scenario manifests and runner manifests.
+4. Identify the scenario representing the app behavior affected by the task.
+5. Reuse an existing scenario when it expresses the intended behavior.
+
+Do not copy runner infrastructure into the application.
+
+## Validate Before Execution
+
+Run the project validation command configured by the repository. Then validate the selected scenario and execution plan.
+
+Stop before live execution when required capabilities are unavailable. Report the missing capability, selected platform, runner, and the command needed to reproduce the failure.
+
+## Select The Proof Lane
+
+Use fixture proof when validating:
+
+- package installation;
+- scenario parsing;
+- artifact contracts;
+- comparison behavior;
+- agent summaries.
+
+Use Android or iOS live proof when making claims about actual app behavior. Use both platforms when the task or release gate requires cross-platform evidence.
+
+## Interpret Results
+
+Read evidence in this order:
+
+1. `health.json`
+2. `verdict.json`
+3. `comparison.json`, when present
+4. `agent-summary.md`
+5. supporting raw evidence and captures when diagnosis is needed
+
+If health is not passed:
+
+- do not trust dependent timing or budget conclusions;
+- classify the failure as execution, environment, instrumentation, lifecycle, or evidence capture;
+- fix or report the evidence problem before claiming a product regression.
+
+If health passed but verdict failed:
+
+- treat the run as trustworthy evidence of product failure;
+- diagnose the failed budget, event, milestone, or expectation.
+
+Only interpret a comparison when ASL considers the baseline compatible.
+
+## Non-Negotiable Rules
+
+- Run planner validation before expensive device work.
+- Prefer an existing durable scenario over inventing an ad hoc script.
+- Never infer product improvement from unhealthy or partial evidence.
+- Treat passed health plus failed verdict as trustworthy evidence of failure.
+- Do not silently retry and discard failed attempts.
+- Do not change budgets or scenarios merely to turn a failure green.
+- Keep selectors, app identifiers, authentication assumptions, routes, and truth events inside the consuming app.
+- Preserve the artifact directory and cite exact artifact paths in the final report.
+- Use fixture proof for package and contract validation; use live proof for product claims.
+- Avoid adding new runners when an existing capability already satisfies the plan.
+
+## Report
+
+Include:
+
+- scenario ID;
+- platform;
+- run ID;
+- health status;
+- product verdict;
+- comparison status;
+- failed evidence dependencies;
+- relevant artifact paths;
+- recommended next action.
+
+Do not summarize a run as simply "passed" or "failed" when health and verdict differ.
+
+## References
+
+- `references/artifact-interpretation.md`
+- `references/adoption-checklist.md`

package/templates/skills/agent-scenario-loop/references/adoption-checklist.md

@@ -0,0 +1,17 @@
+# Adoption Checklist
+
+Use this checklist when bringing ASL into a consuming app or validating an existing adoption.
+
+1. Confirm `agent-scenario-loop` is installed from the registry, not a local tarball or link.
+2. Inspect `package.json` for project-owned `asl:*` scripts.
+3. Locate `asl.config.json` and verify app identifiers, artifact roots, and supported drivers are project-owned.
+4. Inspect scenario manifests under the configured scenario root.
+5. Inspect runner and evidence-provider manifests.
+6. Run the project validation script.
+7. Run the selected scenario's plan check before live device work.
+8. Use fixture/profile proof for package, parsing, and artifact-contract validation.
+9. Use Android or iOS live proof for product behavior claims.
+10. Use both platforms when a release or task requires cross-platform evidence.
+11. Preserve generated artifacts; do not delete failed attempts to make a later run look cleaner.
+12. Cite `health.json`, `verdict.json`, `comparison.json` when present, and `agent-summary.md` in the final report.
+13. Keep selectors, app identifiers, credentials, routes, and truth events in the consuming app, not ASL core.

package/templates/skills/agent-scenario-loop/references/artifact-interpretation.md

@@ -0,0 +1,26 @@
+# Artifact Interpretation
+
+ASL separates evidence health, product verdict, and comparison status. Keep those meanings distinct.
+
+## Read Order
+
+1. `health.json`: whether the evidence-producing run completed with enough trustworthy data to interpret downstream artifacts.
+2. `verdict.json`: whether the product behavior satisfied the scenario's expectations, budgets, milestones, and required events.
+3. `comparison.json`: whether a compatible baseline/current pair improved, regressed, stayed unchanged, or remained inconclusive.
+4. `agent-summary.md`: compressed outcome for humans and agents after the structured artifacts are understood.
+
+## Health
+
+When health is not passed, do not claim product improvement or regression from dependent timing, budget, or comparison artifacts. Classify the issue as execution, environment, instrumentation, lifecycle, or evidence capture.
+
+## Verdict
+
+Passed health plus failed verdict is trustworthy evidence of a product failure. Diagnose the failed event, milestone, budget, or expectation instead of treating the run as untrusted.
+
+## Comparison
+
+Only interpret comparison output when ASL selected or accepted a compatible baseline. If no trusted compatible prior exists, keep the current run as evidence and avoid before/after claims.
+
+## Reporting
+
+Reports must cite exact artifact paths and distinguish health status, product verdict, and comparison status.