feat(examples): prospect demo flow — LLM to Slack to observer (#344)

[kjgbot]

Closes #344. Delivered via implement-slice.flow.ts (flows-driven dogfood, mixed codex/claude).

---

Note

Low Risk
Documentation and example-only code; no changes to runtime libraries or production paths.

Overview
Adds examples/prospect-demo, a minimal end-to-end sample for prospects: an LLM-generated intro message posted to Slack #test, with the observer link coming from flows run (no observer step in the flow).

demo.flow.ts wires f.llm → f.slack.post → f.done('success'). The new README documents setup (Node 22.18+, Claude or Codex via flows.json, relayfile Slack mount, RELAYCAST_WORKSPACE_KEY), flows check / flows run --local-agent, and optional RELAYFLOWS_SLACK_MOCK=1 for local runs without live Slack.

^{Reviewed by Cursor Bugbot for commit a723605. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 2dd9b715-1d7c-45ee-86c9-700f37837c93

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[kjgbot]

maintainability lens — FAIL

Maintainability review — PR #348 (prospect-demo)

Scope: examples/prospect-demo/README.md (new, 64 lines) and examples/prospect-demo/demo.flow.ts (new, 11 lines).

Blockers

demo.flow.ts:10 — comment asserts behavior the code does not perform.

f.done('success');
// `flows run` prints the observer URL after the run summary when configured.

The comment sits inside the flow body but describes external CLI behavior. It cannot be validated from this file, has no scope hook, and will silently rot when the CLI's observer print path changes. This is exactly the failure mode the maintainability lens exists to catch — a comment that says what the code does not do. The information is already in the README (README.md:50–57); delete the code comment.

README.md:16 — install list includes a package the demo does not use.

npm install relayflows @relayflows/surface

demo.flow.ts:1 only imports from @relayflows/surface. Either relayflows is a runtime dep for npx flows run/flows check and that dependency must be stated, or it is dead weight and must be removed. A reader in six months cannot tell which; both possible fixes are behavior-changing. Either name the reason (e.g., "provides the flows CLI") or drop it.

Concerns

• README.md:11–20 — unpinned deps, no package.json/tsconfig.json in examples/prospect-demo/. Contrast examples/social-post-pipeline/ which is picked up by npm run typecheck:examples. Nothing here breaks if f.slack.post renames or f.llm's return type changes; the demo drifts silently until a prospect runs it.
• README.md:28–29, 58 — implicit CLI contract on secret handling. The user sets RELAYCAST_WORKSPACE_KEY=rk_live_... yet AGENTS.md:59–63 forbids rk_live_ on observer links. The README asserts the CLI mints an ot_live_ scoped token from that workspace key, but never cites where that mechanism is documented. FLOWS_NO_OBSERVER is introduced only as a debugging hint — no cross-link, no owner. A reader diagnosing a missing observer line has nothing to verify against.
• README.md:42–43 — --input '{}' unexplained. The flow takes no input but the reader must pass empty JSON. Six months from now this reads as cargo-culted. Add one sentence, or make the CLI default.
• README.md:47 — asserted behavior with no failure path. "The Slack helper waits for a delivery receipt before completing" is a testable claim, but demo.flow.ts has no timeout, retry, or note on what a stuck receipt looks like from the terminal. SLACK-HELPER.md:47–52 covers this — link to it.
• demo.flow.ts:8 — return value of f.slack.post is discarded silently. SLACK-HELPER.md:11–13 shows the receipt shape (posted.ts); a maintainer extending the demo (add a thread reply, react) has no in-file hint that a receipt is available.

Notes

• No test exercises this example, and no CI hook would flag a surface break. That is consistent with examples/README.md framing these as advisory, but worth stating in the README (this demo is copy-paste-only, not typecheck-verified).
• #test as a hardcoded channel is fine for a starter; README already tells the reader to create it.

REVIEW_FAILED

[kjgbot]

history lens — PASS

Blockers: none. PR #348 does not meet any of the three HISTORY rejection criteria.

Notes:

• examples/prospect-demo/demo.flow.ts, lines 3–10, composes existing surface operations: f.llm, awaited f.slack.post, and f.done('success'). It introduces no provider transport, kernel vocabulary, or execution dependency on Relaycast. This fits settled decisions gate1: kernel + sdk skeletons (bootstrap relayflow output) #1, flow/drive f59e279 08271341 #7, and drive: WP-13: Fix SDK test failures from sandbox environment gaps #13.

• examples/prospect-demo/README.md, lines 28–36, preserves the earlier Slack helper correction in 86a2ec20: delivery requires relayfile writeback; a bot token alone is insufficient. Lines 53–60 also preserve the observer correction in f72e2bad: the dashboard uses agentrelay.com and an ot_live_ token, with the workspace key used for minting.

• README lines 62–64 explicitly distinguish mock receipts from live Slack delivery. That avoids the unsupported-evidence pattern repeatedly documented in DRIVE-LOG.

• The commit headline accurately describes the example and makes no test, crash-recovery, or evidence claims. Literal inspection:

  $ git show a7236050 --format='%h %s%n%b' --name-only
  a7236050 feat(examples): prospect demo flow — LLM to Slack to observer (#344)
  
  
  examples/prospect-demo/README.md
  examples/prospect-demo/demo.flow.ts
  

Concerns, non-blocking: README lines 40–47 demonstrate the existing file-based authoring path, without demonstrating immutable bundle execution or whole-body recovery. Those remain implementation limitations outside this example’s scope; the diff does not regress previously fixed behavior or claim those capabilities. The older gate references in ops/NEXT.md likewise do not implicate this change.

This is a historical and source review. I did not execute the demo or send a Slack message.

REVIEW_PASSED

[kjgbot]

structure lens — MISSING

[kjgbot]

🎯 review-swarm: FAILED (M:fail H:pass S:missing)

Lens transcripts posted as sibling comments above.