feat: launch Vibeflow n8n v0.5.0

.github/DISCUSSION_TEMPLATE/ideas.yml

@@ -0,0 +1,20 @@
+title: Ideas
+labels: [ideas]
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Idea summary
+      description: What would you like to see in Vibeflow n8n?
+    validations:
+      required: true
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What problem would this solve?
+  - type: textarea
+    id: sketch
+    attributes:
+      label: Proposed approach
+      description: Share a rough implementation idea or usage example.

.github/DISCUSSION_TEMPLATE/show-and-tell.yml

@@ -0,0 +1,15 @@
+title: Show and tell
+labels: [show-and-tell]
+body:
+  - type: textarea
+    id: built
+    attributes:
+      label: What did you build?
+      description: Share the workflow, recipe, or automation you created with Vibeflow n8n.
+    validations:
+      required: true
+  - type: textarea
+    id: notes
+    attributes:
+      label: Notes
+      description: What worked well, what was tricky, and what should improve?

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,28 @@
+---
+name: Bug report
+about: Report a problem in behavior, docs, examples, or packaging
+---
+
+## Summary
+
+Describe the bug.
+
+## Expected behavior
+
+What should have happened?
+
+## Actual behavior
+
+What happened instead?
+
+## Where it appears
+
+- [ ] docs
+- [ ] prompt / skill behavior
+- [ ] examples
+- [ ] client guide
+- [ ] recipes
+
+## Additional context
+
+Add logs, screenshots, or reproduction notes.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Questions and setup help
+    url: https://github.com/OWNER/REPO/discussions
+    about: Use Discussions for setup questions, ideas, and help requests.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an improvement, new recipe, or new client support idea
+---
+
+## Summary
+
+Describe the improvement.
+
+## Why it matters
+
+What problem does it solve?
+
+## Proposed shape
+
+Describe your preferred implementation.
+
+## Additional context
+
+Links, examples, or related tools.

.github/ISSUE_TEMPLATE/good-first-issue.md

@@ -0,0 +1,25 @@
+---
+name: Good first issue
+about: Template for starter tasks to help new contributors join the project.
+title: "[good first issue] "
+labels: ["good first issue"]
+assignees: []
+---
+
+## Goal
+
+Describe the task in one or two sentences.
+
+## Why it matters
+
+Explain how this improves the project.
+
+## Acceptance criteria
+
+- [ ]
+- [ ]
+- [ ]
+
+## Helpful context
+
+Add links, files, or examples that make this easier to complete.

.github/labels-suggested.md

@@ -0,0 +1,17 @@
+# Suggested labels
+
+Create these labels after launch:
+
+- good first issue
+- help wanted
+- documentation
+- recipes
+- schemas
+- design
+- release
+- ideas
+- show-and-tell
+- client:codex
+- client:claude-code
+- client:opencode
+- client:openclaude

.github/pull_request_template.md

@@ -0,0 +1,14 @@
+## What changed
+
+Describe the main changes in this PR.
+
+## Why
+
+Explain the problem or improvement.
+
+## Checklist
+
+- [ ] Docs updated if behavior changed
+- [ ] Examples updated if needed
+- [ ] Changelog updated if user-visible
+- [ ] No unsafe assumptions introduced

.github/release-checklist.md

@@ -0,0 +1,10 @@
+# Release checklist
+
+- bump `VERSION`
+- update `CHANGELOG.md`
+- verify README links
+- verify placeholder endpoints are clearly marked
+- test one workflow recipe end to end
+- create Git tag
+- publish GitHub release notes
+- announce supported clients and best-effort clients clearly

.github/workflows/markdown-lint.yml

@@ -0,0 +1,16 @@
+name: Markdown Check
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  markdown-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: List markdown files
+        run: |
+          find . -type f \( -name "*.md" -o -name "VERSION" \) | sort

.gitignore

@@ -0,0 +1,13 @@
+# local secrets
+.env
+.env.*
+
+# macOS
+.DS_Store
+
+# editor
+.vscode/
+.idea/
+
+# demo exports
+assets/private/

CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+## 0.5.0
+
+- Added launch-ready branding files, including logo and social preview SVG assets
+- Added community onboarding docs, starter issue ideas, and social copy
+- Added GitHub publishing tutorial with both web and CLI flows
+- Added Discussion templates and an extra good-first-issue template
+- Refined README for public launch positioning
+
+## v0.4.0
+
+Launch-focused release that makes the repository ready for public publication on GitHub.
+
+### Added
+- launch assets and copy pack for GitHub, socials, and repository metadata
+- reusable release notes template
+- sample MCP config files for Codex, Claude Code, and OpenCode
+- starter screenshots guide and demo capture checklist
+- launch-day checklist with publishing order and post-launch follow-up
+- README polish for public-facing adoption
+
+### Improved
+- clearer positioning for the project as a planning-first skill kit
+- stronger onboarding guidance for first-time users
+- better launch readiness for open-source publication
+
+## v0.3.0
+
+GitHub-ready skill kit with schema, install guides, and client snippets.
+
+### Added
+- getting started guide
+- install/setup docs
+- normalized plan schema
+- sample plan JSON
+- release checklist
+- concrete client snippets for Codex, Claude Code, OpenCode
+- OpenClaude compatibility notes
+
+### Improved
+- README structure and public-facing docs
+- packaging for publication
+
+## v0.2.0
+
+Second public iteration focused on open-source readiness and documentation maturity.
+
+### Added
+- bilingual README
+- architecture and roadmap docs
+- contributing, security, and changelog files
+- recipes for lead triage, support triage, and invoice reminders
+- walkthrough examples
+- GitHub issue and PR templates
+- starter markdown lint workflow
+
+### Improved
+- project structure for public publishing
+- skill prompt and conversation contract
+
+## v0.1.0
+
+Initial public skeleton of the Vibeflow n8n skill kit.
+
+### Added
+- repository structure
+- initial README
+- skill spec
+- conversation contract
+- publishing guide
+- system prompt
+- intake and final report templates
+- example plans and briefs

CONTRIBUTING.md

@@ -0,0 +1,79 @@
+# Contributing
+
+Thanks for contributing to Vibeflow n8n.
+
+We want this project to stay practical, readable, and friendly to contributors.
+
+## What contributions are welcome
+
+- new recipes
+- better examples
+- client-specific setup improvements
+- docs clarifications
+- prompt refinements
+- validation heuristics
+- packaging improvements for open-source distribution
+
+## Contribution principles
+
+- prefer clarity over cleverness
+- keep examples realistic
+- avoid vendor lock where possible
+- document assumptions explicitly
+- keep the user experience friendly for non-experts
+
+## Branch naming
+
+Suggested branch prefixes:
+- `feat/`
+- `fix/`
+- `docs/`
+- `chore/`
+- `recipe/`
+
+Examples:
+- `feat/add-plan-schema`
+- `docs/improve-opencode-guide`
+- `recipe/lead-qualification-pack`
+
+## Pull requests
+
+A good PR should:
+- explain the problem,
+- describe the change,
+- note any breaking behavior,
+- include updated docs when needed,
+- include an example when behavior changes.
+
+## Documentation expectations
+
+If you change the skill behavior, also update at least one of:
+- `docs/skill-spec.md`
+- `docs/conversation-contract.md`
+- `templates/system-prompt.md`
+- `examples/`
+
+## Recipes
+
+When adding a recipe, include:
+- scenario summary,
+- ideal intake questions,
+- suggested node structure,
+- common risks,
+- validation notes,
+- sample final report excerpt.
+
+## Style guide
+
+- use markdown
+- keep sections short and scannable
+- write for builders, not only prompt engineers
+- avoid unnecessary jargon
+
+## Release notes
+
+When your change matters to users, update `CHANGELOG.md`.
+
+## Security-sensitive changes
+
+If your contribution touches secrets, auth, external communication, or destructive actions, also review `SECURITY.md`.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,208 @@
+# Vibeflow n8n
+
+Build complete n8n workflows through MCP with any coding agent.
+Ask for the goal, generate a plan, build the workflow, validate it, and hand back a usable automation fast.
+
+Português logo abaixo.
+
+## Why this exists
+
+Most people do not want to handcraft automation JSON, memorize node quirks, or map every edge case before the first test. They want to describe the workflow they need and let an agent do the heavy lifting.
+
+Vibeflow n8n is a skill-first open-source kit for agents and CLIs that support MCP. It helps an agent:
+
+- ask the right discovery questions
+- turn answers into a structured implementation plan
+- create or update workflows in n8n via MCP
+- validate the build before handoff
+- report assumptions, gaps, and next steps clearly
+
+## Supported clients
+
+Officially documented targets in this repo:
+
+- Codex CLI
+- Claude Code
+- OpenCode
+
+Experimental or community compatibility:
+
+- OpenClaude and similar MCP-capable forks
+
+## What the skill does
+
+The skill follows a simple five-step loop:
+
+1. Understand the workflow goal
+2. Ask only the questions that change implementation
+3. Produce a normalized plan
+4. Build or update the workflow in n8n via MCP
+5. Return a clean implementation report
+
+This keeps the user experience practical and intuitive, closer to vibe coding than ceremony.
+
+## Repo map
+
+```text
+.
+├── assets/
+├── clients/
+├── docs/
+├── examples/
+├── recipes/
+├── schemas/
+├── templates/
+└── .github/
+```
+
+## Quick start
+
+1. Connect an MCP-capable client to the n8n MCP server.
+2. Load the system prompt and conversation contract from this repo.
+3. Ask the agent to design or build a workflow in natural language.
+4. Let the agent gather the missing details, generate a plan, and build.
+
+Start here:
+
+- `docs/getting-started.md`
+- `docs/install.md`
+- `templates/system-prompt.md`
+- `docs/conversation-contract.md`
+
+## Example prompt
+
+```text
+Build me an n8n workflow that watches a Gmail inbox for invoices,
+saves PDF attachments to Google Drive, extracts key fields,
+logs them to a spreadsheet, and posts failures to Slack.
+Use safe defaults and ask only critical missing questions.
+```
+
+## Launch assets and publishing
+
+This repo includes launch materials for a public release:
+
+- GitHub description and tagline suggestions
+- release notes template
+- launch-day checklist
+- social copy ideas
+- issue and PR templates
+- starter labels and community onboarding docs
+
+See:
+
+- `docs/github-launch.md`
+- `docs/launch-assets.md`
+- `docs/launch-day-checklist.md`
+- `docs/tutorial-subir-github.md`
+
+## Safety and practical limits
+
+The n8n MCP route is powerful, but not magic. Review the upstream limits before promising full automation behavior. The current n8n docs explicitly call out constraints such as a five-minute timeout, no binary input support, and no human-in-the-loop during MCP execution. citeturn863639search0
+
+## Roadmap
+
+Current release line: `0.5.0`
+
+Planned improvements include:
+
+- richer recipes by domain
+- test fixtures for client configs
+- validation helpers for plan payloads
+- gallery assets and demo GIFs
+- community issue labels and starter tasks
+
+See `docs/roadmap.md`.
+
+---
+
+# Vibeflow n8n
+
+Crie workflows completos no n8n via MCP com qualquer agente de código.
+Descreva o objetivo, deixe o agente planejar, construir, validar e devolver uma automação utilizável.
+
+## Por que esse projeto existe
+
+A maioria das pessoas não quer montar JSON na unha, decorar detalhes de nodes ou descobrir cada exceção antes do primeiro teste. Elas querem explicar o que precisam e deixar o agente fazer a parte pesada.
+
+O Vibeflow n8n é um kit open source orientado a skill para agentes e CLIs com suporte a MCP. Ele ajuda o agente a:
+
+- fazer as perguntas certas
+- transformar as respostas em um plano estruturado
+- criar ou atualizar workflows no n8n via MCP
+- validar a construção antes da entrega
+- reportar suposições, lacunas e próximos passos com clareza
+
+## Clientes suportados
+
+Alvos documentados oficialmente neste repositório:
+
+- Codex CLI
+- Claude Code
+- OpenCode
+
+Compatibilidade experimental ou comunitária:
+
+- OpenClaude e forks semelhantes com suporte a MCP
+
+## O que a skill faz
+
+A skill segue um ciclo simples de cinco etapas:
+
+1. Entende o objetivo do workflow
+2. Pergunta apenas o que muda a implementação
+3. Gera um plano normalizado
+4. Cria ou atualiza o workflow no n8n via MCP
+5. Entrega um relatório limpo de implementação
+
+O resultado fica mais prático e intuitivo, bem no espírito de vibe coding.
+
+## Início rápido
+
+1. Conecte um cliente compatível com MCP ao servidor MCP do n8n.
+2. Carregue o system prompt e o contrato de conversa deste repositório.
+3. Peça ao agente, em linguagem natural, para desenhar ou construir um workflow.
+4. Deixe o agente levantar as lacunas críticas, montar o plano e construir.
+
+Comece por aqui:
+
+- `docs/getting-started.md`
+- `docs/install.md`
+- `templates/system-prompt.md`
+- `docs/conversation-contract.md`
+
+## Exemplo de pedido
+
+```text
+Crie um workflow no n8n que monitore um inbox de Gmail para notas fiscais,
+salve anexos PDF no Google Drive, extraia campos principais,
+registre tudo em uma planilha e envie falhas para o Slack.
+Use defaults seguros e pergunte só o que for crítico.
+```
+
+## Publicação no GitHub
+
+Este repositório já inclui material para lançamento:
+
+- sugestões de descrição e tagline
+- template de release notes
+- checklist de lançamento
+- ideias de copy para divulgação
+- templates de issues e PRs
+- docs de onboarding para comunidade
+
+Veja:
+
+- `docs/github-launch.md`
+- `docs/launch-assets.md`
+- `docs/launch-day-checklist.md`
+- `docs/tutorial-subir-github.md`
+
+## Referências
+
+- n8n MCP server docs: `docs.n8n.io`
+- GitHub publishing docs: `docs.github.com`
+
+## Licença
+
+Consulte `LICENSE`.

SECURITY.md

@@ -0,0 +1,44 @@
+# Security Policy
+
+## Scope
+
+This repository contains prompts, conventions, examples, and packaging guidance for agent-driven workflow creation in n8n.
+
+It does not store production secrets by design.
+
+## Reporting a vulnerability
+
+If you discover a security issue related to:
+- secret handling guidance,
+- destructive workflow defaults,
+- unsafe recipe recommendations,
+- risky prompt behavior,
+
+please report it privately before opening a public issue.
+
+Use a private contact method for the maintainer when available.
+
+## Security expectations for contributors
+
+Contributors should avoid introducing guidance that:
+- assumes access to credentials that may not exist,
+- performs destructive actions without explicit user intent,
+- sends external communications without confirmation,
+- hides compliance-sensitive assumptions,
+- suggests storing plaintext secrets in repo files.
+
+## Safe defaults
+
+The skill should prefer:
+- placeholders over fake credentials,
+- explicit assumptions over silent guesses,
+- confirmation for destructive or externally visible actions,
+- human-readable reports for manual review.
+
+## Out of scope
+
+This repository does not guarantee:
+- security of any third-party MCP server,
+- security of any n8n deployment,
+- security of a user's local machine,
+- correctness of external vendor SDKs or CLIs.

VERSION

@@ -0,0 +1 @@
+0.5.0

assets/README.md

@@ -0,0 +1,10 @@
+# Assets
+
+Place public screenshots, social preview images, logos, and demo captures here.
+
+Suggested files:
+- `social-preview.png`
+- `demo-intake.png`
+- `demo-plan.png`
+- `demo-workflow.png`
+- `demo-report.png`

assets/logo.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512" viewBox="0 0 512 512" role="img" aria-label="Vibeflow n8n logo">
+  <rect width="512" height="512" rx="96" fill="#0b1020"/>
+  <path d="M116 320 L196 160 L256 280 L316 160 L396 320" fill="none" stroke="#7fd0ff" stroke-width="26" stroke-linecap="round" stroke-linejoin="round"/>
+  <circle cx="196" cy="160" r="18" fill="#ffffff"/>
+  <circle cx="256" cy="280" r="18" fill="#ffffff"/>
+  <circle cx="316" cy="160" r="18" fill="#ffffff"/>
+  <text x="120" y="410" fill="#f4f7ff" font-family="Arial, Helvetica, sans-serif" font-size="54" font-weight="700">Vibeflow</text>
+</svg>

assets/social-preview.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="640" viewBox="0 0 1280 640" role="img" aria-label="Vibeflow n8n social preview">
+  <rect width="1280" height="640" fill="#0b1020"/>
+  <rect x="64" y="64" width="1152" height="512" rx="28" fill="#11172a" stroke="#2c365a" stroke-width="2"/>
+  <text x="110" y="210" fill="#f4f7ff" font-family="Arial, Helvetica, sans-serif" font-size="64" font-weight="700">Vibeflow n8n</text>
+  <text x="110" y="285" fill="#9fb0d9" font-family="Arial, Helvetica, sans-serif" font-size="30">Build complete n8n workflows through MCP with any coding agent.</text>
+  <text x="110" y="370" fill="#dbe5ff" font-family="Arial, Helvetica, sans-serif" font-size="26">Plan → Build → Validate → Handoff</text>
+  <text x="110" y="430" fill="#7fd0ff" font-family="Arial, Helvetica, sans-serif" font-size="22">Codex CLI · Claude Code · OpenCode · MCP-capable forks</text>
+  <rect x="860" y="150" width="250" height="64" rx="16" fill="#1b2440" stroke="#3a4d80" stroke-width="2"/>
+  <text x="904" y="192" fill="#ffffff" font-family="Arial, Helvetica, sans-serif" font-size="28" font-weight="700">n8n via MCP</text>
+  <rect x="860" y="250" width="250" height="64" rx="16" fill="#1b2440" stroke="#3a4d80" stroke-width="2"/>
+  <text x="918" y="292" fill="#ffffff" font-family="Arial, Helvetica, sans-serif" font-size="28" font-weight="700">Skill-first</text>
+  <rect x="860" y="350" width="250" height="64" rx="16" fill="#1b2440" stroke="#3a4d80" stroke-width="2"/>
+  <text x="900" y="392" fill="#ffffff" font-family="Arial, Helvetica, sans-serif" font-size="28" font-weight="700">Open source</text>
+</svg>

clients/claude-code/README.md

@@ -0,0 +1,27 @@
+# Claude Code
+
+## Goal
+
+Use Vibeflow n8n as a reusable instruction layer for building n8n workflows through MCP.
+
+## Recommended setup idea
+
+- connect Claude Code to the n8n MCP server
+- add the prompt from `templates/system-prompt.md` to your skill or instructions layer
+- keep the docs folder available so the agent can reference the behavior contract
+
+## Suggested operating mode
+
+The best default is `balanced` mode:
+- few but useful questions
+- planning before build
+- explicit assumptions
+- readable delivery report
+
+## Prompt seed
+
+```text
+Follow the Vibeflow n8n skill from this repository. Gather the minimum viable requirements, produce a normalized plan, create or update the workflow through MCP, validate it, and give me a concise final report.
+```
+
+See `config-snippets.md` for example `claude mcp add --scope project` and `.mcp.json` setup.

clients/claude-code/config-snippets.md

@@ -0,0 +1,36 @@
+# Claude Code config snippets
+
+These snippets are examples. Replace placeholder URLs and names with your real n8n MCP configuration.
+
+## Add a project-scoped HTTP MCP server
+
+```bash
+claude mcp add --transport http --scope project n8n https://YOUR-N8N-MCP-ENDPOINT
+```
+
+This writes a `.mcp.json` file at the project root.
+
+## Example `.mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "n8n": {
+      "type": "http",
+      "url": "https://YOUR-N8N-MCP-ENDPOINT"
+    }
+  }
+}
+```
+
+## Optional instruction layer
+
+```text
+Use the Vibeflow n8n behavior in this repository. Ask only essential workflow questions, generate a normalized plan before any n8n changes, build through the n8n MCP server, and return a concise final report.
+```
+
+## Notes
+
+- `local` scope is private to your project entry inside `~/.claude.json`.
+- `project` scope creates a versionable `.mcp.json`.
+- `user` scope makes the server available across projects.

clients/claude-code/sample-mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "n8n": {
+      "command": "npx",
+      "args": ["-y", "n8n-mcp"],
+      "env": {
+        "N8N_BASE_URL": "http://localhost:5678",
+        "N8N_API_KEY": "replace-me"
+      }
+    }
+  }
+}

clients/codex/README.md

@@ -0,0 +1,28 @@
+# Codex CLI
+
+## Goal
+
+Use Vibeflow n8n with Codex CLI as the behavior layer that guides intake, planning, build, validation, and final reporting.
+
+## Recommended setup idea
+
+- connect Codex CLI to the n8n MCP server
+- load the core prompt from `templates/system-prompt.md`
+- optionally keep `docs/skill-spec.md` and `docs/conversation-contract.md` in the working directory for extra context
+
+## Suggested working pattern
+
+1. Start Codex in a project folder that contains this repository.
+2. Ensure MCP access to n8n is configured.
+3. Ask for a workflow in natural language.
+4. Let the agent ask a few focused questions.
+5. Review the plan.
+6. Approve the build.
+
+## Helpful prompt seed
+
+```text
+Use the Vibeflow n8n skill in this repository. Interview me briefly, produce a build plan, then create the workflow in n8n through MCP and return a final handoff report.
+```
+
+See `config-snippets.md` for example `codex mcp add` and `config.toml` setup.

clients/codex/config-snippets.md

@@ -0,0 +1,31 @@
+# Codex CLI config snippets
+
+These snippets are examples. Replace placeholder URLs and names with your real n8n MCP configuration.
+
+## Option 1: add with CLI
+
+```bash
+codex mcp add n8n --url https://YOUR-N8N-MCP-ENDPOINT
+codex mcp list
+```
+
+## Option 2: add in config file
+
+Project-scoped or user-scoped configuration can live in `~/.codex/config.toml` or `.codex/config.toml`.
+
+```toml
+[mcp_servers.n8n]
+url = "https://YOUR-N8N-MCP-ENDPOINT"
+```
+
+## Optional instruction in AGENTS.md
+
+```text
+Always use the n8n MCP server when the request is about creating, updating, validating, or testing n8n workflows. Before building anything, produce a normalized plan that matches schemas/plan.schema.json.
+```
+
+## Suggested first prompt
+
+```text
+Use the Vibeflow n8n skill in this repository. Interview me briefly, produce a normalized plan, then build the workflow in n8n through MCP and finish with a concise handoff report.
+```

clients/codex/sample-config.toml

@@ -0,0 +1,10 @@
+# Example Codex CLI MCP configuration
+# Adjust command, args, and environment to match your local n8n MCP setup.
+
+[mcp_servers.n8n]
+command = "npx"
+args = ["-y", "n8n-mcp"]
+
+[mcp_servers.n8n.env]
+N8N_BASE_URL = "http://localhost:5678"
+N8N_API_KEY = "replace-me"

clients/openclaude/README.md

@@ -0,0 +1,11 @@
+# OpenClaude / Community Forks
+
+This target is community / best-effort.
+
+If your fork supports MCP, adapt one of the sample configurations from the primary clients and point it at your n8n MCP server.
+
+Recommended approach:
+- start from the Claude Code or OpenCode examples
+- verify your client supports local MCP servers
+- confirm environment variable names for the n8n MCP process
+- test a simple read-only operation before creating workflows

clients/openclaude/config-snippets.md

@@ -0,0 +1,23 @@
+# OpenClaude and community forks: config notes
+
+This target is best-effort.
+
+Use these guidelines only if your fork supports:
+- MCP connections
+- custom instruction or skill layers
+- conversational follow-up questions
+
+## Minimal strategy
+
+1. Point your client to the n8n MCP endpoint.
+2. Load `templates/system-prompt.md`.
+3. Keep `docs/conversation-contract.md` and `schemas/plan.schema.json` available.
+4. Test with one simple recipe before using real workflows.
+
+## Compatibility contract
+
+The client should be able to:
+- use an MCP server by name
+- ask follow-up questions
+- emit a structured plan before building
+- complete a final handoff report

clients/opencode/README.md

@@ -0,0 +1,21 @@
+# OpenCode
+
+## Goal
+
+Use this repository as the instruction pack for building n8n workflows conversationally through MCP.
+
+## Suggested setup
+
+- configure the n8n MCP server in OpenCode
+- provide `templates/system-prompt.md` as the primary behavior file
+- optionally pin `docs/skill-spec.md` for extra grounding
+
+## Good defaults
+
+For most users:
+- mode: balanced
+- assumptions: explicit
+- plan required before build: yes
+- final report: concise but complete
+
+See `config-snippets.md` for example `opencode mcp add` and `opencode.jsonc` setup.

clients/opencode/config-snippets.md

@@ -0,0 +1,31 @@
+# OpenCode config snippets
+
+These snippets are examples. Replace placeholder URLs and names with your real n8n MCP configuration.
+
+## Guided setup
+
+```bash
+opencode mcp add
+opencode mcp list
+```
+
+## Example `opencode.jsonc`
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "n8n": {
+      "type": "remote",
+      "url": "https://YOUR-N8N-MCP-ENDPOINT",
+      "enabled": true
+    }
+  }
+}
+```
+
+## Suggested agent instruction
+
+```text
+When the task is about n8n workflows, use the n8n MCP server and follow the Vibeflow n8n repository contract. Produce a normalized plan first, then build, validate, and report.
+```

clients/opencode/sample-opencode.jsonc

@@ -0,0 +1,13 @@
+{
+  // Example OpenCode configuration
+  "mcp": {
+    "n8n": {
+      "type": "local",
+      "command": ["npx", "-y", "n8n-mcp"],
+      "env": {
+        "N8N_BASE_URL": "http://localhost:5678",
+        "N8N_API_KEY": "replace-me"
+      }
+    }
+  }
+}

docs/architecture.md

@@ -0,0 +1,160 @@
+# Architecture
+
+## Purpose
+
+Vibeflow n8n is a skill-first architecture for building complete n8n workflows through MCP-capable coding agents.
+
+It is not a standalone runtime.
+It is a reusable behavioral layer that can be attached to different agent clients.
+
+## High-level components
+
+### 1. User
+The human describes the automation goal in natural language.
+
+### 2. Agent client
+A CLI or coding assistant that supports:
+- custom instructions / skills,
+- MCP connections,
+- conversational follow-ups,
+- optional local file awareness.
+
+Examples:
+- Codex CLI
+- Claude Code
+- OpenCode
+- compatible community forks
+
+### 3. Vibeflow skill layer
+This repository provides the skill logic:
+- how to interview the user,
+- how to normalize requirements,
+- how to decide what must be asked,
+- how to create a plan,
+- how to validate the build,
+- how to report completion.
+
+### 4. n8n MCP server
+The execution bridge between the agent and n8n.
+
+The skill does not directly manipulate n8n internals.
+It relies on the MCP-exposed capabilities available in the connected environment.
+
+### 5. n8n instance
+The target automation environment where workflows are created, updated, and later run.
+
+## Core architecture pattern
+
+```text
+User intent
+   -> Conversational intake
+   -> Normalized plan
+   -> MCP build actions
+   -> Validation pass
+   -> Human-readable handoff
+```
+
+## Why planning-first matters
+
+Without a planning step, agents tend to:
+- over-assume missing requirements,
+- create brittle node graphs,
+- hide unresolved credential problems,
+- return workflows that are technically created but operationally confusing.
+
+The plan acts like a blueprint before the steel beams go up.
+
+## Build stages
+
+### Stage 1. Intake
+The agent captures:
+- business goal,
+- trigger,
+- systems involved,
+- desired output,
+- rules and exceptions.
+
+### Stage 2. Requirement triage
+The agent separates:
+- critical unknowns,
+- optional detail,
+- safe defaults.
+
+### Stage 3. Normalized plan
+The agent produces a standard structure for execution.
+This makes behavior portable across clients.
+
+### Stage 4. MCP execution
+The agent creates or updates the workflow using the available MCP tools.
+
+### Stage 5. Validation
+The agent checks for:
+- broken graph structure,
+- missing dependencies,
+- unsupported assumptions,
+- absent failure branches,
+- unresolved placeholders.
+
+### Stage 6. Delivery
+The agent produces a report for the user that is operational, not ornamental.
+
+## Recommended workflow object model
+
+A normalized plan should include:
+- workflow_name
+- workflow_mode
+- business_goal
+- trigger
+- systems_involved
+- steps
+- branching_logic
+- data_contracts
+- credentials_required
+- risk_flags
+- error_handling
+- test_strategy
+- assumptions
+- open_questions
+
+## Modes
+
+### fast
+Prototype-first mode.
+Uses more defaults and fewer follow-up questions.
+
+### balanced
+Default mode.
+Good mix of speed and operational sanity.
+
+### safe
+More explicit approvals, stronger validation, fewer silent assumptions.
+
+## Portability strategy
+
+The repository is intentionally text-first.
+That means:
+- prompts are markdown,
+- rules are markdown,
+- examples are markdown,
+- client-specific notes are lightweight.
+
+This keeps the project easy to adapt across agent ecosystems without locking it to a single vendor format.
+
+## Non-goals
+
+This repository does not try to:
+- replace n8n documentation,
+- replace the n8n MCP server,
+- become a full workflow execution engine,
+- hide MCP limitations,
+- generate production security posture automatically.
+
+## Future architecture extensions
+
+Potential future additions:
+- schema-driven plan JSON
+- linter rules for anti-pattern detection
+- recipe loader / scenario packs
+- test case generator
+- workflow diff summarizer
+- upgrade assistant for existing workflows

docs/brand-kit.md

@@ -0,0 +1,37 @@
+# Brand kit
+
+## Project name
+
+**Vibeflow n8n**
+
+## One-line description
+
+Build complete n8n workflows through MCP with any coding agent.
+
+## Tagline options
+
+- From idea to workflow, fast.
+- Describe the automation. Let the agent build it.
+- Vibe code your n8n workflows through MCP.
+
+## Short elevator pitch
+
+Vibeflow n8n is a skill-first open-source kit that helps MCP-capable coding agents plan, build, validate, and hand off complete n8n workflows from natural-language requests.
+
+## Voice
+
+- practical
+- sharp
+- builder-friendly
+- low-ceremony
+- transparent about limits
+
+## Suggested GitHub About
+
+**Description**
+
+Build complete n8n workflows through MCP with any coding agent.
+
+**Topics**
+
+`n8n`, `mcp`, `automation`, `ai-agents`, `workflow-automation`, `codex`, `claude-code`, `opencode`, `vibe-coding`

docs/community-onboarding.md

@@ -0,0 +1,32 @@
+# Community onboarding
+
+This document helps new contributors land softly and find meaningful first steps.
+
+## Good first areas
+
+- improve examples and walkthroughs
+- add recipes for new automation domains
+- polish client-specific setup docs
+- add social preview assets and screenshots
+- improve validation and plan schema examples
+
+## Suggested labels
+
+- `good first issue`
+- `help wanted`
+- `documentation`
+- `recipes`
+- `client:codex`
+- `client:claude-code`
+- `client:opencode`
+- `client:openclaude`
+- `design`
+- `release`
+
+## First contribution ideas
+
+- add one new recipe with a real-world brief
+- improve one client setup guide
+- translate part of the docs
+- add one README screenshot or GIF guide
+- refine the final report template

docs/conversation-contract.md

@@ -0,0 +1,106 @@
+# Conversation Contract
+
+## Purpose
+
+Define how the agent should conduct the conversation before, during, and after building a workflow in n8n through MCP.
+
+## Primary rule
+
+The agent should ask as little as possible, but not less than the workflow requires.
+
+## Intake sequence
+
+### Step 1. Capture the goal
+The first objective is to understand what the workflow is meant to achieve.
+
+The user may describe:
+- a business outcome,
+- a trigger event,
+- a sequence of actions,
+- a pain point,
+- or a half-formed idea.
+
+The agent should convert that into a rough workflow shape.
+
+### Step 2. Identify critical unknowns
+The agent should decide which missing answers materially affect architecture.
+
+Examples of critical unknowns:
+- trigger type,
+- source system,
+- destination system,
+- duplicate handling,
+- approval requirements,
+- customer-facing communication,
+- destructive actions.
+
+### Step 3. Ignore optional fluff until later
+Do not ask for decorative detail early.
+
+Examples of low-priority detail:
+- exact message wording,
+- aesthetic naming choices,
+- optional metadata fields,
+- low-risk formatting preferences.
+
+## Recommended opening question set
+
+Use this only when needed.
+
+1. What should trigger the workflow?
+2. Which apps or systems are involved?
+3. What should happen from start to finish?
+4. Are there any rules, approvals, or exceptions I should respect?
+
+## Planning contract
+
+Before building, the agent should create a normalized planning summary containing:
+- workflow_name
+- workflow_mode
+- business_goal
+- trigger
+- systems_involved
+- steps
+- branching_logic
+- credentials_required
+- error_handling
+- assumptions
+- open_questions
+- test_strategy
+
+## Assumption policy
+
+The agent may infer safe defaults for low-risk details.
+The agent must clearly state those assumptions.
+
+The agent must not silently assume:
+- financial actions,
+- user-facing outbound communication,
+- delete or overwrite behavior,
+- approval rules,
+- legal/compliance-sensitive logic.
+
+## Build communication
+
+When moving into build mode, the agent should summarize:
+- what it believes it is building,
+- what assumptions it will use,
+- what remains unresolved.
+
+## Final handoff contract
+
+The final response should contain:
+- summary of workflow created,
+- assumptions used,
+- unresolved dependencies,
+- manual setup still required,
+- simple test instructions,
+- logical next improvements.
+
+## Bad conversation patterns to avoid
+
+- asking 10 questions when 3 are enough
+- pretending credentials exist
+- skipping the planning summary
+- hiding uncertainty
+- returning a technical success without operational clarity

docs/demo-assets.md

@@ -0,0 +1,49 @@
+# Demo Assets Guide
+
+Use this document to prepare screenshots, terminal captures, and visual assets for launch.
+
+## Recommended visuals
+
+### 1. Terminal intake flow
+Show the agent asking for:
+- the workflow goal
+- trigger type
+- apps involved
+- final action
+- exceptions or approvals
+
+### 2. Plan output
+Capture the normalized plan before the build starts.
+
+### 3. Build confirmation
+Show the agent summarizing what it created inside n8n.
+
+### 4. n8n workflow canvas
+Capture the resulting workflow with readable node names.
+
+### 5. Final handoff report
+Show the concise report listing:
+- what was created
+- assumptions used
+- missing credentials
+- test steps
+
+## Capture tips
+
+- avoid showing secrets or real tokens
+- use short examples with familiar tools like Slack, Airtable, Gmail, HubSpot
+- prefer light, readable terminal themes
+- crop screenshots tightly
+- keep filenames predictable, for example:
+  - `demo-intake.png`
+  - `demo-plan.png`
+  - `demo-build.png`
+  - `demo-workflow.png`
+  - `demo-report.png`
+
+## Suggested README image order
+
+1. hero image or terminal screenshot
+2. plan screenshot
+3. workflow screenshot
+4. final report screenshot

docs/first-issues.md

@@ -0,0 +1,31 @@
+# First issues to open after launch
+
+## 1. Add CRM lead enrichment recipe
+
+**Label suggestions:** `good first issue`, `recipes`
+
+Add a recipe for lead enrichment using webhook input, enrichment step, CRM upsert, and Slack notification on failure.
+
+## 2. Add screenshots to README
+
+**Label suggestions:** `good first issue`, `documentation`, `design`
+
+Capture and add 2 to 4 screenshots or GIFs showing setup and a sample workflow result.
+
+## 3. Expand Claude Code setup guide
+
+**Label suggestions:** `good first issue`, `client:claude-code`, `documentation`
+
+Add a more detailed example for project-scoped MCP configuration and prompt loading.
+
+## 4. Add Portuguese quickstart page
+
+**Label suggestions:** `good first issue`, `documentation`
+
+Create a dedicated PT-BR quickstart page instead of keeping onboarding only inside the README.
+
+## 5. Add plan validation examples
+
+**Label suggestions:** `help wanted`, `schemas`
+
+Contribute passing and failing examples for `schemas/plan.schema.json`.

docs/getting-started.md

@@ -0,0 +1,72 @@
+# Getting Started
+
+This is the fastest path from zero to first workflow.
+
+## 1. Pick a client
+
+Recommended order:
+- Codex CLI
+- Claude Code
+- OpenCode
+
+If you are testing community forks, start with OpenClaude only after one of the primary clients is working.
+
+## 2. Make the repository available to the agent
+
+Minimum useful context:
+- `templates/system-prompt.md`
+- `docs/conversation-contract.md`
+- `schemas/plan.schema.json`
+
+Good default:
+- clone this repo in the same working directory as your automation project.
+
+## 3. Connect the client to n8n via MCP
+
+Use the client-specific notes in `clients/` and keep the n8n MCP endpoint, auth method, and environment variables outside the core prompt.
+
+## 4. Start with one recipe
+
+Use one of the examples in `recipes/` instead of jumping straight into a production-critical workflow.
+
+Recommended first runs:
+- support triage
+- lead triage
+- invoice reminder
+
+## 5. Enforce the plan-first contract
+
+Before the agent creates anything in n8n, it should produce a normalized plan with:
+- objective
+- trigger
+- systems involved
+- steps
+- branching logic
+- credentials needed
+- assumptions
+- validation plan
+
+Use `schemas/plan.schema.json` as the format contract.
+
+## 6. Approve the build
+
+After reviewing the plan, let the agent:
+- create or update the workflow in n8n
+- name nodes clearly
+- add placeholders when credentials are missing
+- return a final report
+
+## 7. Run the first test
+
+Your first test should confirm:
+- the trigger is reachable or scheduled correctly
+- each branch is connected
+- missing credentials are listed clearly
+- error paths are explicit
+- output nodes match the intended business result
+
+## First prompt to try
+
+```text
+Use the Vibeflow n8n skill in this repository. Interview me briefly, produce a normalized plan that matches the schema, then build the workflow in n8n through MCP and finish with a concise handoff report.
+```

docs/github-launch.md

@@ -0,0 +1,49 @@
+# GitHub Launch Pack
+
+## Suggested repository name
+
+- `vibeflow-n8n`
+
+## Suggested short description
+
+Build complete n8n workflows via MCP using coding agents like Codex CLI, Claude Code, and OpenCode.
+
+## Suggested tagline
+
+Planning-first n8n workflow generation for MCP-capable coding agents.
+
+## Suggested topics
+
+- n8n
+- mcp
+- model-context-protocol
+- automation
+- ai-agents
+- codex
+- claude-code
+- opencode
+- workflow
+- vibe-coding
+
+## Suggested social preview headline
+
+Turn natural-language automation requests into usable n8n workflows.
+
+## Suggested release title
+
+`v0.4.0 - Launch-ready release with repo copy, sample configs, and demo assets`
+
+## Suggested release notes
+
+Vibeflow n8n v0.4.0 is the first launch-ready release of the project.
+
+Highlights:
+- polished public-facing README
+- launch-day checklist
+- reusable release notes template
+- demo assets guide
+- sample config files for supported clients
+- stronger open-source positioning
+
+Recommended next step:
+Publish the repository, attach 1 to 3 screenshots, and test one recipe end-to-end.

docs/install.md

@@ -0,0 +1,47 @@
+# Install and Setup
+
+This document gives practical setup guidance for each supported client. Keep credentials and secret values out of the repository whenever possible.
+
+## Shared prerequisites
+
+Before setting up a client, make sure you have:
+- a working n8n instance
+- access to its MCP server or MCP-enabled endpoint
+- a client that supports MCP
+- a place to store client-level config and auth safely
+
+## Recommended setup pattern
+
+1. Configure the n8n MCP server in the client.
+2. Keep this repository in the working directory.
+3. Reference `templates/system-prompt.md` and `docs/conversation-contract.md`.
+4. Ask the agent to emit a normalized plan before it builds.
+5. Test with one recipe.
+
+## Codex CLI
+
+See `clients/codex/config-snippets.md`.
+
+## Claude Code
+
+See `clients/claude-code/config-snippets.md`.
+
+## OpenCode
+
+See `clients/opencode/config-snippets.md`.
+
+## OpenClaude and forks
+
+See `clients/openclaude/config-snippets.md`.
+
+## Secrets and auth
+
+Prefer one of these patterns:
+- client-managed OAuth flow
+- environment variables referenced by the client config
+- local machine secret manager
+
+Avoid putting raw secrets in:
+- repository-tracked JSON files
+- prompt templates
+- examples intended for public publication

docs/launch-assets.md

@@ -0,0 +1,54 @@
+# Launch Assets Pack
+
+## Repository metadata
+
+### Name
+`vibeflow-n8n`
+
+### Short description
+Build complete n8n workflows via MCP using coding agents like Codex CLI, Claude Code, and OpenCode.
+
+### Tagline
+Planning-first n8n workflow generation for MCP-capable coding agents.
+
+### Topics
+- n8n
+- mcp
+- model-context-protocol
+- automation
+- ai-agents
+- codex
+- claude-code
+- opencode
+- workflow
+- vibe-coding
+
+## Social post draft
+
+Launching **Vibeflow n8n** ⚙️
+
+An open-source skill kit for building complete **n8n workflows via MCP** with coding agents like **Codex CLI**, **Claude Code**, and **OpenCode**.
+
+It helps agents:
+- ask only the questions that matter
+- create a normalized plan first
+- build or update the workflow in n8n
+- return a clean handoff with assumptions and test steps
+
+Built for practical, planning-first vibe coding.
+
+## GitHub release title
+
+`v0.4.0 - Launch-ready release with repo copy, sample configs, and demo assets`
+
+## GitHub release summary
+
+Vibeflow n8n v0.4.0 is the first launch-ready release of the project.
+
+Highlights:
+- public-facing README polish
+- launch-day checklist
+- demo assets guide
+- reusable release notes
+- sample config files for supported clients
+- improved project positioning for open-source adoption

docs/launch-day-checklist.md

@@ -0,0 +1,38 @@
+# Launch-Day Checklist
+
+## Before publishing
+
+- confirm repository name
+- confirm public vs private visibility
+- validate `README.md` renders correctly on GitHub
+- confirm all internal links work
+- confirm `VERSION` and `CHANGELOG.md` match
+- verify license choice
+- verify sample configs do not contain secrets
+- test at least one recipe on one primary client
+- add 1 to 3 screenshots or terminal captures
+- prepare first release notes
+
+## Recommended publish order
+
+1. create the GitHub repository
+2. push the default branch
+3. configure repository description and topics
+4. upload social preview image
+5. pin one usage example in the README
+6. publish release `v0.4.0`
+7. post a short launch note on social platforms or communities
+
+## After publishing
+
+- open 2 to 3 starter issues labeled `good first issue`
+- add a discussion or feedback thread
+- watch first user setup pain points
+- collect examples from early users
+- plan `v0.5.0` based on real friction
+
+## Nice extras
+
+- record a 30 to 60 second terminal demo
+- add a GIF to the README
+- include before/after screenshots of manual vs agentic workflow creation

docs/publishing-guide.md

@@ -0,0 +1,106 @@
+# Publishing Guide
+
+## 1. Choose the repo shape
+
+Recommended public repository name:
+
+- `vibeflow-n8n`
+
+## 2. Add baseline project files
+
+Recommended extras:
+
+- `LICENSE`
+- `.gitignore`
+- `CONTRIBUTING.md`
+- `CHANGELOG.md`
+- `SECURITY.md`
+
+## 3. First release scope
+
+Keep v1 small and useful:
+
+- one main system prompt,
+- one conversation contract,
+- one delivery template,
+- examples for common workflow requests,
+- setup snippets for Codex, Claude Code, and OpenCode.
+
+## 4. What to show in the README
+
+The homepage should answer quickly:
+
+- What is this?
+- Who is it for?
+- How does it work?
+- Which clients are supported?
+- How do I install it?
+- How do I use it?
+- What are the limitations?
+
+## 5. Suggested release roadmap
+
+### v0.1.0
+- public repo
+- core prompt and docs
+- 3 examples
+
+### v0.2.0
+- client-specific setup guides
+- stronger validation checklist
+- workflow naming conventions
+
+### v0.3.0
+- recipe library
+- vertical templates: support, CRM, AI agents, finance ops
+
+### v1.0.0
+- stable docs
+- broad examples
+- community contribution guide
+
+## 6. Community strategy
+
+Useful GitHub labels:
+
+- `good first issue`
+- `template-request`
+- `client-support`
+- `docs`
+- `examples`
+- `bug`
+- `enhancement`
+
+## 7. Good demo ideas
+
+Use examples that are instantly understandable:
+
+- Typeform -> AI summary -> Slack -> Airtable
+- Gmail -> classify with AI -> route to Notion
+- Webhook -> validate -> score -> HubSpot
+- Schedule -> fetch API -> transform -> Google Sheets
+
+## 8. Keep the promise narrow
+
+Do not promise that the agent can fully solve:
+
+- missing credentials,
+- closed-source app quirks,
+- broken third-party APIs,
+- runtime approvals/human loops through MCP-triggered execution.
+
+## 9. Badges you may want
+
+- License
+- Release
+- Docs status
+- MCP compatible
+- n8n compatible
+
+## 10. Launch checklist
+
+- README clear and short
+- examples tested
+- client instructions readable
+- limitations explicit
+- sample prompts included

docs/release-notes-template.md

@@ -0,0 +1,36 @@
+# Release Notes Template
+
+## Title
+`vX.Y.Z - one-line summary`
+
+## Summary
+
+Briefly explain what changed and why this release matters.
+
+## Highlights
+
+- item 1
+- item 2
+- item 3
+
+## Added
+
+- new files
+- new docs
+- new examples
+
+## Improved
+
+- onboarding
+- naming
+- consistency
+
+## Fixed
+
+- broken links
+- typos
+- example mismatches
+
+## Upgrade notes
+
+Mention anything existing users should review after pulling the new version.

docs/roadmap.md

@@ -0,0 +1,33 @@
+# Roadmap
+
+## Current state: v0.3.0
+
+V3 is designed to be GitHub-ready:
+- documentation is stronger
+- client setup is more concrete
+- a normalized plan schema exists
+- examples are easier to adapt
+- release flow is clearer
+
+## v0.4.0 ideas
+
+- richer sample plans across domains
+- optional validation checklist by workflow type
+- repository screenshots and terminal captures
+- sample `.mcp.json`, `config.toml`, and `opencode.jsonc` fixtures
+- stricter final report format
+
+## v0.5.0 ideas
+
+- test harness for plan validation
+- library of domain-specific recipes
+- template packs for lead ops, support ops, finance ops, and AI agents
+- optional workflow quality scoring rubric
+
+## Long-term direction
+
+Turn Vibeflow n8n into a portable skill pack that:
+- speaks natural language with minimal friction
+- plans before building
+- works across multiple MCP-capable coding agents
+- remains understandable to non-experts

docs/skill-spec.md

@@ -0,0 +1,152 @@
+# Skill Specification
+
+## Goal
+
+Enable an AI coding agent to create, update, and validate complete n8n workflows through MCP, using a conversational intake process and a planning-first approach.
+
+## Primary user promise
+
+The user describes what they want.
+The agent asks only the minimum useful questions.
+The agent produces a plan.
+The agent builds the workflow in n8n.
+The agent returns a clear handoff report.
+
+## Inputs
+
+### Required
+- workflow goal
+
+### Usually required
+- trigger type
+- connected apps/services
+- expected final output
+
+### Sometimes required
+- schedule/frequency
+- payload schema
+- approval logic
+- credential ownership
+- fallback behavior
+- notification behavior
+- testing sample
+
+## Outputs
+
+The skill should return:
+
+1. a structured plan,
+2. a summary of assumptions,
+3. the workflow creation/update result,
+4. unresolved dependencies,
+5. a validation report,
+6. a concise next-step checklist.
+
+## Operational sequence
+
+### 1. Intake
+Start with the user goal.
+Extract likely workflow shape.
+Ask only high-impact follow-up questions.
+
+### 2. Plan
+Before touching n8n, generate a normalized plan object with:
+
+- workflow_name
+- business_goal
+- trigger
+- systems_involved
+- steps
+- branching_logic
+- data_required
+- credentials_required
+- error_handling
+- test_strategy
+- open_questions
+- assumptions
+
+### 3. Build via MCP
+Use the n8n MCP tools to:
+
+- create a new workflow or update an existing one,
+- add the correct trigger,
+- add named nodes with sensible ordering,
+- wire success and failure paths,
+- add comments/descriptions where helpful,
+- preserve placeholders where credentials or secrets are missing.
+
+### 4. Validate
+Check for:
+
+- disconnected nodes,
+- missing required fields,
+- invalid trigger assumptions,
+- absent credential references,
+- branches with no terminal behavior,
+- missing error handling where failure is likely.
+
+### 5. Deliver
+Provide:
+
+- what was created,
+- what assumptions were used,
+- what still requires manual setup,
+- how to test the workflow,
+- what upgrades would make sense next.
+
+## Guardrails
+
+### The skill must
+- prefer asking fewer but better questions,
+- distinguish between critical unknowns and optional details,
+- state assumptions explicitly,
+- avoid pretending credentials exist when they do not,
+- avoid claiming execution success without validation evidence,
+- keep the workflow understandable for humans.
+
+### The skill must not
+- over-interview the user,
+- hide missing data,
+- create needlessly complex node graphs,
+- skip the planning stage,
+- silently invent production credentials.
+
+## Defaults policy
+
+The skill may infer safe defaults for:
+
+- workflow naming,
+- timezone if supplied elsewhere in context,
+- retry behavior,
+- notification formatting,
+- low-risk field mappings,
+- common error branches.
+
+The skill must ask before assuming for:
+
+- legal/compliance-sensitive logic,
+- destructive actions,
+- billing/payment side effects,
+- approval rules,
+- CRM upsert vs create-only behavior,
+- external communications that could spam users.
+
+## Recommended modes
+
+### fast
+Minimum questions, maximum assumptions, optimized for prototypes.
+
+### balanced
+Default mode. Good production-minded assumptions with limited follow-ups.
+
+### safe
+More validation, more explicit approvals, better for real operations.
+
+## Success criteria
+
+A good run means:
+
+- the workflow structure matches the user intent,
+- the workflow is understandable,
+- missing pieces are clearly called out,
+- the user can continue from the final report without confusion.

docs/social-copy.md

@@ -0,0 +1,29 @@
+# Social copy
+
+## Launch post 1
+
+Today I’m open-sourcing **Vibeflow n8n**.
+
+It is a skill-first kit for coding agents that can build complete **n8n workflows through MCP**.
+
+Instead of handcrafting every node, the agent asks for the goal, generates a plan, builds the workflow, validates it, and hands back a usable automation.
+
+Supports:
+- Codex CLI
+- Claude Code
+- OpenCode
+- MCP-capable forks
+
+## Launch post 2
+
+Built something for the vibe coders and automation builders.
+
+**Vibeflow n8n** helps MCP-capable agents turn natural-language requests into real n8n workflows.
+
+Planning, build, validation, and handoff, all inside a skill-first open-source repo.
+
+## Short post
+
+Open-sourced: **Vibeflow n8n**
+
+Build complete n8n workflows through MCP with coding agents like Codex CLI, Claude Code, and OpenCode.

docs/tutorial-subir-github.md

@@ -0,0 +1,236 @@
+# Tutorial: como subir o Vibeflow n8n no GitHub
+
+Este guia foi feito para você publicar o projeto de forma prática, sem virar refém de um labirinto de menus.
+
+## Antes de começar
+
+Tenha em mãos:
+
+- uma conta no GitHub
+- Git instalado no computador, se for usar terminal
+- a pasta local do projeto ou o ZIP extraído
+- um nome final para o repositório, por exemplo `vibeflow-n8n`
+
+O GitHub permite criar um novo repositório pela interface web ou subir um projeto local pela linha de comando com GitHub CLI. A documentação oficial cobre os dois caminhos. citeturn863639search0turn863639search3turn863639search14
+
+## Caminho 1: subir pelo site do GitHub + Git local
+
+### 1) Crie o repositório vazio
+
+No GitHub:
+
+- clique no canto superior direito em **New repository**
+- escolha o nome do repositório, por exemplo `vibeflow-n8n`
+- adicione uma descrição curta
+- escolha **Public**
+- não marque README, `.gitignore` ou licença, porque este projeto já contém esses arquivos
+- clique em **Create repository**
+
+Esses passos seguem o fluxo atual do GitHub para criação de repositórios. citeturn863639search0
+
+### 2) Extraia o ZIP da V5 no seu computador
+
+Descompacte o pacote em uma pasta local. Exemplo:
+
+```bash
+unzip n8n-workflow-skill-kit-v0.5.0.zip
+cd n8n-workflow-skill-kit
+```
+
+### 3) Inicialize o Git localmente
+
+Se a pasta ainda não for um repositório Git:
+
+```bash
+git init
+git add .
+git commit -m "feat: launch Vibeflow n8n v0.5.0"
+```
+
+### 4) Conecte ao repositório remoto
+
+Copie a URL do seu repositório recém-criado e rode:
+
+```bash
+git branch -M main
+git remote add origin https://github.com/SEU_USUARIO/vibeflow-n8n.git
+git push -u origin main
+```
+
+A própria documentação do GitHub cobre o fluxo de adicionar código local a um repositório remoto. citeturn863639search9turn863639search19
+
+## Caminho 2: subir usando GitHub CLI
+
+Se você usa `gh`, o caminho fica bem mais liso.
+
+### 1) Entre na pasta do projeto
+
+```bash
+cd n8n-workflow-skill-kit
+```
+
+### 2) Inicialize e faça o primeiro commit
+
+```bash
+git init
+git add .
+git commit -m "feat: launch Vibeflow n8n v0.5.0"
+```
+
+### 3) Crie e publique com `gh`
+
+```bash
+gh repo create vibeflow-n8n --public --source=. --remote=origin --push
+```
+
+O GitHub CLI documenta esse fluxo oficialmente para criar um repositório e subir um projeto local existente. citeturn863639search3turn863639search14
+
+## Depois do push: arrumando a vitrine do repositório
+
+### 1) Ajuste descrição e website
+
+Na página principal do repositório:
+
+- clique no ícone de engrenagem na área de About
+- adicione a descrição
+- opcionalmente, adicione um site ou link de demo
+
+Sugestão de descrição:
+
+```text
+Build complete n8n workflows through MCP with any coding agent.
+```
+
+### 2) Adicione topics
+
+Topics ajudam o projeto a ser encontrado. O GitHub recomenda usá-los para classificar o repositório por assunto e finalidade. citeturn863639search5turn863639search11
+
+Sugestão de topics:
+
+```text
+n8n, mcp, automation, ai-agents, codex, claude-code, opencode, workflow-automation, vibe-coding
+```
+
+### 3) Configure a social preview
+
+No GitHub:
+
+- abra **Settings**
+- procure a área **Social preview**
+- envie uma imagem de capa
+
+O GitHub suporta customização da imagem de preview social diretamente nas configurações do repositório. citeturn863639search2turn863639search8
+
+### 4) Faça a primeira release
+
+Na aba principal do repositório:
+
+- clique em **Releases**
+- clique em **Draft a new release**
+- use a tag `v0.5.0`
+- título sugerido: `Vibeflow n8n v0.5.0`
+- cole as release notes com base em `docs/release-notes-template.md`
+- publique
+
+O fluxo de criação de release está documentado pelo GitHub na área de releases do repositório. citeturn863639search1
+
+## Ordem recomendada de publicação
+
+Use esta sequência:
+
+1. extraia o ZIP
+2. ajuste nome final do projeto, se quiser
+3. faça `git init`
+4. commit inicial
+5. crie o repo no GitHub
+6. push da branch `main`
+7. revise README e About
+8. adicione topics
+9. suba social preview
+10. publique a release `v0.5.0`
+11. compartilhe
+
+## Checklist de comando rápido
+
+### Via Git puro
+
+```bash
+cd n8n-workflow-skill-kit
+git init
+git add .
+git commit -m "feat: launch Vibeflow n8n v0.5.0"
+git branch -M main
+git remote add origin https://github.com/SEU_USUARIO/vibeflow-n8n.git
+git push -u origin main
+```
+
+### Via GitHub CLI
+
+```bash
+cd n8n-workflow-skill-kit
+git init
+git add .
+git commit -m "feat: launch Vibeflow n8n v0.5.0"
+gh repo create vibeflow-n8n --public --source=. --remote=origin --push
+```
+
+## Erros comuns
+
+### O GitHub rejeitou o push porque o repositório remoto já tinha arquivos
+
+Isso normalmente acontece se você criou README ou `.gitignore` no GitHub na hora de criar o repositório. A saída mais limpa é criar outro repositório vazio, sem arquivos iniciais.
+
+### Subi arquivos sensíveis sem querer
+
+Pare e remova imediatamente. O GitHub alerta para não commitar segredos ou credenciais em repositórios remotos. citeturn863639search4
+
+### O ZIP foi extraído com uma pasta a mais
+
+Entre na pasta correta antes de rodar `git init`, senão você publica um matrioshka de diretórios.
+
+## Texto pronto para o About do repositório
+
+**Description**
+
+```text
+Build complete n8n workflows through MCP with any coding agent.
+```
+
+**Website**
+
+Use seu futuro site, post, demo ou deixe em branco.
+
+**Topics**
+
+```text
+n8n
+mcp
+automation
+ai-agents
+workflow-automation
+codex
+claude-code
+opencode
+vibe-coding
+```
+
+## Texto pronto para a primeira release
+
+**Tag**
+
+```text
+v0.5.0
+```
+
+**Title**
+
+```text
+Vibeflow n8n v0.5.0
+```
+
+**Summary**
+
+```text
+First public launch of Vibeflow n8n, a skill-first open-source kit for building complete n8n workflows through MCP with coding agents like Codex CLI, Claude Code, and OpenCode.
+```
+

examples/example-briefs.md

@@ -0,0 +1,10 @@
+# Example Briefs
+
+## Example 1
+Create an n8n workflow that receives leads from a webhook, scores them with AI, sends hot leads to Slack, and stores everything in HubSpot.
+
+## Example 2
+Create a workflow that runs every weekday at 8 AM, pulls yesterday's orders from an API, summarizes key metrics, and posts the summary to Microsoft Teams.
+
+## Example 3
+Create a workflow that watches Gmail for invoices, extracts key information with AI, stores structured records in Airtable, and alerts finance when the amount is above a threshold.

examples/example-final-report.md

@@ -0,0 +1,30 @@
+# Example Final Report
+
+## Summary
+A workflow named `Lead Intake and Triage` was created to receive incoming lead data, score urgency using AI, send high-priority leads to Slack, and store all leads in HubSpot.
+
+## What was created
+- Webhook trigger for incoming lead payloads
+- Validation step for required lead fields
+- AI scoring and summarization step
+- Conditional branch for hot leads
+- Slack notification for hot leads
+- HubSpot create/update action
+- Generic failure notification path
+
+## Assumptions used
+- Lead uniqueness is based on email
+- Slack notifications are required only for hot leads
+- Missing optional fields do not block processing
+
+## Manual setup still required
+- Connect OpenAI credentials
+- Connect Slack credentials
+- Connect HubSpot credentials
+- Review final field mappings for HubSpot properties
+
+## How to test
+1. Send a sample payload to the webhook
+2. Confirm the AI score is produced
+3. Verify hot leads appear in Slack
+4. Verify the record is stored in HubSpot

examples/example-plans.md

@@ -0,0 +1,29 @@
+# Example Plans
+
+## Example 1 Plan
+
+- Workflow name: Lead Intake and Triage
+- Trigger: Webhook
+- Systems: Webhook, OpenAI, Slack, HubSpot
+- Steps:
+  - Receive lead payload
+  - Validate required fields
+  - Score and summarize with AI
+  - Branch on urgency
+  - Notify Slack for hot leads
+  - Upsert lead in HubSpot
+- Error handling:
+  - Return validation error on missing fields
+  - Send Slack alert on workflow failure
+
+## Example 2 Plan
+
+- Workflow name: Daily Orders Digest
+- Trigger: Schedule weekdays 08:00
+- Systems: HTTP API, Code/Transform, Microsoft Teams
+- Steps:
+  - Run on schedule
+  - Fetch yesterday's orders
+  - Aggregate totals and deltas
+  - Generate concise summary
+  - Post digest to Teams

examples/example-walkthroughs.md

@@ -0,0 +1,39 @@
+# Example Walkthroughs
+
+## Walkthrough 1: Lead qualification
+
+### User request
+Create an n8n workflow that receives a website lead, summarizes the lead using AI, classifies urgency, sends hot leads to Slack, and saves all leads in Airtable.
+
+### Agent follow-up questions
+1. What triggers the workflow: webhook, form, or CRM event?
+2. How should a hot lead be defined?
+3. Should Airtable create new records only or update existing ones?
+4. Which Slack channel should receive hot leads?
+
+### Normalized plan summary
+- trigger: webhook
+- systems: OpenAI, Slack, Airtable
+- duplicate strategy: upsert by email
+- alert rule: hot if urgency score >= 8
+- fallback: notify ops on failure
+
+### Delivery excerpt
+Workflow created with webhook trigger, AI enrichment, urgency classification, hot lead branch, Slack notification, Airtable upsert path, and failure alert stub.
+
+## Walkthrough 2: Weekly finance digest
+
+### User request
+Every Monday morning, collect unpaid invoices from the ERP, summarize totals by customer, and send the finance team a Slack digest.
+
+### Critical follow-ups
+1. What ERP or source system holds the invoice data?
+2. What timezone should Monday morning use?
+3. Should the digest include overdue aging buckets?
+4. Is Slack the only output?
+
+### Plan summary
+- trigger: schedule weekly
+- output: internal Slack digest
+- data grouping: by customer and due bucket
+- caution: no customer-facing messages

examples/sample-plan.json

@@ -0,0 +1,105 @@
+{
+  "plan_version": "0.3.0",
+  "workflow_name": "Typeform Lead Triage",
+  "objective": "Capture new Typeform submissions, summarize with AI, classify lead temperature, notify Slack for hot leads, and store all submissions in Airtable.",
+  "trigger": {
+    "type": "typeform_submission",
+    "summary": "Runs whenever a new Typeform response is received.",
+    "input_shape": "Form response payload with contact, answers, and metadata."
+  },
+  "systems": [
+    "Typeform",
+    "OpenAI",
+    "Slack",
+    "Airtable",
+    "n8n"
+  ],
+  "steps": [
+    {
+      "id": "step_1",
+      "name": "Receive submission",
+      "action": "Read the incoming Typeform payload."
+    },
+    {
+      "id": "step_2",
+      "name": "Summarize content",
+      "action": "Generate a concise summary with AI.",
+      "depends_on": [
+        "step_1"
+      ]
+    },
+    {
+      "id": "step_3",
+      "name": "Classify lead",
+      "action": "Assign hot, warm, or cold label.",
+      "depends_on": [
+        "step_2"
+      ]
+    },
+    {
+      "id": "step_4",
+      "name": "Branch urgent leads",
+      "action": "If hot, send a Slack alert.",
+      "depends_on": [
+        "step_3"
+      ]
+    },
+    {
+      "id": "step_5",
+      "name": "Persist record",
+      "action": "Write all leads to Airtable.",
+      "depends_on": [
+        "step_3"
+      ]
+    }
+  ],
+  "branching": [
+    {
+      "condition": "lead_temperature == 'hot'",
+      "path": "notify_slack"
+    },
+    {
+      "condition": "lead_temperature != 'hot'",
+      "path": "skip_slack"
+    }
+  ],
+  "credentials": [
+    {
+      "system": "Typeform",
+      "status": "required"
+    },
+    {
+      "system": "OpenAI",
+      "status": "required"
+    },
+    {
+      "system": "Slack",
+      "status": "required"
+    },
+    {
+      "system": "Airtable",
+      "status": "required"
+    }
+  ],
+  "assumptions": [
+    "The Typeform payload includes enough text to summarize.",
+    "Slack alerting is only required for hot leads.",
+    "Airtable base and table are already chosen by the user."
+  ],
+  "risks": [
+    "Missing credentials block full end-to-end testing.",
+    "Lead classification thresholds may need tuning after first runs."
+  ],
+  "validation": {
+    "checks": [
+      "Confirm the Typeform trigger fires with a real payload.",
+      "Confirm AI output contains both summary and label.",
+      "Confirm Slack only receives hot leads.",
+      "Confirm Airtable receives every submission."
+    ],
+    "manual_steps": [
+      "Connect credentials in n8n if placeholders were used.",
+      "Review the prompt used for classification before production rollout."
+    ]
+  }
+}

recipes/invoice-reminder.md

@@ -0,0 +1,17 @@
+# Recipe: Invoice Reminder Workflow
+
+## Scenario
+
+Track invoices nearing due date, notify the internal team, and optionally send customer reminders with explicit approval rules.
+
+## Caution
+
+This recipe should not assume customer-facing messages are allowed without confirmation.
+
+## Suggested intake questions
+
+1. Where do invoice records come from?
+2. How many days before due date should reminders fire?
+3. Is there an approval step before contacting customers?
+4. Which channels should be used for internal vs external notifications?
+5. How should paid invoices be excluded?

recipes/lead-triage.md

@@ -0,0 +1,51 @@
+# Recipe: Lead Triage with AI Enrichment
+
+## Scenario
+
+A user wants to capture incoming leads, enrich them with AI, classify urgency, notify a team, and store the lead in a structured system.
+
+## Typical trigger
+
+- webhook
+- form submission
+- CRM new record
+
+## Systems involved
+
+- form tool or webhook source
+- AI provider
+- Slack or email
+- Airtable / HubSpot / CRM
+
+## Suggested intake questions
+
+1. What triggers the workflow?
+2. Where should the lead be stored?
+3. How should hot leads be defined?
+4. Who should be notified and where?
+5. Should the workflow create-only or upsert existing leads?
+
+## Suggested node sequence
+
+1. Trigger
+2. Normalize payload
+3. AI enrichment / classification
+4. Conditional branch by priority
+5. Notification for high priority
+6. Store record
+7. Error notification branch
+
+## Common risks
+
+- duplicate lead creation
+- unclear hot/warm/cold criteria
+- missing CRM identifiers
+- over-broad notifications
+
+## Validation checklist
+
+- priority branch exists
+- CRM mapping is explicit
+- alert channel is defined
+- duplicate strategy is stated
+- missing credential placeholders are visible

recipes/support-triage.md

@@ -0,0 +1,23 @@
+# Recipe: Support Ticket Triage
+
+## Scenario
+
+Route support requests from a form, email parser, or webhook into categorized queues with optional AI summarization and escalation.
+
+## Suggested node sequence
+
+1. Trigger
+2. Extract or normalize ticket fields
+3. AI summary and category suggestion
+4. Severity classification
+5. Conditional routing
+6. Ticket creation or update
+7. Team notification
+8. Failure path
+
+## High-value follow-ups
+
+- What defines severity?
+- Which queues or teams should receive each category?
+- Should responses be internal-only or customer-facing?
+- Should the workflow auto-tag, auto-assign, or only recommend?

schemas/plan.schema.json

@@ -0,0 +1,171 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.com/vibeflow-n8n/schemas/plan.schema.json",
+  "title": "Vibeflow n8n Plan",
+  "type": "object",
+  "required": [
+    "plan_version",
+    "objective",
+    "trigger",
+    "systems",
+    "steps",
+    "credentials",
+    "assumptions",
+    "validation"
+  ],
+  "properties": {
+    "plan_version": {
+      "type": "string"
+    },
+    "workflow_name": {
+      "type": "string"
+    },
+    "objective": {
+      "type": "string"
+    },
+    "trigger": {
+      "type": "object",
+      "required": [
+        "type",
+        "summary"
+      ],
+      "properties": {
+        "type": {
+          "type": "string"
+        },
+        "summary": {
+          "type": "string"
+        },
+        "schedule": {
+          "type": "string"
+        },
+        "input_shape": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": true
+    },
+    "systems": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "minItems": 1
+    },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "name",
+          "action"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "action": {
+            "type": "string"
+          },
+          "depends_on": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "notes": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": true
+      }
+    },
+    "branching": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "condition",
+          "path"
+        ],
+        "properties": {
+          "condition": {
+            "type": "string"
+          },
+          "path": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": true
+      }
+    },
+    "credentials": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "system",
+          "status"
+        ],
+        "properties": {
+          "system": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "required",
+              "optional",
+              "configured",
+              "placeholder"
+            ]
+          },
+          "notes": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": true
+      }
+    },
+    "assumptions": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "risks": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "validation": {
+      "type": "object",
+      "required": [
+        "checks"
+      ],
+      "properties": {
+        "checks": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          }
+        },
+        "manual_steps": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

templates/final-report-template.md

@@ -0,0 +1,35 @@
+# Final Report Template
+
+## Summary
+
+[One short paragraph describing what the workflow does.]
+
+## What was created
+
+- [Trigger]
+- [Core processing node(s)]
+- [Branching logic]
+- [Destination node(s)]
+- [Error handling]
+
+## Assumptions used
+
+- [Assumption 1]
+- [Assumption 2]
+
+## Manual setup still required
+
+- [Credential setup]
+- [IDs / secrets / endpoint URLs]
+- [Field mapping review]
+
+## How to test
+
+1. [Step]
+2. [Step]
+3. [Step]
+
+## Suggested next upgrades
+
+- [Upgrade 1]
+- [Upgrade 2]

templates/intake-checklist.md

@@ -0,0 +1,38 @@
+# Intake Checklist
+
+Use this when interviewing the user.
+
+## Minimum information
+
+- Workflow goal
+- Trigger
+- Systems/apps involved
+- Final output/result
+
+## High-impact clarifiers
+
+- Frequency or schedule
+- Required fields or payload schema
+- Rules or exceptions
+- Approval steps
+- Error notifications
+- Create vs update behavior
+- Who owns credentials
+
+## Safe assumptions
+
+Usually okay to infer:
+
+- workflow name
+- basic formatting
+- standard retries
+- a generic error branch
+- common field names when obvious
+
+## Must confirm
+
+- deletions
+- payments/billing actions
+- external user messaging
+- compliance-sensitive handling
+- irreversible mutations

templates/system-prompt.md

@@ -0,0 +1,131 @@
+# System Prompt / Skill Prompt
+
+You are a workflow-building agent specialized in creating complete n8n workflows through MCP.
+
+Your role is to turn a user's natural-language automation request into a usable workflow inside n8n while keeping the process simple, practical, and transparent.
+
+## Mission
+
+Help the user move from idea to working automation with minimal friction.
+
+You should:
+- understand the workflow goal,
+- ask only the minimum essential follow-up questions,
+- create a normalized plan before building,
+- create or update the workflow through n8n MCP tools,
+- validate the result,
+- return a clear final handoff report.
+
+## Tone
+
+Be:
+- practical
+- concise
+- collaborative
+- intuitive
+- calm
+
+Do not over-interview the user.
+Do not flood the conversation with jargon.
+
+## Mandatory process
+
+### 1. Understand the intent
+Identify:
+- trigger
+- systems involved
+- desired final outcome
+- key business rules
+- important exceptions
+
+### 2. Ask only high-value questions
+Ask follow-ups only when the answer changes the architecture, creates operational risk, or affects external communication.
+
+### 3. Produce a normalized plan before building
+Always create a normalized plan with:
+- workflow_name
+- workflow_mode
+- business_goal
+- trigger
+- systems_involved
+- key_steps
+- branching_logic
+- credentials_required
+- error_handling
+- assumptions
+- open_questions
+- test_strategy
+
+### 4. Build through n8n MCP
+Create or update the workflow.
+Use readable node names.
+Prefer understandable graphs over clever complexity.
+Leave placeholders where secrets, IDs, or credentials are missing.
+
+### 5. Validate
+Check for:
+- disconnected nodes,
+- missing required fields,
+- absent credentials,
+- unsupported assumptions,
+- weak or missing failure paths,
+- undefined terminal behavior in branches.
+
+### 6. Deliver a handoff report
+The final report should include:
+- what was created,
+- assumptions used,
+- missing manual setup,
+- how to test,
+- suggested next upgrades.
+
+## Defaults policy
+
+You may assume low-risk defaults for:
+- workflow naming,
+- standard retries,
+- formatting details,
+- common internal notifications,
+- simple field mapping.
+
+You must ask before assuming:
+- destructive actions,
+- financial side effects,
+- customer-facing communications,
+- legal or compliance-sensitive rules,
+- approval policies,
+- create-only vs upsert when duplicates matter.
+
+## Mode policy
+
+### fast
+Use fewer questions and more defaults.
+Best for prototypes.
+
+### balanced
+Default mode.
+Use limited follow-ups with practical safeguards.
+
+### safe
+Use more explicit confirmations, stronger validation, and fewer silent assumptions.
+
+## Lightweight opening pattern
+
+When a request is underspecified, start with these questions:
+1. What should trigger the workflow?
+2. Which apps or systems are involved?
+3. What should happen from start to finish?
+4. Are there any rules, approvals, or exceptions I should respect?
+
+## Planning-first rule
+
+Never jump straight into building unless the workflow is already sufficiently specified.
+
+## Delivery quality bar
+
+A good result is:
+- usable,
+- understandable,
+- explicit about assumptions,
+- honest about missing credentials or manual setup,
+- easy for the user to continue from.