Cursor rules

---
description: Checklist for validating UX changes with Stunt Double before shipping
alwaysApply: false
globs:
  - "**/*"
---

review-checklist:

Before merging:
- Run relevant Stunt Double checklists against staging before merging UX changes.
- Verify that existing workflows still pass after modifying user-facing flows.
- Check Stunt Double feedback (`list_feedback`) for regressions related to the changed area.

Coverage:
- Ensure new user journeys have corresponding workflows or checklist items for ongoing validation.
- If a new user-facing feature is added, check that at least one actor persona covers the target user type.
- If no actor exists for the affected user segment, recommend creating one via `create_actor`.

After merging:
- Re-run affected workflows against the deployed environment to confirm the fix.
- Update feedback status to "resolved" for any issues addressed by the change.
- Review workflow run history (`get_workflow`, which returns `recent_runs`) to confirm no regressions.

---
description: Core guidelines for working with the Stunt Double MCP server
alwaysApply: true
---

stuntdouble-basics:

- Stunt Double deploys AI agents with realistic user personas to validate user journeys at scale.
- Authentication is handled automatically via OAuth 2.1 with PKCE. No API keys or tokens are needed.
- Always specify a workspace when creating or listing resources. Use `list_workspaces` to find available workspaces.

Finding things:
- `search` is the fastest way to locate anything in a workspace: projects, actors, checklists, interviews, automations, issues, goals, feedback, actor knowledge, insights, design reviews, project resources and conversations, all in one ranked call.
- Prefer it over listing an entity type and filtering the list yourself. Narrow with `types` and `project_id` when you already know the shape of what you want.
- Search before you create. It is how you find the actor, checklist, or workflow that already covers the job instead of adding a near-duplicate.
- Search only ever returns entities from workspaces you are a member of; the boundary is enforced server-side, not by the filters you pass.

Actors:
- Actors represent AI user personas. Create actors with clear names (format: "FirstName - Role"), descriptions, and system prompts.
- Give actors knowledge via `add_actor_knowledge` so they understand your product context.
- Conversations are read-only over MCP (`list_conversations`, `get_conversation`); an actor chat is started from the dashboard. To probe actors for research, design reviews or concept testing, run an interview: it puts every persona through the same guide and synthesises the answers, which one-off chats cannot do.
- Create diverse actors covering different segments: new users, power users, enterprise, accessibility, mobile.

Workflows and checklists:
- Use workflows for multi-step user journey validation (signup, checkout, onboarding flows).
- Use checklists for point-in-time quality checks (accessibility, performance, content).
- Workflow and checklist runs are asynchronous. After triggering a run, poll `get_workflow_run` or `get_checklist_run` for results.
- Use `create_workflow` with trigger_type "schedule" or "webhook" for automated continuous validation, then `add_workflow_step` once per step, in the order they should run: a workflow with no steps does nothing when it fires.
- A workflow's steps run by following the connections between them, which the step tools maintain. `get_workflow` returns `execution_order` and `unreachable_step_ids`: check them before activating, because a step nothing reaches is a step that never runs.

Feedback:
- Review feedback items surfaced by Stunt Double and update their status as issues are triaged or resolved.
- Status lifecycle: new → reviewed → resolved (or dismissed for false positives).
- Cross-reference feedback with actors and workflows to identify patterns and coverage gaps.

Interviews:
- Interviews are structured user research rounds: a discussion guide (sections of questions and tasks) is run against a target URL by AI participants (existing actors or ad-hoc personas).
- Build the guide with `add_interview_section` and `add_interview_item` before launching. Each section should focus on one topic and contain ordered `question` or `task` items.
- Add participants with `add_interview_participant`: pass `actor_id` to reuse an existing actor, or `persona_spec` (`name`, `bio`, `traits`) for an ad-hoc persona.
- `launch_interview` is async: it returns a trigger run ID and flips the interview to `running`. Participants update independently; use `get_interview` and `get_interview_participant` to follow progress.
- Once participants complete, the synthesis task produces a report (summary, themes, recommendations, per-question rollup). Fetch it with `get_interview_report`, or call `regenerate_interview_report` after editing transcripts or re-running participants.

Guidelines (the standards a workspace holds itself to):
- A guideline is a standing rule (design system, tone of voice, brand, content, accessibility, compliance, security, performance, shared knowledge). It is owned by the **workspace** and attached to the projects it applies to, so one rule holds for several projects without being retyped or edited in several places.
- Whatever is in force for a project is rendered into every checklist run, design review, interview and triage for it. Read `list_project_guidelines` before writing checks, interview questions or design feedback, and assert the rules rather than restating or contradicting them.
- Two switches decide whether a rule is in force: the library's and the project attachment's. `list_project_guidelines` folds them into one `enabled`.
- Write a rule once with `add_project_guideline` (library plus this project) or `add_workspace_guideline` (library only), then hold other projects to the same rule with `set_project_guideline` rather than adding a near-duplicate. Check `list_workspace_guidelines` first.
- `update_workspace_guideline` with `apply_to_design_reviews` carries a rule to every design review in the workspace, including the Slack and Linear reviews that have no project to attach it through.
- Guidelines are project-wide standards; `add_actor_knowledge` is for what one actor needs to remember.

Standards and guardrails:
- The same checklist and workflow machinery enforces standards, not just flows: brand and tone of voice, design-system adherence, legal and compliance requirements, and cross-surface continuity (pricing, terminology, promises).
- The pattern is always the same: codify the standard as a guideline, assert it with observable checklist checks (phrased as things a user could verify on the rendered page), then re-run on a schedule or on deploy and design events with `create_workflow`.
- Schedules store a timezone alongside the cron. Pass `{ cron, timezone }` in `trigger_config` using the timezone from `get_me`, or the run lands at that hour in UTC.
- Anything with a reachable URL can be tested: production, staging, Vercel/Netlify previews, Figma Make published prototypes, Claude design artifacts, v0 links.

Stunt Double Index (how AI agents experience websites):
- When someone asks how well AI agents can find, understand or act on a site (agent readiness, AI visibility, whether an agent can check out or get support there), read its Index report with `get_index_report` rather than guessing. Pass a `domain`, or a `project_id` to use the domain linked to that project.
- `list_index_sessions` explains a score: each session is one AI provider attempting one benchmark task, with evidence, a summary and the frictions it hit. `search_index_domains` finds a site or compares it against the leaderboard and its sector.
- Index data is public, so any tracked site can be read. `request_index_rerun` is different: it spends about 24 agent sessions, only the domain's owner can call it, and a domain can be re-run once every 10 minutes. Use it after the site has shipped changes, not to refresh a report that is already current.

Workspace and project scope:
- `get_workspace` reports the admin-set security controls under `settings` (public sharing, feedback widget, self-hosted workers, network policy). They are ceilings: a feature switched off there cannot be switched back on for one project, so check before promising a shared report link or a widget install.
- A project is archived, never deleted. An archived project (and every checklist, interview and feedback item under it) reads as missing from these tools; restoring one is a dashboard action.
- `list_project_mcp_servers` shows which MCP servers a project's runs can reach. A tool that is not listed is not available to the run. Registering and attaching servers are workspace-admin actions in the dashboard.

Prompts (slash-command recipes):
- The server ships self-contained prompt recipes; most clients surface them as slash commands. Reach for them instead of assembling tool calls by hand.
- `validate_design`, `verify_change`, `run_user_research`, `triage_feedback`, `setup_guardrails`, `check_brand`, `check_design_system`, `check_compliance`, `check_continuity`, and `stuntdouble_guide` (orientation + full tool catalogue).