AutoMetabuilder/backend/autometabuilder/workflow/plugins

Workflow Plugins Documentation

This document describes all available workflow plugins for building declarative n8n-style workflows.

Directory Structure

Plugins are organized using an npm-style package structure. Each category folder contains:

• A package.json with category metadata
• Individual plugin folders, each containing:
  • The plugin Python file (plugin_name.py)
  • A package.json with plugin metadata

Categories

• backend/ - Backend infrastructure and initialization plugins (15 plugins)
• core/ - Core workflow orchestration plugins (7 plugins)
• tools/ - Tool execution and development plugins (7 plugins)
• notifications/ - External notification integrations (3 plugins)
• logic/ - Logic and comparison operations (9 plugins)
• list/ - List/array operations (7 plugins)
• dict/ - Dictionary/object operations (6 plugins)
• string/ - String manipulation (8 plugins)
• math/ - Mathematical operations (10 plugins)
• convert/ - Type conversions (7 plugins)
• control/ - Control flow (1 plugin)
• var/ - Variable management (4 plugins)
• test/ - Unit testing and assertions (5 plugins)
• utils/ - Utility functions (7 plugins)
• web/ - Web UI and Flask operations (24 plugins)

Total: 120 plugins in 15 categories

Example Structure

backend/workflow/plugins/
  math/
    package.json              # Category metadata
    math_add/
      package.json            # Plugin metadata
      math_add.py             # Plugin implementation
    math_divide/
      package.json
      math_divide.py
    ...

Categories

• Core Plugins - AI and context management
• Tool Plugins - File system and SDLC operations
• Notification Plugins - External notification integrations
• Logic Plugins - Boolean logic and comparisons
• List Plugins - Collection operations
• Dictionary Plugins - Object/map operations
• String Plugins - Text manipulation
• Math Plugins - Arithmetic operations
• Conversion Plugins - Type conversions
• Control Flow Plugins - Branching and switching
• Variable Plugins - State management
• Test Plugins - Unit testing and assertions
• Backend Plugins - System initialization
• Utility Plugins - General utilities
• Web Plugins - Web UI and Flask operations

---

Core Plugins

core.load_context

Load SDLC context (roadmap, issues, PRs) from GitHub.

Outputs:

• context - String containing SDLC context

core.seed_messages

Initialize empty message array for AI conversation.

Outputs:

• messages - Empty array

core.append_context_message

Add context to messages array.

Inputs:

• messages - Message array
• context - Context text

Outputs:

• messages - Updated array

core.append_user_instruction

Add user instruction to messages.

Inputs:

• messages - Message array

Outputs:

• messages - Updated array

core.ai_request

Make AI request with messages.

Inputs:

• messages - Message array

Outputs:

• response - AI response message
• has_tool_calls - Boolean
• tool_calls_count - Number

core.run_tool_calls

Execute tool calls from AI response.

Inputs:

• response - AI response message

Outputs:

• tool_results - Array of results

core.append_tool_results

Add tool results to messages.

Inputs:

• messages - Message array
• tool_results - Tool results array

Outputs:

• messages - Updated array

---

Tool Plugins

tools.list_files

List files in directory.

Inputs:

• path - Directory path

Outputs:

• files - Array of file paths

tools.read_file

Read file contents.

Inputs:

• path - File path

Outputs:

• content - File content

tools.run_tests

Execute test suite.

Outputs:

• success - Boolean
• output - Test output

tools.run_lint

Run linter.

Outputs:

• success - Boolean
• output - Lint output

tools.create_branch

Create Git branch.

Inputs:

• branch_name - Branch name

Outputs:

• success - Boolean

tools.create_pull_request

Create GitHub pull request.

Inputs:

• title - PR title
• body - PR description

Outputs:

• pr_number - PR number

tools.run_docker

Run command inside Docker container.

Inputs:

• image - Docker image name
• command - Command to execute
• volumes - Optional volume mappings dict
• workdir - Optional working directory

Outputs:

• output - Command output
• error - Error message (if any)

---

Notification Plugins

Note: Notification plugins require the corresponding backend plugins (backend.create_slack and/or backend.create_discord) to be run first to initialize the clients.

notifications.slack

Send notification to Slack.

Prerequisites:

• backend.create_slack must be run first to initialize the Slack client

Inputs:

• message - The message to send
• channel - Optional channel (defaults to SLACK_CHANNEL env var)

Outputs:

• success - Boolean (true if sent successfully)
• message - Status message
• error - Error message (if failed)
• skipped - Boolean (true if skipped due to missing config)

notifications.discord

Send notification to Discord.

Prerequisites:

• backend.create_discord must be run first to initialize the Discord configuration

Inputs:

• message - The message to send
• channel_id - Optional channel ID (defaults to DISCORD_CHANNEL_ID env var)

Outputs:

• success - Boolean (true if sent successfully)
• message - Status message
• error - Error message (if failed)
• skipped - Boolean (true if skipped due to missing config)

notifications.all

Send notification to all configured channels (Slack and Discord).

Prerequisites:

• backend.create_slack and backend.create_discord should be run first for full functionality

Inputs:

• message - The message to send to all channels

Outputs:

• success - Boolean
• message - Status message

---

Logic Plugins

logic.and

Logical AND operation.

Inputs:

• values - Array of boolean values

Outputs:

• result - Boolean (all values are true)

logic.or

Logical OR operation.

Inputs:

• values - Array of boolean values

Outputs:

• result - Boolean (any value is true)

logic.xor

Logical XOR operation.

Inputs:

• a - First boolean
• b - Second boolean

Outputs:

• result - Boolean (exactly one is true)

logic.equals

Equality comparison.

Inputs:

• a - First value
• b - Second value

Outputs:

• result - Boolean (a == b)

logic.gt

Greater than comparison.

Inputs:

• a - First value
• b - Second value

Outputs:

• result - Boolean (a > b)

logic.lt

Less than comparison.

Inputs:

• a - First value
• b - Second value

Outputs:

• result - Boolean (a < b)

logic.gte

Greater than or equal comparison.

Inputs:

• a - First value
• b - Second value

Outputs:

• result - Boolean (a >= b)

logic.lte

Less than or equal comparison.

Inputs:

• a - First value
• b - Second value

Outputs:

• result - Boolean (a <= b)

logic.in

Membership test.

Inputs:

• value - Value to find
• collection - Array or string

Outputs:

• result - Boolean (value in collection)

---

List Plugins

list.find

Find first item matching condition.

Inputs:

• items - Array of objects
• key - Property name
• value - Value to match

Outputs:

• result - Found item or null
• found - Boolean

list.some

Check if any item matches.

Inputs:

• items - Array
• key - Optional property name
• value - Optional value to match

Outputs:

• result - Boolean

list.every

Check if all items match.

Inputs:

• items - Array
• key - Optional property name
• value - Optional value to match

Outputs:

• result - Boolean

list.concat

Concatenate multiple lists.

Inputs:

• lists - Array of arrays

Outputs:

• result - Concatenated array

list.slice

Extract slice from list.

Inputs:

• items - Array
• start - Start index (default: 0)
• end - End index (optional)

Outputs:

• result - Sliced array

list.sort

Sort list.

Inputs:

• items - Array
• key - Optional sort key
• reverse - Boolean (default: false)

Outputs:

• result - Sorted array

list.length

Get list length.

Inputs:

• items - Array

Outputs:

• result - Number (length)

---

Dictionary Plugins

dict.get

Get value from dictionary.

Inputs:

• object - Dictionary
• key - Key name
• default - Default value (optional)

Outputs:

• result - Value
• found - Boolean

dict.set

Set value in dictionary.

Inputs:

• object - Dictionary
• key - Key name
• value - Value to set

Outputs:

• result - Updated dictionary

dict.merge

Merge multiple dictionaries.

Inputs:

• objects - Array of dictionaries

Outputs:

• result - Merged dictionary

dict.keys

Get dictionary keys.

Inputs:

• object - Dictionary

Outputs:

• result - Array of keys

dict.values

Get dictionary values.

Inputs:

• object - Dictionary

Outputs:

• result - Array of values

dict.items

Get dictionary items as [key, value] pairs.

Inputs:

• object - Dictionary

Outputs:

• result - Array of [key, value] arrays

---

String Plugins

string.concat

Concatenate strings.

Inputs:

• strings - Array of strings
• separator - Separator string (default: "")

Outputs:

• result - Concatenated string

string.split

Split string.

Inputs:

• text - Input string
• separator - Split separator (default: " ")
• max_splits - Max splits (optional)

Outputs:

• result - Array of strings

string.replace

Replace occurrences in string.

Inputs:

• text - Input string
• old - String to replace
• new - Replacement string
• count - Max replacements (default: -1 for all)

Outputs:

• result - Modified string

string.trim

Trim whitespace.

Inputs:

• text - Input string
• mode - "both", "start", or "end" (default: "both")

Outputs:

• result - Trimmed string

string.upper

Convert to uppercase.

Inputs:

• text - Input string

Outputs:

• result - Uppercase string

string.lower

Convert to lowercase.

Inputs:

• text - Input string

Outputs:

• result - Lowercase string

string.format

Format string with variables.

Inputs:

• template - Template string with {placeholders}
• variables - Dictionary of variables

Outputs:

• result - Formatted string

string.length

Get string length.

Inputs:

• text - Input string

Outputs:

• result - Number (length)

---

Math Plugins

math.add

Add numbers.

Inputs:

• numbers - Array of numbers

Outputs:

• result - Sum

math.subtract

Subtract numbers.

Inputs:

• a - Minuend
• b - Subtrahend

Outputs:

• result - Difference (a - b)

math.multiply

Multiply numbers.

Inputs:

• numbers - Array of numbers

Outputs:

• result - Product

math.divide

Divide numbers.

Inputs:

• a - Dividend
• b - Divisor

Outputs:

• result - Quotient (a / b)

math.modulo

Modulo operation.

Inputs:

• a - Dividend
• b - Divisor

Outputs:

• result - Remainder (a % b)

math.power

Power operation.

Inputs:

• a - Base
• b - Exponent

Outputs:

• result - a^b

math.min

Find minimum value.

Inputs:

• numbers - Array of numbers

Outputs:

• result - Minimum value

math.max

Find maximum value.

Inputs:

• numbers - Array of numbers

Outputs:

• result - Maximum value

math.abs

Absolute value.

Inputs:

• value - Number

Outputs:

• result - |value|

math.round

Round number.

Inputs:

• value - Number
• precision - Decimal places (default: 0)

Outputs:

• result - Rounded number

---

Conversion Plugins

convert.to_string

Convert to string.

Inputs:

• value - Any value

Outputs:

• result - String

convert.to_number

Convert to number.

Inputs:

• value - String or number
• default - Default value (default: 0)

Outputs:

• result - Number

convert.to_boolean

Convert to boolean.

Inputs:

• value - Any value

Outputs:

• result - Boolean

convert.to_list

Convert to list.

Inputs:

• value - Any value

Outputs:

• result - Array

convert.to_dict

Convert to dictionary.

Inputs:

• value - List of [key, value] pairs or dict

Outputs:

• result - Dictionary

convert.parse_json

Parse JSON string.

Inputs:

• text - JSON string

Outputs:

• result - Parsed object

convert.to_json

Convert to JSON string.

Inputs:

• value - Any value
• indent - Indentation (optional)

Outputs:

• result - JSON string

---

Control Flow Plugins

control.switch

Switch/case statement.

Inputs:

• value - Value to match
• cases - Dictionary of case values
• default - Default value (optional)

Outputs:

• result - Matched case value
• matched - Boolean

utils.branch_condition

Branch based on condition.

Inputs:

• condition - Boolean

Outputs:

• Routes to output 0 (true) or 1 (false)

---

Variable Plugins

var.get

Get variable from workflow store.

Inputs:

• key - Variable name
• default - Default value (optional)

Outputs:

• result - Variable value
• exists - Boolean

var.set

Set variable in workflow store.

Inputs:

• key - Variable name
• value - Value to set

Outputs:

• result - Set value
• key - Variable name

var.delete

Delete variable from workflow store.

Inputs:

• key - Variable name

Outputs:

• result - Boolean (success)
• deleted - Boolean

var.exists

Check if variable exists.

Inputs:

• key - Variable name

Outputs:

• result - Boolean

---

Test Plugins

test.assert_equals

Assert that two values are equal.

Inputs:

• actual - Actual value
• expected - Expected value
• message - Optional assertion message

Outputs:

• passed - Boolean (true if values are equal)
• expected - Expected value
• actual - Actual value
• error - Error message (if failed)

test.assert_true

Assert that a value is true.

Inputs:

• value - Value to check
• message - Optional assertion message

Outputs:

• passed - Boolean (true if value is true)
• value - The checked value
• error - Error message (if failed)

test.assert_false

Assert that a value is false.

Inputs:

• value - Value to check
• message - Optional assertion message

Outputs:

• passed - Boolean (true if value is false)
• value - The checked value
• error - Error message (if failed)

test.assert_exists

Assert that a value exists (is not None/null).

Inputs:

• value - Value to check
• message - Optional assertion message

Outputs:

• passed - Boolean (true if value is not None)
• value - The checked value
• error - Error message (if failed)

test.run_suite

Run a suite of test assertions and aggregate results.

Inputs:

• results - Array of test result objects (each with 'passed' field)
• suite_name - Optional name for the test suite

Outputs:

• passed - Boolean (true if all tests passed)
• total - Total number of tests
• passed_count - Number of tests that passed
• failed_count - Number of tests that failed
• failures - Array of failed test details
• summary - Summary string

---

Backend Plugins

backend.create_github

Initialize GitHub client.

Outputs:

• result - GitHub client
• initialized - Boolean

backend.create_openai

Initialize OpenAI client.

Outputs:

• result - OpenAI client
• initialized - Boolean

backend.create_slack

Initialize Slack WebClient.

Inputs:

• token - Optional Slack bot token (defaults to SLACK_BOT_TOKEN env var)

Outputs:

• result - Slack client
• initialized - Boolean
• error - Error message (if failed)

backend.create_discord

Initialize Discord client configuration.

Inputs:

• token - Optional Discord bot token (defaults to DISCORD_BOT_TOKEN env var)

Outputs:

• result - Discord token
• initialized - Boolean
• error - Error message (if failed)

backend.load_metadata

Load metadata.json.

Outputs:

• result - Metadata dictionary

backend.load_messages

Load translation messages.

Outputs:

• result - Messages dictionary

backend.load_tools

Load tool definitions.

Outputs:

• result - Tools array

backend.load_prompt

Load prompt.yml.

Outputs:

• result - Prompt dictionary

backend.build_tool_map

Build tool registry map.

Outputs:

• result - Tool map dictionary

backend.load_plugins

Load and register plugins.

Outputs:

• result - Boolean (success)

backend.parse_cli_args

Parse command line arguments.

Outputs:

• dry_run - Boolean (dry-run mode)
• yolo - Boolean (execute without confirmation)
• once - Boolean (run single iteration)
• web - Boolean (start web UI)

backend.load_env

Load environment variables from .env file.

Outputs:

• result - String (status message)

backend.load_tool_registry

Load tool registry entries.

Outputs:

• result - Tool registry array

backend.load_tool_policies

Load tool policies from JSON.

Outputs:

• result - Tool policies dictionary

---

Utility Plugins

utils.filter_list

Filter list by condition.

Inputs:

• items - Array
• mode - Filter mode
• pattern - Pattern/condition

Outputs:

• result - Filtered array

utils.map_list

Map/transform list items.

Inputs:

• items - Array
• transform - Transformation

Outputs:

• result - Transformed array

utils.reduce_list

Reduce list to single value.

Inputs:

• items - Array
• separator - Join separator

Outputs:

• result - Reduced value

utils.not

Logical NOT operation.

Inputs:

• value - Boolean value

Outputs:

• result - Negated boolean

utils.check_mvp

Check if MVP section in ROADMAP.md is completed.

Outputs:

• mvp_reached - Boolean

utils.update_roadmap

Update ROADMAP.md with new content.

Inputs:

• content - New roadmap content

Outputs:

• result - Status message

---

Variable Binding

All plugins support variable binding using $variable_name syntax in inputs. Variables are stored in the workflow runtime store and can be accessed across nodes.

Example:

{
  "parameters": {
    "text": "$user_input",
    "template": "Hello {name}!",
    "variables": {
      "name": "$user_name"
    }
  }
}

Error Handling

Plugins may return an error field in their output when an error occurs. Check for this field to handle errors gracefully in your workflow.

Example:

{
  "result": null,
  "error": "Division by zero"
}