studioflow 0.1.5 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StudioFlow contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,16 +1,18 @@
 # StudioFlow
 
-StudioFlow turns a plain-language demo request into a deterministic recorded run.
+StudioFlow turns a plain-language demo request into a deterministic recorded product run.
 
 This package includes:
 - a CLI runtime (`studioflow`) for deterministic artifact execution
-- bundled agent skills for Codex and Claude (`studioflow-investigate`, `studioflow-cli`)
+- bundled agent skills for Codex and Claude (`studioflow-investigate`, `studioflow-author`, `studioflow-cli`)
+
+StudioFlow supports both QuickTime Player and Screen Studio recording backends.
 
 ## Requirements
 
-- macOS (Screen Studio automation)
-- Screen Studio installed
+- macOS (recorder automation is macOS-only)
 - Node.js 22+
+- QuickTime Player (built into macOS) or Screen Studio
 
 ## Install
 
@@ -18,69 +20,123 @@ This package includes:
 npm install -g studioflow
 ```
 
-## Setup Runtime + Skills
+## Quickstart (2 Minutes)
 
-`setup` installs Playwright Chromium, installs bundled skills for Codex and Claude, and checks permissions.
+1. Setup runtime dependencies and bundled skills:
 
 ```bash
 studioflow setup
+studioflow doctor
+studioflow config check
 ```
 
-## Default Workflow (Agent-First)
-
-You should not need to manually invoke multiple skills or manually run CLI commands for a normal demo request.
-Open Codex or Claude in your project and describe the demo you want.
-
-1. Start your agent from the project root.
-
-Codex:
+2. Open Codex or Claude from your project root:
 
 ```bash
 cd /path/to/your/project
 codex
+# or
+claude
 ```
 
-Claude Code:
+3. Ask in plain language:
 
-```bash
-cd /path/to/your/project
-claude
+```text
+Record a demo for onboarding and billing.
 ```
 
-If your launcher command differs, start your usual Codex or Claude session in this repo root.
+or
 
-2. Ask for the demo in plain language.
+```text
+Record a demo for onboarding and billing using Screen Studio.
+```
 
-Example:
+4. Expected successful run output includes:
 
 ```text
-Record a demo for onboarding and billing.
+Run completed successfully.
+Run ID: <timestamp-id>
+Artifacts: <path-to-run-dir>
 ```
 
-3. StudioFlow skills + CLI handle the rest:
-- investigate the codebase
-- generate deterministic artifacts (`artifacts/flow.json`, related context artifacts)
-- validate the flow
-- execute recording through the CLI runtime
+## Recorder Backends
+
+- `quicktime` (default): no extra app install required.
+- `screenstudio`: just specify Screen Studio in your agent request.
+
+Manual CLI mode still supports `--recorder screenstudio` when you want direct runtime control.
+
+## What `setup` Changes
+
+`studioflow setup`:
+- installs Playwright Chromium runtime
+- installs StudioFlow skills into:
+  - Codex: `$CODEX_HOME/skills` or `~/.codex/skills`
+  - Claude: `$CLAUDE_HOME/skills` or `~/.claude/skills`
+- runs permission diagnostics
+- writes setup state under `~/.studioflow` (or `$STUDIOFLOW_DATA_DIR`)
+
+## Command Cheat Sheet
+
+| Task | Command |
+| --- | --- |
+| Setup runtime + skills | `studioflow setup` |
+| Check permissions | `studioflow doctor` |
+| Show effective config | `studioflow config show` |
+| Validate config health | `studioflow config check` |
+| Validate flow artifact | `studioflow validate --flow artifacts/flow.json` |
+| Run deterministic demo | `studioflow demo --flow artifacts/flow.json --intent "your demo intent"` |
+| List built-in flows | `studioflow list-flows` |
+| QuickTime diagnostics | `studioflow quicktime-prep` |
+| Screen Studio diagnostics | `studioflow screenstudio-prep` |
+
+## Minimal Manual Flow (Optional)
+
+If you want to run the CLI directly without agent authoring first, start with a minimal artifact:
+
+```json
+{
+  "id": "landing_capture",
+  "description": "Capture the landing page",
+  "tags": ["smoke"],
+  "steps": [
+    { "id": "open-home", "action": "goto", "value": "/" },
+    { "id": "capture-home", "action": "screenshot", "value": "home" }
+  ]
+}
+```
+
+Then run:
+
+```bash
+studioflow validate --flow artifacts/flow.json
+studioflow demo --flow artifacts/flow.json --intent "landing page smoke"
+```
 
-`run`/`demo` automatically performs Screen Studio preflight checks. Use manual prep only for troubleshooting.
-Headed runs auto-open a maximized browser window for cleaner recording composition.
-Runs do not auto-export by default; include `recorder_export` in flow steps only when export is explicitly needed.
+## Quick Troubleshooting
 
-## Advanced Manual Mode (Optional)
+- Permission failures:
+  - `studioflow doctor` and approve macOS prompts.
+- QuickTime preflight failures:
+  - `studioflow quicktime-prep`
+- Screen Studio preflight failures:
+  - `studioflow screenstudio-prep`
+- App health timeout:
+  - `studioflow config show` and verify `baseUrl`, `startCommand`, `healthPath`.
+- Flow validation failures:
+  - `studioflow validate --flow <path>`
 
-If you want to run the runtime yourself:
+## Uninstall / Cleanup
 
 ```bash
-studioflow validate --flow artifacts/flow.json
-studioflow demo --flow artifacts/flow.json --intent "onboarding and billing demo"
+npm uninstall -g studioflow
 ```
 
-## Documentation
+Optional local cleanup:
+- remove `~/.studioflow` (or `$STUDIOFLOW_DATA_DIR`)
+- remove installed skill folders under `~/.codex/skills` and `~/.claude/skills` if you no longer want them
+
+## Contact
 
-- Day 0 runbook: https://github.com/ydarar/studioflow/blob/main/docs/day0-runbook.md
-- CLI reference: https://github.com/ydarar/studioflow/blob/main/docs/cli-reference.md
-- Configuration: https://github.com/ydarar/studioflow/blob/main/docs/configuration.md
-- Smoke checklist: https://github.com/ydarar/studioflow/blob/main/docs/testing-manual-smoke.md
-- Open intent tests: https://github.com/ydarar/studioflow/blob/main/docs/studioflow-open-intent-tests.md
-- Full docs map: https://github.com/ydarar/studioflow/blob/main/docs/README.md
+- X: https://x.com/Ydarar_dev (@Ydarar_dev)
+- GitHub: https://github.com/ydarar/studioflow/issues

package/bundled/skills/manifest.json

@@ -0,0 +1,17 @@
+{
+  "schemaVersion": 1,
+  "packageName": "studioflow",
+  "packageVersion": "0.2.1",
+  "generatedAt": "2026-02-15T00:48:20.093Z",
+  "skills": {
+    "studioflow-cli": {
+      "hash": "ff59e41a56a6f1289c37e4d167d62eb00f80442fca08f571297444e45aa0e747"
+    },
+    "studioflow-investigate": {
+      "hash": "8e3034b43ea84834008900886e94a744f3bf22e7b05d2548c0123492f694f693"
+    },
+    "studioflow-author": {
+      "hash": "cd42e054957736b1d1d47e93839a5daf40bfe40cafda0c8d26380c0ac63d078d"
+    }
+  }
+}

package/bundled/skills/studioflow-author/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: studioflow-author
+description: Create or repair deterministic StudioFlow artifacts for a clarified demo intent. Use when `studioflow-investigate` routes to `patch-existing` or `create-new`, or when the user explicitly asks to generate/edit `artifacts/flow.json` and runtime handoff.
+---
+
+# StudioFlow Author
+
+Author and validate deterministic artifacts for runtime execution.
+
+## Workflow
+
+1. Consume clarified intent + routing context.
+
+Expected upstream context:
+- resolved anchors (`target_route`, `user_goal`, `done_assertion`)
+- recorder preference (`quicktime` or `screenstudio`)
+- route decision (`patch-existing` or `create-new`)
+
+2. Collect project context artifacts automatically. Do not ask the user to run these commands manually.
+
+```bash
+pnpm bootstrap -- --out artifacts/bootstrap.json
+pnpm discover -- --out artifacts
+```
+
+Fallback if workspace scripts are unavailable:
+
+```bash
+studioflow bootstrap --out artifacts/bootstrap.json
+studioflow discover --out artifacts
+```
+
+3. Review:
+- `artifacts/bootstrap.json`
+- `artifacts/structure-report.json`
+- `artifacts/navigation-graph.json`
+- existing `artifacts/flow.json` if present
+
+4. Author `artifacts/flow.json` for the clarified intent.
+
+Rules:
+- Deterministic steps only.
+- Prefer stable selectors (`data-testid`).
+- Include clear step IDs and assertions at key transitions.
+- Always synthesize pacing fields (`preDelayMs`, `postDelayMs`, `mouseMoveMs`, `highlightMs`, `dwellMs`) for interaction-heavy steps to keep demos human-looking.
+- Model scroll risk explicitly. For below-fold or overflow-container targets, add deterministic setup/wait steps before interaction.
+- Add `recorder_export` only when user explicitly asks for export at run completion.
+- If clarification context is still incomplete, generate best-effort deterministic flow with explicit assumptions.
+
+5. Validate the authored artifact:
+
+```bash
+pnpm validate -- --flow artifacts/flow.json
+```
+
+6. If validation fails, patch flow selectors/actions/pacing and rerun validation.
+
+7. Emit runtime handoff for `studioflow-cli`.
+
+Write:
+- `artifacts/studioflow-cli-handoff.json`
+
+Use `references/cli-handoff-spec.md`.
+Always include:
+- `runtimePacing`
+- `recorder`
+
+8. Handoff to `studioflow-cli` immediately when the user intent is to run/record now.
+
+## Output Requirements
+
+Always produce:
+1. `artifacts/bootstrap.json`
+2. `artifacts/structure-report.json`
+3. `artifacts/navigation-graph.json`
+4. `artifacts/flow.json`
+5. `artifacts/studioflow-cli-handoff.json`
+
+Include a concise authoring summary:
+- what changed (new vs patched)
+- assumptions
+- confidence (`high|medium|low`)
+
+Use references in:
+- `references/artifact-spec.md`
+- `references/cli-handoff-spec.md`

package/{skills/studioflow-investigate → bundled/skills/studioflow-author}/references/artifact-spec.md

@@ -32,10 +32,16 @@ Flow steps may include pacing fields:
 - dwellMs
 - narrativeCheckpoint
 
+Authoring intelligence rules:
+- Prefer setting pacing fields for click/type/assert transition steps by default, not only on outliers.
+- Anticipate scroll-sensitive interactions (below fold, nested overflow containers) and add deterministic setup steps (`wait_for` container/section) before click/type actions.
+- Keep selectors stable (`data-testid`) and avoid positional selectors for scroll-sensitive regions.
+
 Recorder note:
 - Include `recorder_export` only when user explicitly asks to export at run completion.
 - Without `recorder_export`, StudioFlow stops recording and completes the run without export.
+- Recorder software selection is not encoded in `flow.json`; include it in `studioflow-cli-handoff.json` as `recorder`.
 
-## Open-intent fallback note
+## 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.
+When clarification inputs remain incomplete, still generate deterministic `flow.json` and include assumptions + confidence in handoff summary.

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

@@ -0,0 +1,60 @@
+# CLI Handoff Spec
+
+Use this artifact to hand execution from `studioflow-author` 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",
+  "recorder": "screenstudio",
+  "baseUrl": "http://localhost:4280",
+  "startCommand": "pnpm dev:demo-lab",
+  "healthPath": "/",
+  "runtimePacing": {
+    "profile": "standard",
+    "cursorMoveMs": 430,
+    "cursorHighlightMs": 170,
+    "typingDelayMs": 55,
+    "clickPulseMs": 220,
+    "stepPreDelayMs": 90,
+    "stepPostDelayMs": 130,
+    "stepDwellMs": 180
+  },
+  "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`.
+- `recorder`: recorder backend used by CLI `--recorder`.
+  - Allowed values: `quicktime`, `screenstudio`.
+  - Selection rule: if user explicitly requests Screen Studio/QuickTime, preserve that; otherwise default `quicktime`.
+- `baseUrl`: runtime host URL.
+- `startCommand`: command used when app is not already healthy.
+- `healthPath`: health probe path used by runtime.
+- `runtimePacing`: required runtime timing overrides derived from authored flow pacing.
+  - Allowed fields: `profile`, `cursorMoveMs`, `cursorHighlightMs`, `typingDelayMs`, `clickPulseMs`, `stepPreDelayMs`, `stepPostDelayMs`, `stepDwellMs`.
+  - `profile` values: `fast`, `standard`, `cinematic`.
+- `notes`: optional operator notes.
+
+## Invocation contract
+
+When handoff artifact is written and the user asked to run/record now, invoke `studioflow-cli` (or equivalent runtime workflow in same agent) to execute:
+
+1. `pnpm validate -- --flow <flowPath>`
+2. `pnpm demo -- --flow <flowPath> --intent "<intentSummary>" --recorder <recorder> --base-url <baseUrl> --start-command "<startCommand>" --health-path <healthPath>`
+3. Set matching `STUDIOFLOW_*` env vars from `runtimePacing` on the demo command.
+
+Do not ask the user to translate handoff into commands.

package/{skills → bundled/skills}/studioflow-cli/SKILL.md

@@ -7,12 +7,28 @@ description: Execute validated demo artifacts with StudioFlow CLI. Use when the
 
 Run validated artifacts through deterministic execution.
 
+## Sandbox Escalation (Required)
+
+When executing StudioFlow CLI commands from Codex tool environments, run the commands below with `sandbox_permissions: require_escalated` on the first attempt. Do not run them in sandbox first and retry after failure.
+
+- `pnpm install` (when dependencies are missing)
+- `pnpm run setup`
+- `pnpm run doctor`
+- `pnpm quicktime-prep`
+- `pnpm screenstudio-prep`
+- `pnpm validate -- --flow <flowPath>`
+- `pnpm demo -- --flow <flowPath> --intent "<intent-summary>" --recorder <recorder> --base-url <baseUrl> --start-command "<startCommand>" --health-path <healthPath>`
+
+Reason: these commands can require network access, local IPC sockets (`tsx`), GUI automation, recorder control, and app process orchestration that are commonly blocked in sandboxed 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`.
+Handoff may be produced by `studioflow-author`, or reused by `studioflow-investigate` when routing to execute-existing.
+If handoff includes `recorder`, treat it as source of truth and preserve explicit user recorder choice.
 If present, also consume `runtimePacing` from handoff for runtime timing env values.
 
 1. Confirm artifact presence:
@@ -29,7 +45,14 @@ pnpm run setup
 pnpm run doctor
 ```
 
-If run preflight fails, collect explicit Screen Studio diagnostics:
+If run preflight fails, collect recorder-specific diagnostics:
+- For `recorder=quicktime`:
+
+```bash
+pnpm quicktime-prep
+```
+
+- For `recorder=screenstudio`:
 
 ```bash
 pnpm screenstudio-prep
@@ -44,10 +67,11 @@ pnpm validate -- --flow artifacts/flow.json
 4. Execute recording run from artifact:
 
 ```bash
-STUDIOFLOW_CURSOR_MOVE_MS=<cursorMoveMs> STUDIOFLOW_CURSOR_HIGHLIGHT_MS=<cursorHighlightMs> STUDIOFLOW_TYPING_DELAY_MS=<typingDelayMs> STUDIOFLOW_CLICK_PULSE_MS=<clickPulseMs> STUDIOFLOW_STEP_PRE_DELAY_MS=<stepPreDelayMs> STUDIOFLOW_STEP_POST_DELAY_MS=<stepPostDelayMs> STUDIOFLOW_STEP_DWELL_MS=<stepDwellMs> pnpm demo -- --flow <flowPath> --intent "<intent-summary>" --base-url <baseUrl> --start-command "<startCommand>" --health-path <healthPath>
+STUDIOFLOW_CURSOR_MOVE_MS=<cursorMoveMs> STUDIOFLOW_CURSOR_HIGHLIGHT_MS=<cursorHighlightMs> STUDIOFLOW_TYPING_DELAY_MS=<typingDelayMs> STUDIOFLOW_CLICK_PULSE_MS=<clickPulseMs> STUDIOFLOW_STEP_PRE_DELAY_MS=<stepPreDelayMs> STUDIOFLOW_STEP_POST_DELAY_MS=<stepPostDelayMs> STUDIOFLOW_STEP_DWELL_MS=<stepDwellMs> pnpm demo -- --flow <flowPath> --intent "<intent-summary>" --recorder <recorder> --base-url <baseUrl> --start-command "<startCommand>" --health-path <healthPath>
 ```
 
 Only set timing env vars that are provided (or implied by selected run-feel profile) in handoff.
+If `recorder` is missing from handoff, default to `quicktime`.
 
 5. Inspect outputs:
 - `<runsDir>/<run-id>/run.json`

package/{skills → bundled/skills}/studioflow-cli/references/handoff-spec.md

@@ -1,6 +1,6 @@
 # Handoff Input Spec
 
-`studioflow-cli` accepts a runtime handoff file from `studioflow-investigate`:
+`studioflow-cli` accepts a runtime handoff file from `studioflow-author` (or from `studioflow-investigate` when reusing existing artifacts):
 
 - `artifacts/studioflow-cli-handoff.json`
 
@@ -11,11 +11,12 @@
   "version": 1,
   "intentSummary": "Record only onboarding + CRM in Demo Lab",
   "flowPath": "artifacts/flow.json",
+  "recorder": "screenstudio",
   "baseUrl": "http://localhost:4280",
   "startCommand": "pnpm dev:demo-lab",
   "healthPath": "/",
   "runtimePacing": {
-    "profile": "balanced",
+    "profile": "standard",
     "cursorMoveMs": 430,
     "cursorHighlightMs": 170,
     "typingDelayMs": 55,
@@ -33,18 +34,22 @@
 - `version`
 - `intentSummary`
 - `flowPath`
+- `recorder`
 - `baseUrl`
 - `healthPath`
 
 `startCommand` is recommended. If omitted, runtime can still proceed when app is already healthy.
-`runtimePacing` is optional for conversation-driven speed tuning.
+`recorder` values: `quicktime`, `screenstudio`. If missing, default to `quicktime`.
+When intent explicitly names recorder software, preserve that recorder in handoff and execution.
+`runtimePacing` should be present for investigate-generated handoff and should drive timing env vars directly.
+Use `runtimePacing.profile` values `fast`, `standard`, `cinematic`.
 
 ## 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>`
+2. `pnpm demo -- --flow <flowPath> --intent "<intentSummary>" --recorder <recorder> --base-url <baseUrl> --start-command "<startCommand>" --health-path <healthPath>`
 3. If `runtimePacing` exists, set mapped env vars on the `pnpm demo` command:
    - `STUDIOFLOW_CURSOR_MOVE_MS`
    - `STUDIOFLOW_CURSOR_HIGHLIGHT_MS`
@@ -54,4 +59,8 @@ From payload, execute:
    - `STUDIOFLOW_STEP_POST_DELAY_MS`
    - `STUDIOFLOW_STEP_DWELL_MS`
 
+Preflight diagnostics mapping:
+- `recorder=quicktime` -> `pnpm quicktime-prep`
+- `recorder=screenstudio` -> `pnpm screenstudio-prep`
+
 If payload is missing, fall back to explicit user arguments or repo defaults.

package/bundled/skills/studioflow-investigate/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: studioflow-investigate
+description: Intake and route StudioFlow demo requests. Use when the user asks to run or record a demo from natural language and you must (1) clarify intent anchors, (2) decide whether existing artifacts already fit the request, and (3) route to `studioflow-author` (create/repair) or `studioflow-cli` (execute existing artifacts).
+---
+
+# StudioFlow Investigate
+
+Resolve intent and route execution to the right downstream skill.
+
+## Workflow
+
+1. Resolve intent specificity first.
+
+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
+
+Recorder selection:
+- Detect explicit recorder preference from user wording before authoring handoff:
+  - If intent says `screen studio` (or equivalent), set recorder to `screenstudio`.
+  - If intent says `quicktime` or `quicktime player`, set recorder to `quicktime`.
+  - If not specified, default to `quicktime`.
+- Treat explicit user recorder wording as authoritative over defaults.
+
+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.
+- Infer run feel and pacing automatically from user intent + discovered UI complexity.
+- Ask about run-feel preferences only when user intent explicitly asks for a style (for example: `fast`, `standard`, `cinematic`).
+- 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`.
+- If anchors remain unclear after round 2, make a best-effort route decision with explicit assumptions.
+
+2. Evaluate current artifact readiness after clarification.
+
+Check for:
+- `artifacts/flow.json`
+- optional `artifacts/studioflow-cli-handoff.json`
+- optional `artifacts/bootstrap.json`
+- optional `artifacts/structure-report.json`
+- optional `artifacts/navigation-graph.json`
+
+3. Run intent-to-artifact fit evaluation using `references/artifact-fit-spec.md`.
+
+Classify route:
+- `execute-existing`: artifacts are present and intent fit is high enough to run safely.
+- `patch-existing`: artifacts exist but require targeted edits.
+- `create-new`: artifacts are missing or intent fit is low.
+
+Write decision trace to:
+- `artifacts/intent-fit-report.json`
+
+4. Route deterministically based on classification.
+
+- For `execute-existing`:
+  - Invoke `studioflow-cli` immediately with existing artifacts and handoff/default runtime anchors.
+- For `patch-existing` or `create-new`:
+  - Invoke `studioflow-author` to create/repair deterministic artifacts for this intent.
+  - After `studioflow-author` completes, invoke `studioflow-cli` in the same turn.
+
+5. Do not stop at command suggestions when the user asked to run/record a demo.
+
+- If your host supports explicit skill invocation, invoke downstream skills directly.
+- If explicit invocation is unavailable, execute equivalent workflows directly.
+
+## Output Requirements
+
+Always produce:
+1. `artifacts/intent-fit-report.json`
+2. concise route decision (`execute-existing|patch-existing|create-new`)
+
+Always include a concise handoff summary in the response:
+- resolved intent anchors
+- route decision and reason
+- unresolved assumptions (if any)
+- confidence (`high|medium|low`)
+
+Use references in:
+- `references/question-card-spec.md`
+- `references/clarification-state.md`
+- `references/artifact-fit-spec.md`

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

@@ -0,0 +1,73 @@
+# Artifact Fit Spec
+
+Use this rubric to decide whether existing artifacts satisfy the clarified demo intent.
+
+## Inputs
+
+- Clarified intent anchors:
+  - `target_route`
+  - `user_goal`
+  - `done_assertion`
+  - `recorder_backend`
+  - optional run-feel/profile
+- Existing artifacts (if present):
+  - `artifacts/flow.json`
+  - `artifacts/studioflow-cli-handoff.json`
+  - `artifacts/bootstrap.json`
+  - `artifacts/structure-report.json`
+  - `artifacts/navigation-graph.json`
+
+## Fit dimensions
+
+Score each dimension as `pass|partial|fail`.
+
+1. Route coverage:
+- `flow.json` steps reach the intended route/workspace.
+
+2. Goal coverage:
+- Steps demonstrate the requested business outcome, not just generic navigation.
+
+3. Completion evidence:
+- Assertions/screenshots prove the requested done state.
+
+4. Runtime anchors:
+- `baseUrl`, `healthPath`, `startCommand` can be resolved from handoff/bootstrap/config.
+
+5. Recorder and style alignment:
+- Recorder preference (`quicktime|screenstudio`) and pacing profile are preserved.
+
+## Route decision rules
+
+- `execute-existing`:
+  - no `fail` dimensions
+  - at most one `partial`
+- `patch-existing`:
+  - artifacts exist and deterministic edits are enough (selectors, assertions, pacing, minor scope drift)
+- `create-new`:
+  - artifacts missing
+  - or core route/goal/done coverage is `fail`
+
+## Required output
+
+Write `artifacts/intent-fit-report.json`:
+
+```json
+{
+  "version": 1,
+  "decision": "execute-existing",
+  "confidence": "high",
+  "intentAnchors": {
+    "targetRoute": "/flows/crm",
+    "userGoal": "advance and create a CRM lead",
+    "doneAssertion": "Created L-300 for Aurora Systems.",
+    "recorder": "quicktime"
+  },
+  "dimensions": [
+    { "name": "route_coverage", "result": "pass", "notes": "Flow reaches /flows/crm." },
+    { "name": "goal_coverage", "result": "pass", "notes": "Includes lead advance and creation." }
+  ],
+  "reasons": ["Existing flow already matches clarified scope."]
+}
+```
+
+Keep notes concrete and tie them to selectors/steps whenever possible.