bps-kit 1.2.2 → 1.3.1

package/.bps-kit.json

@@ -1,6 +1,6 @@
 {
-  "mode": "extra",
-  "vscode": true,
-  "version": "1.2.1",
-  "installedAt": "2026-03-09T22:52:06.758Z"
+  "mode": "normal",
+  "vscode": false,
+  "version": "1.3.0",
+  "installedAt": "2026-03-11T00:38:59.884Z"
 }

package/README.md

@@ -104,6 +104,9 @@ O **BPS Kit** deve sua fundação brilhante e seu mar enciclopédico de regras a
 3. **[stitch-skills (by google-labs-code)](https://github.com/google-labs-code/stitch-skills)**  
    O cérebro visual e criativo do BPS Kit. Responsável pelas skills de design cinematográfico (`design-md`, `enhance-prompt`, `react-components`, `remotion`, `stitch-loop`) que elevam a qualidade de componentes React e landing pages a um nível de pixel-perfect e alta fidelidade que vai muito além do padrão genérico de IA.
 
+4. **[n8n-skills + n8n-mcp (by czlonkowski)](https://github.com/czlonkowski/n8n-skills)**  
+   A camada de inteligência para automação n8n do BPS Kit. As 7 skills especializadas (`n8n-mcp-tools-expert`, `n8n-workflow-patterns`, `n8n-expression-syntax`, `n8n-node-configuration`, `n8n-validation-expert`, `n8n-code-javascript`, `n8n-code-python`) e o servidor MCP [`n8n-mcp`](https://github.com/czlonkowski/n8n-mcp) que provê acesso a 1.084 nós e 2.700+ templates de workflow diretamente do IDE.
+
 A engenharia inteira do **BPS Kit** serve massivamente para unificar essas três titânicas inteligências em um fluxo só — através da magia do Auto-Routing isolacionista por Glob e do Vaulting Comprimido — ultrapassando enfim as limitações brutais da context-window. Sem a colaboração fundadora de vudovn, sickn33 e google-labs-code, essa maravilha não existiria.
 
 ---

package/implementation_plan.md.resolved

@@ -0,0 +1,37 @@
+# Integrating n8n-mcp and n8n-skills into BPS Kit
+
+This plan outlines how to integrate the n8n ecosystem into the BPS Kit. The goal is to provide end-users with a robust way to create and manage n8n automations directly from their IDE using an MCP server and specialized skills.
+
+## Proposed Changes
+
+### 1. New Agent
+Create a specialized agent dedicated to workflow automation, interacting with n8n and orchestrating webhook-based capabilities.
+#### [NEW] .agents/agents/automation-specialist.md
+
+### 2. Vault Skills
+Copy the 7 original Claude Code skills from `czlonkowski/n8n-skills` into BPS Kit vault skills without changing their core content. We will format them as [SKILL.md](file:///f:/VSCode/bpskit/bps-kit/.agents/skills/plan-writing/SKILL.md) to fit the BPS Kit architecture.
+#### [NEW] .agents/vault/n8n-expression-syntax/SKILL.md
+#### [NEW] .agents/vault/n8n-mcp-tools-expert/SKILL.md
+#### [NEW] .agents/vault/n8n-workflow-patterns/SKILL.md
+#### [NEW] .agents/vault/n8n-validation-expert/SKILL.md
+#### [NEW] .agents/vault/n8n-node-configuration/SKILL.md
+#### [NEW] .agents/vault/n8n-code-javascript/SKILL.md
+#### [NEW] .agents/vault/n8n-code-python/SKILL.md
+
+### 3. Workflow (Slash Command)
+Create an `/automate` slash command that end-users can invoke. This workflow will guide the user through using the `n8n-mcp` tools, activating the `automation-specialist` agent, and leveraging the vault skills to build their own n8n automations.
+#### [NEW] .agents/workflows/automate.md
+
+### 4. Index, Architecture, Readme, and Routing Updates
+Add the new n8n vault skills, the agent, and the workflow to the manifest files. Give appropriate credits to the original creators in the README. Update `GEMINI.md` to ensure the routing system automatically redirects automation/n8n requests to the `automation-specialist` agent and its skills, even when the `/automate` workflow isn't explicitly called.
+#### [MODIFY] .agents/VAULT_INDEX.md
+#### [MODIFY] .agents/ARCHITECTURE.md
+#### [MODIFY] README.md
+#### [MODIFY] .agents/rules/GEMINI.md
+
+## Verification Plan
+### Automated Tests
+- Run `python .agents/scripts/checklist.py .` to ensure linting and basic validation pass.
+### Manual Verification
+- Review the content of the adapted skills to ensure they follow BPS Kit markdown and structure conventions.
+- Read through the `/automate` workflow to guarantee it's correctly aimed at end-users wanting to build automations in their projects.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bps-kit",
-  "version": "1.2.2",
+  "version": "1.3.1",
   "description": "BPS Kit - The Ultimate Antigravity Brain",
   "bin": {
     "bps-kit": "./bin/cli.js"
@@ -26,4 +26,4 @@
     "fs-extra": "^11.2.0",
     "ora": "^5.4.1"
   }
-}
+}

package/templates/agents-template/ARCHITECTURE.md

@@ -8,10 +8,10 @@
 
 BPS Kit is a modular system consisting of:
 
-- **20 Specialist Agents** — Role-based AI personas
+- **22 Specialist Agents** — Role-based AI personas
 - **Active Skills** — Domain-specific knowledge modules (varies by profile)
 - **1200+ Vault Skills** — Extended skill library discoverable via index
-- **12 Workflows** — Slash command procedures
+- **15 Workflows** — Slash command procedures
 - **2 Master Scripts** — Validation & verification
 
 ---
@@ -24,16 +24,16 @@ BPS Kit is a modular system consisting of:
 ├── VAULT_INDEX.md           # Vault skill discovery index
 ├── rules/
 │   └── GEMINI.md            # Master rule file (always loaded)
-├── agents/                  # 20 Specialist Agents
+├── agents/                  # 22 Specialist Agents
 ├── skills/                  # Active Skills (profile-dependent)
 ├── vault/                   # 1200+ Vault Skills
-├── workflows/               # 12 Slash Commands
+├── workflows/               # 15 Slash Commands
 └── scripts/                 # Master Validation Scripts
 ```
 
 ---
 
-## 🤖 Agents (20)
+## 🤖 Agents (22)
 
 Specialist AI personas for different domains.
 
@@ -60,6 +60,7 @@ Specialist AI personas for different domains.
 | `code-archaeologist`     | Legacy code, refactoring   | clean-code                                               |
 | `explorer-agent`         | Codebase analysis          | —                                                        |
 | `site-builder`           | Landing pages, websites    | frontend-design, scroll-experience, enhance-prompt       |
+| `automation-specialist`  | n8n workflow automation    | n8n-mcp-tools-expert, n8n-workflow-patterns, n8n-expression-syntax |
 
 ---
 
@@ -118,6 +119,13 @@ Skills availability depends on the installed profile (`basic`, `normal`, or `ext
 | `test-driven-development` | TDD workflow                   |
 | `testing-patterns`        | Jest, Vitest, strategies       |
 | `vercel-deployment`       | Vercel deploy workflows        |
+| `n8n-mcp-tools-expert`    | n8n MCP tool selection & usage |
+| `n8n-workflow-patterns`   | n8n architectural patterns     |
+| `n8n-expression-syntax`   | n8n expression `{{$json.*}}`   |
+| `n8n-node-configuration`  | n8n node operation config      |
+| `n8n-validation-expert`   | n8n validation error fixing    |
+| `n8n-code-javascript`     | n8n Code node (JavaScript)     |
+| `n8n-code-python`         | n8n Code node (Python)         |
 
 ### Extra Profile (adds ~27 more skills)
 
@@ -153,13 +161,14 @@ Skills availability depends on the installed profile (`basic`, `normal`, or `ext
 
 ---
 
-## 🔄 Workflows (12)
+## 🔄 Workflows (15)
 
 Slash command procedures. Invoke with `/command`.
 
 | Command          | Description                     |
 | ---------------- | ------------------------------- |
 | `/brainstorm`    | Socratic discovery              |
+| `/build-site`    | Full website creation workflow  |
 | `/create`        | Create new features             |
 | `/debug`         | Debug issues                    |
 | `/deploy`        | Deploy application              |
@@ -167,10 +176,12 @@ Slash command procedures. Invoke with `/command`.
 | `/orchestrate`   | Multi-agent coordination        |
 | `/plan`          | Task breakdown                  |
 | `/preview`       | Preview changes                 |
+| `/recall`        | Re-anchor AI to rules           |
 | `/setup-brain`   | Initialize agent memory/context |
 | `/status`        | Check project status            |
 | `/test`          | Run tests                       |
 | `/ui-ux-pro-max` | Full UI/UX design workflow      |
+| `/automate`      | n8n workflow automation builder |
 
 ---
 
@@ -212,12 +223,12 @@ Scripts are embedded within skills at `.agents/skills/<skill>/scripts/`:
 
 | Metric              | Value                         |
 | ------------------- | ----------------------------- |
-| **Total Agents**    | 20 (+1 site-builder)          |
+| **Total Agents**    | 22                            |
 | **Basic Skills**    | 11                            |
-| **Normal Skills**   | ~42                           |
+| **Normal Skills**   | ~49                           |
 | **Extra Skills**    | ~69                           |
 | **Vault Skills**    | 1200+                         |
-| **Total Workflows** | 12                            |
+| **Total Workflows** | 15                            |
 
 ---
 
@@ -234,3 +245,4 @@ Scripts are embedded within skills at `.agents/skills/<skill>/scripts/`:
 | Debug    | `debugger`            | systematic-debugging                  |
 | Plan     | `project-planner`     | brainstorming, plan-writing           |
 | Deploy   | `devops-engineer`     | docker-expert, vercel-deployment      |
+| Automate | `automation-specialist` | n8n-mcp-tools-expert, n8n-workflow-patterns |

package/templates/agents-template/agents/automation-specialist.md

@@ -0,0 +1,157 @@
+---
+name: automation-specialist
+description: Expert n8n workflow automation architect. Use for building, editing, and validating n8n workflows via MCP tools, designing webhook-based integrations, creating automation patterns, and configuring n8n nodes. Triggers on n8n, automation, webhook, workflow, automate, integrate, trigger, mcp.
+tools: Read, Grep, Glob, Bash, Edit, Write, mcp
+model: inherit
+skills: clean-code, plan-writing, n8n-mcp-tools-expert, n8n-workflow-patterns, n8n-expression-syntax, n8n-node-configuration, n8n-validation-expert, n8n-code-javascript, n8n-code-python
+---
+
+# Automation Specialist
+
+You are an expert n8n workflow automation architect. You design, build, and validate workflows with precision using the n8n-mcp MCP tools.
+
+## Your Philosophy
+
+**Automation is architecture.** Every workflow you build is a system — it has triggers, data flows, error paths, and deployment requirements. You build automation that is reliable, observable, and maintainable.
+
+## Your Mindset
+
+- **Templates first**: 2,700+ real workflows exist — always check before building from scratch
+- **Validate iteratively**: validate_node → fix → validate again (expect 2-3 cycles)
+- **Parallel execution**: Run independent tool calls simultaneously, not sequentially
+- **Silent execution**: Execute tools, THEN respond — never narrate steps in real time
+- **Progressive disclosure**: Start with `detail: "standard"`, go to `detail: "full"` only when needed
+- **Never trust defaults**: Explicitly configure all parameters that control node behavior
+
+---
+
+## 🛑 CRITICAL: CLARIFY BEFORE BUILDING (MANDATORY)
+
+**When the user's automation request is vague, DO NOT assume. ASK FIRST.**
+
+### You MUST ask before proceeding if these are unspecified:
+
+| Aspect | Ask |
+|--------|-----|
+| **Trigger** | "Webhook (instant) or Schedule (periodic)?" |
+| **Input** | "What data comes in? From where?" |
+| **Output** | "What action should happen? Where does data go?" |
+| **Credentials** | "Which services need authentication?" |
+| **Error handling** | "What happens on failure? Notify someone?" |
+| **n8n instance** | "Local or cloud? API connected?" |
+
+---
+
+## MCP Tools Workflow
+
+When the n8n-mcp MCP server is available, follow this process:
+
+### Phase 1: Template Discovery (ALWAYS FIRST)
+```
+search_templates({query: "user's use case"})
+→ If good match found → get_template(id, {mode: "full"}) → n8n_deploy_template()
+→ If no match → proceed to Node Discovery
+```
+
+### Phase 2: Node Discovery
+```
+search_nodes({query: "keyword"}) in parallel for all required nodes
+→ get_node({nodeType, includeExamples: true}) for each
+```
+
+### Phase 3: Show Architecture
+Present the workflow structure to the user for approval **before building**.
+```
+Trigger → [Node A] → [Node B] → Output
+                  └→ [Error Handler]
+```
+
+### Phase 4: Build
+```
+n8n_create_workflow({name, nodes, connections})
+→ n8n_update_partial_workflow() iteratively (avg 56s between edits)
+```
+
+### Phase 5: Validate
+```
+validate_node({nodeType, config, profile: "runtime"}) for each node
+→ validate_workflow({id})
+→ Fix ALL errors before activation
+```
+
+### Phase 6: Activate
+```
+n8n_update_partial_workflow({operations: [{type: "activateWorkflow"}]})
+```
+
+---
+
+## nodeType Format Rules
+
+| Context | Format | Example |
+|---------|--------|---------|
+| search_nodes / get_node / validate_node | `nodes-base.*` | `nodes-base.slack` |
+| n8n_create_workflow / n8n_update_partial_workflow | `n8n-nodes-base.*` | `n8n-nodes-base.slack` |
+| LangChain nodes | `@n8n/n8n-nodes-langchain.*` | `@n8n/n8n-nodes-langchain.agent` |
+
+---
+
+## Validation Loop (Expected)
+
+```
+1. Configure → 2. validate_node → 3. Fix (58s avg) → 4. validate_node again
+                   ↑                                       |
+                   └───────────── repeat 2-3x ────────────┘
+```
+
+This is **normal behavior** — not an error. The iterative validation loop is built into n8n development.
+
+---
+
+## Expression Syntax (Critical)
+
+```javascript
+// In workflow fields (not Code nodes)
+✅ {{$json.field}}
+✅ {{$json.body.field}}  // Webhook data is ALWAYS under .body!
+✅ {{$node["Node Name"].json.field}}
+
+// In Code nodes (JavaScript)
+✅ $json.field          // No {{ }} needed
+✅ $input.all()
+✅ $input.first().json.body.field  // Webhook data
+```
+
+---
+
+## When n8n-mcp is NOT Connected
+
+If MCP tools are unavailable:
+
+1. Guide the user to install n8n-mcp: `npm install -g n8n-mcp`
+2. Point them to the `/automate` workflow for setup instructions
+3. Help design the workflow architecture as JSON
+4. Provide the workflow structure they can import manually into n8n
+
+---
+
+## ⚠️ Safety Rules (Mandatory)
+
+- **NEVER edit production workflows directly with AI**
+- Always work on a **copy** first
+- Export backups before significant changes
+- Test in development before activating in production
+
+---
+
+## Skill Usage Guide
+
+| Task | Use Skill |
+|------|-----------|
+| Finding / searching nodes | `n8n-mcp-tools-expert` |
+| Designing workflow architecture | `n8n-workflow-patterns` |
+| Writing expressions `{{$json.*}}` | `n8n-expression-syntax` |
+| Configuring node operations | `n8n-node-configuration` |
+| Fixing validation errors | `n8n-validation-expert` |
+| Writing Code node (JS) | `n8n-code-javascript` |
+| Writing Code node (Python) | `n8n-code-python` |

package/templates/agents-template/rules/GEMINI.md

@@ -97,6 +97,7 @@ After invoking any skill, explicitly say: '📖 Using skill: [skill-name]' befor
 | **API/backend** | api-patterns (N) + backend-dev-guidelines (N) |
 | **Git/push** | verification-before-completion → git-pushing |
 | **AI/LLM/RAG** | rag-engineer (N) + llm-app-patterns (N) + prompt-engineer (N) |
+| **n8n / webhook / automation** | n8n-mcp-tools-expert (N) + n8n-workflow-patterns (N) |
 | **Multi-step plan** | plan-writing → executing-plans. Independent: dispatching-parallel-agents (N) |
 | **Other domain** | Search VAULT_INDEX.md → read skill from vault |
 
@@ -218,22 +219,13 @@ Before coding, answer: (1) Goal of agent/skill? (2) Principles to apply? (3) How
 **Priority Execution Order:**
 1. **Security** → 2. **Lint** → 3. **Schema** → 4. **Tests** → 5. **SEO** → 6. **Lighthouse/E2E**
 
-**Available Scripts:**
-
-| Script | Skill | When |
-|---|---|---|
-| `security_scan.py` | vulnerability-scanner | Always on deploy |
-| `lint_runner.py` | lint-and-validate | Every code change |
-| `seo_checker.py` | seo-fundamentals | After page change |
-| `lighthouse_audit.py` | performance-profiling | Before deploy |
-
 > 🔴 **Agents & Skills can invoke ANY script** via `python .agents/skills/<skill>/scripts/<script>.py`
 
 **Rules:**
 - **Completion:** A task is NOT finished until `checklist.py` returns success.
 - **Reporting:** If it fails, fix the **Critical** blockers first (Security/Lint).
 
-### 🎭 Gemini Mode Mapping
+### 🎡 Gemini Mode Mapping
 | Mode | Agent | Behavior |
 |---|---|---|
 | **plan** | `project-planner` | 4-phase. NO CODE before Phase 4. |

package/templates/agents-template/workflows/automate.md

@@ -0,0 +1,153 @@
+---
+description: Build n8n workflow automations with AI assistance. Activates the automation-specialist agent and n8n vault skills. Use when creating, editing, or managing n8n workflows, webhooks, or integrations.
+---
+
+# /automate — n8n Workflow Builder
+
+$ARGUMENTS
+
+---
+
+## Purpose
+
+This workflow activates **automation mode**: the `automation-specialist` agent and all n8n skills are loaded to help you design, build, and deploy n8n workflows with full AI assistance.
+
+---
+
+## 🚀 First Time? Setup the n8n-mcp Server
+
+Before building workflows, the n8n-mcp MCP server must be connected. Choose your setup:
+
+---
+
+### Option A: VS Code + GitHub Copilot (`--vscode` mode)
+
+**Step 1** — Create `.vscode/mcp.json` in your project:
+
+```json
+{
+  "inputs": [
+    {
+      "type": "promptString",
+      "id": "n8n-mcp-token",
+      "description": "Your n8n-MCP AUTH_TOKEN",
+      "password": true
+    }
+  ],
+  "servers": {
+    "n8n-mcp": {
+      "type": "http",
+      "url": "https://n8n.your.production.url/mcp",
+      "headers": {
+        "Authorization": "Bearer ${input:n8n-mcp-token}"
+      }
+    }
+  }
+}
+```
+
+> 💡 Replace `https://n8n.your.production.url` with your n8n instance URL.
+> For local development: use `npx n8n-mcp` in stdio mode (see Option B).
+
+---
+
+### Option B: Antigravity / Standard Mode (local stdio)
+
+**Step 1** — Install n8n-mcp globally:
+```bash
+npm install -g n8n-mcp
+```
+
+**Step 2** — Add to your MCP config (`~/.gemini/antigravity/mcp_config.json`):
+```json
+{
+  "mcpServers": {
+    "n8n-mcp": {
+      "command": "node",
+      "args": [
+        "C:\\Users\\<USER_NAME>\\AppData\\Roaming\\npm\\node_modules\\n8n-mcp\\dist\\mcp\\index.js"
+      ],
+      "env": {
+        "MCP_MODE": "stdio",
+        "LOG_LEVEL": "error",
+        "DISABLE_CONSOLE_OUTPUT": "true",
+        "N8N_API_URL": "http://localhost:5678",
+        "N8N_BASE_URL": "http://localhost:5678",
+        "N8N_API_KEY": "<your-n8n-api-key>"
+      }
+    }
+  }
+}
+```
+
+> 💡 Get your n8n API key: n8n UI → Settings → n8n API → Create API key.
+> Replace `<USER_NAME>` with your Windows username.
+
+**Step 3** — Reload MCP servers in your IDE and confirm `n8n-mcp` appears as connected.
+
+---
+
+### Option C: Hosted Service (No Setup)
+
+Use [dashboard.n8n-mcp.com](https://dashboard.n8n-mcp.com) for instant access:
+- Free tier: 100 tool calls/day
+- No installation required
+- Use the HTTP URL in Option A's `.vscode/mcp.json`
+
+---
+
+## ⚠️ Safety Warning
+
+> **NEVER edit production workflows directly with AI!**
+> Always work on a **copy** first. Export backups before changes. Test in dev before production.
+
+---
+
+## Building Your Automation
+
+Once n8n-mcp is connected, describe what you want to automate:
+
+### Examples
+
+```
+"I want to receive a webhook from Stripe and send a Slack notification"
+"Every morning, fetch my GitHub issues and email me a summary"
+"Sync new Postgres records to a Google Sheet every 15 minutes"
+"Build an AI chatbot that can query my database and respond via webhook"
+```
+
+---
+
+## What Happens Next
+
+The `automation-specialist` agent will:
+
+1. **Clarify** your trigger, data flow, and outputs (if unclear)
+2. **Search templates** — check 2,700+ real workflows before building from scratch
+3. **Present architecture** — show you the workflow structure for approval
+4. **Build iteratively** — create and refine with MCP tools
+5. **Validate everything** — check each node before activating
+6. **Activate** — deploy to your n8n instance
+
+---
+
+## Active Skills in This Mode
+
+| Skill | Purpose |
+|-------|---------|
+| `n8n-mcp-tools-expert` | MCP tool selection, nodeType formats, workflow management |
+| `n8n-workflow-patterns` | Architectural patterns: webhook, API, database, AI agent, scheduled |
+| `n8n-expression-syntax` | Correct `{{$json.*}}` syntax, webhook data access |
+| `n8n-node-configuration` | Operation-specific field requirements |
+| `n8n-validation-expert` | Interpret and fix validation errors |
+| `n8n-code-javascript` | Code nodes in JavaScript |
+| `n8n-code-python` | Code nodes in Python |
+
+---
+
+## Useful Resources
+
+- [n8n-mcp on npm](https://www.npmjs.com/package/n8n-mcp)
+- [n8n-mcp GitHub](https://github.com/czlonkowski/n8n-mcp)
+- [n8n Template Library](https://n8n.io/workflows/)
+- [n8n Documentation](https://docs.n8n.io/)