ci: add Forgejo quality workflow (mirror-friendly)

Runs on self-hosted Forgejo Actions; ignored by GitHub Actions.
GitHub remains source of truth.

.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "vibeflow",
+  "interface": {
+    "displayName": "Vibeflow"
+  },
+  "plugins": [
+    {
+      "name": "vibeflow",
+      "source": {
+        "source": "local",
+        "path": "./plugins/vibeflow"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Developer Tools"
+    }
+  ]
+}

.forgejo/workflows/quality.yml

@@ -0,0 +1,48 @@
+# Roda no Forgejo (homelab). GitHub Actions ignora .forgejo/
+# Source of truth continua no GitHub — só faça push no GH.
+name: quality
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  quality:
+    runs-on: docker
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Detect stack
+        id: stack
+        run: |
+          set -e
+          echo "repo=$(basename "$GITHUB_REPOSITORY")"
+          if [ -f package.json ]; then echo "has_node=true" >> "$GITHUB_OUTPUT"; else echo "has_node=false" >> "$GITHUB_OUTPUT"; fi
+          if [ -f pyproject.toml ] || [ -f requirements.txt ] || [ -f setup.py ]; then echo "has_py=true" >> "$GITHUB_OUTPUT"; else echo "has_py=false" >> "$GITHUB_OUTPUT"; fi
+          if [ -f Cargo.toml ]; then echo "has_rust=true" >> "$GITHUB_OUTPUT"; else echo "has_rust=false" >> "$GITHUB_OUTPUT"; fi
+          if [ -f go.mod ]; then echo "has_go=true" >> "$GITHUB_OUTPUT"; else echo "has_go=false" >> "$GITHUB_OUTPUT"; fi
+          ls -la
+
+      - name: Node check (if any)
+        if: steps.stack.outputs.has_node == 'true'
+        run: |
+          if command -v node >/dev/null 2>&1; then node -v; else echo "node n/a in image — skip"; fi
+          if [ -f package-lock.json ] || [ -f pnpm-lock.yaml ] || [ -f yarn.lock ] || [ -f bun.lockb ] || [ -f bun.lock ]; then
+            echo "lockfile present"
+          fi
+          # ponytail: no install/test yet — add when repo has standard scripts
+          if [ -f package.json ] && command -v node >/dev/null 2>&1; then
+            node -e "const p=require('./package.json'); console.log('name=', p.name||'(none)', 'scripts=', Object.keys(p.scripts||{}).join(','))"
+          fi
+
+      - name: Python check (if any)
+        if: steps.stack.outputs.has_py == 'true'
+        run: |
+          if command -v python3 >/dev/null 2>&1; then python3 --version; else echo "python n/a"; fi
+
+      - name: Quality gate (smoke)
+        run: |
+          echo "quality OK on Forgejo runner"
+          echo "sha=${GITHUB_SHA}"
+          echo "ref=${GITHUB_REF}"

.github/DISCUSSION_TEMPLATE/ideas.yml

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

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

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

.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,22 @@
+name: Bug report
+description: Report incorrect CLI behavior
+title: "bug: "
+labels: [bug]
+body:
+  - type: textarea
+    attributes:
+      label: Minimal workflow
+      description: Attach an anonymized workflow or the smallest JSON that reproduces the problem. Never include credentials.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Command and output
+      render: shell
+    validations:
+      required: true
+  - type: input
+    attributes:
+      label: Vibeflow and Node.js versions
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/bug_report.md

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

.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,5 @@
-blank_issues_enabled: true
+blank_issues_enabled: false
 contact_links:
-  - name: Questions and setup help
-    url: https://github.com/OWNER/REPO/discussions
-    about: Use Discussions for setup questions, ideas, and help requests.
+  - name: Private security report
+    url: https://github.com/domfelipe/vibeflow-n8n/security/advisories/new
+    about: Report vulnerabilities and sensitive findings privately.

.github/ISSUE_TEMPLATE/false-positive.yml

@@ -0,0 +1,23 @@
+name: False positive
+description: Report a policy finding that should not fire
+title: "false-positive: "
+labels: [false-positive]
+body:
+  - type: input
+    attributes:
+      label: Rule ID
+      placeholder: VF006
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Anonymized workflow fragment
+      description: Include relevant nodes and connections without secrets or customer data.
+      render: json
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Why the workflow is safe
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/feature_request.md

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

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

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

.github/ISSUE_TEMPLATE/rule-proposal.yml

@@ -0,0 +1,33 @@
+name: Policy rule proposal
+description: Propose a deterministic check backed by exported workflow JSON
+title: "rule: "
+labels: [enhancement]
+body:
+  - type: textarea
+    id: failure
+    attributes:
+      label: Production failure
+      description: What concrete failure would this rule prevent?
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Static evidence
+      description: Which exported JSON fields prove the unsafe and safe cases?
+    validations:
+      required: true
+  - type: textarea
+    id: fixtures
+    attributes:
+      label: Minimal fixtures
+      description: Paste anonymized unsafe and safe examples, or link to a branch containing them.
+    validations:
+      required: true
+  - type: textarea
+    id: false-positives
+    attributes:
+      label: False-positive boundary
+      description: When should this rule deliberately stay silent?
+    validations:
+      required: true

.github/labels-suggested.md

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

.github/pull_request_template.md

@@ -1,14 +1,11 @@
-## What changed
+## Risk addressed
 
-Describe the main changes in this PR.
+Describe the workflow failure or false positive this change addresses.
 
-## Why
+## Evidence
 
-Explain the problem or improvement.
-
-## Checklist
-
-- [ ] Docs updated if behavior changed
-- [ ] Examples updated if needed
-- [ ] Changelog updated if user-visible
-- [ ] No unsafe assumptions introduced
+- [ ] Added or updated a minimal unsafe fixture.
+- [ ] Added a safe fixture or regression test.
+- [ ] `npm run verify` passes.
+- [ ] No credentials or customer data are included.
+- [ ] Policy and Codex documentation match the implementation.

.github/release-checklist.md

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

.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: CI
+
+on:
+  push:
+    branches: [main, "codex/**"]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Node ${{ matrix.node-version }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [20, 22, 24]
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+      - run: npm ci --ignore-scripts
+      - run: npm test
+      - run: npm run check
+      - run: npm pack --dry-run
+
+  integration:
+    name: GitHub Action and policy fixtures
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 22
+      - name: Exercise the local GitHub Action
+        uses: ./
+        with:
+          path: examples/safe-support-agent.workflow.json
+          output: vibeflow.sarif
+      - name: Ensure unsafe fixture is rejected
+        run: |
+          if node bin/vibeflow.mjs check examples/unsafe-support-agent.workflow.json --format sarif --output unsafe.sarif; then
+            echo "Unsafe fixture unexpectedly passed"
+            exit 1
+          fi
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: vibeflow-sarif
+          path: |
+            vibeflow.sarif
+            unsafe.sarif

.github/workflows/markdown-lint.yml

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

.gitignore

@@ -9,5 +9,8 @@
 .vscode/
 .idea/
 
-# demo exports
-assets/private/
+# local build output
+node_modules/
+*.tgz
+vibeflow.sarif
+.vibeflow.local.json

.vibeflow.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "./schemas/vibeflow-config.schema.json",
+  "rules": {
+    "VF001": "error",
+    "VF002": "error",
+    "VF003": "warning",
+    "VF004": "warning",
+    "VF005": "warning",
+    "VF006": "error",
+    "VF007": "warning",
+    "VF008": "warning",
+    "VF009": "warning",
+    "VF010": "error",
+    "VF011": "warning",
+    "VF012": "warning",
+    "VF013": "warning"
+  }
+}

CHANGELOG.md

@@ -1,91 +1,21 @@
 # Changelog
 
-## 0.7.0
+## 0.9.0 - 2026-07-23
 
-- refreshed README for a stronger public-facing landing experience
-- added a real-demo playbook for terminal-to-n8n walkthroughs
-- added README premium checklist for launch polish
-- added customer support escalation and HubSpot-to-Slack qualification recipes
-- added an illustrative sample workflow export JSON for documentation and local experimentation
-- added release notes for v0.7.0
+- Added outcome-aware policies VF010-VF013 for money, customer, privileged, and destructive-data actions.
+- Added structurally verified outcome contracts for approval, durable audit, idempotency, amount and counterparty limits, failure notification, and recovery.
+- Added detection of silent connected error paths and high-confidence classification of ordinary nodes such as HTTP requests by their real-world action.
+- Added safe and unsafe refund fixtures, configuration schema support, Codex plugin guidance, and adversarial regression tests.
+- Documented the static-analysis ceiling: runtime authorization, limits, audit durability, and recovery still belong in the executing system.
 
-## 0.6.0
+## 0.8.0 - 2026-07-22
 
-- added showcase-oriented demo docs
-- added placeholder SVG assets for hero, terminal, workflow, and report visuals
-- added AI lead enrichment and Slack-to-Notion triage recipes
-- updated README to highlight demo flow and stronger launch materials
-- updated roadmap for a showcase-ready release
+- Repositioned Vibeflow as a safety and contract gate for AI-generated n8n workflows.
+- Added a dependency-free CLI with text, JSON, and SARIF reports.
+- Added VF000-VF009 policies, configuration, fixtures, tests, and a GitHub Action.
+- Added an installable Codex skill and plugin marketplace.
+- Removed the obsolete workflow-builder marketing kit.
 
-## 0.5.0
+## Legacy
 
-- Added launch-ready branding files, including logo and social preview SVG assets
-- Added community onboarding docs, starter issue ideas, and social copy
-- Added GitHub publishing tutorial with both web and CLI flows
-- Added Discussion templates and an extra good-first-issue template
-- Refined README for public launch positioning
-
-## v0.4.0
-
-Launch-focused release that makes the repository ready for public publication on GitHub.
-
-### Added
-- launch assets and copy pack for GitHub, socials, and repository metadata
-- reusable release notes template
-- sample MCP config files for Codex, Claude Code, and OpenCode
-- starter screenshots guide and demo capture checklist
-- launch-day checklist with publishing order and post-launch follow-up
-- README polish for public-facing adoption
-
-### Improved
-- clearer positioning for the project as a planning-first skill kit
-- stronger onboarding guidance for first-time users
-- better launch readiness for open-source publication
-
-## v0.3.0
-
-GitHub-ready skill kit with schema, install guides, and client snippets.
-
-### Added
-- getting started guide
-- install/setup docs
-- normalized plan schema
-- sample plan JSON
-- release checklist
-- concrete client snippets for Codex, Claude Code, OpenCode
-- OpenClaude compatibility notes
-
-### Improved
-- README structure and public-facing docs
-- packaging for publication
-
-## v0.2.0
-
-Second public iteration focused on open-source readiness and documentation maturity.
-
-### Added
-- bilingual README
-- architecture and roadmap docs
-- contributing, security, and changelog files
-- recipes for lead triage, support triage, and invoice reminders
-- walkthrough examples
-- GitHub issue and PR templates
-- starter markdown lint workflow
-
-### Improved
-- project structure for public publishing
-- skill prompt and conversation contract
-
-## v0.1.0
-
-Initial public skeleton of the Vibeflow n8n skill kit.
-
-### Added
-- repository structure
-- initial README
-- skill spec
-- conversation contract
-- publishing guide
-- system prompt
-- intake and final report templates
-- example plans and briefs
+The original documentation-first prototype is preserved at `legacy-v0.7.0`.

CODE_OF_CONDUCT.md

@@ -0,0 +1,7 @@
+# Code of conduct
+
+Vibeflow welcomes evidence-backed contributions from people of every background and experience level.
+
+Be respectful, discuss the work rather than the person, protect private workflow data, and assume good intent while asking for reproducible evidence. Harassment, discrimination, threats, doxxing, and publication of credentials or customer data are not acceptable.
+
+Report conduct or privacy concerns privately to the maintainer through the contact address on the maintainer's GitHub profile. Reports will be reviewed confidentially and may result in warnings, content removal, or exclusion from project spaces.

CONTRIBUTING.md

@@ -1,79 +1,29 @@
 # Contributing
 
-Thanks for contributing to Vibeflow n8n.
+Vibeflow favors small, evidence-backed rules over broad heuristics.
 
-We want this project to stay practical, readable, and friendly to contributors.
+## Development
 
-## What contributions are welcome
+Node.js 20 or newer is required. No dependency installation is needed.
 
-- new recipes
-- better examples
-- client-specific setup improvements
-- docs clarifications
-- prompt refinements
-- validation heuristics
-- packaging improvements for open-source distribution
+```bash
+npm test
+npm run check
+npm pack --dry-run
+```
 
-## Contribution principles
+## Policy changes
 
-- prefer clarity over cleverness
-- keep examples realistic
-- avoid vendor lock where possible
-- document assumptions explicitly
-- keep the user experience friendly for non-experts
+A policy change must include:
 
-## Branch naming
+1. A stable rule ID and remediation in `src/vibeflow.mjs`.
+2. Configuration support in the JSON schema.
+3. A fixture proving the unsafe case.
+4. A safe fixture or test guarding against the likely false positive.
+5. Updated user and Codex policy documentation.
 
-Suggested branch prefixes:
-- `feat/`
-- `fix/`
-- `docs/`
-- `chore/`
-- `recipe/`
+Rules that cannot produce deterministic results from exported JSON belong outside the core CLI.
 
-Examples:
-- `feat/add-plan-schema`
-- `docs/improve-opencode-guide`
-- `recipe/lead-qualification-pack`
+Keep pull requests focused. Show the smallest failing workflow and the before/after CLI output. Never submit real credentials or customer data.
 
-## Pull requests
-
-A good PR should:
-- explain the problem,
-- describe the change,
-- note any breaking behavior,
-- include updated docs when needed,
-- include an example when behavior changes.
-
-## Documentation expectations
-
-If you change the skill behavior, also update at least one of:
-- `docs/skill-spec.md`
-- `docs/conversation-contract.md`
-- `templates/system-prompt.md`
-- `examples/`
-
-## Recipes
-
-When adding a recipe, include:
-- scenario summary,
-- ideal intake questions,
-- suggested node structure,
-- common risks,
-- validation notes,
-- sample final report excerpt.
-
-## Style guide
-
-- use markdown
-- keep sections short and scannable
-- write for builders, not only prompt engineers
-- avoid unnecessary jargon
-
-## Release notes
-
-When your change matters to users, update `CHANGELOG.md`.
-
-## Security-sensitive changes
-
-If your contribution touches secrets, auth, external communication, or destructive actions, also review `SECURITY.md`.
+Participation is governed by the [code of conduct](CODE_OF_CONDUCT.md).

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026
+Copyright (c) 2026 Felipe Domingues
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,471 +1,150 @@
- # ⚡ Vibeflow n8n
+# Vibeflow
 
-<div align="center">
+[![CI](https://github.com/domfelipe/vibeflow-n8n/actions/workflows/ci.yml/badge.svg)](https://github.com/domfelipe/vibeflow-n8n/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
+**Safety and contract checks for AI-generated n8n workflows.**
 
-### Build complete n8n workflows through MCP with any coding agent.
+Vibeflow answers one question before deployment: **does this workflow deserve to reach production?**
 
-**Vibe code your automation. Let the agent handle the wiring.**
+It inspects exported n8n JSON for embedded secrets, dangerous nodes, exposed webhooks, missing failure paths, absent idempotency, unsafe AI paths, unbounded execution, risky retries, and unguarded real-world outcomes such as refunds, customer messages, privileged actions, and destructive writes.
 
-Create, update, and validate n8n workflows using **Codex CLI**, **Claude Code**, **OpenCode**, and other MCP-capable coding agents.
+Vibeflow is not another workflow builder or MCP server. It is a deterministic quality gate for workflows built by people or agents.
 
-[![Version](https://img.shields.io/badge/version-0.7.0-black)](#-release-notes)
-[![n8n](https://img.shields.io/badge/n8n-MCP%20workflows-ff6d00)](#-why-vibeflow)
-[![MCP](https://img.shields.io/badge/MCP-agent%20compatible-blue)](#-supported-clients)
-[![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
-[![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-brightgreen)](#-contributing)
-
-</div>
-
----
-
-## ✨ What is Vibeflow n8n?
-
-**Vibeflow n8n** is an open-source skill kit for coding agents that lets anyone describe an automation in natural language and have the agent:
-
-1. **ask the right questions**
-2. **generate a structured plan**
-3. **build the workflow in n8n through MCP**
-4. **validate the result**
-5. **return a clean implementation report**
-
-Instead of wrestling with nodes, expressions, branching logic, and half-finished drafts, you get a guided workflow-building experience designed for **vibe coding with real structure**.
-
----
-
-## 🔥 Why Vibeflow?
-
-Most agent-based automation flows fail for predictable reasons:
-
-* they start building too early
-* they skip business rules
-* they assume credentials and app behavior
-* they produce fragile workflows with no validation
-* they leave the user with a maze instead of an automation
-
-**Vibeflow n8n** fixes that by forcing a better sequence:
-
-* **brief first** 🧠
-* **plan next** 🗺️
-* **build with MCP** 🔧
-* **validate before delivery** ✅
-* **report what was done and what is missing** 📦
-
-It is opinionated in the useful places and flexible where real-world workflows vary.
-
----
-
-## 🧭 How it works
-
-```mermaid
-flowchart LR
-    A[User describes workflow] --> B[Agent runs intake]
-    B --> C[Plan is normalized]
-    C --> D[Workflow built via n8n MCP]
-    D --> E[Validation and assumptions]
-    E --> F[Final delivery report]
-```
-
-### The default flow
-
-* **Intake**: understand goal, trigger, systems, outputs, business rules, and exceptions
-* **Planning**: transform free-form input into a structured build plan
-* **Execution**: create or update the workflow in n8n through MCP
-* **Validation**: inspect missing credentials, placeholders, trigger logic, branches, and node naming
-* **Delivery**: summarize what was created and what still needs manual configuration
-
----
-
-## 🧩 Supported clients
-
-Vibeflow is built for **MCP-capable coding agents**.
-
-### Officially documented in this repo
-
-* **Codex CLI**
-* **Claude Code**
-* **OpenCode**
-* **Community / experimental MCP clients**
-
-See:
-
-* [`clients/codex/`](./clients/codex)
-* [`clients/claude-code/`](./clients/claude-code)
-* [`clients/opencode/`](./clients/opencode)
-* [`clients/openclaude/`](./clients/openclaude)
-
----
-
-## 🛠️ What you can build
-
-### Growth and ops
-
-* lead triage pipelines
-* AI lead enrichment
-* CRM qualification flows
-* inbound webhook routers
-* campaign handoff automations
-
-### Support workflows
-
-* support triage
-* escalation routing
-* Slack to Notion triage
-* ticket classification and enrichment
-
-### Finance and back office
-
-* invoice reminders
-* approval flows
-* billing follow-ups
-* notification pipelines
-
-### AI-powered workflows
-
-* summarize incoming data
-* classify requests
-* enrich records with LLM outputs
-* hand off low-confidence cases for review
-
----
-
-## 🚀 Quick start
-
-### 1. Clone the repository
+## Quick start
 
 ```bash
-git clone https://github.com/domfelipe/vibeflow-n8n.git
-cd vibeflow-n8n
+npx --yes github:domfelipe/vibeflow-n8n#v0.9.0 check workflow.json
 ```
 
-### 2. Connect an MCP-compatible coding agent
+Or from a checkout:
 
-Pick your client and configure it using the examples in the `clients/` folder.
+```bash
+node bin/vibeflow.mjs check workflow.json
+```
 
-### 3. Point your agent to Vibeflow instructions
-
-Use the prompt and behavioral contract from:
-
-* [`templates/system-prompt.md`](./templates/system-prompt.md)
-* [`docs/conversation-contract.md`](./docs/conversation-contract.md)
-* [`docs/skill-spec.md`](./docs/skill-spec.md)
-
-### 4. Ask for a workflow
-
-Example prompt:
+A safe workflow exits `0`. Blocking findings exit `1`; invalid usage exits `2`.
 
 ```text
-Build an n8n workflow that receives leads from a webhook, enriches them with AI, sends qualified leads to HubSpot, and notifies Slack when confidence is low.
+✖ examples/unsafe-support-agent.workflow.json (Unsafe support agent)
+  ERROR VF001 [Send response] Literal secret-like value
+  ERROR VF002 [Run Shell] Host-level node is blocked
+  ERROR VF006 [AI Agent] No upstream kill switch
+
+Checked 1 workflow(s): 3 error(s), 8 warning(s)
 ```
 
-### 5. Review the plan, then build
+Run the reproducible fixtures:
 
-The agent should:
+```bash
+node bin/vibeflow.mjs check examples/safe-support-agent.workflow.json
+node bin/vibeflow.mjs check examples/unsafe-support-agent.workflow.json --fail-on never
+```
 
-* ask follow-up questions only when needed
-* create a structured plan
-* build in n8n via MCP
-* validate the result
-* deliver a final report
+## Policies
 
----
+| ID | Default | Check |
+|---|---|---|
+| VF000 | error | Valid n8n workflow JSON |
+| VF001 | error | Literal credentials in node parameters |
+| VF002 | error | Host-level command, SSH, and local-file nodes |
+| VF003 | warning | Webhooks without supported auth and a credential reference |
+| VF004 | warning | External actions without a connected failure path |
+| VF005 | warning | Inbound side effects without an atomic idempotency claim |
+| VF006 | error | AI entry paths that bypass a structural kill switch |
+| VF007 | warning | AI paths without a reachable external human handoff |
+| VF008 | warning | Workflows without a 1-3600 second execution timeout |
+| VF009 | warning | Retries without idempotency, bounds, or backoff |
+| VF010 | error | Money or privileged actions without a verified outcome contract |
+| VF011 | warning | Customer communications or destructive writes without an outcome contract |
+| VF012 | warning | Connected error paths that terminate without operator notification |
+| VF013 | warning | High-impact writes without compensation, rollback, or replay evidence |
 
-## 🧠 Core design principles
+Static analysis cannot prove runtime correctness. Configure severity and domain vocabulary in `.vibeflow.json`; document every waiver.
 
-### 1. Plan before touching n8n
+## Outcome contracts
 
-No blind node generation.
+Vibeflow v0.9 separates a dangerous node from a dangerous outcome. A normal HTTP node can issue a refund, notify a customer, or change access. High-confidence cases are detected from the action's name, type, operation, URL, and parameters. Teams can classify other actions explicitly.
 
-### 2. Ask only what changes the build
+Contracts are keyed by the exact action node name:
 
-No interrogation theater.
+```json
+{
+  "outcomeContracts": {
+    "Issue refund": {
+      "impact": "money",
+      "approvalNode": "Approve refund",
+      "auditNode": "Record refund audit",
+      "failureNotificationNode": "Notify refund failure",
+      "amountGuard": { "node": "Limit refund amount", "maximum": 500, "currency": "USD" },
+      "counterpartyGuard": { "node": "Allow refund account", "allowed": ["merchant-primary"] },
+      "recovery": { "strategy": "compensate", "node": "Compensate transaction" }
+    }
+  }
+}
+```
 
-### 3. Defaults should be helpful
+The checker verifies that referenced nodes exist, required gates dominate every entry path, approval/limit allow and deny branches are structural, a durable audit happens before the action, an atomic idempotency claim cannot be bypassed, failure notification is on the error branch, and recovery is represented in the graph.
 
-The agent should use safe, practical assumptions when possible.
+Run the outcome demo:
 
-### 4. Report assumptions clearly
+```bash
+node bin/vibeflow.mjs check examples/unsafe-refund.workflow.json --fail-on never
+node bin/vibeflow.mjs check examples/safe-refund.workflow.json --config examples/outcome-contracts.vibeflow.json
+```
 
-What was inferred should never be hidden.
+Use `--locked` in untrusted CI. It rejects disabled or downgraded rules, changed vocabulary, and removal of default banned node types. The bundled GitHub Action always enables it.
 
-### 5. Output should be editable by humans
+## Automation
 
-The workflow must still make sense inside n8n.
+```bash
+vibeflow check workflow.json --format json
+vibeflow check workflow.json --format sarif --output vibeflow.sarif
+vibeflow check workflows/ --fail-on warning
+```
 
----
+Directories are searched recursively for `*.workflow.json` files.
 
-## 📁 Repository structure
+### GitHub Action
+
+```yaml
+- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+- uses: domfelipe/vibeflow-n8n@v0.9.0
+  with:
+    path: workflows/
+    output: vibeflow.sarif
+```
+
+## Codex plugin
+
+```bash
+codex plugin marketplace add domfelipe/vibeflow-n8n --ref v0.9.0
+```
+
+Install **Vibeflow** from the Plugins Directory, then ask:
 
 ```text
-vibeflow-n8n/
-├── clients/
-│   ├── claude-code/
-│   ├── codex/
-│   ├── opencode/
-│   └── openclaude/
-├── docs/
-│   ├── architecture.md
-│   ├── conversation-contract.md
-│   ├── getting-started.md
-│   ├── github-launch.md
-│   ├── install.md
-│   ├── roadmap.md
-│   └── tutorial-subir-github.md
-├── examples/
-│   ├── sample-plan.json
-│   └── sample-workflow-export.json
-├── recipes/
-│   ├── ai-lead-enrichment.md
-│   ├── customer-support-escalation.md
-│   ├── hubspot-to-slack-qualification.md
-│   ├── invoice-reminder.md
-│   ├── lead-triage.md
-│   ├── slack-to-notion-triage.md
-│   └── support-triage.md
-├── schemas/
-│   └── plan.schema.json
-├── templates/
-│   ├── final-report-template.md
-│   ├── intake-checklist.md
-│   └── system-prompt.md
-└── README.md
+Use $vibeflow to audit this n8n workflow and fix blocking findings.
 ```
 
----
+## Boundaries
 
-## ⚙️ Build contract
+No hosted service, new MCP server, workflow generation, telemetry, secret collection, or live n8n mutation. The CLI uses only the Node.js 20+ standard library.
 
-Vibeflow expects agents to move through these stages:
+An outcome contract is structural evidence, not runtime enforcement. Money and customer-facing actions still need server-side amount and counterparty checks, atomic idempotency, approval authorization, durable audit storage, and tested recovery behavior at runtime.
 
-### Intake
+## Documentation
 
-Capture:
+- [Product brief](docs/product-brief.md)
+- [Architecture and limitations](docs/architecture.md)
+- [Reproducible demo](docs/demo.md)
+- [Release audit](docs/release-audit.md)
+- [Community launch pack](docs/community-launch-v0.9.md)
+- [Roadmap](docs/roadmap.md)
+- [Codex for Open Source application gate](docs/codex-for-oss-application.md)
+- [Contributing](CONTRIBUTING.md)
+- [Security](SECURITY.md)
 
-* workflow goal
-* trigger type
-* systems involved
-* desired output
-* business rules
-* exceptions
-* approval needs
+`v0.9.0` adds outcome-aware preflight checks. `v0.8.0` remains the first executable release, and the original documentation prototype is preserved at `legacy-v0.7.0`.
 
-### Planning
-
-Generate a normalized plan with:
-
-* summary
-* trigger
-* apps and services
-* implementation steps
-* edge cases
-* validation checklist
-* required credentials
-* unresolved questions
-
-### Execution
-
-Use MCP to:
-
-* create or update the workflow
-* name nodes clearly
-* preserve readability
-* add placeholders where secrets are missing
-
-### Validation
-
-Check for:
-
-* broken branches
-* missing credentials
-* malformed assumptions
-* unclear node naming
-* weak error handling
-
-### Delivery
-
-Return:
-
-* what was built
-* what was assumed
-* what still needs manual setup
-* how to test it
-* suggested upgrades
-
----
-
-## 📦 Example use cases
-
-### Example 1: Lead routing
-
-> “Build a workflow that receives website leads, scores them, enriches them with AI, and sends only qualified ones to HubSpot.”
-
-### Example 2: Support escalation
-
-> “Create a workflow that watches urgent support requests, classifies them, escalates high-risk cases to Slack, and creates a tracking record.”
-
-### Example 3: Billing reminder
-
-> “Build a recurring workflow that checks unpaid invoices every weekday and sends reminders only when due dates are inside policy.”
-
-See the full set in [`recipes/`](./recipes).
-
----
-
-## 🖼️ Demo flow
-
-A clean public demo usually looks like this:
-
-1. show the natural-language request
-2. show the planning output
-3. show the workflow created in n8n
-4. show the final delivery report
-
-Helpful references:
-
-* [`docs/demo-script.md`](./docs/demo-script.md)
-* [`docs/real-demo-playbook.md`](./docs/real-demo-playbook.md)
-* [`docs/showcase-checklist.md`](./docs/showcase-checklist.md)
-
----
-
-## 📚 Documentation
-
-### Start here
-
-* [`docs/getting-started.md`](./docs/getting-started.md)
-* [`docs/install.md`](./docs/install.md)
-* [`docs/architecture.md`](./docs/architecture.md)
-
-### Agent behavior
-
-* [`docs/skill-spec.md`](./docs/skill-spec.md)
-* [`docs/conversation-contract.md`](./docs/conversation-contract.md)
-* [`templates/system-prompt.md`](./templates/system-prompt.md)
-
-### Publishing and community
-
-* [`docs/github-launch.md`](./docs/github-launch.md)
-* [`docs/community-onboarding.md`](./docs/community-onboarding.md)
-* [`CONTRIBUTING.md`](./CONTRIBUTING.md)
-* [`SECURITY.md`](./SECURITY.md)
-
----
-
-## 🌍 Who is this for?
-
-Vibeflow is a good fit for:
-
-* automation builders using n8n
-* developers who prefer CLI agents
-* consultants delivering automation fast
-* internal ops teams
-* founders building workflows without a huge engineering ceremony
-* anyone who likes **vibe coding**, but also likes finishing things
-
----
-
-## 🧪 Status
-
-Vibeflow is currently a **skill kit / workflow-building framework for coding agents**, with practical support material for MCP-based clients and progressive improvements across releases.
-
-If you want the fastest route to value, start with:
-
-* one recipe
-* one client
-* one end-to-end demo
-
-Then expand.
-
----
-
-## 🗺️ Roadmap
-
-Planned areas of evolution:
-
-* richer client-specific setup examples
-* more production-grade workflow recipes
-* exportable demo workflows
-* stronger plan validation
-* public demo assets and GIFs
-* starter kits by domain
-
-See [`docs/roadmap.md`](./docs/roadmap.md).
-
----
-
-## 🤝 Contributing
-
-Contributions are welcome.
-
-You can help by:
-
-* improving docs
-* adding recipes
-* refining client setup guides
-* validating agent behavior in real workflows
-* contributing examples and demos
-
-Start here:
-
-* [`CONTRIBUTING.md`](./CONTRIBUTING.md)
-* [`.github/ISSUE_TEMPLATE/`](./.github/ISSUE_TEMPLATE)
-* [`.github/DISCUSSION_TEMPLATE/`](./.github/DISCUSSION_TEMPLATE)
-
----
-
-## 🛡️ Security
-
-Please do **not** commit secrets, credentials, or private tokens.
-
-If you find a security issue, check [`SECURITY.md`](./SECURITY.md).
-
----
-
-## 📝 Release notes
-
-Recent release materials:
-
-* [`docs/release-v0.7.0.md`](./docs/release-v0.7.0.md)
-* [`CHANGELOG.md`](./CHANGELOG.md)
-
----
-
-## 💬 Community
-
-This project is designed to become easier the more people share their patterns.
-
-If you build something cool with Vibeflow:
-
-* open a discussion
-* share your workflow idea
-* submit a recipe
-* improve the docs for the next builder
-
----
-
-## ⭐ Support the project
-
-If this repo helps you build better automations:
-
-* give it a star
-* share it with your team
-* open an issue with ideas
-* contribute a recipe or improvement
-
-That kind of signal helps the project grow legs.
-
----
-
-## 📄 License
-
-This project is available under the terms of the license in [`LICENSE`](./LICENSE).
-
----
-
-<div align="center">
-
-### ⚡ Vibeflow n8n
-
-**Describe the workflow. Vibe code the idea. Let the agent build the machinery.**
-
-</div>
+MIT licensed.

SECURITY.md

@@ -1,44 +1,15 @@
-# Security Policy
+# Security policy
+
+## Reporting
+
+Use GitHub private vulnerability reporting for this repository. Do not open a public issue containing exploit details, credentials, or customer workflow data.
+
+## Supported versions
+
+Security fixes target the latest tagged release.
 
 ## Scope
 
-This repository contains prompts, conventions, examples, and packaging guidance for agent-driven workflow creation in n8n.
+Vibeflow reads local JSON and optionally writes a caller-selected report. It does not contact n8n, execute workflows, collect telemetry, or upload workflow content.
 
-It does not store production secrets by design.
-
-## Reporting a vulnerability
-
-If you discover a security issue related to:
-- secret handling guidance,
-- destructive workflow defaults,
-- unsafe recipe recommendations,
-- risky prompt behavior,
-
-please report it privately before opening a public issue.
-
-Use a private contact method for the maintainer when available.
-
-## Security expectations for contributors
-
-Contributors should avoid introducing guidance that:
-- assumes access to credentials that may not exist,
-- performs destructive actions without explicit user intent,
-- sends external communications without confirmation,
-- hides compliance-sensitive assumptions,
-- suggests storing plaintext secrets in repo files.
-
-## Safe defaults
-
-The skill should prefer:
-- placeholders over fake credentials,
-- explicit assumptions over silent guesses,
-- confirmation for destructive or externally visible actions,
-- human-readable reports for manual review.
-
-## Out of scope
-
-This repository does not guarantee:
-- security of any third-party MCP server,
-- security of any n8n deployment,
-- security of a user's local machine,
-- correctness of external vendor SDKs or CLIs.
+The secret rule is a defensive heuristic, not a replacement for repository secret scanning. A clean report is not proof of runtime security.

VERSION

@@ -1 +0,0 @@
-0.7.0

action.yml

@@ -0,0 +1,34 @@
+name: "Vibeflow n8n safety gate"
+description: "Audit an exported n8n workflow and fail on blocking safety findings"
+author: "Felipe Domingues"
+inputs:
+  path:
+    description: "Workflow JSON file or directory containing *.workflow.json files"
+    required: false
+    default: "."
+  format:
+    description: "Report format: text, json, or sarif"
+    required: false
+    default: "sarif"
+  output:
+    description: "Report output path"
+    required: false
+    default: "vibeflow.sarif"
+  fail-on:
+    description: "Failure threshold: error, warning, or never"
+    required: false
+    default: "error"
+runs:
+  using: "composite"
+  steps:
+    - name: Run Vibeflow
+      shell: bash
+      env:
+        VIBEFLOW_INPUT_PATH: ${{ inputs.path }}
+        VIBEFLOW_INPUT_FORMAT: ${{ inputs.format }}
+        VIBEFLOW_INPUT_OUTPUT: ${{ inputs.output }}
+        VIBEFLOW_INPUT_FAIL_ON: ${{ inputs.fail-on }}
+      run: >-
+        node "$GITHUB_ACTION_PATH/bin/vibeflow.mjs" check "$VIBEFLOW_INPUT_PATH"
+        --format "$VIBEFLOW_INPUT_FORMAT" --output "$VIBEFLOW_INPUT_OUTPUT"
+        --fail-on "$VIBEFLOW_INPUT_FAIL_ON" --locked

assets/README.md

@@ -1,22 +0,0 @@
-# Assets
-
-This folder contains launch and showcase assets for the repository.
-
-## Included
-
-- `logo.svg`
-- `social-preview.svg`
-- `hero-banner.svg`
-- `terminal-demo.svg`
-- `workflow-demo.svg`
-- `final-report-demo.svg`
-
-## Usage
-
-Use these SVG files as placeholders until you capture real screenshots or GIFs from an end-to-end run.
-
-Recommended replacement order:
-1. terminal demo
-2. workflow canvas
-3. final report
-4. hero banner

assets/final-report-demo.svg

@@ -1,13 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="1400" height="900" viewBox="0 0 1400 900">
-<rect width="1400" height="900" fill="#ffffff"/>
-<rect x="90" y="70" width="1220" height="760" rx="24" fill="#f8fafc" stroke="#cbd5e1"/>
-<text x="130" y="140" fill="#0f172a" font-size="42" font-family="Arial, Helvetica, sans-serif" font-weight="700">Implementation Report</text>
-<text x="130" y="220" fill="#0f172a" font-size="28" font-family="Arial, Helvetica, sans-serif" font-weight="700">Created</text>
-<text x="170" y="270" fill="#334155" font-size="26" font-family="Arial, Helvetica, sans-serif">• Slack trigger, urgency classifier, Notion insert, status reporter</text>
-<text x="130" y="360" fill="#0f172a" font-size="28" font-family="Arial, Helvetica, sans-serif" font-weight="700">Assumptions</text>
-<text x="170" y="410" fill="#334155" font-size="26" font-family="Arial, Helvetica, sans-serif">• Urgent means billing, outage, or executive mention</text>
-<text x="130" y="500" fill="#0f172a" font-size="28" font-family="Arial, Helvetica, sans-serif" font-weight="700">Missing credentials</text>
-<text x="170" y="550" fill="#334155" font-size="26" font-family="Arial, Helvetica, sans-serif">• Slack bot token, Notion integration, escalation channel id</text>
-<text x="130" y="640" fill="#0f172a" font-size="28" font-family="Arial, Helvetica, sans-serif" font-weight="700">How to test</text>
-<text x="170" y="690" fill="#334155" font-size="26" font-family="Arial, Helvetica, sans-serif">• Send one urgent message and one normal message, then confirm both paths</text>
-</svg>

assets/hero-banner.svg

@@ -1,14 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="900" viewBox="0 0 1600 900">
-<rect width="1600" height="900" fill="#0b1020"/>
-<rect x="70" y="80" width="1460" height="740" rx="32" fill="#111831" stroke="#2a3768"/>
-<text x="120" y="220" fill="#ffffff" font-size="72" font-family="Arial, Helvetica, sans-serif" font-weight="700">Vibeflow n8n</text>
-<text x="120" y="300" fill="#9fb4ff" font-size="32" font-family="Arial, Helvetica, sans-serif">Plan-first workflow generation for MCP-capable coding agents</text>
-<rect x="120" y="380" width="1360" height="290" rx="24" fill="#0e1530" stroke="#2a3768"/>
-<text x="170" y="470" fill="#7dd3fc" font-size="26" font-family="Courier New, monospace">User:</text>
-<text x="260" y="470" fill="#e5e7eb" font-size="26" font-family="Courier New, monospace">Build a Slack-to-Notion triage workflow with urgency routing.</text>
-<text x="170" y="540" fill="#86efac" font-size="26" font-family="Courier New, monospace">Agent:</text>
-<text x="260" y="540" fill="#e5e7eb" font-size="26" font-family="Courier New, monospace">1) Asking only critical questions</text>
-<text x="260" y="585" fill="#e5e7eb" font-size="26" font-family="Courier New, monospace">2) Generating normalized plan</text>
-<text x="260" y="630" fill="#e5e7eb" font-size="26" font-family="Courier New, monospace">3) Building workflow in n8n via MCP</text>
-<text x="120" y="760" fill="#94a3b8" font-size="24" font-family="Arial, Helvetica, sans-serif">Use this as a placeholder hero until you replace it with a real screenshot or GIF.</text>
-</svg>

assets/logo.svg

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

assets/social-preview.svg

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

assets/terminal-demo.svg

@@ -1,17 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="1400" height="900" viewBox="0 0 1400 900">
-<rect width="1400" height="900" fill="#0a0f1f"/>
-<rect x="80" y="70" width="1240" height="760" rx="24" fill="#111827" stroke="#334155"/>
-<circle cx="130" cy="110" r="10" fill="#f87171"/>
-<circle cx="160" cy="110" r="10" fill="#fbbf24"/>
-<circle cx="190" cy="110" r="10" fill="#34d399"/>
-<text x="120" y="170" fill="#93c5fd" font-size="28" font-family="Courier New, monospace">$ use vibeflow skill to build a support triage workflow</text>
-<text x="120" y="245" fill="#86efac" font-size="28" font-family="Courier New, monospace">Agent&gt; What should trigger the workflow?</text>
-<text x="120" y="300" fill="#e5e7eb" font-size="28" font-family="Courier New, monospace">User&gt; New support emails tagged urgent or billing</text>
-<text x="120" y="375" fill="#86efac" font-size="28" font-family="Courier New, monospace">Agent&gt; Which systems should receive the result?</text>
-<text x="120" y="430" fill="#e5e7eb" font-size="28" font-family="Courier New, monospace">User&gt; Zendesk, Slack, and a spreadsheet</text>
-<text x="120" y="505" fill="#86efac" font-size="28" font-family="Courier New, monospace">Agent&gt; Generating normalized plan...</text>
-<text x="120" y="580" fill="#7dd3fc" font-size="28" font-family="Courier New, monospace">✔ objective</text>
-<text x="120" y="625" fill="#7dd3fc" font-size="28" font-family="Courier New, monospace">✔ trigger</text>
-<text x="120" y="670" fill="#7dd3fc" font-size="28" font-family="Courier New, monospace">✔ branching logic</text>
-<text x="120" y="715" fill="#7dd3fc" font-size="28" font-family="Courier New, monospace">✔ validation plan</text>
-</svg>

assets/workflow-demo.svg

@@ -1,24 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="900" viewBox="0 0 1600 900">
-<rect width="1600" height="900" fill="#f8fafc"/>
-<text x="80" y="90" fill="#0f172a" font-size="40" font-family="Arial, Helvetica, sans-serif" font-weight="700">Sample Workflow Layout</text>
-<rect x="100" y="220" width="220" height="100" rx="18" fill="#dbeafe" stroke="#60a5fa"/>
-<text x="145" y="278" fill="#1e3a8a" font-size="28" font-family="Arial, Helvetica, sans-serif">Slack Trigger</text>
-<rect x="420" y="220" width="250" height="100" rx="18" fill="#dcfce7" stroke="#4ade80"/>
-<text x="455" y="278" fill="#166534" font-size="28" font-family="Arial, Helvetica, sans-serif">Normalize Message</text>
-<rect x="790" y="220" width="240" height="100" rx="18" fill="#fef3c7" stroke="#f59e0b"/>
-<text x="835" y="278" fill="#92400e" font-size="28" font-family="Arial, Helvetica, sans-serif">Classify Urgency</text>
-<rect x="1170" y="120" width="220" height="100" rx="18" fill="#fee2e2" stroke="#f87171"/>
-<text x="1238" y="178" fill="#991b1b" font-size="28" font-family="Arial, Helvetica, sans-serif">Urgent Path</text>
-<rect x="1170" y="320" width="220" height="100" rx="18" fill="#e0e7ff" stroke="#818cf8"/>
-<text x="1230" y="378" fill="#3730a3" font-size="28" font-family="Arial, Helvetica, sans-serif">Normal Path</text>
-<rect x="790" y="520" width="240" height="100" rx="18" fill="#ede9fe" stroke="#8b5cf6"/>
-<text x="835" y="578" fill="#5b21b6" font-size="28" font-family="Arial, Helvetica, sans-serif">Create Notion Item</text>
-<rect x="1170" y="520" width="220" height="100" rx="18" fill="#cffafe" stroke="#22d3ee"/>
-<text x="1225" y="578" fill="#155e75" font-size="28" font-family="Arial, Helvetica, sans-serif">Report Status</text>
-<line x1="320" y1="270" x2="420" y2="270" stroke="#64748b" stroke-width="6"/>
-<line x1="670" y1="270" x2="790" y2="270" stroke="#64748b" stroke-width="6"/>
-<line x1="1030" y1="270" x2="1170" y2="170" stroke="#64748b" stroke-width="6"/>
-<line x1="1030" y1="270" x2="1170" y2="370" stroke="#64748b" stroke-width="6"/>
-<line x1="1280" y1="420" x2="1280" y2="520" stroke="#64748b" stroke-width="6"/>
-<line x1="1030" y1="570" x2="1170" y2="570" stroke="#64748b" stroke-width="6"/>
-</svg>

bin/vibeflow.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+
+import { writeFile } from "node:fs/promises";
+import {
+  VERSION,
+  checkPaths,
+  formatJson,
+  formatSarif,
+  formatText,
+  loadConfig,
+  safeDisplay,
+} from "../src/vibeflow.mjs";
+
+const HELP = `Vibeflow ${VERSION}
+
+Usage:
+  vibeflow check <workflow.json|directory>... [options]
+
+Options:
+  --config <path>        Policy configuration (default: .vibeflow.json)
+  --format <type>        text, json, or sarif (default: text)
+  --output <path>        Write the report to a file
+  --fail-on <level>      error, warning, or never (default: error)
+  --locked               Reject configuration that weakens built-in policy
+  --version              Print the version
+  --help                 Print this help
+
+Directories are searched recursively for *.workflow.json files.
+Exit codes: 0 passed, 1 policy failure, 2 invalid input or usage.`;
+
+function parseArgs(argv) {
+  const options = {
+    command: null,
+    inputs: [],
+    configPath: null,
+    format: "text",
+    output: null,
+    failOn: "error",
+    locked: false,
+    help: false,
+    version: false,
+  };
+
+  const args = [...argv];
+  while (args.length) {
+    const arg = args.shift();
+    if (arg === "--help" || arg === "-h") options.help = true;
+    else if (arg === "--version" || arg === "-v") options.version = true;
+    else if (arg === "--config") options.configPath = requireValue(arg, args);
+    else if (arg === "--format") options.format = requireValue(arg, args);
+    else if (arg === "--output") options.output = requireValue(arg, args);
+    else if (arg === "--fail-on") options.failOn = requireValue(arg, args);
+    else if (arg === "--locked") options.locked = true;
+    else if (arg.startsWith("-")) throw new Error(`Unknown option: ${arg}`);
+    else if (!options.command) options.command = arg;
+    else options.inputs.push(arg);
+  }
+
+  if (!options.help && !options.version) {
+    if (options.command !== "check") throw new Error("The only command is: check");
+    if (!options.inputs.length) throw new Error("Pass at least one workflow file or directory");
+    if (!["text", "json", "sarif"].includes(options.format)) {
+      throw new Error("--format must be text, json, or sarif");
+    }
+    if (!["error", "warning", "never"].includes(options.failOn)) {
+      throw new Error("--fail-on must be error, warning, or never");
+    }
+  }
+
+  return options;
+}
+
+function requireValue(option, args) {
+  const value = args.shift();
+  if (!value || value.startsWith("-")) throw new Error(`${option} requires a value`);
+  return value;
+}
+
+function shouldFail(report, failOn) {
+  if (failOn === "never") return false;
+  if (failOn === "warning") return report.summary.errors + report.summary.warnings > 0;
+  return report.summary.errors > 0;
+}
+
+async function main() {
+  try {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help) {
+      console.log(HELP);
+      return;
+    }
+    if (options.version) {
+      console.log(VERSION);
+      return;
+    }
+
+    const config = await loadConfig(options.configPath, process.cwd(), options.locked);
+    const report = await checkPaths(options.inputs, config);
+    const rendered = options.format === "json"
+      ? formatJson(report)
+      : options.format === "sarif"
+        ? formatSarif(report)
+        : formatText(report);
+
+    if (options.output) await writeFile(options.output, `${rendered}\n`, "utf8");
+    else console.log(rendered);
+
+    if (shouldFail(report, options.failOn)) process.exitCode = 1;
+  } catch (error) {
+    console.error(`vibeflow: ${safeDisplay(error.message)}`);
+    process.exitCode = 2;
+  }
+}
+
+await main();

clients/claude-code/README.md

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

clients/claude-code/config-snippets.md

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

clients/claude-code/sample-mcp.json

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

clients/codex/README.md

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

clients/codex/config-snippets.md

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

clients/codex/sample-config.toml

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

clients/openclaude/README.md

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

clients/openclaude/config-snippets.md

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

clients/opencode/README.md

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

clients/opencode/config-snippets.md

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

clients/opencode/sample-opencode.jsonc

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

docs/architecture.md

@@ -1,160 +1,57 @@
 # 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.
+VF010-VF013 introduce outcome contracts. High-confidence classification inspects a side-effect node's name, type, operation, URL, and parameters for money, customer communication, privileged access, and destructive-data semantics. Explicit `outcomeContracts` cover domain actions the built-in vocabulary does not recognize.
 
-### Stage 4. MCP execution
-The agent creates or updates the workflow using the available MCP tools.
+For a contracted action, the analyzer verifies graph evidence rather than labels alone:
 
-### Stage 5. Validation
-The agent checks for:
-- broken graph structure,
-- missing dependencies,
-- unsupported assumptions,
-- absent failure branches,
-- unresolved placeholders.
+- an atomic idempotency claim dominates the action;
+- durable audit storage dominates the action;
+- approval, amount, and counterparty guards are IF/Switch nodes with both an allowed route and a route that cannot reach the action;
+- the declared failure notification is reachable from the action's error output;
+- compensation and rollback nodes are downstream from the action; replay nodes must exist and carry recovery semantics.
 
-### Stage 6. Delivery
-The agent produces a report for the user that is operational, not ornamental.
+Money and privileged outcomes default to blocking VF010. Customer communications and destructive writes default to advisory VF011. Missing recovery and silent error paths are separate findings so teams can triage them independently.
 
-## Recommended workflow object model
+`--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`.
 
-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
+## Trust boundaries
 
-## Modes
+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.
 
-### fast
-Prototype-first mode.
-Uses more defaults and fewer follow-up questions.
+Output paths are selected by the caller. The GitHub Action passes inputs as quoted environment values.
 
-### balanced
-Default mode.
-Good mix of speed and operational sanity.
+## Known limitations
 
-### safe
-More explicit approvals, stronger validation, fewer silent assumptions.
+- Static structure cannot prove that a condition, SQL claim, or handoff works at runtime.
+- Outcome contracts cannot prove caller authorization, amount calculation, counterparty identity, audit durability, or successful compensation at runtime.
+- Automatic outcome classification is intentionally conservative and can miss domain-specific actions; declare them explicitly in configuration.
+- 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.
 
-## 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.

docs/brand-kit.md

@@ -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`

docs/codex-for-oss-application.md

@@ -0,0 +1,176 @@
+# Codex for Open Source — submission pack
+
+Application: <https://openai.com/pt-BR/form/codex-for-oss/>
+
+Program overview: <https://developers.openai.com/community/codex-for-oss>
+
+Program terms: <https://learn.chatgpt.com/docs/codex-for-oss-terms>
+
+Prepared: 2026-07-22
+
+Official form rechecked: 2026-07-22
+
+Submission reported complete: 2026-07-24
+
+The maintainer reported that the application was submitted. The ChatGPT-account email, OpenAI Organization ID, confirmation page, and exact submission timestamp remain private and are not stored in this repository.
+
+## Recommendation
+
+Submit in **English**, even through the PT-BR form. OpenAI publishes no language requirement and no evidence that language changes selection odds. English is recommended only to reduce translation friction for a global technical review.
+
+Submit now that v0.9.0 is public. Do not wait for arbitrary star, fork, or PR targets. Vibeflow's strongest evidence is its Codex-native engineering, first real 92-node audit, and a public maintenance loop that turned community feedback into tested policy features.
+
+## Copy-and-paste form
+
+### First name
+
+`Felipe`
+
+### Last name
+
+`Domingues`
+
+### Email
+
+`[FILL PRIVATELY: email associated with the ChatGPT account]`
+
+### GitHub username
+
+`domfelipe`
+
+### GitHub repository URL
+
+`https://github.com/domfelipe/vibeflow-n8n`
+
+### Maintainer role
+
+Select: **Primary maintainer**.
+
+### Why is this repository eligible?
+
+Character count: **356/500**.
+
+> Vibeflow is an MIT-licensed safety gate for AI-generated n8n workflows, rebuilt end-to-end with Codex. It audited a real 92-node workflow in read-only mode, finding 3 blocking risks and 57 warnings. Community feedback then shaped v0.9: outcome-aware checks for refunds, customer actions, silent failures, audit, idempotency, approval, limits, and recovery.
+
+### Interests
+
+Select both:
+
+- **Codex Security**
+- **API credits for my project**
+
+### OpenAI Organization ID
+
+`[FILL PRIVATELY: org-...]`
+
+Use the organization that should receive the API credits. Confirm it in the OpenAI Platform before submitting; do not place it in this public document.
+
+### How will API credits be used?
+
+Character count: **390/500**.
+
+> API credits would power OSS maintenance workflows: turn anonymized failures into adversarial fixtures, evaluate new policies, reproduce false positives, review contributed rules, triage issues, and generate release audits. Codex would assist these workflows; the Vibeflow scanner will remain local, dependency-free, telemetry-free, and will not upload or process private customer workflows.
+
+### Anything else we should know?
+
+Character count: **381/500**.
+
+> Vibeflow is a public case study in Codex-native OSS development. Codex drove the project from product repositioning through implementation, adversarial review, remediation, CI, plugin packaging, releases, a real-workflow audit, and the v0.9 response to user feedback. Adoption is early, but the engineering, maintenance history, and real-world evidence are public and reproducible.
+
+## PT-BR review translation
+
+These translations are for review only. Paste the English versions above into the form.
+
+### Repository eligibility
+
+> Vibeflow é um gate MIT de segurança para workflows n8n gerados por IA, reconstruído de ponta a ponta com Codex. Ele auditou em modo somente leitura um workflow real de 92 nós, encontrando 3 riscos bloqueantes e 57 avisos. O feedback da comunidade então moldou a v0.9: checks de resultados reais para reembolsos, ações com clientes, falhas silenciosas, auditoria, idempotência, aprovação, limites e recuperação.
+
+### API-credit use
+
+> Os créditos financiariam fluxos de manutenção OSS: transformar falhas anonimizadas em fixtures adversariais, avaliar novas políticas, reproduzir falsos positivos, revisar regras contribuídas, triar issues e gerar auditorias de release. O Codex auxiliaria esses fluxos; o scanner Vibeflow permanecerá local, sem dependências ou telemetria, e não enviará nem processará workflows privados de clientes.
+
+### Additional context
+
+> Vibeflow é um estudo de caso público de desenvolvimento open source nativo em Codex. O Codex conduziu o projeto desde o reposicionamento e implementação até revisão adversarial, correções, CI, plugin, releases, auditoria de workflow real e a resposta da v0.9 ao feedback de usuários. A adoção ainda é inicial, mas a engenharia, o histórico de manutenção e a evidência real são públicos e reproduzíveis.
+
+## Evidence map
+
+Use these links only if OpenAI requests verification; the form has no dedicated evidence field.
+
+- Public MIT repository: <https://github.com/domfelipe/vibeflow-n8n>
+- Executable release: <https://github.com/domfelipe/vibeflow-n8n/releases/tag/v0.9.0>
+- Reproducible demo: <https://github.com/domfelipe/vibeflow-n8n/blob/main/docs/demo.md>
+- Release and Red Team audit: <https://github.com/domfelipe/vibeflow-n8n/blob/main/docs/release-audit.md>
+- CI history: <https://github.com/domfelipe/vibeflow-n8n/actions/workflows/ci.yml>
+- Launch discussion: <https://github.com/domfelipe/vibeflow-n8n/discussions/3>
+- Public r/n8n feedback that shaped v0.9: <https://www.reddit.com/r/n8n/comments/1v3is1w/i_built_an_opensource_safety_gate_for_aigenerated/>
+- Public runtime feedback and anonymized-corpus offer: <https://www.reddit.com/r/n8n/comments/1v3is1w/comment/ozbyh0f/>
+- Recorded static/runtime evidence boundary: <https://github.com/domfelipe/vibeflow-n8n/blob/main/docs/community-launch-v0.9.md#post-release-runtime-feedback--2026-07-24>
+- Engineering PRs: <https://github.com/domfelipe/vibeflow-n8n/pulls?q=is%3Apr+is%3Amerged>
+
+## Evidence snapshot
+
+Captured on 2026-07-23 after release:
+
+- public repository with MIT license;
+- public `v0.9.0` release, with v0.8.0 preserved in release history;
+- 36 adversarial tests passing locally and in remote Node.js 20, 22, and 24 CI;
+- dependency-free CLI, GitHub Action, and installable Codex plugin;
+- 7 maintainer PRs merged with green CI, including the v0.9 implementation and release-evidence PR;
+- 4 stars, 0 forks, and no verified external contributor yet;
+- public r/n8n launch thread with several substantive comments that directly shaped VF010-VF013;
+- first real audit: anonymized 92-node workflow, 3 blocking findings, 57 warnings, no workflow mutation;
+- Codex used across product repositioning, implementation, review, Red Team, remediation, packaging, CI, release, real-workflow audit, and the community-feedback-driven v0.9 cycle.
+
+Do not describe maintainer PRs, the maintainer's own workflow, clones, or unattributed stars as external adoption.
+
+## Post-submission evidence snapshot
+
+Captured on 2026-07-24:
+
+- an external Reddit commenter publicly validated the static-preflight/runtime-observability split;
+- the commenter reported fail-open Code execution, error-as-data, and AI-output truncation cases from a community-workflow corpus;
+- the commenter offered to run anonymized failing workflows through Vibeflow and share false positives;
+- the linked Pisama node and runtime project were independently verified, including their separate MIT and fair-code licensing boundaries;
+- no workflow fixture, false-positive result, PR, contributor relationship, partnership, or integration had been received or established at capture time.
+
+This is evidence of substantive community engagement and a prospective evaluation path, not evidence of adoption or contribution.
+
+## Confidentiality boundary
+
+Do not submit or link the full real-workflow audit. Application materials must not include:
+
+- client, clinic, or workflow names;
+- remote workflow IDs, version IDs, hashes, or timestamps;
+- node names that reveal business logic;
+- private workflow JSON, credentials, customer data, or infrastructure identifiers.
+
+The approved public description is: **“a real, production-scale 92-node conversational workflow audited in read-only mode.”**
+
+## Submission checklist
+
+- [x] Repository is public and not archived.
+- [x] GitHub username is public.
+- [x] Role is primary maintainer.
+- [x] Repository URL is correct.
+- [x] Both requested benefits are selected.
+- [x] All narrative answers are under 500 characters.
+- [x] Real-workflow evidence is anonymized.
+- [x] Early adoption is described honestly.
+- [x] Supply the exact ChatGPT-account email privately in the form; do not retain it in the repository.
+- [x] Supply the OpenAI Organization ID privately in the form; do not retain it in the repository.
+- [ ] Re-read the current Program Terms immediately before submission.
+- [ ] Save the confirmation page and submission timestamp privately.
+- [x] Application submission reported complete by the maintainer on 2026-07-24.
+
+## After submission
+
+Continue collecting organic evidence without delaying the application:
+
+1. publish the v0.9 follow-up in r/n8n;
+2. invite users to report anonymized false positives and missed unsafe cases;
+3. respond to every issue or discussion with reproducible evidence;
+4. keep releases, CI, and the public maintenance trail current;
+5. never request artificial stars, forks, or empty PRs.
+
+OpenAI reviews applications continuously. If additional evidence is requested, provide a fresh public snapshot and the anonymized outcome of subsequent real-world audits.

docs/community-launch-v0.9.md

@@ -0,0 +1,114 @@
+# Community launch pack — v0.9.0
+
+Publish only after the public `v0.9.0` release URL works.
+
+## Feedback provenance
+
+The v0.9 scope came from the public [original r/n8n launch thread](https://www.reddit.com/r/n8n/comments/1v3is1w/i_built_an_opensource_safety_gate_for_aigenerated/), not a speculative roadmap.
+
+| Community feedback | v0.9 response |
+|---|---|
+| Separate dangerous nodes from dangerous outcomes | VF010 and VF011 classify money, customer, privileged, and destructive-data actions. |
+| Require idempotency, approval, amount/counterparty limits, and durable audit | `outcomeContracts` verifies graph evidence for those controls. |
+| Error paths can exist but notify nobody | VF012 requires an operator-visible failure path. |
+| Writes need rollback or replay stories | VF013 requires compensation, rollback, or replay evidence. |
+| Static checks cannot replace runtime guardrails | The CLI and documentation explicitly preserve that boundary. |
+
+Captured on 2026-07-22: the thread had 3 votes and several substantive comments. Treat the comments as product evidence; do not present the vote count as broad adoption.
+
+## Post-release runtime feedback — 2026-07-24
+
+Reddit user [`Fit_Preference_1795`](https://www.reddit.com/r/n8n/comments/1v3is1w/comment/ozbyh0f/) publicly described the runtime counterpart to Vibeflow's static checks and offered to test anonymized failing workflows against Vibeflow. The report identified three failure classes:
+
+- a `continueOnFail` Code node crash that leaves the execution marked successful;
+- an error object flowing through an item's JSON as ordinary data;
+- truncated AI output reaching downstream nodes despite valid JSON and a successful node status.
+
+The commenter also noted that intentional token caps must be distinguished from accidental truncation to avoid false positives. These cases reinforce the product boundary: Vibeflow can detect deterministic fail-open configuration or require a structural completeness guard, but it cannot observe runtime output or prove that an alert is watched.
+
+The linked [`n8n-nodes-pisama`](https://github.com/Pisama-AI/n8n-nodes-pisama) community node is MIT-licensed and forwards execution telemetry. Runtime detection is implemented by the separate, self-hostable [`pisama-n8n`](https://github.com/Pisama-AI/pisama-n8n) service under a fair-code license. Its public [July 2026 corpus campaign](https://github.com/Pisama-AI/pisama-n8n/blob/main/eval/campaigns/2026-07-guard-campaign.md) records 70 committed workflows, 67 real executions, and 19 observed-and-detected failures. The comment's 69-workflow report and the repository campaign are different snapshots and must not be combined into one metric.
+
+Evidence status at capture time:
+
+- verified: substantive public technical feedback and a public offer to provide anonymized false-positive evidence;
+- not yet verified: receipt of the workflows, Vibeflow verdicts, false-positive count, or a shared interoperability contract;
+- not claimed: partnership, external contribution, external user adoption, or a shipped Pisama integration.
+
+The smallest useful follow-up is three anonymized cases: fail-open Code execution, error-as-data, and intentional versus accidental truncation. A new Vibeflow rule should be added only when paired unsafe/safe fixtures expose a deterministic static signal.
+
+## Reddit — r/n8n
+
+### Title
+
+I built your feedback into Vibeflow v0.9: outcome-aware preflight checks for n8n workflows
+
+### Post
+
+I shared Vibeflow here earlier and two pieces of feedback changed the direction of the project:
+
+1. A dangerous outcome is not the same thing as a dangerous node. A normal HTTP node can still issue a refund, send a payment, notify a customer, change access, or delete data.
+2. A connected error branch is not enough if it silently terminates, and a write is not production-ready without a rollback, compensation, or replay story.
+
+That feedback is now implemented in Vibeflow v0.9.
+
+Vibeflow is a local, dependency-free preflight checker for exported n8n workflow JSON. The new release adds:
+
+- `VF010`: blocks money and privileged actions without an outcome contract;
+- `VF011`: warns about uncontracted customer communications and destructive writes;
+- `VF012`: detects error paths that notify nobody;
+- `VF013`: requires compensation, rollback, or replay evidence.
+
+For a contracted action, the checker verifies structural evidence in the workflow graph:
+
+- an atomic idempotency claim cannot be bypassed;
+- a durable audit write happens before the action;
+- approval, amount, and counterparty checks have real allow/deny branches;
+- the failure notification is connected to the action's error output;
+- recovery is represented in the graph.
+
+The important boundary: this is static preflight, not runtime enforcement. The payment/customer system must still enforce authorization, limits, counterparties, durable audit, and recovery at runtime.
+
+There is a reproducible unsafe refund workflow and a passing contracted version in the repository:
+
+https://github.com/domfelipe/vibeflow-n8n
+
+Release: https://github.com/domfelipe/vibeflow-n8n/releases/tag/v0.9.0
+
+I am especially looking for anonymized examples of:
+
+- a real-world action the classifier misses;
+- a false positive where the workflow is demonstrably safe;
+- a control that looks present in JSON but can still be bypassed;
+- a recovery pattern that does not fit compensate/rollback/replay.
+
+Please remove credentials and customer data before sharing workflow fragments. The best reports will become paired unsafe/safe regression fixtures.
+
+## Short reply to the original commenters
+
+Your distinction between dangerous nodes and dangerous outcomes became the core of v0.9. The release now detects ordinary HTTP/database/message nodes by impact and validates idempotency, approval, amount/counterparty limits, durable audit, operator-visible failures, and recovery evidence. I kept runtime enforcement explicitly outside the claim. Thank you — this materially improved the project.
+
+## GitHub Discussion
+
+### Title
+
+Vibeflow v0.9: help test outcome contracts against real n8n workflows
+
+### Body
+
+Vibeflow v0.9 adds outcome-aware preflight policies for money, customer, privileged, and destructive-data actions. The implementation was driven by community feedback that ordinary nodes can still produce dangerous real-world outcomes.
+
+Please test an exported workflow and report anonymized false positives, missed actions, bypassable controls, or recovery patterns. Useful reports need a minimal unsafe case, the expected safe case, and the exported JSON fields that distinguish them.
+
+- Release: https://github.com/domfelipe/vibeflow-n8n/releases/tag/v0.9.0
+- Demo: https://github.com/domfelipe/vibeflow-n8n/blob/v0.9.0/docs/demo.md
+- False-positive report: https://github.com/domfelipe/vibeflow-n8n/issues/new?template=false-positive.yml
+- Policy proposal: https://github.com/domfelipe/vibeflow-n8n/issues/new?template=rule-proposal.yml
+
+Never attach credentials, customer data, or a private production workflow.
+
+## Evidence rules
+
+- Do not ask for artificial stars, forks, or empty PRs.
+- Record only public, attributable usage or anonymized audit outcomes.
+- Convert actionable feedback into an issue and paired unsafe/safe fixture.
+- Never publish customer workflow names, IDs, node names, credentials, or infrastructure identifiers.

docs/community-onboarding.md

@@ -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

docs/conversation-contract.md

@@ -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

docs/demo-assets.md

@@ -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

docs/demo-script.md

@@ -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

docs/demo.md

@@ -0,0 +1,49 @@
+# 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.
+
+## Dangerous outcome
+
+```bash
+node bin/vibeflow.mjs check examples/unsafe-refund.workflow.json --fail-on never
+```
+
+Expected result: the ordinary HTTP refund node triggers blocking VF010 plus VF012 and VF013, even though its node type is not inherently dangerous.
+
+## Contracted outcome
+
+```bash
+node bin/vibeflow.mjs check examples/safe-refund.workflow.json \
+  --config examples/outcome-contracts.vibeflow.json
+```
+
+Expected result: exit `0`, zero findings. The graph contains a dominating atomic claim and durable audit, structural approval/amount/counterparty gates, error notification, and compensation evidence.
+
+## 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
+```

docs/first-issues.md

@@ -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`.

docs/getting-started.md

@@ -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.
-```

docs/github-launch.md

@@ -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.

docs/install.md

@@ -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

docs/launch-assets.md

@@ -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

docs/launch-day-checklist.md

@@ -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

docs/launch.md

@@ -0,0 +1,32 @@
+# v0.9.0 launch checklist
+
+Released: 2026-07-23
+
+## Release gate
+
+- [x] VF010-VF013 implementation and configuration schema are complete.
+- [x] Safe and unsafe refund fixtures are reproducible.
+- [x] Local `npm run verify` and `npm audit --omit=dev` pass.
+- [x] QA, adversarial Red Team, and Guardião reviews are documented.
+- [x] Pull request CI passes on Node.js 20, 22, and 24.
+- [x] Release commit is merged and tagged `v0.9.0`.
+- [x] Released CLI and pinned Codex marketplace install successfully.
+- [x] GitHub release is public and marked latest.
+
+Release: <https://github.com/domfelipe/vibeflow-n8n/releases/tag/v0.9.0>
+
+## Positioning
+
+The launch message is: **dangerous outcomes are not limited to dangerous nodes**.
+
+A normal HTTP, database, or messaging node can refund money, contact a customer, change access, or destroy data. Vibeflow v0.9 adds a preflight contract for the controls that should surround those outcomes: atomic idempotency, approval, amount and counterparty limits, durable audit, operator-visible failure paths, and recovery.
+
+## Announcement
+
+> Vibeflow v0.9 asks a more useful preflight question for generated n8n workflows: not only “is this valid JSON?” or “does it use a dangerous node?”, but “what can this workflow do in the real world if the input is messy or the model is wrong?”
+>
+> The new outcome contracts detect money, customer, privileged, and destructive-data actions — including ordinary HTTP nodes — and verify structural evidence for idempotency, approval, limits, durable audit, failure notification, and recovery. It is local, dependency-free, CI-friendly, and explicit about what still needs runtime enforcement.
+
+Link to the repository and the safe/unsafe refund demo. Ask users for anonymized workflows, classifier false positives/negatives, and missing domain actions.
+
+Ready-to-post Reddit and GitHub Discussion copy: [community-launch-v0.9.md](community-launch-v0.9.md).

docs/product-brief.md

@@ -0,0 +1,49 @@
+# 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, run forever, issue a refund, notify a customer, or destroy data without the required controls.
+
+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.9 scope
+
+- dependency-free Node.js CLI;
+- text, JSON, and SARIF output;
+- configurable VF000-VF013 policies;
+- outcome contracts for money, customer, privileged, and destructive-data actions;
+- structural checks for approval, durable audit, idempotency, limits, failure notification, and recovery;
+- safe and unsafe support and refund 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 operations: an off switch before inference, human handoff after low-confidence output, duplicate-event protection, explicit error paths, bounded retries, trust-boundary hygiene, and declared controls around real-world outcomes. It asks not only whether the workflow is valid JSON or uses a suspicious node, but what it can do when input is messy or a model is wrong.
+
+## 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.

docs/publishing-guide.md

@@ -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

docs/readme-premium-checklist.md

@@ -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

docs/real-demo-playbook.md

@@ -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."

docs/recipes-gallery.md

@@ -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.

docs/release-audit.md

@@ -0,0 +1,73 @@
+# Release audit — v0.9.0
+
+Released: 2026-07-23
+
+## Decision
+
+**APTO** within Vibeflow's documented static-preflight boundary.
+
+No blocking defect remains in the reviewed static-analysis boundary. Vibeflow can verify structural evidence in an exported workflow, but it cannot enforce authorization, amount limits, counterparty identity, audit durability, or recovery behavior in the executing systems.
+
+## QA evidence
+
+- 36 automated tests pass, including safe and unsafe support workflows and a fully contracted refund workflow.
+- The unsafe refund fixture detects an ordinary HTTP node as a money outcome and produces VF010, VF012, and VF013.
+- The contracted refund fixture exits 0 in normal and `--locked` modes.
+- Text, JSON, SARIF, configuration validation, package packing, and CLI exit behavior are exercised.
+- `npm run verify`, `npm audit --omit=dev`, JSON parsing, and `git diff --check` pass locally.
+- The package remains dependency-free and targets Node.js 20+.
+- The public `v0.9.0` tag resolves to release commit `7552eeca7cfdd56376eab2007988b81a9726fba4`.
+- The released GitHub CLI package passes the safe refund fixture with zero findings and reports VF010, VF012, and VF013 for the unsafe refund fixture.
+- The released Codex marketplace installs `vibeflow@vibeflow` version `0.9.0` in an isolated `CODEX_HOME`.
+
+## Red Team
+
+The first v0.9 implementation was hardened after adversarial review. Regression tests now cover:
+
+1. ordinary HTTP refunds that would evade a dangerous-node-only policy;
+2. read-only refund queries, preventing an obvious classifier false positive;
+3. named or disconnected approval, amount, counterparty, audit, and idempotency controls;
+4. constant approval conditions and decorative amount values;
+5. read-only or fail-open audit nodes, including an audit error branch that still reaches the action;
+6. fail-open idempotency nodes and idempotency error branches that still reach the side effect;
+7. prototype-like contract keys, self-referential notification/recovery evidence, and audit-like labels used to hide a money action;
+8. connected error paths that terminate without a recognized operator notification.
+
+The graph checks use actual `main` edges, require dominating controls, and reject evidence that reaches the action after the control itself fails.
+
+## Guardião security review
+
+### In scope
+
+- local CLI parsing of untrusted workflow/configuration JSON;
+- graph and parameter analysis;
+- text, JSON, and SARIF output;
+- npm package contents, GitHub Action boundary, and Codex plugin instructions.
+
+### Controls confirmed
+
+- no runtime dependencies, telemetry, hosted service, or live n8n mutation;
+- no workflow expressions or embedded code are evaluated;
+- no URLs found in a workflow are contacted;
+- file, node, edge, contract, vocabulary, and finding budgets are bounded;
+- terminal text is sanitized and prototype-like contract keys are handled as data;
+- the GitHub Action uses locked policy mode so a pull request cannot disable its own built-in checks;
+- examples contain credential references and reserved invalid domains, not live secrets.
+
+### Residual limitations
+
+- an exported graph cannot prove a referenced credential, approval identity, SQL policy, external API limit, notification, or compensation works at runtime;
+- custom/community nodes may need explicit impact declarations or new regression-backed adapters;
+- repository owners may intentionally weaken policy outside `--locked` mode;
+- remote Node 20/22/24 CI and released `npx`/plugin installation passed.
+
+## Release blockers
+
+- [x] Pull request CI passes on Node.js 20, 22, and 24.
+- [x] Release commit is merged without unrelated changes.
+- [x] `v0.9.0` tag and GitHub release are public.
+- [x] Released CLI and Codex plugin install paths are smoke-tested.
+
+## Final gate
+
+There are zero known critical or high security findings in the released static-analysis boundary. Runtime enforcement remains explicitly outside the product claim.

docs/release-notes-template.md

@@ -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.

docs/release-notes-v0.9.md

@@ -0,0 +1,24 @@
+# Vibeflow v0.9.0 — Outcome-aware preflight for n8n
+
+Generated workflows need more than valid JSON. A normal HTTP node can still issue a refund, notify a customer, change access, or delete production data.
+
+Vibeflow v0.9 introduces outcome contracts and four policies:
+
+- **VF010** blocks uncontracted money and privileged actions.
+- **VF011** warns on uncontracted customer communications and destructive writes.
+- **VF012** detects connected error paths that notify nobody.
+- **VF013** requires a compensation, rollback, or replay story.
+
+For contracted actions, Vibeflow checks whether atomic idempotency and durable audit dominate the action, approval and limit nodes have real allow/deny branches, failure notification is connected to the error output, and recovery is represented in the graph.
+
+Try the unsafe case:
+
+```bash
+npx --yes github:domfelipe/vibeflow-n8n#v0.9.0 check examples/unsafe-refund.workflow.json --fail-on never
+```
+
+Then inspect the passing contract in `examples/outcome-contracts.vibeflow.json` and `examples/safe-refund.workflow.json`.
+
+This is a static preflight, not a runtime policy engine. Authorization, amount/counterparty enforcement, audit durability, and tested recovery still belong in the services that execute the action.
+
+Full changelog: <https://github.com/domfelipe/vibeflow-n8n/blob/v0.9.0/CHANGELOG.md>

docs/release-v0.7.0.md

@@ -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.

docs/roadmap.md

@@ -1,34 +1,27 @@
 # 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
+## 0.9.0 — shipped 2026-07-23
 
-- 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
+Separate dangerous nodes from dangerous outcomes. Add VF010-VF013, explicit outcome contracts, graph evidence for policy gates, safe/unsafe refund fixtures, and clear runtime boundaries.
 
-## v0.8.0 ideas
+## Next release gate
 
-- optional plan linter
-- workflow quality checklist by recipe type
-- starter gallery page for examples
-- benchmark prompts for comparing clients
+Do not add another integration by default. Prioritize evidence from real workflows:
 
-## Long-term direction
+1. Measure false positives by rule and impact classifier.
+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.
+8. Add impact categories and adapters only with a real anonymized workflow and an adversarial fixture.
+9. Explore optional runtime attestations only after users demonstrate that static contracts are insufficient.
 
-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
+## Explicitly deferred
+
+Hosted UI, custom MCP server, live n8n mutation, workflow generation, and broad multi-agent wrappers.

docs/showcase-checklist.md

@@ -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

docs/skill-spec.md

@@ -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.

docs/social-copy.md

@@ -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.

docs/tutorial-subir-github.md

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

examples/example-briefs.md

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

examples/example-final-report.md

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

examples/example-plans.md

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

examples/example-walkthroughs.md

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

examples/outcome-contracts.vibeflow.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "../schemas/vibeflow-config.schema.json",
+  "outcomeContracts": {
+    "Issue refund": {
+      "impact": "money",
+      "approvalNode": "Approve refund",
+      "auditNode": "Record refund audit",
+      "failureNotificationNode": "Notify refund failure",
+      "amountGuard": { "node": "Limit refund amount", "maximum": 500, "currency": "USD" },
+      "counterpartyGuard": { "node": "Allow refund account", "allowed": ["merchant-primary"] },
+      "recovery": { "strategy": "compensate", "node": "Compensate transaction" }
+    }
+  }
+}

examples/safe-refund.workflow.json

@@ -0,0 +1,85 @@
+{
+  "name": "Safe refund with outcome contract",
+  "nodes": [
+    {
+      "id": "webhook",
+      "name": "Webhook",
+      "type": "n8n-nodes-base.webhook",
+      "parameters": { "authentication": "headerAuth", "path": "refund" },
+      "credentials": { "httpHeaderAuth": { "id": "credential-reference", "name": "Webhook Header Auth" } }
+    },
+    {
+      "id": "idempotency",
+      "name": "Claim idempotency event",
+      "type": "n8n-nodes-base.postgres",
+      "parameters": {
+        "operation": "executeQuery",
+        "query": "INSERT INTO event_ledger (event_id) VALUES ($1) ON CONFLICT (event_id) DO NOTHING RETURNING event_id"
+      }
+    },
+    {
+      "id": "audit",
+      "name": "Record refund audit",
+      "type": "n8n-nodes-base.postgres",
+      "parameters": { "operation": "insert", "table": "refund_audit" }
+    },
+    {
+      "id": "approval",
+      "name": "Approve refund",
+      "type": "n8n-nodes-base.if",
+      "parameters": { "conditions": { "boolean": [{ "value1": "={{ $json.approved }}", "value2": true }] } }
+    },
+    {
+      "id": "amount",
+      "name": "Limit refund amount",
+      "type": "n8n-nodes-base.if",
+      "parameters": {
+        "conditions": { "number": [{ "value1": "={{ $json.amount }}", "operation": "smallerEqual", "value2": 500 }] },
+        "currency": "USD"
+      }
+    },
+    {
+      "id": "counterparty",
+      "name": "Allow refund account",
+      "type": "n8n-nodes-base.switch",
+      "parameters": { "value": "={{ $json.counterparty }}", "rules": [{ "value": "merchant-primary" }] }
+    },
+    {
+      "id": "refund",
+      "name": "Issue refund",
+      "type": "n8n-nodes-base.httpRequest",
+      "onError": "continueErrorOutput",
+      "parameters": { "method": "POST", "url": "https://payments.invalid/refund" }
+    },
+    {
+      "id": "failure-alert",
+      "name": "Notify refund failure",
+      "type": "n8n-nodes-base.slack",
+      "parameters": { "channel": "operations", "text": "Notify failure for refund {{ $json.event_id }}" }
+    },
+    {
+      "id": "compensation",
+      "name": "Compensate transaction",
+      "type": "n8n-nodes-base.httpRequest",
+      "parameters": { "method": "POST", "url": "https://payments.invalid/reverse", "operation": "compensate" }
+    }
+  ],
+  "connections": {
+    "Webhook": { "main": [[{ "node": "Claim idempotency event", "type": "main", "index": 0 }]] },
+    "Claim idempotency event": { "main": [[{ "node": "Record refund audit", "type": "main", "index": 0 }]] },
+    "Record refund audit": { "main": [[{ "node": "Approve refund", "type": "main", "index": 0 }]] },
+    "Approve refund": { "main": [[{ "node": "Limit refund amount", "type": "main", "index": 0 }], []] },
+    "Limit refund amount": { "main": [[{ "node": "Allow refund account", "type": "main", "index": 0 }], []] },
+    "Allow refund account": { "main": [[{ "node": "Issue refund", "type": "main", "index": 0 }], []] },
+    "Issue refund": {
+      "main": [
+        [],
+        [
+          { "node": "Notify refund failure", "type": "main", "index": 0 },
+          { "node": "Compensate transaction", "type": "main", "index": 0 }
+        ]
+      ]
+    }
+  },
+  "settings": { "executionTimeout": 120, "errorWorkflow": "global-error-handler" }
+}

examples/safe-support-agent.workflow.json

@@ -0,0 +1,112 @@
+{
+  "name": "Safe support agent",
+  "nodes": [
+    {
+      "id": "webhook",
+      "name": "Authenticated Webhook",
+      "type": "n8n-nodes-base.webhook",
+      "parameters": { "authentication": "headerAuth", "path": "support" },
+      "credentials": { "httpHeaderAuth": { "id": "credential-reference", "name": "Webhook Header Auth" } }
+    },
+    {
+      "id": "dedupe",
+      "name": "Claim idempotency event",
+      "type": "n8n-nodes-base.postgres",
+      "onError": "continueErrorOutput",
+      "parameters": {
+        "operation": "executeQuery",
+        "query": "INSERT INTO event_ledger (event_id) VALUES ($1) ON CONFLICT (event_id) DO NOTHING RETURNING event_id",
+        "queryReplacement": "={{ $json.event_id }}"
+      },
+      "credentials": { "postgres": { "id": "credential-reference", "name": "Event Ledger" } }
+    },
+    {
+      "id": "ledger-failure",
+      "name": "Ledger failure stop",
+      "type": "n8n-nodes-base.noOp",
+      "parameters": {}
+    },
+    {
+      "id": "enabled",
+      "name": "Agent enabled kill switch",
+      "type": "n8n-nodes-base.if",
+      "parameters": { "conditions": { "boolean": [{ "value1": "={{ $json.agent_enabled }}", "value2": true }] } }
+    },
+    {
+      "id": "agent",
+      "name": "AI Agent",
+      "type": "@n8n/n8n-nodes-langchain.agent",
+      "parameters": { "text": "={{ $json.body.message }}" }
+    },
+    {
+      "id": "model",
+      "name": "OpenAI Chat Model",
+      "type": "@n8n/n8n-nodes-langchain.lmChatOpenAi",
+      "parameters": { "modelName": "gpt-4.1-mini" },
+      "credentials": { "openAiApi": { "id": "credential-reference", "name": "OpenAI" } }
+    },
+    {
+      "id": "confidence",
+      "name": "Confidence gate",
+      "type": "n8n-nodes-base.if",
+      "parameters": { "conditions": { "number": [{ "value1": "={{ $json.confidence }}", "operation": "smaller", "value2": 0.7 }] } }
+    },
+    {
+      "id": "handoff",
+      "name": "Human handoff ticket",
+      "type": "n8n-nodes-base.slack",
+      "onError": "continueErrorOutput",
+      "parameters": { "channel": "support", "text": "={{ $json.summary }}" }
+    },
+    {
+      "id": "handoff-failure",
+      "name": "Handoff failure stop",
+      "type": "n8n-nodes-base.noOp",
+      "parameters": {}
+    },
+    {
+      "id": "failure-alert",
+      "name": "Operator error alert",
+      "type": "n8n-nodes-base.slack",
+      "onError": "continueErrorOutput",
+      "parameters": { "channel": "operations", "text": "Failure alert: {{ $json.error.message }}" }
+    },
+    {
+      "id": "response",
+      "name": "Respond to Webhook",
+      "type": "n8n-nodes-base.respondToWebhook",
+      "parameters": { "respondWith": "json", "responseBody": "={{ $json }}" }
+    }
+  ],
+  "connections": {
+    "Authenticated Webhook": { "main": [[{ "node": "Claim idempotency event", "type": "main", "index": 0 }]] },
+    "Claim idempotency event": {
+      "main": [
+        [{ "node": "Agent enabled kill switch", "type": "main", "index": 0 }],
+        [{ "node": "Operator error alert", "type": "main", "index": 0 }]
+      ]
+    },
+    "Agent enabled kill switch": { "main": [[{ "node": "AI Agent", "type": "main", "index": 0 }], []] },
+    "OpenAI Chat Model": { "ai_languageModel": [[{ "node": "AI Agent", "type": "ai_languageModel", "index": 0 }]] },
+    "AI Agent": { "main": [[{ "node": "Confidence gate", "type": "main", "index": 0 }]] },
+    "Confidence gate": {
+      "main": [
+        [{ "node": "Human handoff ticket", "type": "main", "index": 0 }],
+        [{ "node": "Respond to Webhook", "type": "main", "index": 0 }]
+      ]
+    },
+    "Human handoff ticket": {
+      "main": [
+        [],
+        [{ "node": "Operator error alert", "type": "main", "index": 0 }]
+      ]
+    },
+    "Operator error alert": {
+      "main": [
+        [],
+        [{ "node": "Handoff failure stop", "type": "main", "index": 0 }]
+      ]
+    }
+  },
+  "settings": { "executionTimeout": 120 }
+}

examples/sample-plan.json

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

examples/sample-workflow-export.json

@@ -1,57 +0,0 @@
-{
-  "name": "Vibeflow Demo - Support Escalation",
-  "active": false,
-  "meta": {
-    "source": "vibeflow-n8n",
-    "note": "Illustrative export skeleton for documentation and local experimentation."
-  },
-  "nodes": [
-    {
-      "id": "Webhook_1",
-      "name": "Incoming Ticket",
-      "type": "n8n-nodes-base.webhook",
-      "position": [260, 280],
-      "parameters": {
-        "path": "support-escalation-demo",
-        "httpMethod": "POST"
-      }
-    },
-    {
-      "id": "Set_1",
-      "name": "Normalize Payload",
-      "type": "n8n-nodes-base.set",
-      "position": [520, 280],
-      "parameters": {
-        "keepOnlySet": false,
-        "values": {
-          "string": [
-            {"name": "ticket_id", "value": "={{$json.id || ''}}"},
-            {"name": "priority", "value": "={{$json.priority || 'normal'}}"},
-            {"name": "summary", "value": "={{$json.summary || ''}}"}
-          ]
-        }
-      }
-    },
-    {
-      "id": "If_1",
-      "name": "Urgent?",
-      "type": "n8n-nodes-base.if",
-      "position": [780, 280],
-      "parameters": {
-        "conditions": {
-          "string": [
-            {"value1": "={{$json.priority}}", "operation": "equal", "value2": "high"}
-          ]
-        }
-      }
-    }
-  ],
-  "connections": {
-    "Incoming Ticket": {
-      "main": [[{"node": "Normalize Payload", "type": "main", "index": 0}]]
-    },
-    "Normalize Payload": {
-      "main": [[{"node": "Urgent?", "type": "main", "index": 0}]]
-    }
-  }
-}

examples/unsafe-refund.workflow.json

@@ -0,0 +1,29 @@
+{
+  "name": "Unsafe refund without outcome contract",
+  "nodes": [
+    {
+      "id": "webhook",
+      "name": "Public refund webhook",
+      "type": "n8n-nodes-base.webhook",
+      "parameters": { "authentication": "none", "path": "refund" }
+    },
+    {
+      "id": "refund",
+      "name": "Issue refund",
+      "type": "n8n-nodes-base.httpRequest",
+      "onError": "continueErrorOutput",
+      "parameters": { "method": "POST", "url": "https://payments.invalid/refund" }
+    },
+    {
+      "id": "swallow",
+      "name": "Swallow refund failure",
+      "type": "n8n-nodes-base.noOp",
+      "parameters": {}
+    }
+  ],
+  "connections": {
+    "Public refund webhook": { "main": [[{ "node": "Issue refund", "type": "main", "index": 0 }]] },
+    "Issue refund": { "main": [[], [{ "node": "Swallow refund failure", "type": "main", "index": 0 }]] }
+  },
+  "settings": {}
+}

examples/unsafe-support-agent.workflow.json

@@ -0,0 +1,43 @@
+{
+  "name": "Unsafe support agent",
+  "nodes": [
+    {
+      "id": "webhook",
+      "name": "Public Webhook",
+      "type": "n8n-nodes-base.webhook",
+      "parameters": { "path": "support" }
+    },
+    {
+      "id": "agent",
+      "name": "AI Agent",
+      "type": "@n8n/n8n-nodes-langchain.agent",
+      "parameters": { "text": "Respond to the customer" }
+    },
+    {
+      "id": "api",
+      "name": "Send response",
+      "type": "n8n-nodes-base.httpRequest",
+      "retryOnFail": true,
+      "maxTries": 10,
+      "waitBetweenTries": 0,
+      "parameters": {
+        "url": "https://api.example.com/messages",
+        "headerParameters": {
+          "parameters": [{ "name": "Authorization", "value": "Bearer vf_fake_0123456789abcdef" }]
+        }
+      }
+    },
+    {
+      "id": "shell",
+      "name": "Run Shell",
+      "type": "n8n-nodes-base.executeCommand",
+      "parameters": { "command": "echo done" }
+    }
+  ],
+  "connections": {
+    "Public Webhook": { "main": [[{ "node": "AI Agent", "type": "main", "index": 0 }]] },
+    "AI Agent": { "main": [[{ "node": "Send response", "type": "main", "index": 0 }]] },
+    "Send response": { "main": [[{ "node": "Run Shell", "type": "main", "index": 0 }]] }
+  },
+  "settings": {}
+}

package-lock.json

@@ -0,0 +1,19 @@
+{
+  "name": "vibeflow-n8n",
+  "version": "0.9.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "vibeflow-n8n",
+      "version": "0.9.0",
+      "license": "MIT",
+      "bin": {
+        "vibeflow": "bin/vibeflow.mjs"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    }
+  }
+}

package.json

@@ -0,0 +1,38 @@
+{
+  "name": "vibeflow-n8n",
+  "version": "0.9.0",
+  "description": "Safety and contract checks for AI-generated n8n workflows",
+  "type": "module",
+  "bin": {
+    "vibeflow": "./bin/vibeflow.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "schemas",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "check": "node ./bin/vibeflow.mjs check ./examples/safe-support-agent.workflow.json",
+    "test": "node --test",
+    "verify": "npm test && npm run check && npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/domfelipe/vibeflow-n8n.git"
+  },
+  "keywords": [
+    "n8n",
+    "workflow",
+    "security",
+    "lint",
+    "ai-agents",
+    "codex"
+  ],
+  "author": "Felipe Domingues",
+  "license": "MIT"
+}

plugins/vibeflow/.codex-plugin/plugin.json

@@ -0,0 +1,28 @@
+{
+  "name": "vibeflow",
+  "version": "0.9.0",
+  "description": "Audit and repair AI-generated n8n workflows before production",
+  "author": {
+    "name": "Felipe Domingues",
+    "url": "https://github.com/domfelipe"
+  },
+  "homepage": "https://github.com/domfelipe/vibeflow-n8n",
+  "repository": "https://github.com/domfelipe/vibeflow-n8n",
+  "license": "MIT",
+  "keywords": ["n8n", "workflow", "security", "quality", "ai-agents"],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Vibeflow",
+    "shortDescription": "Preflight checks for real-world n8n outcomes",
+    "longDescription": "Run deterministic safety and outcome-contract checks on n8n workflow exports, explain findings, and repair blocking issues before deployment.",
+    "developerName": "Felipe Domingues",
+    "category": "Productivity",
+    "capabilities": ["Read", "Write"],
+    "websiteURL": "https://github.com/domfelipe/vibeflow-n8n",
+    "defaultPrompt": [
+      "Audit this n8n workflow before production.",
+      "Fix the blocking Vibeflow findings.",
+      "Explain the safety risks in this workflow."
+    ]
+  }
+}

plugins/vibeflow/skills/vibeflow/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: vibeflow
+description: Audit and repair exported n8n workflow JSON with deterministic safety and outcome-contract checks. Use when reviewing AI-generated or customer-facing n8n workflows before deployment, investigating Vibeflow VF000-VF013 findings, adding kill switches or human handoffs, checking secrets, retries, webhook exposure, money or customer side effects, recovery paths, or preparing workflow changes for CI and pull requests.
+---
+
+# Vibeflow
+
+Use the CLI as the source of truth. Do not infer that a workflow is safe from its README, prompt, or visual layout.
+
+## Workflow
+
+1. Locate the exported workflow JSON. Never inspect or mutate a live production workflow unless the user explicitly requests it.
+2. Run Vibeflow from a repository checkout:
+
+   ```bash
+   node bin/vibeflow.mjs check path/to/workflow.json
+   ```
+
+   For a released version without a checkout:
+
+   ```bash
+   npx --yes github:domfelipe/vibeflow-n8n#v0.9.0 check path/to/workflow.json
+   ```
+
+3. Read [references/policies.md](references/policies.md) when interpreting or repairing a finding.
+4. Fix errors before warnings. Preserve credential references, expressions, node IDs, and unrelated workflow behavior.
+5. Re-run the check after every repair. Stop only when blocking findings are gone or explicitly waived in `.vibeflow.json` with a documented reason.
+6. Report changed nodes, remaining warnings, and what still needs runtime validation in n8n.
+
+## Safety boundaries
+
+- Never copy literal credentials into a workflow to silence `VF001`.
+- Never disable `VF006` for customer-facing agents without explicit user approval; an off switch must block inference and all AI responses.
+- Treat static analysis as a preflight, not proof of runtime correctness.
+- Treat `VF010` and `VF011` as outcome risks, even when the underlying node type is ordinary HTTP, database, or messaging.
+- Do not claim an outcome contract enforces runtime authorization, limits, audit durability, or recovery; verify those separately in the executing system.
+- Prefer fixing a shared upstream node over duplicating guards across branches.
+- Keep fixes local to the exported workflow until the user authorizes deployment.
+
+## Output
+
+Return the CLI result, the smallest safe repair, and any unresolved runtime check. Use SARIF for GitHub code scanning and JSON for automation.

plugins/vibeflow/skills/vibeflow/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Vibeflow"
+  short_description: "Safety checks for AI-generated n8n workflows"
+  default_prompt: "Use $vibeflow to audit this n8n workflow and fix blocking findings."

plugins/vibeflow/skills/vibeflow/references/policies.md

@@ -0,0 +1,22 @@
+# Vibeflow policy reference
+
+| ID | Default | Meaning | Minimum repair |
+|---|---|---|---|
+| VF000 | error | Invalid workflow export | Export valid n8n JSON with a `nodes` array. |
+| VF001 | error | Literal secret in parameters | Use n8n credentials, a vault, or an environment expression. |
+| VF002 | error | Host-level node | Remove it or explicitly approve the node type in policy. |
+| VF003 | warning | Webhook without supported auth and a credential reference | Add header/basic/JWT auth backed by an n8n credential. |
+| VF004 | warning | External action without a connected failure path | Connect a `continueErrorOutput` branch or configure `settings.errorWorkflow`. |
+| VF005 | warning | Inbound side effects without an atomic deduplication gate | Use a claim that emits no item for duplicates, such as `INSERT ... ON CONFLICT DO NOTHING ... RETURNING`, on every path. |
+| VF006 | error | An AI entry path bypasses the structural kill switch | Put a real IF/Switch/Code gate that reads agent status on every entry path. |
+| VF007 | warning | AI Agent without a reachable external handoff action | Add a downstream ticket, chat, email, or equivalent human escalation action. |
+| VF008 | warning | Missing or excessive execution timeout | Set the workflow timeout between 1 and 3600 seconds. |
+| VF009 | warning | Unsafe retry policy | Add idempotency, bound attempts, and configure backoff. |
+| VF010 | error | Money or privileged action lacks verified policy evidence | Declare the action and connect dominating approval, durable audit, atomic idempotency, limits where applicable, failure notification, and recovery. |
+| VF011 | warning | Customer communication or destructive write lacks an outcome contract | Declare the impact and connect durable audit, atomic idempotency, failure notification, and recovery evidence. |
+| VF012 | warning | Connected error path terminates silently | Route the action's error output to a recognized operator alert, ticket, incident, or escalation node. |
+| VF013 | warning | High-impact write has no recovery contract | Declare compensation, rollback, or replay and reference the implementing node. |
+
+Configuration changes severity or domain vocabulary; it does not prove the suppressed risk is safe. Keep waivers visible in `.vibeflow.json` and explain them in the pull request.
+
+Outcome contracts are static evidence. Runtime systems must still authorize approvers, enforce limits and counterparties server-side, create durable audit entries before acting, deduplicate atomically, and test recovery behavior.

recipes/ai-lead-enrichment.md

@@ -1,48 +0,0 @@
-# Recipe: AI Lead Enrichment
-
-## Goal
-
-Capture a new inbound lead, enrich the company context, generate a short structured summary, score the lead using simple rules, and write the result to the CRM.
-
-## Typical trigger
-
-- new CRM lead
-- form submission
-- webhook from a landing page
-
-## Systems involved
-
-- CRM such as HubSpot or Pipedrive
-- enrichment source such as Clearbit-like data or internal lookup
-- optional LLM step for summarization
-- Slack for alerts
-
-## Core steps
-
-1. Receive the lead payload.
-2. Normalize fields such as company name, email domain, and source.
-3. Query enrichment data.
-4. Generate a concise structured summary.
-5. Apply a scoring rule based on company size, geography, and source.
-6. Update the CRM record.
-7. Notify Slack if the lead crosses a threshold.
-
-## Important assumptions
-
-- scoring starts with safe defaults
-- enrichment can fail without blocking the whole workflow
-- missing optional fields should not break CRM updates
-
-## What makes this recipe good for demos
-
-- shows practical AI usage
-- stays grounded in business logic
-- produces an output people immediately understand
-
-## Validation checklist
-
-- lead payload is parsed correctly
-- enrichment failures are captured clearly
-- summary format is stable
-- score thresholds are visible and editable
-- CRM update succeeds even when optional data is missing

recipes/customer-support-escalation.md

@@ -1,35 +0,0 @@
-# Recipe: Customer Support Escalation
-
-## Goal
-
-Create an n8n workflow that watches a support inbox or helpdesk webhook, detects priority signals, enriches the ticket context, and escalates high-risk items to Slack with a clear summary.
-
-## Why it demos well
-
-- obvious business value
-- clear trigger and escalation outcome
-- easy to explain in less than two minutes
-- one branch can demonstrate prioritization logic
-
-## Suggested steps
-
-1. Trigger from webhook or helpdesk event
-2. Normalize ticket payload
-3. Score urgency using rules or an LLM step
-4. Route high-priority items to Slack
-5. Log normal-priority items to a sheet or database
-6. Add error notifications
-
-## Critical questions
-
-- What tool sends the ticket event?
-- What counts as urgent?
-- Who should receive escalations?
-- Should every item be logged, or only urgent ones?
-
-## Safe defaults
-
-- urgency based on keywords, SLA breach flag, and VIP marker
-- Slack notification for high priority only
-- spreadsheet log for all processed tickets
-- retry once before failure alert

recipes/hubspot-to-slack-qualification.md

@@ -1,34 +0,0 @@
-# Recipe: HubSpot to Slack Qualification
-
-## Goal
-
-Create an n8n workflow that listens for new or updated HubSpot leads, evaluates qualification rules, and sends only promising leads to Slack with a concise summary.
-
-## Why it demos well
-
-- popular stack
-- simple trigger, filter, and notification pattern
-- easy to narrate as a sales ops use case
-
-## Suggested steps
-
-1. Trigger on lead created or updated
-2. Map company, role, source, and score fields
-3. Apply qualification rules
-4. Send qualified leads to Slack
-5. Log non-qualified leads for later review
-6. Emit failure alerts when processing breaks
-
-## Critical questions
-
-- Which HubSpot event should trigger the flow?
-- What rules define a qualified lead?
-- What Slack channel should receive alerts?
-- Should the workflow update HubSpot properties too?
-
-## Safe defaults
-
-- qualify by score threshold and role/company fit
-- send concise Slack message with source and score
-- log rejected leads to a review table
-- leave CRM write-back optional

recipes/invoice-reminder.md

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

recipes/lead-triage.md

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

recipes/slack-to-notion-triage.md

@@ -1,47 +0,0 @@
-# Recipe: Slack to Notion Triage
-
-## Goal
-
-Capture important Slack mentions, classify them, create a Notion item for tracking, and route urgent cases to an escalation channel.
-
-## Typical trigger
-
-- mention of a bot in Slack
-- reactions on flagged messages
-- specific channel messages matching a pattern
-
-## Systems involved
-
-- Slack
-- Notion
-- optional AI classification step
-- optional email or secondary Slack alert
-
-## Core steps
-
-1. Listen for the configured Slack trigger.
-2. Normalize message text, author, channel, and timestamp.
-3. Classify urgency and category.
-4. Create a Notion page or database item.
-5. Route urgent messages to an escalation destination.
-6. Write a final status field for reporting.
-
-## Important assumptions
-
-- urgency rules should be explicit and editable
-- Notion database schema is known or mapped in advance
-- Slack formatting should be simplified before storage
-
-## What makes this recipe good for demos
-
-- looks modern and relatable
-- easy to understand visually
-- strong before-and-after story from message to tracked item
-
-## Validation checklist
-
-- trigger fires only for intended messages
-- urgency logic is deterministic
-- Notion fields are mapped correctly
-- urgent path and normal path both succeed
-- duplicate handling is defined

recipes/support-triage.md

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

schemas/plan.schema.json

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