docs: human-friendly README + three v2 relayflow use-case examples

Merged
KH
2mo ago
+455-55

Summary

  • Rewrite the top-level README for humans: a working fix-failing-tests snippet (typechecks against the real @relayflows/surface package) plus a Use Cases section.
  • Back each use case with a real, typechecked example flow: examples/social-post-pipeline/, examples/pr-review-pipeline/, examples/dependency-upgrade-bot/.
  • Add a typecheck:examples script to packages/surface, mirroring the existing typecheck:regressions convention.

Details

  • social-post-pipeline — research → draft → adversarial fact-check → graphic → f.human approval. Every gate reads a file the agent wrote, never a substring of what it said.
  • pr-review-pipeline — security/correctness/performance reviewer agents fan out in parallel, gated on writing findings, then a consensus agent reconciles disagreement between them (mirrors My Senior Dev's real multi-agent review coordination).
  • dependency-upgrade-bot — deterministic npm outdated gate → agent upgrades in a sandbox → a second, independent agent verifies the whole app with computer use in a separate sandbox → PR only opens once verified.

All three typecheck clean today but don't run yet — f.agent parks without a worker attached, and f.human still throws unsupported_verb in the SDK's authored-flow executor pending gate 6 wiring. Each example's README states plainly what's real today vs. what it's waiting on.

Test plan

  • cd packages/surface && npm run typecheck:examples passes clean
  • Reviewer sanity-checks the README use-case bullets against the linked examples

🤖 Generated with Claude Code

https://claude.ai/code/session_01GjmLai123x6nHpTio418Q6


Summary by cubic

Rewrites the top-level README with a human-friendly fix-failing-tests snippet and a Use Cases section, and adds three typechecked v2 relayflow examples that document real multi-agent patterns (social post with adversarial fact-check, parallel PR review with consensus, and a dependency upgrade bot with independent sandbox verification).

Status

  • The examples are written directly against @relayflows/surface and typecheck via the new typecheck:examples script (mirrors typecheck:regressions).
  • They don't run yet: f.agent parks without a worker attached, and f.human still throws unsupported_verb in the SDK's authored-flow executor.
  • Each example README states exactly what's real today and what gate work it's waiting on.