feat: launch Vibeflow n8n v0.5.0

docs/architecture.md

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