n8n-workflow-builder

name	n8n-workflow-builder
description	Compose and chain cleaned snippets into n8n operational triage workflows — a webhook trigger, read-only idempotent triage steps in order, and a markdown-to-HTML response served back to the caller. Produces n8n workflow JSON in tools/n8n/workflows/ ready to POST to the n8n API (you post it, not the skill), plus a local_workflow.sh equivalent a developer can run without n8n. Use when building or iterating a triage workflow from cleaned snippets.
owner	Compliance and Enforcement
tags	["n8n","workflow","triage","webhook","automation"]

Workflow Builder

Takes cleaned snippets (produced by the runbook-parser skill) and chains them into an n8n workflow JSON that performs operational triage. The workflow is webhook-triggered and serves an HTML page of the results, so an operator can click a URL and read the triage report in a browser.

Every step is read-only and idempotent — the cleaned-snippet contract already guarantees this, and this skill restates it on each node as a second line of defence. No mutating steps (writes, restarts, restores, schema/config edits) ever go into a triage workflow.

Shape of every workflow this skill builds:

[Sticky Note: production URL]   [Webhook (responseMode=responseNode)]
                                          │
        ┌─────────────────────────────────┘
        ▼
  snippet · snippet · …  →  Merge snippets (merge.sh)      (Execute-Command, one per snippet, read-only)
        ▼
  validator · validator · …  →  Merge validations (merge.sh -k)
        ▼
  Report (report.sh) → Respond to Webhook — serves a marked.js page (Content-Type: text/html)

It writes the JSON to tools/n8n/workflows/<name>.json. It does not POST it — push.sh does that (this skill owns it; see below).

Alongside the JSON it emits a local equivalent — tools/n8n/workflows/<name>.local.sh, the same chain as a shell script (collect snippets -> merge -> render.sh -> view.sh) so a developer can run the triage locally and read the HTML report in a browser, no n8n needed. See references/LOCAL_WORKFLOW.md.

The chain's lib scripts — merge.sh, report.sh, render.sh, view.sh, utils.sh, n8n-entrypoint.sh — plus the n8n API client push.sh / pull.sh live in this skill under scripts/ (it owns them; the n8n image, the local workflow, and devs syncing workflows to/from n8n all call them). They self-locate via $0 and resolve utils.sh / render.sh / snippets/<group> relative to that location, so they must run from the triage tree root, alongside snippets/. scripts/sync.sh --config <config.yaml> does exactly that — copies every canonical script (lib scripts and push/pull) to the tree root, which it derives from the config's directory (idempotent; --check verifies without writing). When building an n8n image, run it so the scripts sit beside the Dockerfile — as committed here in tools/n8n/, which the Dockerfile bakes into /opt/triage and n8n-entrypoint.sh puts on PATH. scripts/ is canonical (the skill is installed separately). The local workflow does not self-sync — before a local run (or a push/pull), the agent runs sync.sh --check and, if it reports drift, sync.sh to refresh the deployed copies, so the dev always runs the installed skill's current scripts (unless the dev syncs themselves). See "Keeping the deployed scripts current" below.

Use When

• Building an n8n triage workflow by chaining cleaned snippet-* blocks from snippets/<group>/.
• Iterating on an existing triage workflow (add/remove/re-order steps).
• Producing n8n workflow JSON to hand to push.sh / the n8n API.

Don't Use When

• Cleaning raw snippets into cleaned blocks → use the runbook-parser skill (references/CLEANING.md).
• Posting or pulling workflow JSON to/from n8n → use this skill's push.sh / pull.sh. Set N8N_API_KEY and point them at the project's config (--config <tree-root>/config.yaml or N8N_CONFIG=...); they read workflows/ beside it. The copy deployed at the tree root finds its sibling config.yaml automatically, so a synced/dev run needs no flag.
• Any mutating or non-triage automation → this skill only emits read-only, idempotent triage.

Workflow

1. Choose the cleaned snippets to chain, in triage order, from snippets/<group>/. If none exist yet, run the runbook-parser cleaning step first.
2. Copy assets/skeleton.json as the starting point — it already has the Sticky Note (with the production URL placeholder), the Webhook (responseMode: responseNode), and the Report -> Respond tail.
3. Give every snippet and validator its OWN n8n-nodes-base.executeCommand node, one call each: a collection node runs NAMESPACE={{ ($('Webhook').item.json.query||{}).namespace }} snippet-*.sh; a validator node pipes the merged JSON in with echo {{ $('Merge snippets').item.json.stdout.base64Encode() }} | base64 -d | validator-*.sh. Set each node's notes to a brief, specific line on what it does (references/N8N_NODES.md).
4. Join with tools/n8n/merge.sh, never a Code node. A "Merge snippets" node lists one export MERGE_<KEY>={{ $('<collection node>').item.json.stdout.base64Encode() }} per collection node, then merge.sh --b64 (flat — snippet fields stay top-level). A "Merge validations" node does the same over the validator nodes (key = the check name), then merge.sh -k --b64 (keyed -> the .validations object).
5. Render with one "Report" node: export DATA={{ $('Merge snippets').item.json.stdout.base64Encode() }}, export VALS={{ $('Merge validations').item.json.stdout.base64Encode() }}, export NAMESPACE={{ … }}, then report.sh <group> <report.md> … — report.sh assembles merged + {validations} and renders the chained report. End with a single Respond node that serves the report markdown as a marked.js + github-markdown-css page (Content-Type: text/html) — no Markdown node, identical to view.sh (see references/N8N_NODES.md).
6. Fill the Sticky Note from assets/sticky-note.md: substitute <BASE_URL> (config.yaml spec.n8n.base_url), <PATH> (the Webhook path = workflow name), <TITLE>, and <QUERY>.
7. Write valid workflow JSON (name, nodes, connections, settings) to tools/n8n/workflows/<name>.json per references/API_SCHEMA.md. Do not POST it.
8. Emit the local equivalent: copy assets/local-workflow.sh to tools/n8n/workflows/<name>.local.sh and fill it — it runs the same merge.sh / report.sh, so local and n8n stay in lockstep, and it must pass shellcheck. See references/LOCAL_WORKFLOW.md.

Rules

• Every node is read-only and idempotent — the cleaned-snippet contract makes triage safe to fire repeatedly from a webhook. Keep notes brief and specific to what the node does; don't restate read-only/idempotent or repeat boilerplate (a reviewer sees that in the snippet itself).
• Never include a mutating step. If a cleaned snippet is not read-only, it should already be dropped upstream; never add one here.
• Always start with a Webhook trigger plus a Sticky Note holding the production URL, built from assets/sticky-note.md with the host from config.yaml spec.n8n.base_url (<base_url>/webhook/<workflow-name>) — never hardcode a host.
• Always end with a Report node (report.sh) -> Respond to Webhook that serves the report markdown as a marked.js page with Content-Type: text/html; the Webhook node responseMode must be responseNode.
• Emit only the API-writable fields (name, nodes, connections, settings); never POST — hand the file to push.sh.
• Give every node a unique name and id, and wire connections by node name.
• Each snippet and validator is its own one-call Execute-Command node, and the report is one report.sh node — copy-pasteable, reorderable within their group. Join with tools/n8n/merge.sh, NEVER a Code node: a "Merge snippets" node (merge.sh --b64, flat) and a "Merge validations" node (merge.sh -k --b64, keyed by check) (Why: transparent + no jsCode reaching into nodes by name).
• Keep each node command short — a snippet/validator call is well under ~200 chars and stays a plain JSON string. The exception is a merge/report node whose export … block is multi-line and long; store THAT command as a JSON array of lines (one element per line) so git diffs stay readable. push.sh joins the array with \n (the string n8n wants); pull.sh splits a > 200-char multi-line command back to an array — both accept either form. Pass node stdout base64-encoded ({{ $('node').item.json.stdout.base64Encode() }} + merge.sh --b64) so JSON survives the shell.
• n8n node commands call the baked scripts by bare name (merge.sh, report.sh crunchy-triage …, snippet-*.sh). The image bakes the triage tree under /opt/triage (NOT /data, a runtime PVC mount that shadows it) and chmod +x's the scripts; the n8n-entrypoint.sh wrapper adds /opt/triage + every baked snippets/<group> dir to PATH at startup, so any group the team adds just works — no per-group Dockerfile edit. (local-workflow.sh calls the same scripts as bash "$N8N/…" from its own location — dev machines have nothing on PATH.)
• The lib scripts live in scripts/ (canonical) and must be deployed to the triage tree root alongside snippets/ to run. scripts/sync.sh --config <config.yaml> deploys/verifies them (--check guards CI). For an n8n image build, run it so the scripts sit beside the Dockerfile (committed here as tools/n8n/*.sh).

Keeping the deployed scripts current

The deployed copies under the tree root are produced by sync.sh; nothing self-syncs. Locate the dev's RunbookParser config — the --config/N8N_CONFIG pointer all three scripts share — then act on it:

• Find the config: honor N8N_CONFIG if set, else the RunbookParser default tools/n8n/config.yaml (the parser's default; its directory is the triage tree root). That one path drives everything — sync.sh deploys into its directory; push.sh/pull.sh read workflows/ beside it.
• Before a local run, a push, or a pull: run bash <skill>/scripts/sync.sh --check --config <config>. If it reports drift (exit 1), run it without --check to refresh — unless the dev says they sync themselves. The dev only ever needs to set N8N_API_KEY; the agent supplies --config.
• Then run the tool with the same pointer, e.g. N8N_API_KEY=… push.sh --config <config> (or pull.sh --config <config>), or invoke the deployed copy from the tree root where config.yaml is its sibling and no flag is needed.
• Emit the local-workflow.sh equivalent too — it runs the SAME merge.sh / report.sh, so local and n8n stay in lockstep; it must pass shellcheck.
• Shellcheck every .sh this skill produces (the local-workflow.sh) before signing off; fall back to bash -n only if shellcheck is unavailable.

Examples

• "Build a triage workflow from these cleaned blocks" then chain the collection snippets in order, end with markdown->HTML->respond, and write tools/n8n/workflows/<name>.json.
• "Add another check to the workflow" then insert one Execute-Command node and rewire connections.
• "Serve the report as a web page" then confirm the Webhook is responseNode and the final Respond-to-Webhook sets Content-Type: text/html.

Edge Cases

• A snippet emits non-JSON then normalize it in a Code node before chaining.
• No cleaned snippets exist then run the runbook-parser cleaning step first.
• The page renders blank then check the Respond node's page got the Report stdout (the base64 expression resolves) and that responseMode is responseNode.
• Long-running steps then keep the webhook responsive by chaining quick read-only checks; do not block on anything that mutates or waits.

References

• references/N8N_NODES.md — the node JSON for each type (webhook, sticky note, execute-command, respond-to-webhook), the merge/report nodes, connections, and the serve-HTML (marked.js) pattern.
• references/API_SCHEMA.md — the n8n workflow JSON schema to POST (name/nodes/ connections/settings), per the n8n API reference; push.sh posts it.
• assets/skeleton.json — a minimal, importable workflow (sticky + webhook + collect + merge + report + respond) to copy and extend.
• assets/sticky-note.md — the standard Sticky Note (Production URL) content; fill <BASE_URL> from config.yaml spec.n8n.base_url.
• assets/local-workflow.sh — the local-workflow skeleton (the shell equivalent) to copy to tools/n8n/workflows/<name>.local.sh and fill.
• scripts/ — the chain's lib scripts (merge.sh, report.sh, render.sh, view.sh, utils.sh, n8n-entrypoint.sh) and the n8n API client (push.sh, pull.sh), plus sync.sh, which deploys/verifies them all into the triage tree root (derived from --config <config.yaml>) alongside snippets/ (--check for CI; committed there as tools/n8n/*.sh). The agent runs sync.sh before a local run / push / pull — nothing self-syncs.
• references/LOCAL_WORKFLOW.md — the local-workflow mapping (n8n node -> shell stage), merging, and the view.sh helper.
• scripts/view.sh — builds the marked.js + github-markdown-css page for the local workflow; the n8n Respond node serves the same page (keep them in sync).
• ../runbook-parser/references/CLEANING.md — where the cleaned snippets come from.