docs: dogfood test scenarios — trigger prompts mapped to FLOWS.md

[ZaxShen]

Need

docs/architecture/FLOWS.md describes 9 workflows abstractly. To verify them in a real session, a contributor needs the exact user prompt that triggers each scenario plus the observable expected behavior. Today they have to read every agent prompt + every skill to figure out what to type.

Proposal

New file: docs/architecture/SCENARIOS.md — pairs each FLOWS.md flow with concrete trigger prompts. For each scenario:

• The user sentence to type, verbatim
• Pre-conditions (e.g., "≥2 planning agents must exist in .claude/agents/")
• Expected agent behavior (what the user should observe)
• Verification (what to grep / query in the trajectory DB to confirm)

Coverage

For every flow in FLOWS.md:

• Onboarding: fresh-DB trigger, hold-and-resume cases
• Simple task: typo / comment / no-API refactor
• Difficult task: new module / schema change / new dependency
• Agent-creator: domain role request, approval/refusal paths, reserved-name handling
• Skill creation: pattern recurrence (mostly internal architect flow)
• PR review: SWE completion → pr-reviewer chain
• Architecture regen: explicit phrase + lazy session-start variants
• SWE retry/escalation: validation-fail → retry → 3-fail escalation
• Roundtable with all four corner cases:
  • Explicit magic word, planners exist — "let's do a roundtable on X"
  • Explicit magic word, no planners — bro proposes agent-creator first
  • Implicit cross-domain trigger, planners exist — architect detects, launches roundtable
  • Implicit cross-domain trigger, no planners — bro/architect proposes agent-creator first

Acceptance criteria

• docs/architecture/SCENARIOS.md exists, ~30 scenarios across 9 flows
• Each scenario has: trigger prompt + pre-conditions + expected behavior + verification
• Cross-linked from FLOWS.md (each flow header links to its scenarios)
• Cross-linked from docs/local-testing.md (replaces the 10-row checklist OR extends it)
• Roundtable has all 4 corner cases (explicit/implicit × planners/no-planners) explicitly written

[ZaxShen]

Progress update

PR #58 + PR #64 partially refreshed scenarios + flow diagrams to reflect the bro-as-planner / push-gate doctrine. Status of each flow:

Flow	Scenario file (tests/manual/scenarios.md)	FLOWS.md diagram
1 (Onboarding)	Current ✓	Current ✓
2 (Simple task)	NEW 2.1.bro added (#58); 2.1/2.2/2.3 marked STALE	Refreshed in PR #64 with bro task-gate + batched handoff + parallel SWE first-response
3 (Difficult task)	STALE	STALE — refresh pending
4 (Agent-creator)	Current	Current
5 (Skill creation)	STALE	STALE
6 (PR review)	n/a	Refreshed in PR #64 — reframed as push-gate flow with parallel pr-reviewer spawns
7 (Architecture regen)	Current	Current
8 (SWE retry)	STALE	STALE — needs architect→bro substitution
9 (Roundtable)	STALE	STALE — multi-consultant voting tracked in #57 / #68
C (Consultant invocation)	NEW C.1 added (#58)	NEW in PR #64
R (Push gate)	n/a	Implicit in Flow 6 refresh

#51 is the dedicated sub-issue for bringing scenarios 2-9 up to the comprehensive template. Most relevant after PR #64 settles.