etiennelescot/n8n-as-code/n8n-architect

n8n Architect

Use this skill for all n8n-as-code work: workspace readiness, environments, managed local instances, tunnels, workflow authoring, validation, sync, push, and pull.

Use npx --yes n8nac as the primary interface. Use npx --yes @n8n-as-code/n8n-manager only for local managed runtime lifecycle, tunnels, and workflow presentation commands that are explicitly exposed by n8n-manager.

Context Root Protocol

• Treat the current context root as the directory containing n8nac-config.json, AGENTS.md, .agents/skills, and the configured workflowsPath.
• Generated context root hint: not embedded. Use the shell launch directory or the workspace path explicitly given by the user.
• Before any n8n work, first run npx --yes n8nac update-ai from the context root, then read AGENTS.md. update-ai is designed to create or refresh the n8n-as-code block without destroying existing user or agent instructions.
• Use the exact n8nac command and n8n-manager command listed in AGENTS.md. Those context-root commands override the portable examples in this skill.
• Run every npx --yes n8nac env ..., npx --yes n8nac workspace ..., npx --yes n8nac list, pull, push, validate, test, and update-ai command from the context root unless the user explicitly gives another context root.
• AGENTS.md is bootstrap context only, not a source of configuration truth.
• Do not infer environment, project, or workflowsPath from AGENTS.md.
• Before n8n work, resolve the effective context from the backend:

npx --yes n8nac env status --json

• Use the returned workflowsPath for workflow files. It is the configured workflow directory for the active environment.
• Do not reconstruct workflowsPath from environment name/id, instanceIdentifier, instanceUserIdentifier, projectId, projectName, or legacy sync fields.
• Never write n8nac-config.json, ~/.n8n-manager, or n8n-manager secret files by hand.

Workspace Readiness

Resolve the effective environment through the backend before workflow work:

npx --yes n8nac env status --json

• Treat env status --json as the source of effective workspace readiness.
• Do not infer readiness from raw files, generated agent docs, or directory names.
• A workspace .env holding N8N_HOST (plus any of N8N_API_KEY, N8N_NATIVE_MCP_URL, N8N_NATIVE_MCP_TOKEN) configures the default environment on first use: env status --json then resolves with no env add, env auth set, env use, or native-mcp configure.
• If env status --json fails because the workspace is not configured, use env add, env auth set, and env use to create or select a V4 workspace environment.
• Managed local instances remain machine-global runtime resources.
• Workspace environments remain workspace-scoped and are managed through npx --yes n8nac env ....

Bootstrap Order

1. cd to the context root.
2. Run npx --yes n8nac update-ai, then read AGENTS.md.
3. Run npx --yes n8nac env status --json. If it resolves with accessStatus: "ready", the workspace is ready — skip steps 4-9. A resolution with missing-api-key or invalid-api-key means only the credential is missing: go to step 7.
4. If the context root is not ready, inspect managed local instances with npx --yes @n8n-as-code/n8n-manager instance list.
5. Reuse an existing environment or managed local instance when suitable.
6. If no suitable environment exists, stop and ask the user whether they want to connect a remote n8n URL or create/reuse a managed local n8n instance. Do not create infrastructure by default. If the user chooses a managed local instance, ask separately whether they want a public tunnel.
7. Ask for host/API key only for an explicitly remote n8n environment.
8. Configure the environment with:

npx --yes n8nac env add <name> --base-url <url> --workflows-path workflows/<name>
npx --yes n8nac env auth set <name> --api-key-stdin
npx --yes n8nac env use <name>

For a managed local instance:

npx --yes n8nac env add Local --managed-instance <id> --workflows-path workflows/local
npx --yes n8nac env use Local

1. Run npx --yes n8nac update-ai after changing environments when the facade does not do it automatically.

Environments

Use npx --yes n8nac env ... for workspace environments, remote URLs, active environment, API-key binding, projects, and workflow paths.

npx --yes n8nac env status --json
npx --yes n8nac env list
npx --yes n8nac env add <name> --base-url <url> --workflows-path workflows/<name>
npx --yes n8nac env auth set <name> --api-key-stdin
npx --yes n8nac env use <name>

• Prefer --api-key-stdin for API keys.
• Prefer env add --pin to create and pin the default environment in one process instead of a separate env use.
• Do not pass secrets inline in shell arguments.
• env auth set binds the key to one environment, so several environments may share a base URL with one key each. Run it once per environment; apiKeySource in env status --json is workspace-environment when the environment uses its own key.
• Do not ask for host/API key when the user wants a managed local Docker instance.
• Do not print API keys or credential secret values back to the user.
• If a command or flag is unfamiliar, run npx --yes n8nac env --help or npx --yes n8nac env <subcommand> --help.

Attach a managed local instance to the workspace with npx --yes n8nac env ...:

npx --yes n8nac env add Local --managed-instance <id> --workflows-path workflows/local
npx --yes n8nac env use Local

Managed Local Runtime

Use npx --yes @n8n-as-code/n8n-manager only for local managed instance lifecycle, tunnels, and workflow presentation commands that are part of the local runtime layer.

Inspect existing managed instances before changing local machine state:

npx --yes @n8n-as-code/n8n-manager instance list
npx --yes @n8n-as-code/n8n-manager instance --help
npx --yes @n8n-as-code/n8n-manager config get

Do not invent n8n-manager subcommands. Use npx --yes @n8n-as-code/n8n-manager <subcommand> --help when unsure.

When the context root is not configured and no suitable existing instance is available, stop and ask the user to choose. Do not create infrastructure by default.

Present these choices clearly:

• use an existing managed local instance if one is available;
• create a new managed local n8n instance;
• configure a remote n8n URL as a workspace environment through npx --yes n8nac env.

If the user chooses a managed local Docker instance, ask the tunnel question separately:

• without public tunnel: local n8n only, suitable for normal UI/API workflow work;
• with public tunnel: exposes the instance through a public URL, useful for webhooks/forms/chat triggers and remote callbacks.

Do not enable, refresh, or start a public tunnel unless the user explicitly requested public access, webhook testing, or approved the tunnel option. If public access is not needed, create/start the managed instance without --tunnel.

Only run these commands after the user has explicitly chosen the corresponding option.

Managed local instance without public tunnel:

npx --yes @n8n-as-code/n8n-manager instance create
npx --yes @n8n-as-code/n8n-manager instance start <id>
npx --yes @n8n-as-code/n8n-manager instance list

Managed local instance with public tunnel:

npx --yes @n8n-as-code/n8n-manager instance create
npx --yes @n8n-as-code/n8n-manager instance start <id>
npx --yes @n8n-as-code/n8n-manager tunnel start <id>

Instance and tunnel operations are per managed local instance:

npx --yes @n8n-as-code/n8n-manager instance start <id>
npx --yes @n8n-as-code/n8n-manager instance stop <id>
npx --yes @n8n-as-code/n8n-manager instance remove <id>
npx --yes @n8n-as-code/n8n-manager tunnel start <id>
npx --yes @n8n-as-code/n8n-manager tunnel stop <id>

• Do not delete local instance data unless the user explicitly asks for destructive deletion.
• If Docker is unavailable or the daemon is stopped, report the backend diagnostic and stop. Do not loop.
• If a command fails repeatedly, stop after two attempts and explain the backend diagnostic.

Sync Discipline

• Pull before reading or modifying an existing workflow.
• Push after every modification.
• Use list to inspect workflow IDs, file paths, and sync status.

npx --yes n8nac list
npx --yes n8nac pull <workflowId>
npx --yes n8nac push <path-to-workflow.workflow.ts> --verify

• push requires the full workflow file path, either absolute or context-root-relative. Do not pass a bare filename.
• On n8n 2.x, pushing to a published workflow also releases it to production — the API re-publishes on update. Treat every push to a published workflow as a deploy. Use push --draft when the user wants to check the change in n8n first: it re-pins the previously published version so production keeps running what it already ran.
• For a new workflow, create the file inside the workflowsPath returned by env status --json, then confirm it with npx --yes n8nac list --local.
• If push/pull reports a conflict, use explicit resolution commands. Do not overwrite remote changes blindly.
• pull and conflict resolution operate on a single workflow ID.
• list is the lightweight command that covers all workflows at once.
• If you skip pull, a later push can be rejected by optimistic concurrency control when the remote changed.

Conflict Handling

If push or pull reports a conflict, stop and inspect the conflict. Use explicit resolution commands only after choosing the intended direction:

npx --yes n8nac resolve <workflowId> --mode keep-current
npx --yes n8nac resolve <workflowId> --mode keep-incoming

• keep-current force-pushes the local version.
• keep-incoming force-pulls the remote version.
• Never silently force-push over a remote change.

Schema-First Research

Never guess n8n node parameters.

npx --yes n8nac skills examples search "<workflow pattern>"
npx --yes n8nac skills search "<node or capability>"
npx --yes n8nac skills node-info <nodeName>
npx --yes n8nac skills validate <workflow.workflow.ts>

• Batch node queries: query multiple nodes in a single command using npx --yes n8nac skills node-info <node1> <node2> ... --compact to inspect essential properties, required parameters, and valid options in one fast, token-efficient turn.
• Use exact node type and valid typeVersion values from node-info.
• Use exact resource, operation, option, and parameter names from schema output.
• Parameters of type resourceLocator must be structured as { __rl: true, value: '...', mode: 'list' | 'id' | 'url' }.
• Do not invent parameters, operations, credential types, or CLI flags.
• Treat schema output as the absolute source of truth even if examples or memory disagree.
• Prefer the highest valid typeVersion returned by schema output.
• For fixed collections such as Switch/If rules, Wait form fields, or nested options, read the full node-info output before writing values.

Optional Native n8n MCP Assist

The n8n-as-code MCP server is a client adapter for N8NAC tools. The native n8n MCP server is a separate live n8n instance endpoint. Native n8n MCP can complement this workflow for native knowledge, live state, and runtime execution, but it does not replace npx --yes n8nac, bundled knowledge, .workflow.ts, Git, or the sync discipline.

Use this routing policy: