refactor(instance-ai): Harmonize prompting between builders (no-changelog)

[OlegIvaniv]

Summary

Both instance-ai and ai-workflow-builder.ee had their own forked copies of the same prompting content, expression references, workflow rules, parameter guides, best-practices docs, node recommendations. When one got updated the other drifted. This PR moves all of that shared content into @n8n/workflow-sdk/prompts (both packages already depend on workflow-sdk) so there's a single source of truth, then deletes the 46 dead files that got replaced.

Also fixes a bug in the search-nodes tool where multi-word queries like "data table tool" returned 0 results when combined with connectionType, which meant the builder couldn't find auto-generated tool nodes (dataTableTool, googleCalendarTool, etc).

What changed

Moved SDK reference constants (expression reference, additional functions, workflow rules, SDK patterns) into workflow-sdk/src/prompts/sdk-reference/. Both packages now import from there.

Moved all 11 parameter guides (IF, Switch, Set, HTTP, Gmail, etc.), 2 node tips (Webhook, Structured Output Parser), and 4 node recommendations (text/image/video/audio generation) into workflow-sdk/src/prompts/node-guidance/. Extracted types locally so there's no dependency on framework-specific packages.

Moved the WorkflowTechnique enum, BestPracticesDocument interface, and all 16 guide classes into workflow-sdk/src/prompts/best-practices/. This also wired up 5 guides that were previously commented out (data-analysis, enrichment, knowledge-base, human-in-the-loop, monitoring).

Replaced the ~300-line inline SDK_RULES_AND_PATTERNS block in instance-ai's builder prompt with composed imports from the shared parameter guides. The instance-ai-specific stuff (AI Agent subnodes, Code Node, Data Table, Google Sheets, web app pattern) stays local.

Deleted 46 original source files across both packages (~5,900 lines).

Fixed searchByConnectionType in the node search engine, it was calling sublimeSearch directly with the raw query string, which breaks on multi-word input. Extracted a fuzzySearchNodes method (with per-term splitting + display-name fallback) that both searchByName and searchByConnectionType now share. Also improved the connectionType param description so the agent actually knows to use connectionType="ai_tool" when looking for tool nodes to attach to an AI Agent.

Layout

@n8n/workflow-sdk/src/prompts/
├── index.ts
├── sdk-reference/          expressions, functions, rules, patterns
├── node-guidance/
│   ├── parameter-guides/   11 guides + types
│   ├── node-tips/          2 tips + types
│   └── node-recommendations/  4 recs + types + format utility
└── best-practices/
    ├── types.ts            WorkflowTechnique enum, interfaces
    └── guides/             16 guide classes + registry

Review / Merge checklist

• I have seen this code, I have run this code, and I take responsibility for this code.
• PR title and summary are descriptive. (conventions)
• Docs updated or follow-up ticket created.
• Tests included.
• PR Labeled with Backport to Beta, Backport to Stable, or Backport to v1 (if the PR is an urgent fix that needs to be backported)

[github-actions]

! PR exceeds size limit (1,713 lines added)

This PR adds 1,713 lines, exceeding the 1,000-line limit (test files excluded).

Large PRs are harder to review and increase the risk of bugs going unnoticed. Please consider:

• Breaking this into smaller, logically separate PRs
• Moving unrelated changes to a follow-up PR

If the size is genuinely justified (e.g. generated code, large migrations, test fixtures), a maintainer can override by commenting /size-limit-override and then pushing a new commit or re-running this check.

[codecov]

Codecov Report

❌ Patch coverage is 13.79310% with 125 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...n/workflow-sdk/src/prompts/best-practices/index.ts	0.00%	30 Missing ⚠️
...ance/node-recommendations/format-recommendation.ts	0.00%	14 Missing ⚠️
...rc/prompts/node-guidance/parameter-guides/index.ts	0.00%	11 Missing ⚠️
...rompts/node-guidance/node-recommendations/index.ts	0.00%	8 Missing ⚠️
packages/@n8n/workflow-sdk/src/prompts/index.ts	0.00%	7 Missing ⚠️
...n/workflow-sdk/src/prompts/node-selection/index.ts	0.00%	5 Missing ⚠️
...8n/workflow-sdk/src/prompts/sdk-reference/index.ts	0.00%	5 Missing ⚠️
...8n/workflow-sdk/src/prompts/node-guidance/index.ts	0.00%	3 Missing ⚠️
...sdk/src/prompts/sdk-reference/workflow-patterns.ts	0.00%	3 Missing ⚠️
...n/workflow-sdk/src/prompts/best-practices/types.ts	0.00%	2 Missing ⚠️
... and 32 more

📢 Thoughts on this report? Let us know!

[cubic-dev-ai]

2 issues found across 83 files

Note: This PR contains a large number of files. cubic only reviews up to 75 files per PR, so some files may not have been reviewed. cubic prioritises the most important files to review.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/@n8n/ai-workflow-builder.ee/src/types/node-recommendations.ts">

<violation number="1" location="packages/@n8n/ai-workflow-builder.ee/src/types/node-recommendations.ts:11">
P1: Custom agent: **Quality & Performance Review**

Avoid re-exporting from the root `@n8n/workflow-sdk/prompts` barrel here; it eagerly loads unrelated prompt modules and increases baseline memory for consumers of this type file. Re-export from the narrower node-recommendations entrypoint instead.</violation>
</file>

<file name="packages/@n8n/workflow-sdk/src/prompts/sdk-reference/workflow-patterns.ts">

<violation number="1" location="packages/@n8n/workflow-sdk/src/prompts/sdk-reference/workflow-patterns.ts:218">
P2: The parallel execution pattern uses two separate trigger instances, so the Merge inputs won’t be produced in the same execution. Use a single trigger node feeding both branches.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant Agent as AI Agent / Orchestrator
    participant InstanceAI as instance-ai (Package)
    participant EEBuilder as ai-workflow-builder.ee (Package)
    participant SDK as @n8n/workflow-sdk/prompts
    participant Search as NodeSearchEngine

    Note over InstanceAI, SDK: Prompt Construction Flow (Consolidated)

    InstanceAI->>SDK: NEW: Import SDK Reference (Rules, Expressions)
    EEBuilder->>SDK: NEW: Import Best Practices & Node Guidance
    
    alt Request for Best Practices
        Agent->>InstanceAI: get_best_practices(technique)
        InstanceAI->>SDK: NEW: bestPracticesRegistry.getDocumentation()
        SDK-->>InstanceAI: Return Markdown content
        InstanceAI-->>Agent: Formatted Best Practices
    end

    alt Request to Build/Update Workflow
        InstanceAI->>SDK: NEW: Fetch Parameter Guides (IF, Switch, Set, etc.)
        InstanceAI->>InstanceAI: Compose System Prompt with SDK Rules
        InstanceAI-->>Agent: Validated instructions for code generation
    end

    Note over Agent, Search: Node Discovery Flow (Improved Multi-word Search)

    Agent->>InstanceAI: search_nodes(query="google calendar tool", connectionType="ai_tool")
    InstanceAI->>Search: fuzzySearchNodes("google calendar tool")
    
    Search->>Search: CHANGED: Split query into terms ["google", "calendar", "tool"]
    
    loop For each term
        Search->>Search: Perform sublimeSearch against node database
    end
    
    Search->>Search: CHANGED: Merge scores + fallback to display name matches
    
    opt Filter by Connection Type
        Search->>Search: CHANGED: Intersect fuzzy results with ai_tool connections
    end
    
    Search-->>InstanceAI: Ranked search results
    InstanceAI-->>Agent: JSON Node Definitions (including auto-generated tools)

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.}

[cubic-dev-ai]

1 issue found across 17 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/@n8n/workflow-sdk/package.json">

<violation number="1" location="packages/@n8n/workflow-sdk/package.json:21">
P2: This change introduces a breaking public API change by removing the `@n8n/workflow-sdk/prompts` subpath export. Keep a compatibility alias for `./prompts` (and its `typesVersions` entry) to avoid breaking existing consumers.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.}

[github-actions]

Performance Comparison

Comparing current → latest master → 14-day baseline

Idle baseline with Instance AI module loaded

Metric	Current	Latest Master	Baseline (avg)	vs Master	vs Baseline	Status
instance-ai-heap-used-baseline	186.33 MB	186.02 MB	186.31 MB (σ 0.25)	+0.2%	+0.0%	✅
instance-ai-rss-baseline	344.02 MB	380.71 MB	369.52 MB (σ 24.20)	-9.6%	-6.9%	⚠️

Memory consumption baseline with starter plan resources

Metric	Current	Latest Master	Baseline (avg)	vs Master	vs Baseline	Status
memory-rss-baseline	355.00 MB	352.66 MB	283.64 MB (σ 42.70)	+0.7%	+25.2%	⚠️
memory-heap-used-baseline	113.86 MB	114.20 MB	113.67 MB (σ 1.06)	-0.3%	+0.2%	✅

docker-stats

Metric	Current	Latest Master	Baseline (avg)	vs Master	vs Baseline	Status
docker-image-size-n8n	1269.76 MB	1269.76 MB	1269.76 MB (σ 0.00)	+0.0%	+0.0%	—
docker-image-size-runners	393.00 MB	418.00 MB	391.43 MB (σ 11.93)	-6.0%	+0.4%	✅

How to read this table

• Current: This PR's value (or latest master if PR perf tests haven't run)
• Latest Master: Most recent nightly master measurement
• Baseline: Rolling 14-day average from master
• vs Master: PR impact (current vs latest master)
• vs Baseline: Drift from baseline (current vs rolling avg)
• Status: ✅ within 1σ | ⚠️ 1-2σ | 🔴 >2σ regression

[cubic-dev-ai]

1 issue found across 5 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/@n8n/workflow-sdk/src/prompts/best-practices/index.ts">

<violation number="1" location="packages/@n8n/workflow-sdk/src/prompts/best-practices/index.ts:48">
P1: This change disables five best-practice guides in the registry, so lookups for those techniques now return `undefined` instead of a document.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.}

[mutdmour]

Looks good. thanks for addressing my feedback

[n8n-assistant]

Got released with n8n@