sre-n8n-converter

Files (1)

• SKILL.md

SKILL.md (first lines)

# n8n to Sentinel Kit Conversion

Convert the workflow's behavior, not its node graph.

## Outcomes

For each converted workflow, produce:

- a kit directory `{ns}.{name}/`
- `kit.yaml`
- only the folders actually needed: `fl/`, `cn/`, `md/`, `fm/`, `tp/`, `pb/`
- skill twins for every generated Lua file
- an explicit secret inventory for vault setup
- a short UAT checklist

Default namespace for examples: `sn.eg-*`

## Conversion Rules

1. Refactor, do not transliterate.
   The target is clean Sentinel code, not a one-to-one replay of n8n nodes and edges.

2. Prefer one coherent flow over many tiny node-shaped helpers.
   Keep orchestration in `fl/*.lua`. Extract only reusable or integration-heavy logic.

3. Put external service logic in connectors.
   Reusable API calls belong in `cn/`. Small data shaping stays inline unless it becomes noisy.

4. Keep pure logic in modules.
   Use `md/` for transforms, normalization, templating helpers, ranking logic, and shared parsing.

5. Move every credential into the vault.
   Never hardcode secrets. Use `ctx.secret("name")` in runtime code and document required secret names.

6. Preserve semantics, not topology.
   Parallel branches, retries, conditions, and fan-out should be re-expressed in straightforward Lua.

7. Prefer explicit failure handling.
   n8n often hides failure behavior in UI defaults. Sentinel code must make it obvious.

## Workflow

### 1. Read the n8n export first

Identify:

- workflow purpose
- entrypoints: webhook, schedule, manual trigger, app event
- external services and credentials
- data stores
- code nodes and transformations
- branching, retry, wait, and loop behavior
- outputs the user/operator actually cares about

Summarize the workflow in a few sentences before writing code.

### 2. Choose the Sentinel shape

Map the workflow into one of these patterns:

- single trigger flow
- trigger flow plus connectors
- form-driven kit UI plus event-wired flow
- webhook flow plus modules for transformation
- multi-flow kit only if the original workflow is truly multiple concerns

Do not split into multiple flows just because n8n had many nodes.

### 3. Scaffold the kit

Create:

- `kit.yaml`
- minimal directory set
- initial flow file
- `events.yaml` only if forms are involved

Use Sentinel naming:

- kit dir: `{ns}.{name}`
- flow ID: `{ns}-{name}:{flow}`
- prefer hyphens, not underscores

### 4. Translate triggers correctly

#### n8n trigger mapping

- Webhook node -> lifecycle flow with `triggers = { webhook("/path") }`
- Schedule/Cron node -> lifecycle flow with `triggers = { cron("...") }`
- Event-style source -> lifecycle flow with `triggers = { event("pattern") }`
- Manual/test-only trigger -> plain lifecycle flow callable through `/fl/{id}/run`
- Form submission UX -> form in `fm/` plus `events.yaml` wiring to a flow

Important:

- Standard triggered flows use lifecycle hooks: `setup`, `main`, `cleanup`, `failed`
- Form submission flows may use the trigger-return pattern if that is the cleanest fit
- Do not force form behavior into webhook flows

### 5. Extract connectors and modules

Use a connector when the logic:

- calls an external API
- handles auth headers/signing
- will likely be reused by more than one flow
- benefits from a stable service-specific interface

Use a module when the logic:

- is pure computation
- formats payloads
- normalizes input/output
- ranks, filters, validates, or maps data

Keep in the flow when the logic is:

- short

From ndx-au/sre-init, MIT.

More from ndx-au/sre-init