<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/ricky-logo-dark.png">
    <source media="(prefers-color-scheme: light)" srcset="assets/ricky-logo-light.png">
    <img src="assets/ricky-logo-light.png" alt="Ricky runner logo" width="180">
  </picture>
</p>

<p align="center"><strong>Workflow reliability at runner speed.</strong></p>

# 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.
- **Proactive runtime agent** — implemented for scheduled background-run monitoring via `@agent-relay/agent`.
- **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` and the SDK from `dist/index.js`.

For local development from the repo:

```sh
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:

```sh
npx @agentworkforce/ricky --help
ricky --help
```

## SDK Usage

Projects can import Ricky directly instead of shelling out to the CLI:

```ts
import { createRickySdk } from '@agentworkforce/ricky';

const ricky = createRickySdk({ cwd: process.cwd() });

const generated = await ricky.generateLocalWorkflow({
  spec: 'Generate a workflow that checks package health',
  workflowName: 'package-health',
});

const run = await ricky.runLocalWorkflow({
  workflowPath: 'workflows/generated/package-health.ts',
  autoFixAttempts: 3,
});
```

The SDK also exposes `generateCloudWorkflow`, `scheduleWorkflow`, `listWorkflowSchedules`, and `runCli`. The published CLI uses `runRickyCli` from the SDK, so command behavior and package imports share the same implementation boundary.

## 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:

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

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

```sh
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.

## Proactive Runtime Monitoring

Ricky now exposes a proactive runtime entrypoint at [`src/agent.ts`](./src/agent.ts). The scheduled agent wakes every 5 minutes with `agent({ schedule: "*/5 * * * *" })`, scans Ricky's persisted background-run state, and posts terminal run updates to `RICKY_MONITOR_CHANNEL` (default `#ricky`).

Environment knobs for the scheduled agent:
- `RICKY_WORKSPACE_ID` — Relaycast/relayfile workspace name for the agent runtime. Defaults to `ricky`.
- `RICKY_MONITOR_CHANNEL` — channel that receives proactive run updates. Defaults to `#ricky`.
- `RICKY_MONITOR_REPO_ROOT` — repo root whose persisted run-state tree should be monitored. Defaults to the current working directory. Both `<repo>/.workflow-artifacts/ricky-local-runs/` and the XDG state-home tree are scanned.
- `RICKY_STATE_HOME` — optional override for the base state directory Ricky already uses for background runs.

Run it locally with:

```sh
tsx src/agent.ts
```

## 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}`.

```sh
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 run premerge     # run typecheck, full tests, and the local auto-fix ladder e2e
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 run premerge` — run typecheck, the full test suite, and `test/local-auto-fix-workflow-failures.e2e.test.ts` as an explicit pre-merge regression gate
- `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/state/overnight/<queue-mode>/checkpoint.env` (legacy `.workflow-artifacts/overnight-state/...` checkpoints are still imported automatically)
- `npm run prepack` — build before package packing (runs automatically on `npm pack` and `npm publish`)

Node and npm versions are pinned: `engines.node = ">=22.14.0"`, `packageManager = "npm@11.11.0"`, `engine-strict=true` in `.npmrc`, and `.nvmrc = 22.14.0`. 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.
