---
name: run
description: >
  Launch the app or Storybook from the intended Workbench checkout. Use for
  /workbench:run, /workbench:run app, /workbench:run storybook, or a request to
  preview the active Workbench change. Discover repository commands, check
  process ownership and ports, and return a working URL with stop instructions.
  This is an optional utility, not full feature verification.
---

# Run the checkout

Use `/workbench:run`, `/workbench:run app` or `/workbench:run storybook`. Launch in the checkout assigned to the current task, whether Local or a native worktree. Reconcile an older task-note path after a host handoff; do not launch from the previous directory. Run does not select an environment, create a worktree or switch branches.

Read [the shared contract](../../references/workflow.md). Run is available at any stage; it does not require a ticket, completed plan or clean working tree, and does not advance the delivery stage by itself.

1. **Identify the target.** Resolve the host-assigned task checkout with Git, then confirm its HEAD, branch or detached state, and current changes. If the user requested a different path, reconcile it with the task environment before launching. Resolve conflicting task-note and workspace paths before launching. Read applicable repository instructions and the target application's setup guide and scripts. Use an explicit `app` or `storybook` choice; otherwise infer from the current task, defaulting to its app. Ask only if the checkout or application remains ambiguous. Support both the primary checkout and linked worktrees. Do not create checkouts or switch branches as part of run.
2. **Find the launch command.** Prefer the matching action from the selected native local environment, with its platform-specific command and working directory. Inspect the configured action before using it. Use the supported native action/terminal when available; otherwise execute the same verified command in the assigned checkout without redefining the environment. Check setup status and avoid rerunning worktree setup merely to launch. If no suitable action is available, discover the repository command. Reuse the launch and identity guidance in an existing [verification recipe](../../references/verification-recipes.md), checking it against current repository scripts and pinned runtimes. Discover missing commands from the repository rather than assuming a framework, port or package manager. Check dependencies, environment and backend/proxy requirements. Use documented local setup where authorized; preserve lockfiles and existing configuration, keep secrets out of output, and report missing credentials or access precisely. Do not copy environment files from a different checkout or point at production by assumption.
3. **Check existing instances.** Inspect candidate processes, their working directories/arguments and listening ports. Reuse a healthy instance only when its app, checkout and relevant configuration match. A responding port alone does not establish identity. Leave other or unidentified instances running. If the expected port is occupied, use a supported port override only after checking proxy, auth callback and origin constraints. Otherwise explain the conflict and ask for the specific decision needed; do not kill a process or rewrite shared config to claim the port.
4. **Launch and keep it available.** Run the repository command with an explicit working directory inside the selected checkout, using the host's supported persistent terminal/session. Record the command, working directory, URL/port and process/session handle, distinguishing a new instance from a borrowed one. Wait for readiness with bounded log checks, inspect startup errors, and confirm the served app or Storybook loads using supported browser tools when available. If a route/story is known, open its actual URL. Report an auth redirect or backend failure as such; a ready dev server is not proof that the feature works. If no persistent session is available, report that limitation rather than claiming the server will remain running.
5. **Hand back the preview.** Leave the requested server running for the user. Report its URL, checkout/branch, app or Storybook mode, readiness and any blockers, plus a concrete stop instruction tied to the recorded session/PID. Never recommend a broad process-name kill; a borrowed instance remains owned by its original session. Update an existing task note with launch details without overwriting the delivery stage; a standalone run does not need a new note or verification recipe. Do not claim a recipe proven from launch alone.

Finish with the **Next-step handoff** in the shared contract. Default to `/workbench:verify` for a working preview of implemented changes; suggest `/workbench:implement` when the preview is for work still to build. For startup blockers, name the fix and resume `/workbench:run`.