Init n8n Workflow Repo

Bootstrap a brand-new n8n workflow repo so the user can immediately start with /n8n-autopilot:build-workflow.

This skill is the single entrypoint for new-repo setup. Replaces the manual checklist.

Reference n8nac version: 2.7.0 (minimum 2.3.0). The setup flow below targets the environment-centric model: environments are created with n8nac env add, authenticated with n8nac env auth set, and pinned per repo via N8NAC_ENVIRONMENT in .claude/settings.json (never env use — the env-gate blocks it). Workspace/instance config lives in user home (~/n8nac-config.json + ~/.n8n-manager/), not in the workspace root. An in-repo n8nac-config.json may be the LIVE config on n8nac ≥ 2.5 — never tell the user to delete it without checking (docs/rules/setup.md).

Arguments

Pre-flight

1. Detect plugin self-bootstrap. Refuse if target dir contains .claude-plugin/plugin.json with "name": "n8n-autopilot" — that's the plugin source, not a consumer repo.
2. Check tools. npx --version and git --version must work. Fail loud if missing. 2b. Check for an existing remote of the same name (#53). Before scaffolding into a directory with no origin, ask GitHub whether the org already has it: gh repo view <org>/<dir-name> --json url,pushedAt 2>/dev/null. If it exists, STOP and offer to clone it (or git remote add origin + git pull) instead of creating an unrelated history — a parallel bootstrap once hid a day of authoritative specs that already lived on the remote.
3. Detect legacy in-repo config. If <target>/n8nac-config.json exists (legacy workspace-local config from n8nac < 2.2), warn the user that workspace migrate-v1 no longer exists and the file must be deleted manually — config now lives in user home (~/n8nac-config.json + ~/.n8n-manager/). Do not delete the file automatically.

Steps

1. Scaffold files

bash "${CLAUDE_PLUGIN_ROOT}/skills/init-repo/scripts/init-repo.sh" "<target-dir>" [--force] [--no-git]

Creates workflows/, schemas/nodes/, data/, docs/ and writes templated CLAUDE.md, README.md, .gitignore, .env.example, runs git init. Idempotent. No .mcp.json is scaffolded — n8n-autopilot 4.x is CLI-only.

It then runs ensure-claude-section.js to anchor the n8n-autopilot section into CLAUDE.md (idempotent): a brand-new repo already has the full template (the script SKIPs, no duplicate); an existing repo with its own CLAUDE.md gets the marked section (<!-- n8n-autopilot:start -->…<!-- n8n-autopilot:end -->) appended, and re-runs only refresh that block — repo-specific content outside the markers is never touched.

Output to user: Summarize what was written / skipped / appended.

Anchor into an existing repo without full scaffolding: to only add/refresh the autopilot section in a repo that already has its own CLAUDE.md (e.g. an established customer repo), run just:

node "${CLAUDE_PLUGIN_ROOT}/skills/init-repo/scripts/ensure-claude-section.js" --workspace .

2. Collect connection info

Ask the user — one prompt, two answers — for:

• n8n host URL (e.g. https://n8n.customer.example.com)
• n8n API key (from n8n UI → Settings → API)

Project assignment is decided in step 5 once setup has surfaced available projects.

If user can't provide right now: skip steps 3–6, print the remaining manual commands (see init-repo.sh "Next steps" tail), and stop. Don't fail.

3. Write .env

In the target dir, copy .env.example → .env and substitute N8N_API_URL and N8N_API_KEY with what the user gave.

Use the Edit tool, NOT sed -i — Windows safety.

4. Create and authenticate the environment (n8nac 2.3 flow)

cd <target-dir>
# Register the environment (name, instance URL, workflows folder, optional project)
npx n8nac env add <env-name> \
  --base-url "<host>" \
  --workflows-path workflows \
  [--project-name "<project>"]   # omit for single-project instances

# Store the API key (via stdin — never echoed to shell history)
printf "%s" "$N8N_API_KEY" | npx n8nac env auth set <env-name> --api-key-stdin

<env-name> is a short label for this environment (e.g. Prod, CustomerX). Use the same name throughout the session.

4b. Native n8n MCP for this environment (tests + push gate)

The plugin's n8n-native MCP server and the push-lint gate reach the instance's own MCP server (<host>/mcp-server/http) with a token stored per environment. Without it, every push is blocked and no workflow can be tested. The token cannot be created by an agent:

1. Ask the user to enable MCP in the n8n UI (Settings → MCP) and create an access token.

2. The user stores it in the customer's Infisical project (internal instances: thecluster), then configures n8nac in their own terminal — --token-stdin reads a pipe and waits silently without one:

   $t = Read-Host "n8n MCP Token" -MaskInput; $t | npx n8nac native-mcp configure <env-name> --token-stdin --level 2

3. Verify: N8NAC_ENVIRONMENT=<env-name> node "${CLAUDE_PLUGIN_ROOT}/scripts/check-native-mcp.mjs" --live must print ✅ native MCP ready. The repo's .claude/settings.json must pin N8NAC_ENVIRONMENT=<env-name> — n8n-native refuses to guess the instance otherwise.

New and edited workflows need settings.availableInMCP: true; the push-lint gate enforces it. Contract and traps: docs/rules/testing.md.

5. Pin the environment for this repo + verify

Never npx n8nac env use — it rewrites the machine-global active env that every other session inherits, and the plugin's env-gate blocks it unconditionally (#49). A repo pins its env in .claude/settings.json instead, so every session opened in it (and every subagent) targets it:

{ "env": { "N8NAC_ENVIRONMENT": "<env-name>", "N8N_AUTOPILOT_MODE": "always" } }

N8N_AUTOPILOT_MODE: always only for a dedicated n8n repo: every session there loads the SessionStart probes and the feedback hooks. In a project monorepo (n8n is one folder among many) leave it out — the n8n mode then switches on per session, with the first n8nac command or /n8n-autopilot:n8n-mode (see skills/n8n-mode).

Write that file (merge into an existing one; keep it TRACKED in git — see the .gitignore note below) and verify with the session-aware command (not workspace status, which is env-blind):

N8NAC_ENVIRONMENT=<env-name> npx n8nac env status --json

accessStatus: ok + the expected host and project = good.

If the user's n8n has multiple projects and the user did not specify one at env add time, update the environment:

npx n8nac env update <env-name> --project-name "<project>"

6. Pull schemas

Unless --skip-schemas:

→ Invoke skill /n8n-autopilot:pull-schemas (run it inline — same session).

Schemas land in schemas/nodes/, index in schemas/_index.json. Both gitignored.

6.5 Mirror remote workflows

Pull every workflow that already exists in the bound project so the repo starts as a complete local mirror of the instance. This is what makes /n8n-autopilot:build-workflow-v2's local-first edit flow valid, and what the SessionStart drift probe (check-mirror-drift.sh) keeps honest afterwards.

→ Invoke skill /n8n-autopilot:mirror-sync (run it inline — same session). It discovers remote-only workflows and fan-out-pulls them.

A brand-new/empty project pulls nothing (mirror already complete) — that's fine. Failures are non-fatal: report them, the user can re-run /n8n-autopilot:mirror-sync or npx n8nac pull <id> manually.

7. Verify

bash "${CLAUDE_PLUGIN_ROOT}/scripts/setup-check.sh"

Expect "All checks passed". If errors → diagnose and report, don't silently swallow.

8. Final message

Print to the user:

✅ Repo ready: <target-dir>

Try it now:
  /n8n-autopilot:build-workflow "your idea here"

Or deploy an existing workflow:
  /n8n-autopilot:deploy workflows/foo.workflow.ts

First commit:
  cd <target-dir>
  git add .
  git commit -m "chore: bootstrap n8n-autopilot repo"

Failure handling

• Tool missing (npx/git): stop, tell user how to install, don't continue.
• npx n8nac env add fails: print exact stderr, leave repo half-bootstrapped, tell user what to fix and how to rerun (just the failing step, not the whole skill).
• npx n8nac env auth set fails: most likely cause is a wrong env name or an invalid API key — verify with npx n8nac env list and re-run.
• pull-schemas fails: continue anyway — schemas are nice-to-have, user can run /n8n-autopilot:pull-schemas later.
• setup-check fails: report errors, do NOT delete anything, give user the rerun command.

Never delete files the user might have written between steps.

Notes

• Skill is idempotent at the file-scaffold level (Step 1) — never overwrites existing files. The CLAUDE.md autopilot section is marker-delimited and refreshed in place (no duplication); content outside the markers is preserved.
• Steps 3–7 will re-run cleanly on a partially bootstrapped repo.
• Templates live in ${CLAUDE_PLUGIN_ROOT}/skills/init-repo/assets/templates/ (colocated with the skill per skill-creator convention).
• For multi-environment setups (one repo, many n8n tenants), run npx n8nac env add <name> per environment and switch per session via N8NAC_ENVIRONMENT=<name> (settings env block, export, or --env) — never env use.
• The legacy init / init-auth / init-project commands were removed in n8nac 2.2 — do NOT use them.
• The workspace pin-instance, workspace set-sync-folder, workspace set-project, workspace migrate, and workspace migrate-v1 commands were removed in n8nac 2.3 — do NOT use them.