studioflow 0.1.0

package/flows/billing.yaml

@@ -0,0 +1,21 @@
+id: billing
+description: Open billing page and pick a plan
+tags:
+  - billing
+estimated_duration_sec: 20
+steps:
+  - id: goto-billing
+    action: goto
+    value: /billing
+  - id: assert-billing-title
+    action: assert_visible
+    target: '[data-testid="billing-title"]'
+  - id: choose-plan
+    action: click
+    target: '[data-testid="plan-pro"]'
+  - id: assert-success
+    action: assert_visible
+    target: '[data-testid="success-title"]'
+  - id: assert-plan
+    action: assert_text
+    value: "Selected plan: pro"

package/flows/onboarding.yaml

@@ -0,0 +1,26 @@
+id: onboarding
+description: Complete onboarding form and continue to billing
+tags:
+  - onboarding
+  - setup
+estimated_duration_sec: 25
+steps:
+  - id: goto-home
+    action: goto
+    value: /
+  - id: click-onboarding
+    action: click
+    target: '[data-testid="go-onboarding"]'
+  - id: assert-onboarding
+    action: assert_visible
+    target: '[data-testid="onboarding-title"]'
+  - id: fill-company
+    action: type
+    target: '[data-testid="company-name-input"]'
+    value: Acme Inc
+  - id: continue
+    action: click
+    target: '[data-testid="complete-onboarding"]'
+  - id: assert-billing
+    action: assert_visible
+    target: '[data-testid="billing-title"]'

package/flows/onboarding_billing.yaml

@@ -0,0 +1,30 @@
+id: onboarding_billing
+description: Run onboarding and billing as a single showcase flow
+tags:
+  - onboarding
+  - billing
+  - full-demo
+estimated_duration_sec: 45
+steps:
+  - id: goto-home
+    action: goto
+    value: /
+  - id: click-onboarding
+    action: click
+    target: '[data-testid="go-onboarding"]'
+  - id: fill-company
+    action: type
+    target: '[data-testid="company-name-input"]'
+    value: Acme Incorporated
+  - id: continue
+    action: click
+    target: '[data-testid="complete-onboarding"]'
+  - id: choose-plan
+    action: click
+    target: '[data-testid="plan-pro"]'
+  - id: assert-success
+    action: assert_visible
+    target: '[data-testid="success-title"]'
+  - id: screenshot-success
+    action: screenshot
+    value: success-screen

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "studioflow",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Deterministic AI-assisted product demo automation CLI for Screen Studio workflows",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "os": [
+    "darwin"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "flows",
+    "scripts/sync-skills.mjs",
+    "scripts/build.mjs",
+    "tsconfig.json",
+    "package.json"
+  ],
+  "bin": {
+    "studioflow": "dist/index.js"
+  },
+  "scripts": {
+    "prepare:assets": "node scripts/sync-skills.mjs",
+    "build": "node scripts/build.mjs",
+    "prepack": "node scripts/sync-skills.mjs && node scripts/build.mjs",
+    "demo": "tsx src/index.ts run",
+    "config": "tsx src/index.ts config",
+    "setup": "tsx src/index.ts setup",
+    "install-skills": "tsx src/index.ts install-skills",
+    "discover": "tsx src/index.ts discover",
+    "bootstrap": "tsx src/index.ts bootstrap",
+    "screenstudio-prep": "tsx src/index.ts screenstudio-prep",
+    "validate": "tsx src/index.ts validate",
+    "doctor": "tsx src/index.ts doctor",
+    "list-flows": "tsx src/index.ts list-flows"
+  },
+  "dependencies": {
+    "playwright": "^1.55.0"
+  },
+  "devDependencies": {
+    "@studioflow/adapters-desktop": "workspace:*",
+    "@studioflow/adapters-playwright": "workspace:*",
+    "@studioflow/adapters-screenstudio": "workspace:*",
+    "@studioflow/artifacts": "workspace:*",
+    "@studioflow/contracts": "workspace:*",
+    "@studioflow/flow-registry": "workspace:*",
+    "@studioflow/orchestrator": "workspace:*",
+    "esbuild": "^0.25.11",
+    "kleur": "^4.1.5",
+    "tsx": "^4.20.5"
+  }
+}

package/scripts/build.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { build } from "esbuild";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(__dirname, "..");
+
+await build({
+  entryPoints: [path.join(packageRoot, "src/index.ts")],
+  outfile: path.join(packageRoot, "dist/index.js"),
+  bundle: true,
+  format: "esm",
+  platform: "node",
+  target: "node22",
+  sourcemap: true,
+  external: ["playwright", "playwright/*"],
+  alias: {
+    "@studioflow/contracts": path.join(packageRoot, "../../packages/contracts/src/index.ts"),
+    "@studioflow/flow-registry": path.join(packageRoot, "../../packages/flow-registry/src/index.ts"),
+    "@studioflow/orchestrator": path.join(packageRoot, "../../packages/orchestrator/src/index.ts"),
+    "@studioflow/artifacts": path.join(packageRoot, "../../packages/artifacts/src/index.ts"),
+    "@studioflow/adapters-desktop": path.join(packageRoot, "../../packages/adapters-desktop/src/index.ts"),
+    "@studioflow/adapters-playwright": path.join(packageRoot, "../../packages/adapters-playwright/src/index.ts"),
+    "@studioflow/adapters-screenstudio": path.join(packageRoot, "../../packages/adapters-screenstudio/src/index.ts")
+  },
+  banner: {
+    js: "#!/usr/bin/env node"
+  }
+});

package/scripts/sync-skills.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(__dirname, "..");
+const sourceSkillsRoot = path.resolve(packageRoot, "../../skills");
+const targetSkillsRoot = path.join(packageRoot, "skills");
+const sourceFlowsRoot = path.resolve(packageRoot, "../../packages/flow-registry/flows");
+const targetFlowsRoot = path.join(packageRoot, "flows");
+const skillNames = ["studioflow-cli", "studioflow-investigate"];
+const flowNames = ["billing.yaml", "onboarding.yaml", "onboarding_billing.yaml"];
+
+async function ensureSkillExists(skillName) {
+  const skillPath = path.join(sourceSkillsRoot, skillName, "SKILL.md");
+  await fs.access(skillPath);
+}
+
+async function ensureFlowExists(flowName) {
+  const flowPath = path.join(sourceFlowsRoot, flowName);
+  await fs.access(flowPath);
+}
+
+async function main() {
+  await Promise.all(skillNames.map(ensureSkillExists));
+  await Promise.all(flowNames.map(ensureFlowExists));
+
+  await fs.rm(targetSkillsRoot, { recursive: true, force: true });
+  await fs.mkdir(targetSkillsRoot, { recursive: true });
+
+  for (const skillName of skillNames) {
+    const source = path.join(sourceSkillsRoot, skillName);
+    const target = path.join(targetSkillsRoot, skillName);
+    await fs.cp(source, target, { recursive: true });
+  }
+
+  await fs.rm(targetFlowsRoot, { recursive: true, force: true });
+  await fs.mkdir(targetFlowsRoot, { recursive: true });
+
+  for (const flowName of flowNames) {
+    const source = path.join(sourceFlowsRoot, flowName);
+    const target = path.join(targetFlowsRoot, flowName);
+    await fs.cp(source, target);
+  }
+
+  console.log(`Bundled assets synced: skills -> ${targetSkillsRoot}, flows -> ${targetFlowsRoot}`);
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/skills/studioflow-cli/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: studioflow-cli
+description: Execute validated demo artifacts with StudioFlow CLI. Use when the user wants to run a generated flow.json, validate flow artifacts, trigger recording, inspect run artifacts, or troubleshoot deterministic run failures.
+---
+
+# StudioFlow CLI
+
+Run validated artifacts through deterministic execution.
+
+## Workflow
+
+0. Resolve handoff input (if present):
+- `artifacts/studioflow-cli-handoff.json`
+
+If handoff exists, use it as the source of truth for `flowPath`, `intentSummary`, `baseUrl`, `startCommand`, and `healthPath`.
+
+1. Confirm artifact presence:
+- `artifacts/flow.json`
+- `artifacts/bootstrap.json` (recommended)
+- optional `artifacts/structure-report.json`
+- optional `artifacts/navigation-graph.json`
+- optional `artifacts/studioflow-cli-handoff.json`
+
+2. Run doctor checks:
+
+```bash
+pnpm setup
+pnpm run doctor
+```
+
+If run preflight fails, collect explicit Screen Studio diagnostics:
+
+```bash
+pnpm screenstudio-prep
+```
+
+3. Validate flow artifact:
+
+```bash
+pnpm validate -- --flow artifacts/flow.json
+```
+
+4. Execute recording run from artifact:
+
+```bash
+pnpm demo -- --flow <flowPath> --intent "<intent-summary>" --base-url <baseUrl> --start-command "<startCommand>" --health-path <healthPath>
+```
+
+5. Inspect outputs:
+- `.runs/<run-id>/run.json`
+- `.runs/<run-id>/events.jsonl`
+- `.runs/<run-id>/screenshots/*`
+
+6. If run fails, inspect error step in `events.jsonl`, patch flow selectors/pacing, and rerun from step 3.
+
+## Execution Behavior (Required)
+
+1. If the skill is invoked for execution, run the commands directly; do not stop at command suggestions.
+2. Do not ask the user "how to run the CLI" after handoff has already supplied run parameters.
+3. Only ask follow-up questions when required run anchors are missing (`flowPath`, `baseUrl`, or `startCommand`/healthy app).
+
+## Runtime Rules
+
+1. Use artifact execution (`--flow`) only.
+2. Keep execution deterministic; do not modify codebase during run unless explicitly requested.
+3. Report exact artifact paths and failing step IDs for every failure.
+
+Use references in:
+- `references/troubleshooting.md`
+- `references/handoff-spec.md`

package/skills/studioflow-cli/references/handoff-spec.md

@@ -0,0 +1,38 @@
+# Handoff Input Spec
+
+`studioflow-cli` accepts a runtime handoff file from `studioflow-investigate`:
+
+- `artifacts/studioflow-cli-handoff.json`
+
+## Expected payload
+
+```json
+{
+  "version": 1,
+  "intentSummary": "Record only onboarding + CRM in Demo Lab",
+  "flowPath": "artifacts/flow.json",
+  "baseUrl": "http://localhost:4280",
+  "startCommand": "pnpm dev:demo-lab",
+  "healthPath": "/",
+  "notes": []
+}
+```
+
+## Required keys
+
+- `version`
+- `intentSummary`
+- `flowPath`
+- `baseUrl`
+- `healthPath`
+
+`startCommand` is recommended. If omitted, runtime can still proceed when app is already healthy.
+
+## Execution mapping
+
+From payload, execute:
+
+1. `pnpm validate -- --flow <flowPath>`
+2. `pnpm demo -- --flow <flowPath> --intent "<intentSummary>" --base-url <baseUrl> --start-command "<startCommand>" --health-path <healthPath>`
+
+If payload is missing, fall back to explicit user arguments or repo defaults.

package/skills/studioflow-cli/references/troubleshooting.md

@@ -0,0 +1,16 @@
+# Troubleshooting
+
+## Permission failures
+- Error: osascript not allowed to send keystrokes
+- Action: approve Terminal/iTerm in macOS Privacy & Security > Accessibility and Automation
+
+## Selector failures
+- Error: step action missing target or locator timeout
+- Action: patch `artifacts/flow.json` selector and rerun `pnpm validate`
+
+## Browser executable failures
+- Error: Playwright Chromium not installed
+- Action: `studioflow setup` (or `pnpm setup` in this repo)
+
+## Artifact path checks
+- Run artifacts under `.runs/<run-id>/`

package/skills/studioflow-investigate/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: studioflow-investigate
+description: Investigate an arbitrary web project and generate deterministic StudioFlow artifacts. Use when the user asks to discover app structure, map routes/components/actions, synthesize artifacts/flow.json from natural-language intent, or clarify open/ambiguous intent before authoring a flow.
+---
+
+# StudioFlow Investigate
+
+Generate deterministic demo-planning artifacts for any web app.
+
+## Workflow
+
+1. Inspect project root and identify framework, package manager, and startup command.
+2. Always collect project context artifacts before intent mapping.
+
+Do this automatically in the skill workflow. Do not ask the user to run these commands manually.
+
+```bash
+pnpm bootstrap -- --out artifacts/bootstrap.json
+pnpm discover -- --out artifacts
+```
+
+Fallback if `pnpm` workspace scripts are unavailable:
+
+```bash
+studioflow bootstrap --out artifacts/bootstrap.json
+studioflow discover --out artifacts
+```
+
+3. Review generated artifacts:
+- `artifacts/bootstrap.json`
+- `artifacts/structure-report.json`
+- `artifacts/navigation-graph.json`
+
+4. Resolve intent specificity before authoring `artifacts/flow.json`.
+
+Open-intent detection:
+- Treat intent as open when one or more anchors are missing:
+  - `target_route`: where the flow should navigate
+  - `user_goal`: what user action/outcome to demonstrate
+  - `done_assertion`: what text/element proves completion
+
+Clarification loop:
+- Max 2 rounds.
+- Ask 1-3 questions per round (adaptive; only missing high-impact fields).
+- Question priority: `done_assertion` -> `target_route` -> `user_goal` -> optional inputs/scope.
+- If host supports structured question-card requests, emit payloads from `references/question-card-spec.md`.
+- If structured cards are not supported, ask equivalent plain-language questions.
+- Track known/missing fields using `references/clarification-state.md`.
+
+5. Author `artifacts/flow.json` from intent + discovered structure + clarified answers.
+
+Rules for authored flow:
+- Deterministic steps only.
+- Prefer stable selectors (`data-testid`).
+- Include clear step IDs and assertions at key transitions.
+- Include optional pacing fields when useful for recording quality.
+- If clarification remains incomplete after 2 rounds, generate best-effort flow with explicit assumptions.
+
+6. Validate candidate flow:
+
+```bash
+pnpm validate -- --flow artifacts/flow.json
+```
+
+7. If validation fails, edit flow actions/selectors and rerun validation.
+
+8. Emit deterministic runtime handoff for `studioflow-cli`.
+
+Write `artifacts/studioflow-cli-handoff.json` using `references/cli-handoff-spec.md`.
+
+9. Hand off execution to `studioflow-cli` immediately.
+
+- If your host supports explicit skill invocation, invoke `studioflow-cli` in the same turn using the handoff payload.
+- If explicit skill invocation is unavailable, execute the equivalent CLI run workflow directly in the same turn.
+- Do not stop at "here is the command to run" when the user intent is to run/record a demo.
+
+## Output Requirements
+
+Always produce these files for handoff to runtime execution:
+1. `artifacts/bootstrap.json`
+2. `artifacts/structure-report.json`
+3. `artifacts/navigation-graph.json`
+4. `artifacts/flow.json`
+5. `artifacts/studioflow-cli-handoff.json`
+
+Always include a concise handoff summary in the response:
+- resolved intent anchors
+- unresolved assumptions (if any)
+- confidence (`high|medium|low`)
+
+Use references in:
+- `references/artifact-spec.md`
+- `references/question-card-spec.md`
+- `references/clarification-state.md`
+- `references/cli-handoff-spec.md`

package/skills/studioflow-investigate/references/artifact-spec.md

@@ -0,0 +1,37 @@
+# Artifact Spec
+
+## structure-report.json
+- generatedAt
+- projectRoot
+- packageManager
+- frameworkHints[]
+- startCommands[]
+- routes[]
+- components[]
+- existingFlowIds[]
+- notes[]
+
+## navigation-graph.json
+- generatedAt
+- nodes[] with id/route/file
+- edges[] with from/to/via/confidence
+
+## flow.json
+Use StudioFlow FlowDefinition schema:
+- id
+- description
+- tags[]
+- preconditions[] optional
+- steps[]
+
+Flow steps may include pacing fields:
+- preDelayMs
+- postDelayMs
+- mouseMoveMs
+- highlightMs
+- dwellMs
+- narrativeCheckpoint
+
+## Open-intent fallback note
+
+When the user intent remains open after clarification rounds, the assistant should still generate deterministic `flow.json` and include assumptions + confidence in the response handoff.

package/skills/studioflow-investigate/references/clarification-state.md

@@ -0,0 +1,42 @@
+# Clarification State Template
+
+Use this lightweight state model while resolving open intent.
+
+```yaml
+roundsUsed: 0
+maxRounds: 2
+known:
+  target_route: null
+  user_goal: null
+  done_assertion: null
+  data_input: []
+  scope_limit: null
+missing:
+  - target_route
+  - user_goal
+  - done_assertion
+assumptions: []
+confidence: low
+risks: []
+```
+
+## Update rules
+
+1. After each user reply, update `known` and recalculate `missing`.
+2. Stop asking follow-ups when required anchors are all known:
+   - `target_route`
+   - `user_goal`
+   - `done_assertion`
+3. Do not exceed 2 rounds.
+4. If anchors are still missing after round 2:
+   - add explicit `assumptions`
+   - keep `confidence: low`
+   - generate best-effort deterministic `flow.json`
+
+## Handoff summary format
+
+Include in final response:
+
+- `Resolved`: key anchors and selected values
+- `Assumptions`: any inferred defaults
+- `Confidence`: `high|medium|low`

package/skills/studioflow-investigate/references/cli-handoff-spec.md

@@ -0,0 +1,42 @@
+# CLI Handoff Spec
+
+Use this artifact to hand execution from `studioflow-investigate` to `studioflow-cli`.
+
+Path:
+
+- `artifacts/studioflow-cli-handoff.json`
+
+## JSON shape
+
+```json
+{
+  "version": 1,
+  "intentSummary": "Record only onboarding + CRM in Demo Lab",
+  "flowPath": "artifacts/flow.json",
+  "baseUrl": "http://localhost:4280",
+  "startCommand": "pnpm dev:demo-lab",
+  "healthPath": "/",
+  "notes": [
+    "Use deterministic artifact execution only."
+  ]
+}
+```
+
+## Field rules
+
+- `version`: integer, currently `1`.
+- `intentSummary`: concise run label for CLI `--intent`.
+- `flowPath`: deterministic artifact path. Default: `artifacts/flow.json`.
+- `baseUrl`: runtime host URL.
+- `startCommand`: command used when app is not already healthy.
+- `healthPath`: health probe path used by runtime.
+- `notes`: optional operator notes.
+
+## Invocation contract
+
+When handoff artifact is written, immediately invoke `studioflow-cli` (or equivalent runtime workflow in same agent) to execute:
+
+1. `pnpm validate -- --flow <flowPath>`
+2. `pnpm demo -- --flow <flowPath> --intent "<intentSummary>" --base-url <baseUrl> --start-command "<startCommand>" --health-path <healthPath>`
+
+Do not ask the user to translate the handoff into commands.

package/skills/studioflow-investigate/references/question-card-spec.md

@@ -0,0 +1,44 @@
+# Question Card Spec
+
+Use this when intent is open and the host supports structured question-card UI.
+
+If structured cards are unavailable, ask equivalent plain-language questions.
+
+## Payload shape
+
+```json
+{
+  "cardId": "target-route",
+  "reason": "Need primary destination to map deterministic steps.",
+  "question": "Which route should the demo focus on first?",
+  "required": true,
+  "options": [
+    { "label": "Onboarding", "value": "/onboarding" },
+    { "label": "Billing", "value": "/billing" },
+    { "label": "Home", "value": "/" }
+  ],
+  "freeformAllowed": true,
+  "mapsTo": "target_route"
+}
+```
+
+## Fields
+
+- `cardId`: stable identifier for this question.
+- `reason`: single-sentence rationale.
+- `question`: user-facing prompt.
+- `required`: whether this question is mandatory for mapping.
+- `options`: 2-4 suggested choices from discovered app routes/actions when possible.
+- `freeformAllowed`: allow custom response if choices do not fit.
+- `mapsTo`: one of:
+  - `target_route`
+  - `user_goal`
+  - `done_assertion`
+  - `data_input`
+  - `scope_limit`
+
+## Round constraints
+
+- Max 2 rounds total.
+- Ask 1-3 cards/questions per round.
+- Ask only missing high-impact fields.

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts"]
+}