Private beta docs

Run Flock reviews from developer workflows

Start with a target URL, a persona, and a user goal. Flock runs the journey, writes structured evidence, and turns findings into reviewable fix briefs.

These examples show how the same review output can appear in commands, output files, MCP resources, reports, and pull-request comments.

Quickstart shape

Run one review against a preview URL

CLI example

The example below asks a skeptical buyer to create a shared workspace. A useful run should produce a finding only when it can cite what the persona saw.

npm run tester -- \
  --url https://preview.example.com/signup \
  --persona skeptical-buyer \
  --goal "Create a shared workspace and invite a teammate" \
  --success-signals '[{"type":"text_present","value":"Invitation sent"}]'

Outputs written

output.json for structured findings, evidence, and fix guidance.
report.md for a human-readable review summary.
engineering_events.json for console, network, and runtime signals.
timeline.jsonl for step-by-step replay context.

What a finding looks like

output.json

{
  "run_id": "run_20260526_1420",
  "persona_id": "skeptical-buyer",
  "decision": "fix_recommended",
  "findings": [
    {
      "severity": "major",
      "summary": "Workspace setup ends without a clear next step.",
      "evidence": {
        "screenshot": "artifacts://run_20260526_1420/step-05.png",
        "dom_excerpt": "<h1>Workspace created</h1>",
        "observed_text": "No invite, onboarding, or dashboard CTA was visible."
      },
      "fix_prompt": "After workspace creation, show the next action: invite teammates, continue setup, or open the dashboard."
    }
  ]
}

report.md

## Finding: workspace setup dead-end

Severity: Major
Persona: skeptical-buyer
Observed behavior: The user created a shared workspace, then saw no clear next action.
Evidence: screenshot + DOM excerpt + visible page text
Suggested fix: Add a post-create action group with Invite teammate, Continue setup, and Open dashboard.

GitHub PR comment

Flock finding: workspace setup dead-end

The synthetic user completed the workspace form but could not tell what to do next.

Evidence:
- Screenshot: artifacts://run_20260526_1420/step-05.png
- DOM excerpt: <h1>Workspace created</h1>
- Observed text: no invite, onboarding, or dashboard CTA visible

Suggested fix:
Add a post-create action group and regression coverage for the workspace-created state.

CLI

Flock Synthetic CLI

Run synthetic users from terminal workflows and CI jobs with deterministic artifacts.

Review outputs

output.json
report.md
engineering_events.json

View CLI docs

MCP

Flock MCP Server

Planned MCP access lets AI clients request reviews and read evidence artifacts through a standard protocol surface.

Review outputs

Tools
Resources
Prompts

View MCP docs

GitHub App

Flock GitHub App

Planned PR checks will run synthetic journeys and post evidence-backed findings to GitHub.

Review outputs

Inline PR comments
PR summary
Check run status

View GitHub App docs

Quality bar

Evidence-backed or it does not ship

Every claim needs evidence

Findings must tie to observable artifacts: UI text, screenshots, element states, console/runtime errors, or network traces.

Every issue should be addressable

We optimize for findings that map to concrete code and product changes teams can address in a pull request.

Hallucination resistance by design

Agents are constrained to evidential signals and structured outputs to reduce speculative or non-actionable feedback.