Workflows

Capture repeatable step-by-step practices as a visual flowchart your AI agent can follow.

Orkai Workflows capture repeatable step-by-step practices as a visual flowchart your AI agent can follow — coding rituals, debugging recipes, agent-reasoning playbooks. Each workflow is a graph of typed steps (instructions, runnable code, conditional branches) rendered as an n8n-style canvas in the orkai web UI.

Unlike standards and skills (which are prose documents), workflows are structured graphs — your agent walks the nodes, branches on conditions, and executes code steps itself. No backend execution; the agent is the runtime.

What is a workflow?

A workflow is a node/edge graph stored as structured JSON (raw) with a markdown description (text) for semantic search. Each node is a typed step; edges define the flow between them. Workflows are category-scoped and lazy-loaded in overview() — only the title and description appear until you explicitly load the full graph.

Workflows are MCP-first: you create and manage them through your AI assistant. The web UI provides a read-only visual canvas for inspection.

Step types

Type	Purpose	Example
Text	Instructions the agent reads and follows	"Read the task details from orkai. Use search_code to find related components."
Code	Runnable code the agent executes itself	`npm run lint`, `make build-orkai`
Conditional	If/else branch — agent evaluates and follows the matching edge	"Does the request have a task in orkai?" → true / false

Text and code nodes flow sequentially to the next step. Conditional nodes have two outgoing edges: true (emerald, animated) and false (red, animated).

Create a workflow

Workflows are created through the MCP workflow tool. You describe the steps semantically; the backend auto-converts them into the xyflow graph:

workflow(action: "create",
  name: "Bug Report",
  description: "Triage and fix bugs end-to-end",
  category_ids: ["4c5996d0b1dac020d931388e834d5fc8"],
  raw: {
    steps: [
      { id: "repro", type: "text", label: "Reproduce", content: "Reproduce the issue..." },
      { id: "search", type: "code", label: "Search Code", content: "search_code(...)", language: "typescript" },
      { id: "decide", type: "conditional", label: "Root cause found?", condition: "Is the root cause identified?" },
      { id: "fix", type: "code", label: "Fix", content: "Implement the fix", language: "typescript" },
      { id: "handoff", type: "text", label: "Hand off", content: "Create a task and hand off to the role workflow" }
    ]
  },
  text: "## Steps\n1. Reproduce the issue\n2. Search indexed code...")

The raw field holds the structured graph; text is the markdown description used for semantic search. Both are required on create.

The visual canvas

The orkai web UI renders workflows as a read-only n8n-style canvas with three node types and three edge types:

Text nodes — blue, with the instruction content inline
Code nodes — emerald, with syntax-highlighted code
Conditional nodes — amber diamond, with the condition text

Edges are color-coded: default edges are gray, true-branch edges are emerald and animated, false-branch edges are red and animated. Nodes auto-layout horizontally (350px spacing); false branches drop 200px below. The canvas supports pan, zoom, minimap, and controls.

Find and load workflows

overview() surfaces workflow names and descriptions only — the full graph is lazy-loaded. To find a specific workflow:

workflow(action: "search", query: "bug triage")
workflow(action: "list", category: "orkai")
workflow(action: "get", id: "2a7926ce-3aa9-48c5-8fc4-ff444f023fcf")

get returns the full node/edge graph in raw and the markdown description in text. The agent then walks the steps, branches on conditions, and executes code steps itself.

Workflows vs skills vs standards

	Workflow	Skill	Standard
Purpose	Step-by-step practice	Implementation pattern	Engineering guideline
Structure	Node/edge graph + markdown	Prose document	Prose document
Visual	n8n-style canvas	Text only	Text only
Execution	Agent walks nodes, branches, runs code	Agent reads and applies	Agent reads and enforces

Workflows are the only orkai knowledge type with a structured graph and branchable typed steps. Use them when the order of operations matters — skills and standards are better for reference material.

Typical workflow

Agent sees a workflow in overview() (name + description).
Agent loads the full graph with workflow(action: "get", id: ...).
Agent walks the steps sequentially, reading text nodes and executing code nodes.
At conditional nodes, the agent evaluates the condition and follows the matching branch.
Agent runs code steps itself — there is no backend execution engine.

See MCP for connecting your assistant, and Knowledge layer for how workflows fit into the broader knowledge graph.