mirror of
https://github.com/domfelipe/vibeflow-n8n.git
synced 2026-08-07 08:16:43 +00:00
160 lines
3.7 KiB
Markdown
160 lines
3.7 KiB
Markdown
# 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
|