From 02d07ed25450d4a3a431daafe296eeaca90a4cf6 Mon Sep 17 00:00:00 2001 From: mrsaifullah52 Date: Mon, 17 Nov 2025 14:22:44 +0500 Subject: [PATCH] feat(n8n-expert): add create-workflow workflow - Add workflow.yaml with configuration and variables - Add instructions.md with full elicitation and Context7 integration - Add checklist.md for validation - Supports building n8n workflows from scratch with smart elicitation --- .../n8n-expert/create-workflow/checklist.md | 74 ++++ .../create-workflow/instructions.md | 350 ++++++++++++++++++ .../n8n-expert/create-workflow/workflow.yaml | 31 ++ 3 files changed, 455 insertions(+) create mode 100644 src/modules/bmm/workflows/n8n-expert/create-workflow/checklist.md create mode 100644 src/modules/bmm/workflows/n8n-expert/create-workflow/instructions.md create mode 100644 src/modules/bmm/workflows/n8n-expert/create-workflow/workflow.yaml diff --git a/src/modules/bmm/workflows/n8n-expert/create-workflow/checklist.md b/src/modules/bmm/workflows/n8n-expert/create-workflow/checklist.md new file mode 100644 index 00000000..dcd96098 --- /dev/null +++ b/src/modules/bmm/workflows/n8n-expert/create-workflow/checklist.md @@ -0,0 +1,74 @@ +# Create n8n Workflow - Validation Checklist + +## Workflow Structure + +- [ ] Workflow has a valid name +- [ ] Workflow contains at least one trigger node +- [ ] All nodes have unique IDs +- [ ] All nodes have unique names +- [ ] Workflow JSON is valid and parseable + +## Node Configuration + +- [ ] Trigger node is properly configured +- [ ] All action nodes have required parameters set +- [ ] Node types are valid n8n node types +- [ ] Node positions are set and don't overlap +- [ ] TypeVersion is set for all nodes (usually 1) + +## Connections + +- [ ] All nodes are connected (no orphaned nodes except trigger) +- [ ] All connections reference existing node names +- [ ] Connection types are set correctly (usually "main") +- [ ] Connection indices are correct (0 for default, 0/1 for IF nodes) +- [ ] No circular dependencies (unless intentional loops) + +## Error Handling + +- [ ] Error handling strategy matches requirements +- [ ] Critical nodes have retry logic if needed +- [ ] continueOnFail is set appropriately +- [ ] maxTries and waitBetweenTries are configured if retries enabled + +## Data Flow + +- [ ] Data transformations are properly configured +- [ ] Set nodes have correct value mappings +- [ ] Code nodes have valid JavaScript/Python code +- [ ] Expressions use correct n8n syntax (={{ }}) + +## Integrations + +- [ ] All required integrations are included +- [ ] Credential placeholders are set for authenticated services +- [ ] API endpoints and methods are correct +- [ ] Request/response formats are properly configured + +## Best Practices + +- [ ] Workflow follows n8n naming conventions +- [ ] Nodes are logically organized and positioned +- [ ] Complex logic is broken into manageable steps +- [ ] Workflow is documented (node names are descriptive) + +## Testing Readiness + +- [ ] Workflow can be imported into n8n without errors +- [ ] All required credentials are identified +- [ ] Test data requirements are clear +- [ ] Expected outputs are defined + +## File Output + +- [ ] File is saved to correct location +- [ ] File has .json extension +- [ ] File is valid JSON (passes JSON.parse) +- [ ] File size is reasonable (not corrupted) + +## Documentation + +- [ ] User has been informed how to import workflow +- [ ] Credential requirements have been communicated +- [ ] Testing instructions have been provided +- [ ] Any special configuration notes have been shared diff --git a/src/modules/bmm/workflows/n8n-expert/create-workflow/instructions.md b/src/modules/bmm/workflows/n8n-expert/create-workflow/instructions.md new file mode 100644 index 00000000..161ddb27 --- /dev/null +++ b/src/modules/bmm/workflows/n8n-expert/create-workflow/instructions.md @@ -0,0 +1,350 @@ +# Create n8n Workflow - Workflow Instructions + +```xml +The workflow execution engine is governed by: {project_root}/{bmad_folder}/core/tasks/workflow.xml +You MUST have already loaded and processed: {installed_path}/workflow.yaml +This workflow creates a new n8n workflow from scratch based on user requirements. + + + + + Before asking any questions, analyze what the user has already told you + + Review the user's initial request and conversation history + Extract any mentioned: workflow type, trigger, integrations, complexity, requirements + + + Summarize your understanding + Skip directly to Step 2 (Check Context7 MCP) + + + + Note what you already know + Only ask about missing information in Step 1 + + + + Proceed with full elicitation in Step 1 + + + + + Ask Question 1: "What type of automation workflow do you need?" + Present numbered options: + 1. Webhook-based - Receive HTTP requests and process data + 2. Scheduled - Run on a schedule (cron/interval) + 3. Event-driven - Trigger from external service events + 4. Manual - Execute on demand + 5. Database-driven - Trigger from database changes + 6. Other - Describe your specific trigger needs + + WAIT for user selection (1-6) + Store selection in {{workflow_type}} + + + Ask: "Please describe your trigger requirements" + WAIT for user input + Store in {{workflow_type}} + + + Ask Question 2: "What integrations or services will this workflow use?" + Present numbered options: + 1. HTTP/REST APIs - Generic API calls + 2. Databases - PostgreSQL, MySQL, MongoDB, etc. + 3. Cloud Services - Google Sheets, Slack, Notion, Airtable + 4. Email - Send/receive emails + 5. CRM - HubSpot, Salesforce, etc. + 6. Custom Code - JavaScript/Python logic + 7. Multiple - Combination of above + 8. Other - Specify integrations + + WAIT for user selection (1-8) + Store selection in {{integrations}} + + + Ask: "Please list all integrations needed (comma-separated)" + WAIT for user input + Store in {{integrations}} + + + Ask Question 3: "How complex is your workflow logic?" + Present numbered options: + 1. Simple (3-5 nodes) - Linear flow with minimal logic + 2. Medium (6-10 nodes) - Some conditional logic or branching + 3. Complex (11-20 nodes) - Multiple branches, loops, or error handling + 4. Very Complex (20+ nodes) - Advanced logic with parallel processing + + WAIT for user selection (1-4) + Store selection in {{complexity}} + + Ask Question 4: "Do you need error handling and retry logic?" + Present numbered options: + 1. No - Simple workflow without error handling + 2. Basic - Retry failed operations automatically + 3. Advanced - Custom error handling with notifications + 4. Comprehensive - Full error workflow with logging and alerts + + WAIT for user selection (1-4) + Store selection in {{error_handling}} + + Ask Question 5: "What should the workflow be named?" + WAIT for user input + Store in {{workflow_name}} + + Ask Question 6: "Where should the workflow file be saved?" + Present numbered options: + 1. Default location - workflows/[workflow-name].json + 2. Custom path - Specify your own file path + 3. Project root - Save in main project directory + 4. Specific folder - Choose from existing folders + + WAIT for user selection (1-4) + + Ask for specific path + WAIT for user input + + Store final path in {{save_location}} + + Ask Question 7: "Any additional requirements or specific logic needed?" + Present numbered options: + 1. No - Proceed with current requirements + 2. Yes - Describe additional requirements + + WAIT for user selection (1-2) + + Ask: "Please describe additional requirements" + WAIT for user input + Store in {{additional_requirements}} + + + + + Check if Context7 MCP server is configured + Try to list available MCP tools + + + Store true in {{context7_available}} + Proceed to Step 3 + + + + Store false in {{context7_available}} + Inform user: "Context7 MCP server is not configured. This provides up-to-date n8n documentation." + Ask: "Would you like help setting up Context7 MCP? (yes/no)" + WAIT for user response + + + Guide user through Context7 MCP setup: + 1. Inform user: "Context7 MCP requires the 'uvx' command (part of uv Python package manager)" + 2. Ask: "Do you have 'uv' installed? (yes/no/not sure)" + WAIT for response + + + Provide installation guidance: + - macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh + - Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex" + - Or via pip: pip install uv + Ask user to install and confirm when ready + WAIT for confirmation + + + 3. Inform user: "Please configure Context7 MCP in your IDE's MCP settings with:" + + Server name: context7 + Command: uvx + Args: ["context7"] + Auto-approve tools: ["resolve-library-id", "get-library-docs"] + + 4. Ask user to reconnect/restart MCP servers in their IDE + 5. Wait for user confirmation that MCP is reconnected + 6. Verify Context7 is now available + Store result in {{context7_available}} + + + + Inform: "Proceeding without Context7. Using built-in n8n knowledge." + Proceed to Step 4 + + + + + + + Resolve n8n library ID using Context7 + Query Context7 for relevant n8n documentation based on: + - Workflow type: {{workflow_type}} + - Integrations: {{integrations}} + - Complexity: {{complexity}} + Store relevant documentation snippets for reference + + + + Skip Context7 query + Use built-in knowledge and templates + + + + + Based on gathered requirements, plan the workflow structure: + 1. Identify trigger node type + 2. List all action nodes needed + 3. Identify conditional logic (IF nodes) + 4. Plan data transformations (Set/Code nodes) + 5. Design error handling strategy + 6. Map node connections + + Present the planned structure to user in clear format: + - Trigger: [trigger type] + - Nodes: [list of nodes with descriptions] + - Logic: [conditional branches, loops] + - Error Handling: [strategy] + + Ask: "Does this structure meet your needs?" + Present numbered options: + 1. Yes - Proceed with this structure + 2. No - Adjust the structure + 3. Add more details - Provide additional requirements + + WAIT for user selection (1-3) + + + Ask: "What changes or additions are needed?" + WAIT for user input + Adjust structure based on feedback + Repeat this step + + + + + Load {{templates}} file + Identify closest matching template based on workflow type + Load {{helpers}} for node creation guidelines + Extract relevant template sections + + + + Follow guidelines from {{helpers}} for proper node creation + + Initialize workflow structure: + + { + "name": "{{workflow_name}}", + "nodes": [], + "connections": {}, + "active": false, + "settings": { + "executionOrder": "v1" + }, + "tags": [] + } + + + Build nodes ONE at a time following these rules: + + For Each Node: + 1. Generate unique node ID + 2. Set node name (unique, descriptive) + 3. Set node type (e.g., n8n-nodes-base.webhook) + 4. Set typeVersion (usually 1) + 5. Calculate position: + - First node (trigger): [250, 300] + - Subsequent nodes: add 220 to x for each step + - Branches: adjust y by ±100 + 6. Configure parameters based on node type + 7. Add credentials if needed + 8. Set error handling options if required: + - continueOnFail: true/false + - retryOnFail: true/false + - maxTries: number + - waitBetweenTries: milliseconds + + + For Each Connection: + 1. Identify source node name + 2. Identify target node name + 3. Create connection entry in connections object: + "Source Node Name": [ + [ + { + "node": "Target Node Name", + "type": "main", + "index": 0 + } + ] + ] + 4. For IF nodes: + - index 0 = true branch + - index 1 = false branch + 5. Validate all referenced nodes exist + + + Node Building Order: + 1. Trigger node + 2. Main flow action nodes + 3. Conditional nodes (IF/Switch) + 4. Branch nodes + 5. Merge nodes + 6. Final action nodes + 7. Connect all nodes + + + Apply error handling based on {{error_handling}} selection + Validate all node IDs are unique + Validate all node names are unique + Validate all connections reference existing nodes + + + + Review workflow for optimization: + - Remove any unused nodes + - Verify node positions don't overlap + - Ensure proper spacing and alignment + - Validate all required parameters are set + + Save workflow to {{save_location}} + + + + NEVER delete the file if validation fails - always fix syntax errors + + Run: node -e "JSON.parse(require('fs').readFileSync('{{save_location}}', 'utf8')); console.log('✓ Valid JSON')" + + + Read the error message carefully - it shows the syntax error and position + Open the file and navigate to the error location + Fix the syntax error (add missing comma, bracket, or quote as indicated) + Save the file + Re-run validation with the same command + Repeat until validation passes + + + Once validation passes, confirm with user: "n8n workflow created at {{save_location}}" + + + + Inform user how to use the workflow: + 1. Import the JSON file into n8n + 2. Configure credentials for integrated services + 3. Test the workflow with sample data + 4. Activate the workflow when ready + + Ask: "Would you like me to explain any part of the workflow?" + Present numbered options: + 1. No - I'm good to go + 2. Yes - Explain specific nodes + 3. Yes - Explain the overall flow + 4. Yes - Explain how to test it + + WAIT for user selection (1-4) + + + Provide requested explanation + + + + + Validate against checklist at {{validation}} using {{bmad_folder}}/core/tasks/validate-workflow.xml + + + +``` diff --git a/src/modules/bmm/workflows/n8n-expert/create-workflow/workflow.yaml b/src/modules/bmm/workflows/n8n-expert/create-workflow/workflow.yaml new file mode 100644 index 00000000..32705349 --- /dev/null +++ b/src/modules/bmm/workflows/n8n-expert/create-workflow/workflow.yaml @@ -0,0 +1,31 @@ +name: create-workflow +description: "Create new n8n workflow from scratch based on requirements" +author: "Saif" + +# Workflow components +installed_path: "{project-root}/{bmad_folder}/bmm/workflows/n8n-expert/create-workflow" +shared_path: "{project-root}/{bmad_folder}/bmm/workflows/n8n-expert/_shared" +instructions: "{installed_path}/instructions.md" +validation: "{installed_path}/checklist.md" + +# Shared resources +helpers: "{shared_path}/n8n-helpers.md" +templates: "{shared_path}/n8n-templates.yaml" +platform_mappings: "{shared_path}/platform-mappings.yaml" + +# Variables +variables: + workflow_type: "" # Will be elicited + trigger_type: "" # Will be elicited + integrations: [] # Will be elicited + complexity: "" # Will be elicited + error_handling: "" # Will be elicited + save_location: "" # Will be elicited + workflow_name: "" # Will be elicited + additional_requirements: "" # Will be elicited + context7_available: false # Will be checked + +default_output_file: "{project-root}/workflows/workflow-{timestamp}.json" + +standalone: true +web_bundle: false