v5.2.0 — Actionable feedback loop

Feedback loop rebuilt end-to-end around actionable, typed findings, plus the n8nac 2.4 refresh.

Added

• Typed finding records — one finding = one GitHub issue. Findings carry type, severity, area (node type / n8nac command), title, observed, expected, suggestion, and signal evidence. Raw auto-captured counts stay local until the review flow distills them.
• Webhook ingest transport — no gh/GitHub account needed on the consumer side; the ingest creates one labelled issue per finding (reporter included).
• feedback-triage agent (maintainer-side): dedups open feedback issues, adds triage comments, reports a ranked backlog.
• Stop hook: after a work turn with real n8nac activity and no recorded finding, the agent must actively propose /n8n-autopilot:feedback review — once per session, never loops.
• native-mcp coverage (n8nac 2.4): cheat-sheet section, MCP.md test-path evaluation (read-only assist today; binary payloads never via MCP), full command reference.
• Activation-failure hard rule: a failing n8nac workflow activate means the workflow is broken (node issues) — diagnosed as a fixable Class B error; asking the user to activate in the n8n UI is forbidden.
• .gitattributes LF pin for scripts (fixes Workflow-tool CRLF breakage on Windows checkouts).

Changed

• sync.sh: per-sessionId dedup (cumulative counters — last wins), pluginVersion, issue-URL reporting.
• redact-check.js: finding-field allowlist + taxonomy enforcement; node types and n8nac commands are explicitly safe context.
• Reference regenerated for n8nac 2.4.0 (adds the native-mcp command group); stale "MCP broken upstream" notes corrected.

v5.1.0

Hardening pass from a multi-session friction analysis of real production runs: documented gotchas
that were never enforced, and a noisy feedback metric.

Added

• build-workflow-v2 design-quality gate. workflow-reviewer now runs as a hard gate between
  Validate and Deploy (≤2 fix cycles) in both greenfield + edit flows. Design anti-patterns the n8n
  validator cannot catch — raw HTTP in Code nodes, continueOnFail/onError masking real errors, AI
  sub-nodes miswired via .out().to() — now block the push instead of shipping. Warnings are
  surfaced (reviewWarnings) without blocking.
• Orchestrator StructuredOutput resilience. Schema'd subagent calls in build-workflow-v2 +
  build-stack-v2 now route through a safe() wrapper: a subagent that ends without calling
  StructuredOutput (or dies terminally) gets one retry, then a graceful fallback into the existing
  gate-failure path — instead of crashing the whole run with an opaque error after burning the
  tokens (observed: a heavy agent burned ~786k tokens, then the workflow aborted opaquely).
• build-stack-v2 greenfield auto-detect. Before decomposing, a greenfield stack build checks
  docs/*.architecture.md for a stack that already covers the use-case and returns
  needs-decision (re-run as extend, or pass mode: 'greenfield' to force) instead of silently
  rebuilding a working stack from scratch.
• Feedback sync → public repo. Target moved from the private n8n-autopilot-internal to the
  public neurawork-git/n8n-autopilot. repoLabel (a customer basename = PII on a public repo) is
  stripped from the issue title, summary, and raw NDJSON before push; records keep it locally.
• SessionStart plugin-staleness probe (check-plugin-version.sh) — INFO nudge to
  claude plugin update when the installed version is behind the latest GitHub release. Never
  auto-runs (env-changing). Catches the case where a stale install silently lacks newer gotcha hooks.
• Cheat-sheet rows: credential-schema-first (n8nac credential schema <type> before create) and
  sub-workflow-publish-before-parent.

Fixed

• Wrong execution-list flag in the cheat-sheet/reference: --workflow → --workflow-id (n8nac
  rejects --workflow; the documented form caused the same CLI error across sessions). 5 files.
• REST-guard dodge. The PreToolUse curl-block only matched curl/wget, so urllib /
  Invoke-RestMethod / requests. slipped past it. Guard now catches those against /api/v1 too;
  the /api/v1/data-tables carve-out is preserved, and the skill blesses looping its curl for
  polling (instead of reading n8nac's internal secret store).
• env-blind workspace status trap. CLAUDE.md recommended workspace status to verify the env,
  but it reports the GLOBAL active env — this misled the model into the forbidden env use across 3
  sessions. Docs now route env verification to env list --json.
• Noisy feedback metric. capture-feedback.sh matched skill-listing + SessionStart-hook
  injections (false positives) and double-counted on resume. Now scans only real conversation turns
  and keeps one last-write-wins event per session.

v5.0.0 — n8nac 2.3.6 compat + session-env isolation

v4.9.0

Catch-up release spanning 4.3.0 → 4.9.0 (public was last at 4.2.2).

Highlights

• build-workflow-v2 (experimental) — JS-orchestrated GREENFIELD + EDIT pipeline with hard-enforced gates (validate before push, drift-safe push --verify, bounded fix-loops as control flow). 8 reusable agentTypes.
• build-stack-v2 (experimental) — lifts v2 discipline to a whole workflow stack (orchestrator + Execute-Workflow sub-WFs), topological bottom-up build. Plus stack-intake guided interview for users new to n8n.
• mirror-sync — pulls every remote-only workflow so the repo mirrors the instance; auto-triggered by a SessionStart drift probe.
• Environment safety — one env per session (enforce-env PreToolUse gate, report-session-env); workflow subagents inherit N8NAC_ENVIRONMENT.
• Pattern skills — n8n-orchestration-patterns, n8n-structured-extraction.
• Feedback loop — SessionEnd auto-capture of NON-PII friction counts, redact-gated central sync.
• find-project, test-manual, idempotent CLAUDE.md section anchoring, workflow-reviewer 15-point design-quality checks.

See CHANGELOG.md for full per-version detail.

v4.2.2 — Skill frontmatter YAML fix + n8nac >= 2.2 .env handling

Two bugs found via claude --debug log inspection in a consumer repo.

1. YAML parse failure in 2 skill frontmatters — n8nac-cheatsheet and build-workflow had unquoted description: values containing <word>: <word> (e.g. "common workflows: lookup"), which js-yaml interprets as a nested mapping. Both skills were silently dropped from every session. Cheatsheet was the worst hit — entire curated CLI-mapping was invisible to consumers despite shipping in v4.2.0. Fixed by quoting the descriptions and replacing inline colons with em-dashes.

2. check-installed-nodes warned about missing .env on bound workspaces — n8nac >= 2.2 stores the API key in the secure manager store (~/.n8n-manager/), not in a workspace .env. The schema-coverage probe needs that key to query /community-packages but cannot retrieve it from the secure store. Pre-4.2.2 just printed a misleading "ℹ️ .env not found — skipping" on every session. Now silent-skips with an explanatory note when the workspace is bound, keeps the warning only when truly unconfigured.

Full changelog: https://github.com/neurawork-git/n8n-autopilot/blob/main/CHANGELOG.md#422--2026-05-20

v4.2.1 — SessionStart hook path fix

Patch fixing two SessionStart hooks (check-schema-versions.sh + check-installed-nodes.sh) that resolved REPO_DIR to the plugin install dir instead of the consumer workspace. v3.7.1 fixed this for cred-freshness + workspace-migration but missed these. Explains the persistent ".env not found" warning consumers saw on every session despite having a populated .env in the repo root.

No skill changes, no manifest changes beyond the version bump.

Full changelog: https://github.com/neurawork-git/n8n-autopilot/blob/main/CHANGELOG.md#421--2026-05-20

v4.2.0 — Multi-project awareness, push-gate, n8nac knowledge skills

Added — n8nac knowledge skills (full CLI reference + curated cheatsheet)

Two new knowledge skills end the "agent fishing through --help" pattern:

n8nac-reference (skills/n8nac-reference/)

• Auto-generated, machine-walked n8nac --help tree.
• 74 subcommands across 26 top-level groups (workspace, env, instance-target, setup, credentials, credential, workflow, execution, skills, plus 14 root-level commands like list, find, pull, push, promote, verify, test, test-plan, fetch, resolve, convert, convert-batch, mcp, update-ai).
• Source of truth: if a command is not in reference.md, it does not exist — agents must not invent CLI surface.
• Regenerated via scripts/dump-n8nac-help.sh (re-run after any n8nac upgrade).
• Strict-mode help parser (column-3 anchor + alias-strip) keeps the file at ~1500 lines rather than the runaway 11000+ lines the loose parser produced on first attempt.

n8nac-cheatsheet (skills/n8nac-cheatsheet/)

• Curated "user intent → exact command" table, ~60 rows, grouped into Workspace, Multi-Environment, Instance Targets, Workflow Lifecycle, Testing & Execution, Credentials (CRUD + recipes), Schemas/Node Info, Telemetry.
• Highlights the singular credential vs. plural credentials distinction (most common "command not found" footgun), the push-gate bypass env var, and the n8nac >= 2.2 setup commands that replaced the removed init / init-auth / init-project.
• Gotchas section enumerates the 10 most common silent-failure patterns (project visibility, test trigger limits, mcpTrigger publish, archived read-only, etc.).

CLAUDE.md now has a "Knowledge skills" block above the cheat-sheet pointing at both, with the rule: grep the cheatsheet → grep the reference → only then run --help live. The n8n-architect companion skill is also linked as the canonical source for workflow authoring rules.

Added — Multi-project awareness + push-gate (drift protection) + cheat-sheet

Three structural defects fixed after the Falkensteg session showed Claude fishing through --help, inventing CLI subcommands (skills list-credentials), and injecting cross-project credential IDs:

1. New skill /n8n-autopilot:find-credential (skills/find-credential/)

• Search live credentials by name pattern, scoped to the workspace-pinned project by default.
• Flags: --type <credType>, --project <name|id|all>, --exact, --json.
• Returns table grouped by project + paste-ready TypeScript snippets.
• Shows count of cross-project matches as a footnote when default-scoped (no leak, but visible).
• Replaces the ad-hoc "n8nac credential list --json | grep" pattern that ignored project scope and routinely picked the wrong project's credential ID.

2. New skill /n8n-autopilot:find-project (skills/find-project/)

• Enumerates every n8n project visible on the active instance (derived from credential list --json → shared[].name / shared[].id — works without the Enterprise /api/v1/projects endpoint).
• Marks the workspace-pinned project, prints the exact workspace set-project command to switch.
• Falkensteg shipped seven projects; agents had no way to see the others before this.

3. Push-gate hook (scripts/push-gate.sh) — wired into hooks.json PreToolUse(Bash)

• BLOCKS npx n8nac push <file> when n8nac list --search <id> returns status CONFLICT / MODIFIED_BOTH / DIVERGED / REMOTE_ONLY. Hook auto-runs n8nac fetch <id> first, so the verdict is always against fresh remote state.
• BLOCKS npx n8nac resolve <id> --mode keep-current|keep-local|local-wins unconditionally — this command silently overwrites remote with local.
• Single bypass: N8N_AUTOPILOT_ALLOW_LOCAL_WINS=1 <re-run command> (requires explicit user authorization that remote changes are to be discarded).
• New workflows (file with no id: field) are never blocked.

4. sync-credentials --fix-workflows now project-scoped by default

• Joins workflow credential references against ONLY credentials owned by the active workspace project. Cross-project name collisions no longer rewrite IDs into the wrong project.
• Header now reports Project scope: <name> (<id>) and "Skipped N credential(s) owned by other projects" so the scope is visible in every run.
• New flag --all-projects disables the filter (rare, used when migrating workflows between projects).

5. CLAUDE.md cheat-sheet at the top of the file

• "User asks X → run Y" table covering every common request (find credential, list projects, switch project, build, deploy, fix creds, inventory, data-tables, executions, etc.).
• Push-gate section documenting block conditions and the override env var.
• Multi-project rule stated up front: every credential / workflow operation runs in the workspace-pinned project's scope; verify the pin before touching credentials.

6. check-mcps skill + setup-check.sh Section 6 now print the project visibility table on every health check / SessionStart, so multi-project state is visible without an explicit query.

Why this matters (Falkensteg incident pattern): workspace pinned to project A, instance has projects A–G, n8nac credential list --json returns creds from all visible projects. Agent matches by name only → injects credential ID from project F into a workflow in project A → push succeeds, runtime fails with "credential not accessible". After 4.2.0: find-credential shows only project A by default, sync-credentials --fix-workflows will not rewrite cross-project IDs, push-gate refuses to silently overwrite remote changes.

v4.1.0 — CLI-only, scripts in skill folders

What this release is about

n8n-autopilot 4.1 is a structural cleanup. The plugin's tool surface shrinks, its role sharpens, and every skill now invokes bundled scripts instead of embedding executable code in the SKILL.md body.

What changed

CLI-only — no MCP server

Every skill reaches n8nac through npx n8nac …. The mcp__n8n-as-code__* namespace that earlier versions referenced was a phantom: the npm n8nac mcp entry-point crashes in every published version (require('mcp') without a declared dependency in @n8n-as-code/skills), and Etienne Lescot's n8n-as-code plugin ships skill knowledge, not an MCP server. There was no working setup in which those tool names resolved.

Companion plugin required

n8n-as-code@n8nac-marketplace by Etienne Lescot. It owns the n8n-architect skill — schema-first research, workflow authoring rules, AI/LangChain sub-node rules, common-mistakes catalogue, the canonical operating loop. n8n-autopilot delegates those and concentrates on what it uniquely adds.

Skills invoke bundled scripts, no inline executable code

Per the skill-creator norm (skill-name/scripts/), skill-specific executable code lives inside the skill folder. SKILL.md bodies are thin pointers (~50 lines each) — when to invoke and which flag does what. No node -e or bash -c walls in skill prose anymore.

Skill	Bundled scripts
pull-schemas	discover-types.sh, fetch-one.sh, fetch-pkg.js, rebuild-index.js, run.sh (orchestrator)
inventory	aggregate.js
sync-credentials	list.js, fix-workflows.js

This pattern prevents Claude from paraphrasing logic and re-implementing it ad-hoc (the failure mode that produced one-off helper scripts in consumer repos, wrong API paths, misclassified nodes).

What n8n-autopilot uniquely adds

Skill	Role
/n8n-autopilot:init-repo	Workspace bootstrap with n8nac ≥ 2.2 setup flow
/n8n-autopilot:build-workflow	3-phase pipeline (Research → Write+Validate → Deploy+Test) with mandatory community-template lookup, auto-fix loop, mcpTrigger publish gate, completion report
/n8n-autopilot:deploy	validate → push (--verify) → credential check → test-plan → live test, with Class A/B error classification and --activate --prod path
/n8n-autopilot:pull-schemas	Two-stage schema cache: indexed nodes via n8nac skills node-info, non-indexed community nodes via direct npm-package extraction (works for any published n8n node package)
/n8n-autopilot:sync-credentials --fix-workflows	Rewrites stale credential IDs across local .workflow.ts files by matching credential names against the live instance
/n8n-autopilot:inventory	Aggregates node / LLM / credential / trigger usage from local workflows into docs/INVENTORY.md
/n8n-autopilot:data-tables	DataTable CRUD via the n8n REST API (the one curl carve-out, since n8nac has no datatable subcommand)
/n8n-autopilot:check-mcps	Health diagnostic for CLI version, workspace binding, companion plugin status
n8n-code-javascript + n8n-code-python	The only Code-node references that the n8n-architect skill does not cover

SessionStart hooks: setup-check, community-node schema staleness, credential freshness, workspace migration diagnostic.

Removed

• Four knowledge skills duplicated by n8n-architect: n8n-workflow-patterns, n8n-node-configuration, n8n-validation-expert, n8n-expression-syntax
• agents/n8n-researcher.md — n8n-architect is the researcher
• .mcp.json.example + the init-repo MCP template — no MCP needed
• All claude plugin path invocations across docs, scripts, and templates — that subcommand does not exist in the Claude Code CLI

Fixed

• SessionStart hooks (check-workspace-migration, check-credential-freshness) read $PWD instead of $CLAUDE_PLUGIN_ROOT — the former is the user's workspace, the latter is the plugin install path. Earlier versions silently missed workspace-local config files and stale credential references.
• check-workspace-migration reads the version field of any n8nac-config.json it finds and surfaces the right reason (v1/v2 schema → legacy data; v4 schema → wrong location).
• setup-check.sh no longer probes a broken MCP server; warns when the companion plugin is not enabled.
• init-repo no longer scaffolds a .mcp.json (would have been non-functional). Setup flow updated to the n8nac 2.2 storage model.

Migration from 3.x

claude plugin marketplace add EtienneLescot/n8n-as-code
claude plugin install n8n-as-code@n8nac-marketplace
claude plugin install n8n-autopilot@n8n-autopilot

If your repo has a .mcp.json with only the n8n-as-code entry, delete it — it was never functional. If .mcp.json has other MCP entries, drop only the n8n-as-code block.

Verify: /n8n-autopilot:check-mcps — expect green across all rows.

Reference

• n8nac CLI reference: 2.2.1 (minimum 2.2.0)
• Node.js: 18 or higher
• Full changelog: CHANGELOG.md