Use the relayflows SDK directly (consume @relayflows/core; run via the relayflows CLI)

[khaliqgant]

Context

Ricky authors workflows against @agent-relay/sdk/workflows (55 files import it) and runs them via agent-relay run (scripts/run-ricky-batch.sh). Meanwhile the active workflow engine has moved to relayflows: @relayflows/core (the workflow builder, createGitHubStep, integrations) + @relayflows/cli (relayflows run). Both are published on npm (1.0.1).

This split bit us concretely: a new multi-workflow stack (the factory build-out, p1–p13) had to be authored inside the relayflows repo purely so @relayflows/core would resolve and relayflows run could execute it. Ricky couldn't host it, because:

• ricky has no dependency on @relayflows/core (it pins @agent-relay/sdk@^6.0.15), so the import doesn't resolve;
• the agent-relay binary on PATH is a stale shim (~/.local/bin/agent-relay → ~/.agentworkforce/relay/bin/agent-relay) that has no run command.

Goal

Ricky consumes the relayflows SDK directly and resolves its dependencies, so ricky can author and run relayflows-native workflows (and host stacks like factory-build) without them living in the relayflows repo.

Proposal

1. Add deps (published, so no workspace link needed — core's *-primitive deps resolve transitively):

   npm i @relayflows/core@^1.0.1 @relayflows/cli@^1.0.1
   

2. Author against @relayflows/core — import { workflow } from '@relayflows/core'; createGitHubStep from @relayflows/core/integrations/github; models from @agent-relay/config.
3. Run via the relayflows CLI — relayflows run <file> (and --dry-run). Update scripts/run-ricky-batch.sh to invoke relayflows (via the installed bin or node node_modules/@relayflows/cli/dist/cli.js) instead of the stale agent-relay shim.
4. Migrate the 55 existing @agent-relay/sdk/workflows files, or run a transition where both runners are supported. Decide whether @agent-relay/sdk stays for non-workflow uses.

Gotchas (learned the hard way)

• Node --experimental-strip-types runner requires explicit extensions on relative imports — import x from './lib/foo.ts', not './lib/foo' (ERR_MODULE_NOT_FOUND otherwise). Any shared lib/ helper must use .ts specifiers.
• createGitHubStep is a subpath export (@relayflows/core/integrations/github), not on the root.
• Building relayflows from source needs primitives built before core — fixed in AgentWorkforce/relayflows#4 (merged). Irrelevant when consuming the published @relayflows/core (ships dist/), but relevant if ricky ever vendors/links the repo.
• The stale agent-relay shim lacking run should be removed/repointed as part of this so contributors don't hit it.

Acceptance criteria

• package.json depends on @relayflows/core + @relayflows/cli; npm ci resolves them (incl. the *-primitive transitive deps).
• A sample ricky workflow importing @relayflows/core runs via relayflows run --dry-run from the ricky repo.
• scripts/run-ricky-batch.sh drives the relayflows CLI (no dependence on the stale agent-relay shim).
• A decision + plan recorded for the 55 existing @agent-relay/sdk/workflows files (migrate vs dual-support).
• The factory build-out stack (currently relayflows/factory-build/) can be run/owned from ricky once this lands.

References

• relayflows build-order fix: fix(build): build *-primitive workspaces before core relayflows#4 (merged)
• Factory build-out stack: relayflows/factory-build/ (13 workflows, dry-run validated against @relayflows/core)
• Current ricky runner: scripts/run-ricky-batch.sh; authoring rules: workflows/shared/WORKFLOW_AUTHORING_RULES.md

🤖 Generated with Claude Code