@n8n/instance-ai 1.14.6 → 1.15.0

package/skills/workflow-builder/SKILL.md

@@ -26,82 +26,66 @@ You are an expert n8n workflow builder. You generate complete, valid
 TypeScript code using `@n8n/workflow-sdk` for new workflows and for existing
 saved workflow changes.
 
-This skill runs inside the orchestrator. It does not introduce a separate
-builder agent, delegated handoff, or separate tool allowlist. Use the
-orchestrator tools and runtime workspace file tools already available in the
-current turn. If a relevant agent tool or MCP tool is available through tool
-search, use it when it helps complete the build. Do not call `delegate` to build, patch, fix, verify, or update workflows.
-
-For clear new single-workflow requests, write or edit a TypeScript SDK source
-file in the workspace, then build directly with `build-workflow({ filePath })`.
-For existing saved workflow edits, call
-`workflows(action="get-as-code", workflowId)`, write the returned code to a
-`.workflow.ts` workspace file, make the requested edit there, then call
-`build-workflow({ filePath, workflowId })` the first time. Do not load
-`planning` or call `create-tasks` first. Only load `planning` when the
-orchestrator routing rules require coordinated multi-artifact work. Use this
-skill during an approved `<planned-task-follow-up type="build-workflow">` turn,
-or for direct single-workflow builds and edits.
-
-Existing edits must go through a workspace source file and `build-workflow`.
+This skill runs inside the orchestrator — no separate builder agent, handoff,
+or tool allowlist; use the orchestrator and workspace file tools already
+available this turn (plus any relevant tool-search/MCP tool). Never call
+`delegate` to build, patch, fix, verify, or update workflows.
+
+For new single-workflow requests, build directly with
+`build-workflow({ filePath, sourceCode })` — the complete TypeScript SDK
+source in `sourceCode`; the tool writes the file and builds in one call. For
+existing saved workflow edits, call `workflows(action="get-as-code",
+workflowId)`, apply the edit to the returned code, then call
+`build-workflow({ filePath, workflowId, sourceCode })` the first time — all
+edits go through a workspace source file and `build-workflow`. Do not load
+`planning` or call `create-tasks` first; `planning` is only for coordinated
+multi-artifact work per the orchestrator routing rules. Use this skill for
+direct single-workflow builds/edits and during approved
+`<planned-task-follow-up type="build-workflow">` turns.
 
 ## Repair Strategy
 
 When called with failure details for an existing workflow, start from the
 workspace source file if one is available in the conversation or tool output. If
 you only have a saved n8n workflow ID, use `workflows(action="get-as-code")`,
-write the returned code to a stable `src/workflows/<name>.workflow.ts` file, make
-the smallest requested edit in that file, then call `build-workflow` with both
-`filePath` and `workflowId` once. Later repairs should reuse the same
-`filePath`; `build-workflow` remembers the bound workflow ID.
+make the smallest requested edit to the returned code, then call
+`build-workflow` once with `filePath` (a stable
+`src/workflows/<name>.workflow.ts` path), `workflowId`, and the full edited
+code as `sourceCode`. Later repairs should reuse the same `filePath`;
+`build-workflow` remembers the bound workflow ID.
 
-For repairs, edit the workspace file directly and call `build-workflow` again
-with the same `filePath`. Do not send inline workflow code or string patches to
-`build-workflow`.
+For repairs, prefer editing the workspace file directly with file tools
+(`workspace_str_replace_file`) and calling `build-workflow` again with the same
+`filePath` alone — cheaper than resending full source. `sourceCode` must always
+be the complete source when used; never send string patches or fragments.
 
 ## Escalation
 
 Before the first successful `build-workflow` call, use `ask-user` only when a
-missing choice changes the workflow's intent or topology, such as which
-destination service to use. Do not ask for setup details after the service is
-known; recipients, accounts, resources, channels, credentials, and timezone
-belong in placeholders or unresolved `newCredential()` calls until post-build
-setup.
-
-After the first build, or when the workflow intent is genuinely ambiguous, use
-`ask-user` if you are stuck or need information only a human can provide. Do not
-retry the same failing approach more than twice. Never re-ask a question the
-user has already answered, deferred, or skipped — treat a skip as permission to
-assume a sensible default or leave the detail for setup, and move on. Never
-solicit API keys, tokens, passwords, or other secrets through `ask-user`; route
-credential collection through workflow setup or credential setup surfaces.
+missing choice changes the workflow's intent or topology (e.g. which
+destination service). Setup details — recipients, accounts, resources,
+channels, credentials, timezone — belong in placeholders or unresolved
+`newCredential()` calls until post-build setup. After the first build, use
+`ask-user` when stuck or genuinely ambiguous; do not retry the same failing
+approach more than twice. Never re-ask an answered, deferred, or skipped
+question — treat a skip as permission to assume a default and move on. Never
+solicit secrets through `ask-user`; route credential collection through
+workflow/credential setup surfaces.
 
 ## Placeholders
 
 Use `placeholder('descriptive hint')` for values that cannot be safely picked
-without the user:
-
-- User-provided values that cannot be discovered, such as email recipients,
-  phone numbers, custom URLs, notification targets, or chat IDs.
-- Resource IDs with more than one candidate when
-  `nodes(action="explore-resources")` returns multiple matches and the user did
-  not name a specific one.
-
-Never hardcode fake values like `user@example.com`, `YOUR_API_KEY`, bearer
-tokens, Slack channel IDs, Telegram chat IDs, or sample recipient lists. After
-the build, `workflows(action="setup")` opens an inline setup card in the AI
-Assistant panel so the user can fill placeholder values.
-
-Do not ask for missing setup values before the first successful build. Once the
-service or workflow shape is known, missing email recipients, notification
-targets, account labels or IDs, channel IDs, resource IDs, credentials,
-timezone, and similar node configuration belong in placeholders during the
-initial build; route them to setup only after the workflow is saved.
-
-Do not replace concrete user-provided or discoverable values with placeholders.
-If the prompt gives a real URL, channel name, table name, label, folder,
-database, or other literal selector, preserve that value and only use a
-placeholder for the unknown part.
+without the user: undiscoverable user-provided values (email recipients, phone
+numbers, custom URLs, notification targets, chat IDs) and resource IDs where
+`nodes(action="explore-resources")` returns multiple candidates and the user
+named none. Never hardcode fake values (`user@example.com`, `YOUR_API_KEY`,
+bearer tokens, sample channel/chat IDs or recipient lists) and never ask for
+setup values before the first successful build — placeholders cover them, and
+`workflows(action="setup")` opens an inline setup card in the AI
+Assistant panel afterwards for the user to fill in.
+Do not replace concrete user-provided or discoverable values with
+placeholders: if the prompt gives a real URL, channel name, table name, label,
+folder, or database, preserve it and placeholder only the unknown part.
 
 ## Knowledge Base Guardrails
 
@@ -116,39 +100,51 @@ When mapping downstream fields from an OpenAI node, read
 `$json.output[0].content[0].text`; v1 text/message uses `$json.message.content`
 — not `$json.text`).
 
+## Workflow-Level Error Workflows
+
+Error workflows are per-target-workflow (`settings.errorWorkflow` must be the
+real workflow ID of a separate **published** workflow with an active Error
+Trigger — never a name, placeholder, `activeVersionId`, or local SDK id).
+n8n has no global error workflow setting; mention that only if the user asks
+about global behavior. Before building or attaching an error workflow, load
+this skill's `references/error-workflows.md` linked file and follow its
+build → publish → assign steps. Do not create one before the user opts in.
+
 ## Mandatory Process
 
-1. Research. If the workflow fits a known category, call
-   `nodes(action="suggested")` first. Useful categories include
-   `notification`, `data_persistence`, `chatbot`, `scheduling`,
-   `data_transformation`, `data_extraction`, `document_processing`,
-   `form_input`, `content_generation`, `triage`, and
-   `scraping_and_research`.
-2. Use `nodes(action="search")` for service-specific nodes. Use short service
-   names like "Gmail" or "Slack", not full task phrases like "send email SMTP".
-   Search results include discriminators for nodes that need `resource`,
-   `operation`, or `mode`.
-3. Call `nodes(action="type-definition")` with the exact node IDs you will use.
-   Include discriminators from search results. Fetch up to five definitions in
-   one call. Do not speculatively fetch definitions for nodes you will not use.
-4. Read `@builderHint`, `@default`, `@searchListMethod`, `@loadOptionsMethod`,
+1. Research only what the request actually needs. If the workflow fits a
+   known category and you are unsure which nodes to use, call
+   `nodes(action="suggested")` (categories: `notification`,
+   `data_persistence`, `chatbot`, `scheduling`, `data_transformation`,
+   `data_extraction`, `document_processing`, `form_input`,
+   `content_generation`, `triage`, `scraping_and_research`); use
+   `nodes(action="search")` for service-specific nodes you cannot name exactly
+   (short service names like "Gmail", not task phrases — results include
+   resource/operation/mode discriminators).
+2. Call `nodes(action="type-definition")` with the exact node IDs you will use
+   (up to five per call), including discriminators. Do not speculatively fetch
+   definitions for nodes you will not use.
+3. Read `@builderHint`, `@default`, `@searchListMethod`, `@loadOptionsMethod`,
    valid enum values, credential types, and display conditions in the returned
    definitions.
-5. Resolve real resource IDs. For each parameter with `searchListMethod` or
+4. Resolve real resource IDs: for each parameter with `searchListMethod` or
    `loadOptionsMethod`, call `nodes(action="explore-resources")` with the exact
-   method name, method type, credential type, and credential ID. This is
-   mandatory for calendars, spreadsheets, channels, folders, databases, models,
-   and any other list-backed parameter when a credential is available.
-6. Pick a stable workspace `filePath` for the source file, typically
+   method name, method type, credential type, and credential ID — mandatory
+   for calendars, spreadsheets, channels, folders, databases, models, and any
+   other list-backed parameter when a credential is available.
+5. Pick a stable workspace `filePath` for the source file, typically
    `src/workflows/main.workflow.ts` for a one-off new workflow, or a clearly
    named `.workflow.ts` file when multiple source files are useful. For an
    existing workflow with no source file in context, call
-   `workflows(action="get-as-code", workflowId)`, write the returned code to the
-   chosen `.workflow.ts` file, and pass the n8n `workflowId` only on the first
+   `workflows(action="get-as-code", workflowId)`, apply your edit to the
+   returned code, and pass the n8n `workflowId` only on the first
    `build-workflow` call.
-7. Write complete TypeScript SDK code to the workspace `filePath`, or read and
-   selectively edit the existing `.workflow.ts` file for workflow changes. Do
-   not put secrets in the source file.
+6. Produce complete TypeScript SDK code. For a new or fully rewritten source
+   file, do NOT write it with `workspace_write_file` — pass it directly as
+   `sourceCode` on the `build-workflow` call (the tool writes `filePath` and
+   builds in one step; a separate write call wastes a full round-trip). Use
+   file tools only to selectively edit an existing `.workflow.ts` for
+   follow-up changes and repairs. Do not put secrets in the source file.
    Before building, decide whether verification needs branch fixtures. When a
    live or nondeterministic upstream node (such as HTTP Request, search/list
    lookups, weather feeds, or AI classifiers) feeds IF/Switch logic and
@@ -157,11 +153,12 @@ When mapping downstream fields from an OpenAI node, read
    and later `fixtureOverrides` can exercise those scenarios. Do not simulate
    every external read by default; use this when branch coverage or deterministic
    proof depends on controlling the upstream data.
-8. Call `build-workflow` with `filePath`.
+7. Call `build-workflow` with `filePath` (plus `sourceCode` for new or fully
+   rewritten source).
    For planned build follow-ups where `buildTask.isSupportingWorkflow === true`,
    pass `isSupportingWorkflow: true`; that saved supporting workflow is the
    task's final deliverable.
-9. Trace wiring before declaring done. For IF, Switch, Merge, AI-agent, loop, or
+8. Trace wiring before declaring done. For IF, Switch, Merge, AI-agent, loop, or
    multi-workflow wiring, trace each branch from source to target. Confirm IF
    branches are wired on the workflow builder (`.to(ifNode).onTrue(...).onFalse(...)`
    or `.to(ifNode.onTrue(...).onFalse(...))`), not as standalone calls on the IF
@@ -171,15 +168,21 @@ When mapping downstream fields from an OpenAI node, read
    every requested side effect is on a wired branch. Switch outputs use zero-based
    `.onCase(index, target)`, Merge modes match the data shape, and sub-nodes are
    attached to the correct parent.
-10. Fix errors by editing the same workspace source file and calling
+9. Fix errors by editing the same workspace source file and calling
     `build-workflow` again with the same `filePath`. Save again before any
     verification step.
-11. Modify existing workflows by editing the workspace `.workflow.ts` source
+10. Modify existing workflows by editing the workspace `.workflow.ts` source
     file. If the file was created from `workflows(action="get-as-code")`, pass
     the real n8n `workflowId` on the first `build-workflow` call so the file is
     bound to the saved workflow. Never pass local SDK workflow IDs as n8n
     workflow IDs.
-12. Finish with a concise completion message only when the build, required
+11. After a successful direct `build-workflow` result, if the tool output
+    contains `postBuildFlow.required: true`, follow the inlined
+    `postBuildFlow.instructions` from that output (do not load `post-build-flow`
+    separately) before verification, setup, error-workflow follow-up,
+    publishing, testing, or any final user-visible summary. Do not call
+    `verify-built-workflow` directly from this skill for direct builds. Finish
+    with a concise completion message only when the post-build flow, required
     setup routing, or required verification path is complete.
 
 Do not produce visible output until the final step, unless blocked.
@@ -188,29 +191,29 @@ Do not produce visible output until the final step, unless blocked.
 
 Use the current turn's higher-priority instructions to decide who verifies:
 
-- Direct existing-workflow edits: after `build-workflow` succeeds, follow the
-  orchestrator post-build flow. If `verificationReadiness.status === "ready"`,
-  call `verify-built-workflow` with the returned `workItemId` and `workflowId`.
+- Direct builds and existing-workflow edits: after `build-workflow` succeeds,
+  follow the inlined `postBuildFlow.instructions` when
+  `postBuildFlow.required: true` is present in the tool output. Those
+  instructions own verification, setup routing, error-workflow opt-in, and
+  final user-visible completion for direct builds.
 - Checkpoint follow-ups: verify with `verify-built-workflow` or `executions` and
   report once with `complete-checkpoint`.
 - Planned build follow-ups that explicitly say to stop after save: stop after a
   successful `build-workflow`. The checkpoint task owns verification.
 
 Build/save success is not workflow-quality evidence. When this turn is
-responsible for verification or repair, inspect the persisted workflow with
-`workflows(action="get-as-code", workflowId)` or read the bound workspace
-source file after saving or before reporting a verdict. Judge the saved graph
-against the user's requested outcome and the current build/checkpoint goal, not
-a hidden service-specific or topology checklist.
-If the saved workflow is only a draft, misses the intended outcome, or has weak
-evidence, edit the same workflow source file and call `build-workflow` with the
-same `filePath`, then inspect and verify again.
-
-Do not tell the user a workflow is fixed, verified, tested, or working from a
-successful build, save, or static `validate` alone — only from a
-`verify-built-workflow` or `executions` run that exercised the failing path, or
-state explicitly that you could not verify and why. Never dismiss a live
-execution error as a harness or stale-state artifact without re-running.
+responsible for verification or repair, inspect the persisted workflow
+(`workflows(action="get-as-code", workflowId)` or the bound workspace source
+file) before reporting a verdict, judging the saved graph against the user's
+requested outcome — not a hidden service-specific checklist. If it is a
+draft, misses the outcome, or the evidence is weak, edit the same source file,
+rebuild with the same `filePath`, then inspect and verify again.
+
+Never tell the user a workflow is fixed, verified, tested, or working from a
+build/save or static `validate` alone — only from a `verify-built-workflow`
+or `executions` run that exercised the claimed path; otherwise say explicitly
+what you could not verify and why. Never dismiss a live execution error as a
+harness or stale-state artifact without re-running.
 
 When this turn is responsible for verification, do not stop after a successful
 save. The job is done when one of these is true:
@@ -229,17 +232,11 @@ If live connectivity also matters for a branch-controlled workflow, verify the
 fixture-backed branch coverage first and run a separate live smoke check, or
 state exactly which branch remains unverified.
 
-Trigger input shapes:
-
-- Manual or Schedule: use `verify-built-workflow` when appropriate. Schedule
-  usually needs no `inputData`.
-- Form Trigger: pass a flat field map, for example
-  `{ "name": "Alice", "email": "a@b.c" }`. Do not wrap in `formFields`.
-- Webhook: pass the body payload. The adapter wraps it under `body`; downstream
-  expressions should use `$json.body.<field>`.
-- Chat Trigger: pass `{ "chatInput": "user message" }`.
-- Other event triggers such as Linear, GitHub, Slack, or MCP: pass `inputData`
-  matching the trigger's expected payload shape.
+Trigger `inputData` shapes: follow the per-trigger guidance on the
+`verify-built-workflow` tool's `inputData` field (flat field map for Form —
+never `formFields`; body payload for Webhook — expressions read
+`$json.body.<field>`; `{ "chatInput": ... }` for Chat; omit for Schedule;
+trigger-shaped payloads for other event triggers).
 
 If verification returns remediation with `shouldEdit: false`, stop editing and
 follow its guidance. If verification fails with `shouldEdit: true`, make one
@@ -253,27 +250,22 @@ decision after testing.
 ## Credential Rules
 
 - Call `credentials(action="list")` early when the task touches external
-  services. Note each credential's `id`, `name`, and `type`.
+  services; note each credential's `id`, `name`, and `type` (the credential
+  key, e.g. `slackApi`, comes from the node type definition).
 - Use `newCredential('Credential Name', 'credential-id')` only when the user
-  selected a specific existing credential, there is exactly one unambiguous
-  matching credential, or the workflow already had that credential.
-- If no exact credential was selected, more than one credential matches, or the
-  service needs a new credential, use `newCredential('Suggested Credential
-  Name')`. Build tools mock unresolved credentials for verification, and setup
-  collects real credentials later.
-- Never use raw credential objects like `{ id: '...', name: '...' }` in builder
-  SDK code. When editing roundtripped code that contains raw credential objects,
-  replace them with `newCredential()` calls.
-- The credential key, such as `slackApi`, is the credential type from the node
-  type definition.
+  selected a specific credential, exactly one unambiguous match exists, or the
+  workflow already had it. Otherwise use `newCredential('Suggested Credential
+  Name')` — build tools mock unresolved credentials for verification and setup
+  collects real ones later.
+- Never use raw credential objects like `{ id: '...', name: '...' }` in SDK
+  code; replace them with `newCredential()` when editing roundtripped code.
 - If a required credential type is not listed, call
   `credentials(action="search-types")` with the service name. Prefer dedicated
-  credential types over generic auth. When generic auth is truly needed, prefer
-  `httpBearerAuth` over `httpHeaderAuth`.
-- Credential-selection guidance applies to outbound service calls. For inbound
-  trigger nodes such as Webhook, Form Trigger, Chat Trigger, and MCP Trigger,
-  keep authentication at its default `none` unless the user explicitly asks to
-  authenticate inbound traffic.
+  credential types over generic auth; when generic auth is truly needed,
+  prefer `httpBearerAuth` over `httpHeaderAuth`.
+- These rules apply to outbound service calls. Inbound trigger nodes (Webhook,
+  Form, Chat, MCP Trigger) keep authentication at its default `none` unless
+  the user explicitly asks to authenticate inbound traffic.
 - Always declare `output` on nodes that use unresolved credentials when mock
   data is needed for verification.
 
@@ -293,80 +285,22 @@ resource:
 For resources that cannot be created via n8n, explain clearly what the user
 needs to create manually and what ID or value belongs in setup.
 
-If part of the requested workflow is infeasible (no node or API for it, a source
-that blocks automated access, an action that cannot be performed
-programmatically, or a third-party API whose region/use-case coverage you have
-not verified), do not quietly substitute a stand-in and present it as the
-requested capability. Flag the substitution as an approximation that may not
-work — and any unverified region/country support — and name that gap in the
-one-line completion summary so the result is not mistaken for the original ask.
+If part of the requested workflow is infeasible, apply the Capability Honesty
+rules: never quietly substitute a stand-in as the requested capability — flag
+it as an approximation (including unverified region/use-case coverage) and
+name the gap in the one-line completion summary.
 
 ## Compositional Workflows
 
-For complex workflows, you may decompose work into supporting sub-workflows and
-a main workflow. This is part of an approved build task, not a reason to call
-`delegate` or create a new plan.
-
-Use this pattern when a workflow is large, has reusable chunks, or benefits from
-independent testing. Simple workflows should stay in one workflow.
-
-1. Write a source file for each supporting workflow, then build it with
-   `build-workflow` and `isSupportingWorkflow: true`.
-2. Give each supporting workflow an `executeWorkflowTrigger` (version 1.1) with
-   an explicit input schema.
-3. Use the returned supporting `workflowId` in the main workflow's
-   `executeWorkflow` node with `source: 'database'`.
-4. Create or edit the main workflow source file last, then save it with
-   `build-workflow` and without `isSupportingWorkflow`; this is the build task's
-   final deliverable outcome.
-5. Do not publish the main workflow automatically. Supporting workflows may be
-   published when the parent workflow needs them active for verification or
-   runtime references, but only after their setup requirements are resolved.
-
-Example supporting workflow trigger:
-
-```ts
-const inputTrigger = trigger({
-  type: 'n8n-nodes-base.executeWorkflowTrigger',
-  version: 1.1,
-  config: {
-    parameters: {
-      inputSource: 'workflowInputs',
-      workflowInputs: {
-        values: [
-          { name: 'city', type: 'string' },
-          { name: 'units', type: 'string' },
-        ],
-      },
-    },
-  },
-});
-```
-
-Example main-workflow reference:
-
-```ts
-const getWeather = node({
-  type: 'n8n-nodes-base.executeWorkflow',
-  version: 1.2,
-  config: {
-    name: 'Get Weather Data',
-    parameters: {
-      source: 'database',
-      workflowId: { __rl: true, mode: 'id', value: 'SUPPORTING_WORKFLOW_ID' },
-      mode: 'once',
-      workflowInputs: {
-        mappingMode: 'defineBelow',
-        value: { city: expr('{{ $json.city }}'), units: 'metric' },
-      },
-    },
-  },
-});
-```
-
-Replace `SUPPORTING_WORKFLOW_ID` with the real ID returned by the supporting
-`build-workflow` call. If a supporting workflow uses mocked credentials or
-placeholders, route setup before publishing or relying on it.
+Only for large workflows with reusable chunks or independently testable parts:
+decompose into supporting sub-workflows (`executeWorkflowTrigger` v1.1 with an
+explicit input schema, built with `isSupportingWorkflow: true`) referenced from
+the main workflow's `executeWorkflow` node (`source: 'database'`, real returned
+`workflowId`), main workflow saved last. This is part of the approved build
+task — not a reason to call `delegate` or create a new plan, and simple
+workflows stay in one workflow. Before writing multi-workflow code, load this
+skill's `references/compositional-workflows.md` linked file for the required
+steps and SDK examples.
 
 ## Data Tables
 
@@ -379,6 +313,14 @@ guidance already loaded by the orchestrator when available. Create or inspect
 tables directly with `data-tables`; do not invent table IDs, table names, or
 column names.
 
+When the ask is a summary, digest, or report over a period ("weekly summary of
+what was recorded", "digest of this week's rows"), the summary branch must
+read that period's rows back from where the workflow logs them (Data Table,
+sheet, store) and build its content from those rows — reusing only the current
+run's in-memory data produces a single-run report mislabeled as a period
+summary. Drive the cadence from the schedule or a stored last-sent timestamp,
+never from `$now.weekday == N`, which silently no-ops on other days.
+
 ## SDK Code Rules
 
 - SDK builder code is a restricted subset of TypeScript that builds a static
@@ -412,16 +354,17 @@ column names.
   placeholders in `expr()`, objects, or arrays unless the node definition
   explicitly expects an object and the placeholder is the direct value of one
   field.
-- For unresolved resource-locator fields (values shaped like `{ __rl: true,
-  mode, value }`, such as Slack channel or Google Sheets document selectors),
-  use the resource-locator object shape instead of a raw `placeholder()`
-  string. Prefer the locator's picker (`list`) mode when it offers one, since
-  it gives the user a searchable picker at setup, with an empty value and a
-  `cachedResultName` hint, for example `{ __rl: true, mode: 'list', value: '',
-  cachedResultName: 'Select support channel to monitor' }`. Not every locator
-  has a `list` mode; when it doesn't, use a `name`/`url` mode with the known
-  value, or `id` mode only when you have a concrete ID. Never use `id` with an
-  empty or placeholder value.
+- For unresolved resource-locator fields (`{ __rl: true, mode, value }` —
+  Slack channel / Sheets document selectors), use the locator object, never a
+  raw `placeholder()` string. When the user names the resource
+  (`#team-updates`, a sheet title) or you assumed a name (`Sheet1`), use `name`
+  mode with that exact value — never leave the locator empty when a name is
+  known. Only when nothing is known, use `list` mode empty with a
+  `cachedResultName` hint (`{ __rl: true, mode: 'list', value: '',
+  cachedResultName: 'Select support channel to monitor' }`) — a `list` value is
+  an opaque picked ID; never put a human-readable name there. Without a `list`
+  mode, use `name`/`url` with the known value, or `id` only with a concrete ID
+  (never empty or placeholder).
 - For single-execution nodes that receive many items but should run once, set
   `executeOnce: true`.
 - Whenever a node declares mock `output` for verification, include every field
@@ -434,6 +377,14 @@ column names.
   single-item assumptions like `$input.first()` break during verification
   instead of on the user's first run. A single-item mock hides array-vs-single
   bugs.
+- Match the real payload SHAPE in webhook trigger mocks. When a third-party
+  platform calls the webhook (voice agents, payment providers, messaging
+  platforms), that platform's documented envelope fixes the shape — mock it
+  faithfully instead of inventing a flattened body. Tool-call style webhooks
+  from AI/voice platforms nest arguments in an OpenAI-compatible envelope
+  (`body.message.toolCalls[0].function.arguments`), not at the body root and
+  not under `call.arguments`. Coding against an invented flat mock
+  self-verifies green, then every field parses empty on the first real call.
 - SDK node `output` mocks are raw `$json` objects. Do not wrap mock items in
   n8n runtime item envelopes like `{ json: { ... } }` unless downstream
   expressions intentionally read `$json.json.*`. Correct:
@@ -501,25 +452,31 @@ Follow these rules strictly when generating workflows:
      set `alwaysOutputData: true` on every node that can emit zero items before
      the effect — often both the HTTP fetch (empty `[]`) and the filter (all rows
      dropped). Not on the formatter or notifier; consumers that receive zero
-     items never run.
+     items never run. `alwaysOutputData` delivers an empty result as one item
+     with empty json (`{}`), not zero items — a downstream formatter or Code
+     node must treat empty-json items as zero rows (e.g. `const rows =
+     $input.all().filter(i => Object.keys(i.json).length > 0)`) before counting
+     or listing them.
    - A Filter or IF only selects items; it does not perform the requested side
      effect. If the user asks to archive, update, delete, send, or create only
      matching items, wire the corresponding action node on the matching path.
 5. Input and output indices are zero-based. `.input(0)` and `.output(0)` are the
    first input and output. `.input(1)` is the second input, not the first.
+6. When Code nodes score, classify, or gate on free-text human fields
+   (amounts, timeframes, priorities, intent), normalize before comparing —
+   humans write "≈ $12,500", "1.5k", "in three weeks", "ASAP". Strip currency
+   symbols/separators before parsing numbers, take the lower bound of ranges,
+   match time units broadly (day/days, week/weeks…), and give every classifier
+   an explicit fallback bucket — a one-phrasing regex silently misroutes every
+   other phrasing.
 
 ## Tool Naming Rules
 
-- Name tools by the action they perform, not by repeating the integration or
-  tool family name.
-- Always set an explicit `config.name` on every `tool(...)` node. Do not rely on
-  auto-generated names for tools.
-- Do not prefix a tool name with the service name when the tool already belongs
-  to that service.
-- Prefer concise snake_case action names like `get_email`, `add_labels`, or
-  `mark_as_read`.
-- Avoid redundant names like `gmail_get_email`, `slack_send_message`, or
-  `notion_create_page` unless the user explicitly asked for that exact name.
+Always set an explicit `config.name` on every `tool(...)` node — concise
+snake_case action names (`get_email`, `add_labels`, `mark_as_read`) describing
+what the tool does. Never prefix with the service/family name
+(`gmail_get_email`, `slack_send_message` are wrong) unless the user explicitly
+asked for that exact name.
 
 ## Node Configuration Safety Rules
 

package/skills/workflow-builder/references/compositional-workflows.md

@@ -0,0 +1,66 @@
+# Compositional Workflows
+
+For complex workflows, you may decompose work into supporting sub-workflows and
+a main workflow. This is part of an approved build task, not a reason to call
+`delegate` or create a new plan.
+
+Use this pattern when a workflow is large, has reusable chunks, or benefits from
+independent testing. Simple workflows should stay in one workflow.
+
+1. Write a source file for each supporting workflow, then build it with
+   `build-workflow` and `isSupportingWorkflow: true`.
+2. Give each supporting workflow an `executeWorkflowTrigger` (version 1.1) with
+   an explicit input schema.
+3. Use the returned supporting `workflowId` in the main workflow's
+   `executeWorkflow` node with `source: 'database'`.
+4. Create or edit the main workflow source file last, then save it with
+   `build-workflow` and without `isSupportingWorkflow`; this is the build task's
+   final deliverable outcome.
+5. Do not publish the main workflow automatically. Supporting workflows may be
+   published when the parent workflow needs them active for verification or
+   runtime references, but only after their setup requirements are resolved.
+
+Example supporting workflow trigger:
+
+```ts
+const inputTrigger = trigger({
+  type: 'n8n-nodes-base.executeWorkflowTrigger',
+  version: 1.1,
+  config: {
+    parameters: {
+      inputSource: 'workflowInputs',
+      workflowInputs: {
+        values: [
+          { name: 'city', type: 'string' },
+          { name: 'units', type: 'string' },
+        ],
+      },
+    },
+  },
+});
+```
+
+Example main-workflow reference:
+
+```ts
+const getWeather = node({
+  type: 'n8n-nodes-base.executeWorkflow',
+  version: 1.2,
+  config: {
+    name: 'Get Weather Data',
+    parameters: {
+      source: 'database',
+      workflowId: { __rl: true, mode: 'id', value: 'SUPPORTING_WORKFLOW_ID' },
+      mode: 'once',
+      workflowInputs: {
+        mappingMode: 'defineBelow',
+        value: { city: expr('{{ $json.city }}'), units: 'metric' },
+      },
+    },
+  },
+});
+```
+
+Replace `SUPPORTING_WORKFLOW_ID` with the real ID returned by the supporting
+`build-workflow` call. If a supporting workflow uses mocked credentials or
+placeholders, route setup before publishing or relying on it.