# FlowRunner Extensions

This project holds FlowRunner custom extensions, managed with the `flowrunner` CLI. One service per folder
under `services/{id}/`, each a single JavaScript module in `src/index.js`, with its unit suite alongside it
in `services/{id}/tests/`.

## Dispatch service work — don't do it inline

Two agents, split by what they touch. Dispatch one rather than editing a service or a suite directly — each
loads the documents its task needs.

| Agent | Owns |
|---|---|
| `flowrunner-service-code-engineer` | everything inside a service — creating one, reviewing, fixing, extending, and keeping its `README.md` in step with its actions and triggers |
| `flowrunner-service-test-engineer` | everything inside `services/{id}/tests/` — writing a suite, widening one, fixing a red one |

A new service is both, in order: write it, then test it. They are separate agents because the second one's
job is to disagree with the first — a test engineer that also owns the source fixes the service to make its
test pass, which is the one outcome a test suite exists to prevent.

**Do not read the authoring reference on the main thread.** It is the agents' job to load, and reading it
here duplicates that cost without producing anything.

## The authoring reference

The reference ships inside the installed CLI, versioned with it, so it describes the format this project
actually deploys:

`node_modules/flowrunner-cli/ai-docs/instructions/service-code-format/`

Its `README.md` is the source of truth for service format — the reading order, the identity-and-naming
rules, and which document covers what. Where anything conflicts with it, it wins.

If that directory does not exist, stop and ask the developer to install or update `flowrunner-cli` — do not
proceed from memory.

## Testing

`npm test` runs every service's unit suite. The harness is `sandbox/` in the project root — `flowrunner init`
copied it here, and it belongs to this project: it is editable, and a service needing something it does not
do is a reason to extend it.

Suites mock HTTP at the socket and never reach a real API. There is no live-API test kind — a service is
validated against the vendor by deploying it and running a flow.

## Repo rules

- **Never read or analyse `node_modules/` as project source.** The authoring reference above is the only
  exception; in particular, do not read the CLI's bundled runtime or its `templates/` — the reference
  carries a verified example service for that purpose.
- Everything for a service stays inside its own `services/{id}/` folder, tests included.