Ricky

Ricky is a workflow reliability, workflow coordination, and workflow authoring product for AgentWorkforce.

Ricky is the product answer to the workflow monitor problem described in AgentWorkforce/cloud#161: a cheap, workflow-native monitor/recovery agent that can watch long-running workflow programs, diagnose failures, fix common issues, resume from the right point, and keep a truthful evidence trail instead of requiring expensive manual babysitting.

Ricky is built to:

• debug failed workflows
• fix broken workflows
• restart or rerun them safely when appropriate
• proactively report workflow failures from Cloud
• analyze workflow quality over time
• suggest concrete workflow improvements
• help users generate high-quality workflows for local BYOH or Cloud execution
• coordinate workflow runs and return resulting artifacts

Interfaces

Ricky is designed around co-equal interfaces and onboarding surfaces. Current implementation status:

• CLI — implemented as the primary local command surface.
• Local / BYOH — implemented for local workflow generation, artifact execution, background monitoring, and status checks.
• Cloud API — partially implemented for Cloud generation request/response contracts and CLI connection/status flows.
• Slack — planned; no source handler is currently implemented in this repo.
• Web — planned; no browser surface is currently implemented in this repo.

Slack is a surface, not the product identity.

Install and Run

Ricky is an npm package: @agentworkforce/ricky. It publishes the ricky bin from dist/ricky.js.

For local development from the repo:

npm install            # or `npm ci` for a reproducible install from package-lock.json
npm run build          # bundle the CLI to dist/ricky.js
node dist/ricky.js --help
npm start -- --help    # run the CLI from source via tsx

For package consumers, the intended command form is:

npx @agentworkforce/ricky --help
ricky --help

CLI Reference

Common commands:

• ricky — start guided mode.
• ricky status — show local and Cloud readiness.
• ricky connect cloud — connect an AgentWorkforce Cloud account.
• ricky cloud --spec <text> — generate with Cloud.
• ricky local --spec <text> — write a local workflow artifact.
• ricky local --spec-file <path> --run — generate from a file, then run locally.
• ricky run <artifact> — execute an existing workflow artifact.
• ricky run <artifact> --cloud — execute an existing workflow artifact in AgentWorkforce Cloud.
• ricky run <artifact> --background — execute in the background and print a Ricky run id.
• ricky status --run <run-id> — check background run progress.
• ricky version — print the package version.

Common options:

• --mode <local|cloud|both> — set the routing mode.
• --spec <text>, --spec-file <path>, --stdin — provide a workflow spec.
• --artifact <path> or --workflow <path> — alias for ricky run <path>.
• --run / --no-run — execute after generation or generate only.
• --background / --foreground — choose monitoring mode for local execution.
• --start-from <step> and --previous-run-id <id> — resume a prior run.
• --auto-fix[=N] / --no-auto-fix — enable or disable the local diagnose/repair/resume loop.
• --refine[=model] / --with-llm[=model] — opt into the LLM refinement pass.
• --json — print machine-readable results.
• --quiet — print only essential output.
• --verbose — include diagnostic detail for unexpected failures.

Workflow Execution

Ricky can generate a workflow artifact and run it immediately:

ricky --mode local --spec-file ./spec.md --run

It can also run an existing artifact attached to the terminal or in the background:

ricky run workflows/generated/package-checks.ts
ricky run workflows/generated/package-checks.ts --cloud
ricky run workflows/generated/package-checks.ts --background
ricky status --run <run-id>

When generation does not run the artifact, the CLI prints the artifact path plus foreground and background run commands.

CLI Onboarding

Ricky's CLI should be intentionally welcoming and user-friendly.

The CLI onboarding experience should:

• greet users with a recognizable ASCII-art version of the Ricky logo
• help users understand the difference between local/BYOH and Cloud usage
• make the first useful action obvious instead of dropping users into a blank tool
• walk users toward Cloud setup when they want hosted workflow execution

At minimum, Ricky's onboarding surfaces should be able to guide users through:

• local-first workflow authoring and execution
• Cloud connect commands for supported providers
• connecting a Google account for Cloud-backed usage
• connecting the GitHub app through the Cloud/Nango dashboard flow
• starting from Slack, web, or CLI without needing a special privileged setup path

Current Ricky Cloud connection commands:

• ricky connect cloud
• ricky status
• ricky --mode cloud --spec-file ./spec.md --no-run

Provider-specific Cloud connection can still point users at existing AgentWorkforce Cloud flows, including:

• npx agent-relay cloud connect google

For GitHub-app connection flow, Ricky should direct users into the Cloud dashboard integration flow rather than inventing an ad hoc local-only path.

Positioning

Ricky sits between Sage and NightCTO:

• like Sage, it supports user-facing interaction and BYOH/runtime flexibility
• like NightCTO, it is proactive, analytics-driven, and operationally opinionated
• like Relay, it is deeply workflow-native rather than just LLM-chat-native
• like Agent Assistant, it should reuse shared assistant/runtime packages instead of rebuilding those seams locally

First artifact

The first artifact in this repo is the product spec:

• SPEC.md

Branding

The provided runner mark is used as the Ricky project logo and should be used as the default Slack app / manifest image.

• assets/ricky-logo.svg

Bootstrap

Ricky is a single-package npm repo with a flat src/ tree. npm is the only supported package and script surface. The product surfaces live under src/surfaces/, with shared inner layers under src/{shared,runtime,product,cloud,local}.

npm install          # install dependencies for the single root package
npm run typecheck    # typecheck src, tests, workflows, and scripts
npm test             # bundle the CLI and run the repo test suite + proof tests
npm start            # launch the CLI from src/surfaces/cli/commands/cli-main.ts

npm scripts (canonical ordering matches package.json):

• npm run clean — remove dist/
• npm run bundle — run the esbuild bundler directly
• npm run build — alias for bundle; produces dist/ricky.js
• npm run typecheck — typecheck the flat src/ tree plus workflows/proofs/scripts
• npm test — bundle the CLI, then run the full test suite and proof tests
• npm start — launch the interactive CLI from src/surfaces/cli/commands/cli-main.ts
• npm run dev — alias for npm start
• npm run evals — compile and run the Ricky eval suite
• npm run evals:compile — compile Ricky eval definitions
• npm run evals:provider — build Ricky, then run evals through the provider executor path
• npm run evals:opencode — run Ricky evals through the OpenCode executor path
• npm run evals:list — list available Ricky evals
• npm run evals:summary — summarize the latest Ricky eval results
• npm run evals:compare — compare Ricky eval result sets
• npm run batch — run workflow batches via scripts/run-ricky-batch.sh
• npm run overnight — run the overnight workflow queue via scripts/run-ricky-overnight.sh
  • default queue mode is now flight-safe, which only runs the workflows currently classified as unattended-safe
  • default behavior checkpoints after a small bounded chunk (RICKY_OVERNIGHT_MAX_WORKFLOWS_PER_INVOCATION, default 4) and can resume with bash scripts/run-ricky-overnight.sh --resume
  • checkpoint state lives under .workflow-artifacts/overnight-state/<queue-mode>/checkpoint.env
• npm run prepack — build before package packing (runs automatically on npm pack and npm publish)

Node and npm versions are pinned: engines.node = ">=20", packageManager = "[email protected]", engine-strict=true in .npmrc, and .nvmrc = 20. There is no Yarn, pnpm, or other package-manager surface — npm is the default and only path.

Note: prpm.lock at the repo root is not an npm artifact. It tracks AI-agent skills installed under .agents/skills/ via the prpm skill registry, and it is referenced by test/flat-layout-proof/ to verify that legacy Claude skill mirrors stay removed. Treat it as orthogonal to npm.

Package shape

Ricky is a single-package npm repo published as @agentworkforce/ricky. It is intentionally not a workspaces monorepo; if multi-package boundaries are introduced later, that change must be deliberate and scoped, not implicit drift.

Source layout:

• src/shared — shared constants, workflow config models, and workflow evidence models
• src/runtime — local coordination, runtime evidence, failure classification, and diagnostics
• src/product — spec intake, workflow generation, specialists, and analytics
• src/cloud — Cloud auth, workspace scoping, provider guidance, and generate API surfaces
• src/local — local/BYOH request normalization and execution composition
• src/surfaces/cli — onboarding, command surface, and interactive CLI entrypoints

The root keeps workflow program assets, bootstrap scripts, validation config, bundle output, and repo-level proof tests.

Product direction

Ricky should make workflows feel accessible to normal users, not just workflow authors.

The product goal is:

• users can rely on workflows heavily without ever hand-writing one
• users can talk through a spec with Claude or another LLM, then hand that spec directly to Ricky
• Ricky can receive that handoff via CLI or MCP, normalize it, and route it correctly through local/BYOH or Cloud execution
• Ricky should feel fully connected across CLI and Cloud, not like separate disconnected tools

Repo shape

Ricky now uses the flat-layout collapse proved by test/flat-layout-proof/. Product source should live under the root src/ tree, with surfaces under src/surfaces/ and no legacy packages/* workspace sources.