Multi-actor flows

A flow is a journey across multiple actors:

Admin invites a candidate → candidate signs up → admin approves → candidate sees approval in their dashboard.

Traditional E2E tests each stage in isolation. They miss state propagation bugs: what if the admin’s approval doesn’t actually surface on the candidate’s dashboard?

Nitpick’s multi-role-e2e skill tests flows as a single coordinated journey.

Defining a flow

In nitpick.yaml:

flows:
 - name:"Candidate onboarding"
 description: |
 Admin logs in at /admin/invitations and creates a new invitation.
 Candidate receives the invite link, goes to /signup, fills the form,
 and submits. Admin reviews the application at /admin/candidates and
 clicks Approve. Candidate sees the approval on their /dashboard.

Plain language. No YAML schema to remember.

What runs

When a flow is in scope, Nitpick spins up a Flow Lead subagent (multi-role-e2e skill). The Flow Lead:

1. Parses the flow narrative: identifies stages, actors, transitions
2. Delegates each stage to a Junior QA (same prd-e2e-orchestrator skill as per-page tests)
3. Advances state between stages, if admin submits a form, that form is actually submitted, creating the record the next stage depends on
4. Runs cross-actor assertions “after admin approves, candidate’s dashboard should reflect it”

Cross-actor assertions

These are the checks traditional E2E misses. Example:

Stage 1: Admin creates invitation for candidate@example.com
Stage 2: Candidate signs up at /signup
Stage 3: Admin approves candidate

Cross-actor check:
 After Stage 3, switch to candidate auth state, navigate to /dashboard,
 assert"Approved" badge is visible.

If the backend fires the approve API but doesn’t update the candidate’s dashboard query, Nitpick catches it. Traditional tests don’t.

Per-stage reports + unified flow report

Each stage gets its own compliance report (generated by the Junior QA running that stage). The Flow Lead aggregates them into a unified flow report:

• Timeline visualization (stage-by-stage progression)
• Per-stage pass/fail
• Cross-actor assertion results
• Blocked stages (if Stage 2 fails, Stage 3 and 4 are blocked)
• Aggregate metrics

Scope controls

Flows run by default when --scope full is set. To test only flows for a targeted change:

nitpick run --scope iterative --change"I refactored the candidate approval logic"

Nitpick will propose flows that touch candidate approval.

To skip flows entirely:

nitpick run --scope targeted --url /dashboard/tasks

Data isolation

Each flow run uses unique data (timestamp-suffixed emails, UUID identifiers) so repeated runs don’t collide. Downstream stages find the entity via captured_data from the advancing stage.