mirror of
https://github.com/domfelipe/vibeflow-n8n.git
synced 2026-08-07 05:16:43 +00:00
Rebuild Vibeflow as an n8n safety gate
This commit is contained in:
Felipe Domingues
parent
79fc67166a
commit
febec32131
101 changed files with 2405 additions and 3557 deletions
|
|
@ -1,160 +1,43 @@
|
|||
# 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
|
||||
## Data flow
|
||||
|
||||
```text
|
||||
User intent
|
||||
-> Conversational intake
|
||||
-> Normalized plan
|
||||
-> MCP build actions
|
||||
-> Validation pass
|
||||
-> Human-readable handoff
|
||||
workflow JSON -> parser -> graph + parameter analysis -> findings -> text | JSON | SARIF
|
||||
```
|
||||
|
||||
## Why planning-first matters
|
||||
The CLI reads local files, validates their basic n8n shape, builds forward and reverse node graphs, runs deterministic policies, sorts findings, and sets an exit code from the selected threshold.
|
||||
|
||||
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.
|
||||
## Components
|
||||
|
||||
The plan acts like a blueprint before the steel beams go up.
|
||||
- `bin/vibeflow.mjs`: argument parsing, output selection, and exit codes.
|
||||
- `src/vibeflow.mjs`: configuration, file discovery, policies, graph traversal, and formatters.
|
||||
- `.vibeflow.json`: repository policy defaults.
|
||||
- `schemas/`: editor-facing configuration schema.
|
||||
- `examples/`: reproducible safe and unsafe workflows.
|
||||
- `plugins/vibeflow/`: Codex packaging; it calls the same CLI rather than duplicating policy logic.
|
||||
- `action.yml`: composite GitHub Action using the checked-in CLI.
|
||||
|
||||
## Build stages
|
||||
## Policy model
|
||||
|
||||
### Stage 1. Intake
|
||||
The agent captures:
|
||||
- business goal,
|
||||
- trigger,
|
||||
- systems involved,
|
||||
- desired output,
|
||||
- rules and exceptions.
|
||||
Rules have a stable ID, default severity, description, and remediation. Trusted local users may change severity, vocabulary, and banned node types. VF000 remains non-configurable because invalid input cannot be audited safely.
|
||||
|
||||
### Stage 2. Requirement triage
|
||||
The agent separates:
|
||||
- critical unknowns,
|
||||
- optional detail,
|
||||
- safe defaults.
|
||||
Graph policies use the validated n8n `main` connection shape, not node order; AI resource wiring is not control flow. VF005 requires a high-confidence atomic ledger gate that emits no item for duplicate claims and dominates inbound paths to side effects. VF006 rejects any AI entry path that bypasses a positive IF check against a direct agent-status reference. VF007 requires a reachable external handoff action.
|
||||
|
||||
### Stage 3. Normalized plan
|
||||
The agent produces a standard structure for execution.
|
||||
This makes behavior portable across clients.
|
||||
`--locked` rejects configuration that weakens built-in severity, changes safety vocabulary, or removes a default banned node. The GitHub Action always enables locked mode so a pull request cannot silence its own findings by editing `.vibeflow.json`.
|
||||
|
||||
### Stage 4. MCP execution
|
||||
The agent creates or updates the workflow using the available MCP tools.
|
||||
## Trust boundaries
|
||||
|
||||
### Stage 5. Validation
|
||||
The agent checks for:
|
||||
- broken graph structure,
|
||||
- missing dependencies,
|
||||
- unsupported assumptions,
|
||||
- absent failure branches,
|
||||
- unresolved placeholders.
|
||||
Workflow JSON is untrusted input. Vibeflow never evaluates expressions, imports workflow code, runs nodes, follows symlinks during directory discovery, or contacts URLs found in parameters. It caps files, bytes, nodes, edges, configuration vocabulary, and findings; graph traversal is iterative and linear in the validated graph.
|
||||
|
||||
### Stage 6. Delivery
|
||||
The agent produces a report for the user that is operational, not ornamental.
|
||||
Output paths are selected by the caller. The GitHub Action passes inputs as quoted environment values.
|
||||
|
||||
## Recommended workflow object model
|
||||
## Known limitations
|
||||
|
||||
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
|
||||
- Static structure cannot prove that a condition, SQL claim, or handoff works at runtime.
|
||||
- Secret detection can miss unusual key names and can produce false positives.
|
||||
- Community nodes unknown to the side-effect catalog need explicit policy additions.
|
||||
- Locked mode protects policy content, but repository owners must still review changes to the CI workflow itself.
|
||||
- Runtime credentials, permissions, network controls, and n8n version compatibility remain outside the report.
|
||||
|
||||
## 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
|
||||
These ceilings are deliberate. Add runtime integration only when real users demonstrate that static exports are insufficient.
|
||||
|
|
|
|||
|
|
@ -1,37 +0,0 @@
|
|||
# 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`
|
||||
53
docs/codex-for-oss-application.md
Normal file
53
docs/codex-for-oss-application.md
Normal file
|
|
@ -0,0 +1,53 @@
|
|||
# Codex for Open Source application gate
|
||||
|
||||
Application: <https://openai.com/pt-BR/form/codex-for-oss/>
|
||||
|
||||
## Current position
|
||||
|
||||
Vibeflow is public, MIT-licensed, owned by its principal maintainer, and aligned with Codex maintainer workflows. Version 0.8.0 establishes active engineering evidence but does not manufacture adoption.
|
||||
|
||||
Do not submit until the live evidence section is refreshed and contains external usage.
|
||||
|
||||
## Practical submission gate
|
||||
|
||||
These are internal quality targets, not official OpenAI thresholds:
|
||||
|
||||
- a tagged public release with green CI;
|
||||
- at least three unrelated external users or teams with verifiable feedback;
|
||||
- at least one external issue, discussion, or pull request with maintainer activity;
|
||||
- current traffic, clone, installation, or dependent-project evidence;
|
||||
- no confidential information in the application.
|
||||
|
||||
## Live evidence
|
||||
|
||||
Refresh immediately before submission:
|
||||
|
||||
- GitHub stars: `[refresh]`
|
||||
- forks: `[refresh]`
|
||||
- unique clones in the latest available period: `[refresh]`
|
||||
- releases and latest release date: `[refresh]`
|
||||
- external contributors: `[refresh]`
|
||||
- external users or public references: `[refresh]`
|
||||
- maintainer examples: `[refresh issues, reviews, and releases]`
|
||||
|
||||
## Form draft
|
||||
|
||||
### Role
|
||||
|
||||
Principal maintainer.
|
||||
|
||||
### Why is this repository eligible?
|
||||
|
||||
> Vibeflow is an MIT-licensed safety gate for AI-generated n8n workflows. It catches embedded secrets, unsafe webhooks, missing kill switches, human handoffs, idempotency, error paths, timeouts, and risky retries before deployment. It is maintained as a dependency-free CLI, GitHub Action, and Codex plugin. [Add refreshed external usage evidence before submitting.]
|
||||
|
||||
### How will API credits be used?
|
||||
|
||||
> Credits will support OSS maintenance: generate adversarial workflow fixtures, run reproducible policy evaluations, review contributed rules in pull requests, explain regressions, and prepare release reports. They will not fund a hosted commercial runtime or process private customer workflows.
|
||||
|
||||
### Anything else?
|
||||
|
||||
> Vibeflow comes from production lessons operating conversational automations in Brazil. It is deliberately interoperable with n8n and existing MCP tooling: it does not replace builders, it checks their output. The project ships without telemetry and keeps workflow analysis local.
|
||||
|
||||
## Final verification
|
||||
|
||||
Before submitting, confirm the GitHub profile and repository are public, replace every `[refresh]` marker, verify each form answer remains under 500 characters, and use accurate current evidence only.
|
||||
|
|
@ -1,32 +0,0 @@
|
|||
# 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
|
||||
|
|
@ -1,106 +0,0 @@
|
|||
# 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
|
||||
|
|
@ -1,48 +0,0 @@
|
|||
# Demo Assets Guide
|
||||
|
||||
Use this document to prepare screenshots, terminal captures, and visual assets for launch.
|
||||
|
||||
## Recommended visuals
|
||||
|
||||
### 1. Hero banner
|
||||
Use `assets/hero-banner.svg` as a temporary visual until you capture a real workflow screenshot.
|
||||
|
||||
### 2. Terminal intake flow
|
||||
Show the agent asking for:
|
||||
- the workflow goal
|
||||
- trigger type
|
||||
- apps involved
|
||||
- final action
|
||||
- exceptions or approvals
|
||||
|
||||
### 3. Plan output
|
||||
Capture the normalized plan before the build starts.
|
||||
|
||||
### 4. Workflow canvas
|
||||
Use `assets/workflow-demo.svg` as a placeholder, or replace it with a real n8n screenshot.
|
||||
|
||||
### 5. Final handoff report
|
||||
Use `assets/final-report-demo.svg` as a placeholder, or capture a real final report from the agent.
|
||||
|
||||
## Included placeholder assets
|
||||
|
||||
- `assets/hero-banner.svg`
|
||||
- `assets/terminal-demo.svg`
|
||||
- `assets/workflow-demo.svg`
|
||||
- `assets/final-report-demo.svg`
|
||||
- `assets/social-preview.svg`
|
||||
|
||||
## 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
|
||||
|
||||
## Suggested README image order
|
||||
|
||||
1. hero image or terminal screenshot
|
||||
2. plan screenshot
|
||||
3. workflow screenshot
|
||||
4. final report screenshot
|
||||
|
|
@ -1,64 +0,0 @@
|
|||
# Demo Script
|
||||
|
||||
Use this script to record a short terminal demo, GIF, or narrated walkthrough.
|
||||
|
||||
## Goal
|
||||
|
||||
Show that Vibeflow n8n turns a plain-language request into a structured plan and a workflow build process.
|
||||
|
||||
## Recommended demo length
|
||||
|
||||
- 30 to 60 seconds for a GIF
|
||||
- 90 to 180 seconds for a narrated video
|
||||
|
||||
## Suggested scenario
|
||||
|
||||
"Build an n8n workflow that watches Slack mentions, creates a triage page in Notion, alerts the ops channel for urgent items, and stores a summary for later reporting."
|
||||
|
||||
## Demo sequence
|
||||
|
||||
### 1. Open the repo
|
||||
Show the key files:
|
||||
- `templates/system-prompt.md`
|
||||
- `docs/conversation-contract.md`
|
||||
- `recipes/slack-to-notion-triage.md`
|
||||
|
||||
### 2. Start the agent
|
||||
Show the agent receiving a natural-language request.
|
||||
|
||||
### 3. Intake questions
|
||||
Capture a short question set such as:
|
||||
- Which Slack channel or mention pattern should trigger the workflow?
|
||||
- What counts as urgent?
|
||||
- What Notion database should receive the item?
|
||||
- Should failures notify Slack or email?
|
||||
|
||||
### 4. Plan output
|
||||
Show the normalized plan with these visible sections:
|
||||
- objective
|
||||
- trigger
|
||||
- steps
|
||||
- branching logic
|
||||
- credentials needed
|
||||
- validation plan
|
||||
|
||||
### 5. Build handoff
|
||||
Show the agent summarizing what it is about to create in n8n.
|
||||
|
||||
### 6. Workflow view
|
||||
Capture the n8n canvas or a placeholder workflow image.
|
||||
|
||||
### 7. Final report
|
||||
Show a concise final handoff report listing:
|
||||
- what was created
|
||||
- assumptions used
|
||||
- missing credentials
|
||||
- how to test it
|
||||
|
||||
## Recording tips
|
||||
|
||||
- keep the terminal font large
|
||||
- hide secrets and account names
|
||||
- use a short but realistic workflow request
|
||||
- crop tightly and avoid idle pauses
|
||||
- prefer one clean storyline over many cuts
|
||||
32
docs/demo.md
Normal file
32
docs/demo.md
Normal file
|
|
@ -0,0 +1,32 @@
|
|||
# Reproducible demo
|
||||
|
||||
## Safe workflow
|
||||
|
||||
```bash
|
||||
node bin/vibeflow.mjs check examples/safe-support-agent.workflow.json
|
||||
```
|
||||
|
||||
Expected result: exit `0`, zero findings.
|
||||
|
||||
## Unsafe workflow
|
||||
|
||||
```bash
|
||||
node bin/vibeflow.mjs check examples/unsafe-support-agent.workflow.json --fail-on never
|
||||
```
|
||||
|
||||
Expected result: VF001-VF009 findings covering secrets, dangerous nodes, webhook authentication, error handling, idempotency, AI safety, timeouts, and retries.
|
||||
|
||||
## Automation output
|
||||
|
||||
```bash
|
||||
node bin/vibeflow.mjs check examples/unsafe-support-agent.workflow.json --format json --fail-on never
|
||||
node bin/vibeflow.mjs check examples/unsafe-support-agent.workflow.json --format sarif --output vibeflow.sarif --fail-on never
|
||||
```
|
||||
|
||||
For pull requests or other untrusted checkouts, add `--locked`. The bundled GitHub Action does this automatically.
|
||||
|
||||
## Full project gate
|
||||
|
||||
```bash
|
||||
npm run verify
|
||||
```
|
||||
|
|
@ -1,31 +0,0 @@
|
|||
# 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`.
|
||||
|
|
@ -1,72 +0,0 @@
|
|||
# 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.
|
||||
```
|
||||
|
|
@ -1,49 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,47 +0,0 @@
|
|||
# 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
|
||||
|
|
@ -1,54 +0,0 @@
|
|||
# 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
|
||||
|
|
@ -1,38 +0,0 @@
|
|||
# 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
|
||||
16
docs/launch.md
Normal file
16
docs/launch.md
Normal file
|
|
@ -0,0 +1,16 @@
|
|||
# Launch checklist
|
||||
|
||||
## Release gate
|
||||
|
||||
- `npm run verify` passes on Node.js 20, 22, and 24.
|
||||
- Official skill and plugin validators pass.
|
||||
- Safe fixture exits 0; unsafe fixture exits 1.
|
||||
- SARIF is valid JSON and uploaded by CI.
|
||||
- Repository description and topics match the new product.
|
||||
- `v0.8.0` release notes match `CHANGELOG.md`.
|
||||
|
||||
## Announcement
|
||||
|
||||
> Vibeflow is now an executable safety gate for AI-generated n8n workflows. It checks exported JSON for secrets, exposed webhooks, missing kill switches and handoffs, idempotency, failure paths, timeouts, and unsafe retries. It is dependency-free, runs locally or in GitHub Actions, and includes a Codex plugin.
|
||||
|
||||
Link to the repository and the safe/unsafe demo. Ask users for anonymized false-positive cases and real workflow fixtures, not stars alone.
|
||||
47
docs/product-brief.md
Normal file
47
docs/product-brief.md
Normal file
|
|
@ -0,0 +1,47 @@
|
|||
# Product brief
|
||||
|
||||
## Product
|
||||
|
||||
Vibeflow is an open-source safety and contract gate for exported n8n workflows, especially customer-facing workflows produced or edited by coding agents.
|
||||
|
||||
## Problem
|
||||
|
||||
Natural-language workflow generation is now common. The remaining failure is operational: a structurally valid workflow can still leak a credential, answer while disabled, duplicate a side effect, lack a human fallback, retry unsafely, or run forever.
|
||||
|
||||
Existing builders and MCP servers should keep building. Vibeflow checks the result before production.
|
||||
|
||||
## Primary users
|
||||
|
||||
- n8n maintainers reviewing generated workflow changes;
|
||||
- automation consultancies shipping customer-facing agents;
|
||||
- platform teams enforcing workflow policy in pull requests;
|
||||
- coding agents that need deterministic feedback rather than another prompt.
|
||||
|
||||
## Promise
|
||||
|
||||
Given an exported workflow, produce a reproducible pass/fail report with concrete remediation and no network access.
|
||||
|
||||
## Version 0.8 scope
|
||||
|
||||
- dependency-free Node.js CLI;
|
||||
- text, JSON, and SARIF output;
|
||||
- configurable VF000-VF009 policies;
|
||||
- safe and unsafe fixtures;
|
||||
- GitHub Action;
|
||||
- Codex skill and plugin package.
|
||||
|
||||
## Non-goals
|
||||
|
||||
- generating workflows;
|
||||
- replacing n8n, n8n-mcp, or workflow-as-code tools;
|
||||
- executing or mutating live workflows;
|
||||
- proving runtime correctness;
|
||||
- hosting a SaaS dashboard.
|
||||
|
||||
## Differentiation
|
||||
|
||||
Vibeflow starts with policies learned from real conversational-agent operations: an off switch before inference, human handoff after low-confidence output, duplicate-event protection, explicit error paths, bounded retries, and trust-boundary hygiene.
|
||||
|
||||
## Evidence gate
|
||||
|
||||
The project is ready to launch when its own safe fixture passes, unsafe fixture fails, plugin validates, package packs, and CI is green. It becomes a strong Codex for Open Source candidate only after external usage and maintainer work are visible.
|
||||
|
|
@ -1,106 +0,0 @@
|
|||
# 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
|
||||
|
|
@ -1,38 +0,0 @@
|
|||
# README Premium Checklist
|
||||
|
||||
Use this before publishing a release or sharing the repository publicly.
|
||||
|
||||
## Above the fold
|
||||
|
||||
- project name is clear
|
||||
- one-line value proposition is strong
|
||||
- target users are obvious
|
||||
- at least one visual asset appears early
|
||||
|
||||
## Conversion layer
|
||||
|
||||
- quick start is visible without excessive scrolling
|
||||
- supported clients are easy to spot
|
||||
- top recipes are linked directly
|
||||
- install docs are linked directly
|
||||
|
||||
## Trust layer
|
||||
|
||||
- changelog is up to date
|
||||
- security and contributing docs exist
|
||||
- examples are easy to find
|
||||
- roadmap is honest and short
|
||||
|
||||
## Showcase layer
|
||||
|
||||
- hero banner present
|
||||
- at least one terminal or workflow visual
|
||||
- demo script exists
|
||||
- at least three recipes are public-facing and polished
|
||||
|
||||
## Launch polish
|
||||
|
||||
- release version updated
|
||||
- launch copy updated
|
||||
- repo description matches README
|
||||
- social preview ready
|
||||
|
|
@ -1,59 +0,0 @@
|
|||
# Real Demo Playbook
|
||||
|
||||
Use this playbook when you want a real, credible public demo instead of a static repository tour.
|
||||
|
||||
## Goal
|
||||
|
||||
Show a full path from plain-English request to final n8n workflow handoff in less than five minutes.
|
||||
|
||||
## Suggested demo storyline
|
||||
|
||||
1. Start in the terminal with a connected MCP-capable client.
|
||||
2. Paste a short brief with one trigger, one transformation, and one notification path.
|
||||
3. Let the agent ask only one to three critical follow-up questions.
|
||||
4. Show the normalized plan before the build happens.
|
||||
5. Switch to n8n and show the created workflow.
|
||||
6. End with the final implementation report.
|
||||
|
||||
## Best demo characteristics
|
||||
|
||||
- one trigger
|
||||
- two to five core nodes
|
||||
- one error path
|
||||
- one obvious business outcome
|
||||
- one missing credential called out cleanly
|
||||
|
||||
## Good public demo candidates
|
||||
|
||||
- support triage to Slack
|
||||
- invoice reminder workflow
|
||||
- lead enrichment with CRM update
|
||||
- Slack to Notion intake sorter
|
||||
|
||||
## What to avoid
|
||||
|
||||
- giant workflows with many credentials
|
||||
- fragile scraping flows
|
||||
- binary-heavy flows for the first public demo
|
||||
- human approval loops during the live build
|
||||
- anything that needs ten minutes of setup before value appears
|
||||
|
||||
## Demo capture checklist
|
||||
|
||||
- terminal font large enough to read in social clips
|
||||
- n8n canvas zoom at readable level
|
||||
- one file or pane open with the implementation report
|
||||
- timestamps or release tags hidden if they look messy
|
||||
- fake or test credentials only
|
||||
|
||||
## Suggested timing
|
||||
|
||||
- 30s context
|
||||
- 60s planning
|
||||
- 90s build
|
||||
- 45s n8n review
|
||||
- 30s final report and next steps
|
||||
|
||||
## Closing line
|
||||
|
||||
"Describe the workflow. The agent asks only what matters, builds via MCP, and hands back something usable."
|
||||
|
|
@ -1,58 +0,0 @@
|
|||
# Recipes Gallery
|
||||
|
||||
Use this page to choose the strongest recipes for screenshots, demos, and first-run adoption.
|
||||
|
||||
## Recommended hero recipes
|
||||
|
||||
### 1. Lead Triage
|
||||
Best for showing business routing, safe defaults, and clean branching.
|
||||
|
||||
Use when you want to demonstrate:
|
||||
- form or CRM intake
|
||||
- qualification logic
|
||||
- routing to a sales queue
|
||||
- notifications to Slack or email
|
||||
|
||||
### 2. Support Triage
|
||||
Best for showing operational workflows with urgency rules.
|
||||
|
||||
Use when you want to demonstrate:
|
||||
- inbound support intake
|
||||
- priority detection
|
||||
- response classification
|
||||
- escalation paths
|
||||
|
||||
### 3. Invoice Reminder
|
||||
Best for finance or back-office audiences.
|
||||
|
||||
Use when you want to demonstrate:
|
||||
- schedule triggers
|
||||
- spreadsheet or database lookups
|
||||
- reminder logic
|
||||
- retry and failure handling
|
||||
|
||||
### 4. AI Lead Enrichment
|
||||
Best for showing AI-assisted steps without becoming overly abstract.
|
||||
|
||||
Use when you want to demonstrate:
|
||||
- enrichment APIs
|
||||
- summary generation
|
||||
- structured output fields
|
||||
- CRM updates
|
||||
|
||||
### 5. Slack to Notion Triage
|
||||
Best for showing a workflow that feels modern and concrete in demos.
|
||||
|
||||
Use when you want to demonstrate:
|
||||
- Slack triggers
|
||||
- content normalization
|
||||
- Notion inserts
|
||||
- urgent routing and summaries
|
||||
|
||||
## Suggested README order
|
||||
|
||||
1. Slack to Notion Triage
|
||||
2. AI Lead Enrichment
|
||||
3. Invoice Reminder
|
||||
|
||||
This sequence shows speed, intelligence, and operational depth.
|
||||
54
docs/release-audit.md
Normal file
54
docs/release-audit.md
Normal file
|
|
@ -0,0 +1,54 @@
|
|||
# Release audit — v0.8.0
|
||||
|
||||
Date: 2026-07-22
|
||||
|
||||
## Decision
|
||||
|
||||
**APTO COM RESSALVAS** for the first public executable release.
|
||||
|
||||
No blocking defect remains in the reviewed static-analysis boundary. The remaining caveats require runtime or node-specific knowledge that an exported JSON gate cannot prove.
|
||||
|
||||
## QA evidence
|
||||
|
||||
- 26 automated tests pass, including one safe and one intentionally unsafe workflow.
|
||||
- The safe fixture produces zero findings; the unsafe fixture produces VF001-VF009.
|
||||
- Text, JSON, and SARIF output paths are exercised.
|
||||
- Node 20, 22, and 24 are required in CI; local verification used the available Node runtime and the remote matrix is the release gate.
|
||||
- JSON/YAML parsing, package dry-run, official skill/plugin validators, `npm audit`, and `git diff --check` are part of the final gate.
|
||||
|
||||
## Red Team
|
||||
|
||||
The first implementation was rejected. Regression tests now cover the reproduced bypasses:
|
||||
|
||||
- declared webhook authentication without the matching credential reference;
|
||||
- literal secrets in raw headers, URLs, expressions, pinned data, and static data;
|
||||
- disconnected, nominal, or non-gating idempotency controls;
|
||||
- parallel AI paths that bypass a kill switch, inverted or constant conditions, and decorative Code/NoOp nodes;
|
||||
- resource connections misread as control flow and fabricated connection shapes;
|
||||
- disconnected or cyclic error handling;
|
||||
- read-only HTTP requests mislabeled as handoff;
|
||||
- excessive or non-numeric timeouts and unsafe retry settings;
|
||||
- policy weakening from an untrusted checkout;
|
||||
- terminal-control injection, deep JSON, excessive nodes/edges/files/config terms, finding amplification, and quadratic traversal.
|
||||
|
||||
At the 5,000-node limit, the corrected linear traversal completed the synthetic chain in tens of milliseconds on the development machine. Finding truncation always adds blocking VF000.
|
||||
|
||||
## Supply chain
|
||||
|
||||
- GitHub-owned actions are pinned to full verified commit SHAs.
|
||||
- Checkout credentials are not persisted; workflow permissions are `contents: read`.
|
||||
- Jobs have a ten-minute timeout and package installation ignores scripts.
|
||||
- The package has no runtime dependencies and uses a publish allowlist.
|
||||
- The bundled action always enables `--locked`.
|
||||
|
||||
The first merge SHA must replace mutable self-references in the README and Codex skill before the release tag is created.
|
||||
|
||||
## Residual limitations
|
||||
|
||||
- Static analysis cannot prove a referenced credential exists or works.
|
||||
- SQL and IF checks are high-confidence structural evidence, not runtime execution proofs.
|
||||
- An HTTP POST labeled as a ticket or handoff may still fail or target the wrong service.
|
||||
- Unknown community nodes may require a new side-effect adapter and regression fixture.
|
||||
- Repository owners must still review changes to the CI workflow itself.
|
||||
|
||||
The official Codex Security workspace was opened, but its setup was never submitted through the app interface; no result from that scanner is claimed here. The release decision is based on the direct QA, independent Red Team, supply-chain review, and regression evidence above.
|
||||
|
|
@ -1,36 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,15 +0,0 @@
|
|||
# Vibeflow n8n v0.7.0
|
||||
|
||||
This release focuses on public-demo readiness.
|
||||
|
||||
## Highlights
|
||||
|
||||
- premium README refresh
|
||||
- real-demo playbook for terminal-to-n8n walkthroughs
|
||||
- two new showcase recipes
|
||||
- illustrative sample workflow export for safer local experimentation
|
||||
- extra README quality checklist for launch polish
|
||||
|
||||
## Recommended next move
|
||||
|
||||
Attach real screenshots or a short GIF to make the repository feel alive on first visit.
|
||||
|
|
@ -1,34 +1,21 @@
|
|||
# Roadmap
|
||||
|
||||
## Current state: v0.6.0
|
||||
## 0.8.0
|
||||
|
||||
V6 is designed to be showcase-ready:
|
||||
- launch and community docs are in place
|
||||
- client snippets are documented
|
||||
- normalized plan schema exists
|
||||
- demo-oriented recipes are stronger
|
||||
- placeholder visual assets are included for the first public version
|
||||
Ship the executable reset: CLI, nine configurable policies, fixtures, tests, SARIF, GitHub Action, and Codex plugin.
|
||||
|
||||
## v0.7.0 ideas
|
||||
## Next release gate
|
||||
|
||||
- sample workflow exports for safe local testing
|
||||
- richer setup fixtures by client
|
||||
- validation helper scripts for plan payloads
|
||||
- GIFs and screenshots from real runs
|
||||
- recipe packs for sales, support, finance, and internal ops
|
||||
Do not add another integration by default. Prioritize evidence from real workflows:
|
||||
|
||||
## v0.8.0 ideas
|
||||
1. Measure false positives by rule.
|
||||
2. Accept anonymized fixtures from external users.
|
||||
3. Add a node type or policy only with a failing fixture.
|
||||
4. Improve GitHub annotations if SARIF users request it.
|
||||
5. Package for npm only when GitHub installation creates material friction.
|
||||
6. Add node-specific handoff and side-effect adapters only with adversarial safe/unsafe fixtures.
|
||||
7. Model additional atomic idempotency gates only when their duplicate path is proven to stop downstream items.
|
||||
|
||||
- optional plan linter
|
||||
- workflow quality checklist by recipe type
|
||||
- starter gallery page for examples
|
||||
- benchmark prompts for comparing clients
|
||||
## Explicitly deferred
|
||||
|
||||
## 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
|
||||
- feels demo-friendly from the first clone
|
||||
Hosted UI, custom MCP server, live n8n mutation, workflow generation, and broad multi-agent wrappers.
|
||||
|
|
|
|||
|
|
@ -1,30 +0,0 @@
|
|||
# Showcase Checklist
|
||||
|
||||
Use this checklist before sharing the repo publicly.
|
||||
|
||||
## README
|
||||
- clear one-line value proposition
|
||||
- 1 hero visual near the top
|
||||
- 1 example prompt
|
||||
- 3 highlighted recipes
|
||||
- quick-start links visible without scrolling too far
|
||||
|
||||
## Assets
|
||||
- hero banner present
|
||||
- social preview present
|
||||
- at least 3 demo visuals present
|
||||
- filenames are simple and predictable
|
||||
|
||||
## Recipes
|
||||
- at least 3 recipes feel production-adjacent
|
||||
- every recipe includes trigger, steps, assumptions, and test plan
|
||||
- one recipe includes AI enrichment
|
||||
- one recipe includes support or ops logic
|
||||
- one recipe includes finance logic
|
||||
|
||||
## Release
|
||||
- VERSION bumped
|
||||
- CHANGELOG updated
|
||||
- GitHub release notes drafted
|
||||
- topics and description ready
|
||||
- first screenshot or GIF attached
|
||||
|
|
@ -1,152 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,29 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,236 +0,0 @@
|
|||
# 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