---
name: workflow-builder
description: Build, repair, and verify connector-neutral n8n workflows through Life OS MCP. Use when an agent must turn a natural-language process request into a working automation, discover available event sources and actions, connect interfaces or business systems, test real executions, and publish safely.
---

# Workflow Builder

Build the process in n8n. Treat Telegram, CRM, knowledge bases, reports, and
future services as replaceable connectors; never encode a product name into
the core process unless the user explicitly selected that connector.

## User documentation

For questions about the Life OS interface, navigation, connections, agents,
workspaces, reports, CRM, knowledge, or settings, consult
`https://docs.archik.tech` before answering. Treat it as the source of truth
for visible button labels and user flows. Link the most specific page and do
not infer UI details from memory. Use `https://docs.archik.tech/llms.txt` for
the page index or `https://docs.archik.tech/llms-full.txt` for the complete
user-facing corpus.

## Required sequence

1. Call `automation_get_instructions`.
2. Call `automation_list_capabilities`, then use `automation_search_actions`
   with a relevant module or query. Call `automation_describe_action` only for
   actions you intend to use. `automation_search_actions` also returns matching
   push events; use its `events` result when looking for a trigger.
3. Inspect existing n8n workflows before creating a duplicate.
   Use `automation_probe_action` for read-only discovery inside a connected
   system. Never use it for effects.
4. Ask concise questions only for choices that discovery cannot answer:
   account, destination, schedule, approval boundary, and missing credentials.
5. Create an inactive draft with `n8n_create_workflow`.
   Extend it in small batches with `n8n_patch_workflow`; do not resend a large
   complete graph when only a few nodes or connections changed.
6. For every external effect, call `automation_create_action_binding` and use
   its returned binding id and schema in a **Life OS Action** node. Fall back
   to the returned HTTP Request configuration only when the custom node is
   unavailable. Never put a provider token in the workflow.
7. For every push event, add a **Life OS Trigger** node first, then call
   `automation_create_subscription`.
   Discover event adapters by capability instead of assuming a product.
   Choose one of two interface modes:
   - use a managed surface adapter when the user wants an interface available
     without writing or hosting code;
   - use `external_application` / `event.received` when the user owns a fully
     custom service. The service submits provider-neutral events and renders
     Human Tasks through the external API; n8n still owns business flow.
     Life OS credentials contain workspace and scopes, never a provider type.
     Consult `https://docs.archik.tech/connections/external-applications` for
     the exact client-credentials and Events/Tasks/Actions contracts.
   Current Telegram adapters expose:
   - `telegram_mtproto` / `message.received` for incoming private messages on
     a connected user account;
   - `telegram_bot` / `message.received` and
     `callback_query.received` for bot messages and inline-button callbacks.
   The old ids `telegram-account` and `telegram-bot` are compatibility aliases,
   not ids to write into new workflows.
   Never build a polling loop around `telegram_wait_for_settled_message` when
   the push provider is available.
8. For every human decision:
   - call `interactions_get_instructions` and
     `interactions_surface_catalog`;
   - declare `L1_basic`, `L2_conditional`, or `L3_custom`;
   - for L3, discover or register a versioned component with strict input and
     output contracts;
   - call `interactions_define_task_type` and fix every capability/fallback
     incompatibility before creating the task;
   - bind `interactions_create_task`, never an unversioned ad-hoc approval;
   - pass `source_type: "n8n.workflow"`, `source_id: "={{ $workflow.id }}"`,
     and `source_run_id: "={{ $execution.id }}"` so the decision appears
     inside the correct automation and execution;
   - treat the returned interaction as immutable. A later type version applies
     only to later tasks.
   Use JSONLogic only for `visible_if`, `enabled_if`, and `required_if`. If a
   condition describes process flow, split it into tasks and State transitions.
   Never create a Human Task for a notification, log line, or agent output that
   requires no response.
9. Validate node connections and expressions by reading the saved workflow.
10. Publish temporarily, call `automation_test_subscription`, and inspect the
   resulting dry-run execution. Life OS bindings suppress external writes;
   native n8n HTTP/provider nodes do not have this guarantee. After dry-run,
   request confirmation for one live smoke-test when an actual destination is
   part of the acceptance criteria.
   After patching an active graph, republish its current version before
   retesting.
11. Keep the workflow published only after the test succeeds. On failure,
    unpublish it, fix the smallest cause, and retry at most three times.
12. Revoke obsolete subscriptions and action bindings after replacing or
    deleting workflow nodes.
13. Return the workflow id, trigger, actions, test execution id, actual effects,
    and any remaining human setup.

## Safety and correctness

- Prefix temporary records and messages with `[E2E-WORKFLOW]`.
- Do not claim success from node configuration alone.
- Do not invent connector ids, action names, field names, or credentials.
- Prefer actions declared by the selected event/surface provider for replies;
  do not search an unrelated account-level connector for its chat identity.
- Do not bypass a requested human approval.
- Keep collection, reasoning, approval, sending, and delivery confirmation as
  distinct events when the business process distinguishes them.
- Make every ingest idempotent using the provider's stable external id.
- When a process must remember a stage between executions, define a machine
  with `state_validate_machine` and `state_define_machine`, then bind
  `state_transition`. Do not emulate shared state with workflow static data.
- Add a final deduplication check immediately before irreversible actions.
- Bound polling, retries, batches, and retained execution data.
- Delete temporary records only when deletion is safe and explicitly supported.

## Workflow shape

Prefer the smallest graph that preserves the business states:

`Life OS Trigger → validate/deduplicate → state/business logic → Life OS Action`

Add branches only for real distinctions such as human approval, error handling,
or separate destinations. Use semantic field names and annotate non-obvious
nodes. State, events and artifacts are platform primitives, not workflow
runtimes; orchestration remains in n8n.

Read [references/acceptance.md](references/acceptance.md) before declaring a
workflow complete.