mirror of
https://github.com/domfelipe/vibeflow-n8n.git
synced 2026-08-07 06:56:45 +00:00
feat: launch Vibeflow n8n v0.5.0
This commit is contained in:
Felipe Domingues
commit
097f35215f
60 changed files with 2831 additions and 0 deletions
160
docs/architecture.md
Normal file
160
docs/architecture.md
Normal file
|
|
@ -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
|
||||
37
docs/brand-kit.md
Normal file
37
docs/brand-kit.md
Normal file
|
|
@ -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`
|
||||
32
docs/community-onboarding.md
Normal file
32
docs/community-onboarding.md
Normal file
|
|
@ -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
|
||||
106
docs/conversation-contract.md
Normal file
106
docs/conversation-contract.md
Normal file
|
|
@ -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
|
||||
49
docs/demo-assets.md
Normal file
49
docs/demo-assets.md
Normal file
|
|
@ -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
|
||||
31
docs/first-issues.md
Normal file
31
docs/first-issues.md
Normal file
|
|
@ -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`.
|
||||
72
docs/getting-started.md
Normal file
72
docs/getting-started.md
Normal file
|
|
@ -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.
|
||||
```
|
||||
49
docs/github-launch.md
Normal file
49
docs/github-launch.md
Normal file
|
|
@ -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.
|
||||
47
docs/install.md
Normal file
47
docs/install.md
Normal file
|
|
@ -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
|
||||
54
docs/launch-assets.md
Normal file
54
docs/launch-assets.md
Normal file
|
|
@ -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
|
||||
38
docs/launch-day-checklist.md
Normal file
38
docs/launch-day-checklist.md
Normal file
|
|
@ -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
|
||||
106
docs/publishing-guide.md
Normal file
106
docs/publishing-guide.md
Normal file
|
|
@ -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
|
||||
36
docs/release-notes-template.md
Normal file
36
docs/release-notes-template.md
Normal file
|
|
@ -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.
|
||||
33
docs/roadmap.md
Normal file
33
docs/roadmap.md
Normal file
|
|
@ -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
|
||||
152
docs/skill-spec.md
Normal file
152
docs/skill-spec.md
Normal file
|
|
@ -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.
|
||||
29
docs/social-copy.md
Normal file
29
docs/social-copy.md
Normal file
|
|
@ -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.
|
||||
236
docs/tutorial-subir-github.md
Normal file
236
docs/tutorial-subir-github.md
Normal file
|
|
@ -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. citeturn863639search0turn863639search3turn863639search14
|
||||
|
||||
## 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. citeturn863639search0
|
||||
|
||||
### 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. citeturn863639search9turn863639search19
|
||||
|
||||
## 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. citeturn863639search3turn863639search14
|
||||
|
||||
## 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. citeturn863639search5turn863639search11
|
||||
|
||||
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. citeturn863639search2turn863639search8
|
||||
|
||||
### 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. citeturn863639search1
|
||||
|
||||
## 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. citeturn863639search4
|
||||
|
||||
### 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.
|
||||
```
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue