@n8n-as-code/n8nac 2026.3.1 → 2026.4.0-next.11

package/README.md

@@ -37,8 +37,10 @@ Once setup is done, just talk to OpenClaw:
 
 > "What operations does the Google Sheets node support?"
 
-The plugin injects the full n8n-architect instructions into every conversation
-so the AI knows the exact `n8nac` workflow (init-check → pull → edit → push → verify).
+The plugin now keeps its default prompt hook lightweight. OpenClaw can activate
+the bundled `n8n-architect` skill for explicit n8n workflow sessions, and that
+skill then reads the generated workspace `AGENTS.md` for the full workflow
+engineering guidance.
 
 ## CLI commands
 

package/index.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { accessSync, constants, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { registerN8nAcCli } from "./src/cli.js";
@@ -6,7 +6,7 @@ import { createN8nAcTool } from "./src/tool.js";
 import { getWorkspaceDir, isWorkspaceInitialized } from "./src/workspace.js";
 
 // ---------------------------------------------------------------------------
-// AGENTS.md context injection — populated once on service start
+// Lightweight prompt context
 // ---------------------------------------------------------------------------
 
 const BOOTSTRAP_CONTEXT = `\
@@ -21,20 +21,6 @@ Once you have both, call the \`n8nac\` tool with \`action: "init_auth"\`, then
 \`action: "init_project"\` to finish setup.
 `;
 
-const MISSING_AGENTS_CONTEXT = `\
-## n8n-as-code — AI Context Missing
-
-The workspace is initialized, but the generated AI context file (\`AGENTS.md\`) is missing or unreadable.
-
-**Tell the user:**
-> "Your n8n-as-code workspace is connected, but the AI context needs to be regenerated before I can safely guide workflow changes."
-
-Ask the user to run \`npx --yes n8nac update-ai\` in the OpenClaw workspace, or rerun
-\`openclaw n8nac:setup\` if they want the setup wizard to repair it.
-`;
-
-let agentsContext: string | null = null;
-
 function readConfig(workspaceDir: string): Record<string, string> {
   try {
     const raw = readFileSync(join(workspaceDir, "n8nac-config.json"), "utf-8");
@@ -56,26 +42,46 @@ function buildStatusHeader(workspaceDir: string): string {
     `- Workspace directory: \`${workspaceDir}\``,
     `- n8n host: \`${host}\``,
     `- Active project: \`${project}\``,
-    "",
-    "Skip the 'Workspace Bootstrap' section below — setup is complete.",
-    "Proceed directly to the user's request using the `n8nac` tool.",
-    "",
-    "---",
-    "",
   ].join("\n");
 }
 
-function loadAgentsContext(workspaceDir: string): string | null {
-  const p = join(workspaceDir, "AGENTS.md");
-  if (!existsSync(p)) return null;
+function hasAgentsContext(workspaceDir: string): boolean {
+  const agentsPath = join(workspaceDir, "AGENTS.md");
   try {
-    const raw = readFileSync(p, "utf-8");
-    return buildStatusHeader(workspaceDir) + raw;
+    accessSync(agentsPath, constants.R_OK);
+    return true;
   } catch {
-    return null;
+    return false;
   }
 }
 
+export function buildPromptContext(workspaceDir: string): string {
+  if (!isWorkspaceInitialized(workspaceDir)) {
+    return BOOTSTRAP_CONTEXT;
+  }
+
+  const agentsPath = join(workspaceDir, "AGENTS.md");
+  const guidanceLines = hasAgentsContext(workspaceDir)
+    ? [
+        "",
+        "Detailed workflow-authoring guidance is intentionally scoped to the `n8n-architect` skill.",
+        "Only use that deeper n8n workflow context when the request is clearly about n8n workflow work.",
+        `When that happens, read \`${agentsPath}\` for workspace-specific instructions.`,
+      ]
+    : [
+        "",
+        "Detailed workflow-authoring guidance is intentionally scoped to the `n8n-architect` skill, but the generated workspace AI context file (`AGENTS.md`) is missing.",
+        "If the user starts explicit n8n workflow work, regenerate `AGENTS.md` with `npx --yes n8nac update-ai` or rerun `openclaw n8nac:setup` first.",
+      ];
+
+  return [
+    buildStatusHeader(workspaceDir),
+    ...guidanceLines,
+    "",
+    "For unrelated requests, ignore this plugin context.",
+  ].join("\n");
+}
+
 // ---------------------------------------------------------------------------
 // Plugin
 // ---------------------------------------------------------------------------
@@ -94,19 +100,10 @@ const n8nAcPlugin = {
     mkdirSync(workspaceDir, { recursive: true });
 
     // -- Context injection ---------------------------------------------------
-    // Prepend n8n-architect instructions to every prompt build.
+    // Keep default context lightweight; full workflow-authoring guidance lives
+    // in the bundled `n8n-architect` skill and the workspace AGENTS.md file.
     api.on("before_prompt_build", () => {
-      const initialized = isWorkspaceInitialized(workspaceDir);
-      // Lazy-load: setup may have run after the gateway started, so the
-      // service start() missed it.  Re-attempt on every prompt until loaded.
-      // The status header embeds host + project, so re-read on every call
-      // when not yet cached to pick up fresh config after setup.
-      if (agentsContext === null && initialized) {
-        agentsContext = loadAgentsContext(workspaceDir);
-      }
-      const context = agentsContext ?? (initialized ? MISSING_AGENTS_CONTEXT : BOOTSTRAP_CONTEXT);
-      if (!context) return;
-      return { prependContext: context };
+      return { prependContext: buildPromptContext(workspaceDir) };
     });
 
     // -- Agent tool ----------------------------------------------------------
@@ -119,17 +116,12 @@ const n8nAcPlugin = {
     );
 
     // -- Service -------------------------------------------------------------
-    // On gateway start: refresh the AGENTS.md cache so the agent always has
-    // up-to-date node knowledge.
     api.registerService({
       id: "n8nac-context",
       start: async () => {
-        // Invalidate so next before_prompt_build re-reads from disk.
-        agentsContext = null;
         if (isWorkspaceInitialized(workspaceDir)) {
-          agentsContext = loadAgentsContext(workspaceDir);
-          if (agentsContext) {
-            api.logger.info("[n8nac] Workspace ready — AI context loaded.");
+          if (hasAgentsContext(workspaceDir)) {
+            api.logger.info("[n8nac] Workspace ready — lightweight prompt context enabled; n8n skill available.");
           } else {
             api.logger.warn("[n8nac] Workspace ready, but AGENTS.md is missing or unreadable.");
           }
@@ -137,9 +129,7 @@ const n8nAcPlugin = {
           api.logger.info("[n8nac] Workspace not initialized. Run `openclaw n8nac:setup`.");
         }
       },
-      stop: async () => {
-        agentsContext = null;
-      },
+      stop: async () => {},
     });
   },
 };

package/openclaw.plugin.json

@@ -2,6 +2,9 @@
   "id": "n8nac",
   "name": "n8n-as-code",
   "description": "Create and manage n8n workflows from OpenClaw. Guides the AI through n8nac initialization and provides workflow tools.",
+  "skills": [
+    "skills"
+  ],
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@n8n-as-code/n8nac",
-  "version": "2026.3.1",
+  "version": "2026.4.0-next.11",
   "description": "OpenClaw plugin for n8n-as-code — create and manage n8n workflows from OpenClaw",
   "keywords": [
     "n8n",
@@ -38,6 +38,7 @@
     "README.md",
     "index.ts",
     "openclaw.plugin.json",
+    "skills/",
     "src/",
     "tsconfig.json"
   ],

package/skills/n8n-architect/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: n8n-architect
+description: Use when the user explicitly wants to create, edit, validate, sync, or troubleshoot n8n workflows, asks about n8n nodes or automation, or wants to use the n8nac tool.
+---
+
+# n8n Architect
+
+Use this skill only for explicit n8n workflow work.
+
+## First steps
+
+1. Check whether `n8nac-config.json` exists in the workspace root.
+2. If the workspace is initialized, read `AGENTS.md` from the workspace root before making workflow changes. It is the detailed, workspace-specific source of truth generated by `n8nac update-ai`.
+3. If `AGENTS.md` is missing or unreadable, regenerate it with `npx --yes n8nac update-ai` or run the `openclaw n8nac:setup` command before attempting workflow authoring.
+4. If the workspace is not initialized, ask the user for the n8n host URL and API key, then use the `n8nac` tool with `action: "init_auth"` and `action: "init_project"` to complete setup yourself.
+
+## Using the n8nac tool
+
+- Use the `n8nac` tool for setup checks, workflow list/pull/push/verify, validation, and `skills` lookups.
+- Use `action: "skills"` whenever you need node search or schema details.
+- Never guess node parameters. The schema lookup is the source of truth.
+- Treat `AGENTS.md` as the authoritative workflow-engineering protocol once this skill is active.
+
+## Reading workflow files efficiently
+
+Every `.workflow.ts` file starts with a `<workflow-map>` block — a compact index generated automatically at each sync. Always read this block first before opening the rest of the file.
+
+```
+// <workflow-map>
+// Workflow : My Workflow
+// Nodes   : 12  |  Connections: 14
+//
+// NODE INDEX
+// ──────────────────────────────────────────────────────────────────
+// Property name                    Node type (short)         Flags
+// ScheduleTrigger                  scheduleTrigger
+// AgentGenerateApplication         agent                      [AI] [creds]
+// OpenaiChatModel                  lmChatOpenAi               [creds] [ai_languageModel]
+// Memory                           memoryBufferWindow         [ai_memory]
+// GithubCheckBranchRef             httpRequest                [onError→out(1)]
+//
+// ROUTING MAP
+// ──────────────────────────────────────────────────────────────────
+// ⚠️ Nodes flagged [ai_*] are NOT in the → routing — they connect via .uses()
+// ScheduleTrigger
+//   → Configuration1
+//     → BuildProfileSources → LoopOverProfileSources
+//       .out(1) → JinaReadProfileSource → LoopOverProfileSources (↩ loop)
+//
+// AI CONNECTIONS
+// AgentGenerateApplication.uses({ ai_languageModel: OpenaiChatModel, ai_memory: Memory })
+// </workflow-map>
+```
+
+### How to navigate a workflow as an agent
+
+1. Read `<workflow-map>` only — locate the property name you need.
+2. Search for that property name in the file (for example `AgentGenerateApplication =`).
+3. Read only that section — do not load the entire file into context.
+
+This avoids loading 1500+ lines when you only need to patch 10.
+
+
+### AI tool nodes
+
+When an AI agent uses tool nodes:
+
+- ✅ Search for the exact tool node first.
+- ✅ Run `npx --yes n8nac skills node-info <nodeName>` before writing parameters.
+- ✅ Connect tool nodes as arrays: `this.Agent.uses({ ai_tool: [this.Tool.output] })`.
+- ❌ Do not assume tool parameter names or reuse stale node-specific guidance.
+

package/src/child-env.ts

@@ -0,0 +1,34 @@
+/**
+ * Build a minimal environment for child processes.
+ * Only passes the vars needed for npx/node to operate, deliberately excluding
+ * any sensitive credentials that the parent (agent host) may hold in its env
+ * (e.g. LLM API keys), preventing accidental credential forwarding.
+ */
+export function getChildEnv(): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {};
+
+  // Matches var names that look like credentials anywhere in the name — these are never forwarded
+  // even if they match another allowlist prefix (e.g. NODE_AUTH_TOKEN, npm_config_*:_authToken,
+  // npm_config_authority is intentionally over-blocked since we prefer false-positives to leaks).
+  const secretPattern = /(?:auth|token|password|secret|apikey|api_key|_key)/i;
+
+  for (const key of Object.keys(process.env)) {
+    const upperKey = key.toUpperCase();
+    if (
+      // Basic system vars needed by node/npx (case-insensitive, including Windows-specific ones)
+      /^(PATH|HOME|USERPROFILE|HOMEDRIVE|HOMEPATH|TMPDIR|TMP|TEMP|LANG|LC_ALL|SHELL|TERM|TERM_PROGRAM|NODE_PATH|NODE_OPTIONS|SYSTEMROOT|COMSPEC|PATHEXT)$/.test(
+        upperKey,
+      ) ||
+      // npm execution/config vars required by npx — but NOT auth/token vars
+      // (e.g. excludes npm_config_//registry.npmjs.org/:_authToken)
+      (key.startsWith("npm_") && !secretPattern.test(key)) ||
+      // Specific safe NODE_* vars (deliberately NOT a prefix match to exclude NODE_AUTH_TOKEN)
+      /^NODE_(ENV|NO_WARNINGS|ICU_DATA)$/.test(upperKey) ||
+      // n8n-as-code specific vars
+      key.startsWith("N8N_AS_CODE_")
+    ) {
+      env[key] = process.env[key];
+    }
+  }
+  return env;
+}

package/src/cli.ts

@@ -3,6 +3,7 @@ import { spawn } from "node:child_process";
 import type { ChildProcess, ChildProcessWithoutNullStreams } from "node:child_process";
 import * as p from "@clack/prompts";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { getChildEnv } from "./child-env.js";
 import { isWorkspaceInitialized } from "./workspace.js";
 
 type CliProgram = Parameters<Parameters<OpenClawPluginApi["registerCli"]>[0]>[0]["program"];
@@ -24,14 +25,14 @@ function runN8nac(
   opts: {
     cwd: string;
     timeout: number;
-    env?: NodeJS.ProcessEnv;
+    stdinInput?: string;
     stdio?: "pipe" | "inherit";
   },
 ): Promise<RunResult> {
   return new Promise((resolve) => {
     const baseOptions = {
       cwd: opts.cwd,
-      env: { ...process.env, ...opts.env },
+      env: getChildEnv(),
     };
 
     const child: ChildProcess | ChildProcessWithoutNullStreams =
@@ -65,6 +66,11 @@ function runN8nac(
       });
     }
 
+    if (opts.stdinInput !== undefined && "stdin" in child && child.stdin) {
+      child.stdin.write(`${opts.stdinInput}\n`);
+      child.stdin.end();
+    }
+
     const timer = setTimeout(() => {
       timedOut = true;
       child.kill("SIGTERM");
@@ -154,10 +160,10 @@ export function registerN8nAcCli({ program, workspaceDir }: CliOpts): void {
       const authSpinner = p.spinner();
       authSpinner.start("Saving credentials…");
 
-      const authResult = await runN8nac(["init-auth", "--host", host], {
+      const authResult = await runN8nac(["init-auth", "--host", host, "--api-key-stdin"], {
         cwd: workspaceDir,
         timeout: 60_000,
-        env: { N8N_API_KEY: apiKey },
+        stdinInput: apiKey,
       });
 
       if (authResult.exitCode !== 0) {

package/src/tool.ts

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import { Type } from "@sinclair/typebox";
+import { getChildEnv } from "./child-env.js";
 import { isWorkspaceInitialized } from "./workspace.js";
 
 // ---------------------------------------------------------------------------
@@ -100,13 +101,13 @@ type RunResult = {
 function runNpx(
   args: string[],
   cwd: string,
-  env?: NodeJS.ProcessEnv,
+  stdinInput?: string,
 ): Promise<RunResult> {
   return new Promise((resolve) => {
     const child = spawn("npx", ["--yes", "n8nac", ...args], {
       cwd,
-      env: { ...process.env, ...env },
       stdio: "pipe",
+      env: getChildEnv(),
     });
 
     let stdout = "";
@@ -131,6 +132,11 @@ function runNpx(
       stderr += chunk.toString();
     });
 
+    if (stdinInput !== undefined) {
+      child.stdin.write(`${stdinInput}\n`);
+      child.stdin.end();
+    }
+
     const timer = setTimeout(() => {
       timedOut = true;
       child.kill("SIGTERM");
@@ -250,7 +256,7 @@ export function createN8nAcTool(opts: { workspaceDir: string }) {
         if (!host || !key) {
           return ok({ error: "n8nHost and n8nApiKey are required for init_auth" });
         }
-        const r = await runNpx(["init-auth", "--host", host], workspaceDir, { N8N_API_KEY: key });
+        const r = await runNpx(["init-auth", "--host", host, "--api-key-stdin"], workspaceDir, key);
         if (r.exitCode !== 0) {
           return ok({ error: r.stderr || r.stdout, exitCode: r.exitCode });
         }