WorkflowHub, explained properly.

1. Core concepts

Five nouns. Learn these and the rest of the product reads itself.

2. Workflows

A workflow is a design object containing queues, one or more work-item types, the fields on those types, routes between queues, rules, and permissions. You build it on a visual canvas (Workflows in the menu) or by asking an AI to build it for you over MCP.

2.1 Anatomy

• Start point — where new items enter.
• Queues — the steps. See §3.
• Routes — the legal moves between queues. If there is no route, the move is impossible — this is the single most common cause of "my item won't move."
• Junctions — a decision node that picks the next queue by evaluating criteria, instead of asking a person to choose.
• End point — routing here finishes the item (current queue becomes null, status Finished).
• Work-item types — the form definitions. A workflow can carry more than one.
• Variables — named workflow-level values (thresholds, endpoints, feature switches) that rules and external apps both read. Managed under the workflow; permission-gated separately (§8).

2.2 Designing one: the order that works

1. List the steps first. Write the real ones on paper. "Intake → Triage → Work → Review → Done" is a workflow; "stuff we do" is not.
2. Name what each step PRODUCES. This becomes a field. Review produces a verdict. Testing produces a result. Deployment produces an outcome.
3. Create the queues, then the routes between them. Only draw a route where the work legitimately flows. Extra routes are how work escapes your process.
4. Add the fields — one per step output, typed (§4.2), not free prose.
5. Add the rules that gate the moves (§5). "You may not leave Review until ReviewOutcome is set."
6. Set permissions (§8), then publish.

3. Queues

A queue is a step where work waits. Its configuration decides who sees the work and how they get it.

3.1 Queue types

3.2 The settings that actually change behaviour

• Requires human approval — a hard gate. An agent cannot advance work out of this queue; only an interactive human can. This is the Golden Rule made mechanical, and it is enforced at the API, not in the UI, so it holds for every caller.
• Queue context / instructions — the human-facing "what do I do here?" text, shown on the work item's Instructions tab.
• Bound skills — operating guides delivered to whoever (or whatever) works this queue. See §9.3.
• Lease trigger — when work lands here, enqueue a task so an external worker (like the edge agent) can claim it.
• Enrichment (query queues) — on arrival, run a configured query and write the results into the item's fields. This is how you attach "everything we know about this customer" without a human looking it up.
• Subscriptions — users can watch a queue and be notified on arrival.

3.3 Pull, don't assign

The default working pattern is Pull Next: the platform hands the worker the highest-priority eligible item and locks it to them. This beats assignment for throughput because idle capacity finds work instead of waiting for a dispatcher. Assignment still exists for genuine named-owner steps.

4. Work items & fields

4.1 What a work item carries

• Ticket ID — human-facing, e.g. OPS-482. Paste one into the top bar to open it.
• Field values — the structured form data, grouped onto tabs.
• Description — the markdown body.
• Notes — commentary; can be marked internal.
• Attachments — files (with inline preview) or reference links.
• History — every action, who took it, and what kind of actor they were: human, ai, or app. Stamped server-side from the authentication path; never client-supplied, never editable.
• Time entries — active-work timers with actor and source (human / agent), started and ended. This is how "how long did it take" becomes a fact rather than a guess.
• Links & dependencies — relationships to other items, including blocking dependencies.

4.2 Field types

Pick the type by what the value is for. If a rule will test it, it must be discrete and comparable — a combo box, not a paragraph.

5. Routing rules — technical reference

A rule is: trigger (when it evaluates) + scenarios (what must be true) + actions (what happens). Scenarios combine with AllScenariosAreTrue (AND) or AnyScenarioIsTrue (OR).

5.1 Triggers — when a rule fires

5.2 Criteria — what a scenario can test

Each criterion compares something to a value using an operator: IsEqualTo, IsNotEqualTo, IsGreaterThan, IsGreaterThanOrEqualTo, IsLessThan, IsLessThanOrEqualTo, MatchesPattern, DoesNotMatchPattern.

5.3 Actions — what a rule does

Field & form control

Flow control — the ones that govern process

Integration & data

6. Rule recipes

Patterns worth copying, with the exact trigger/criteria/action combination.

6.1 Advance on completion (the engine moves work, not the worker)

Problem: people finish a step and forget to route. Work rots in a queue looking active.

Trigger:   AfterWorkItemSave
Scenario:  Field "TestResult"       IsEqualTo   "Pass"
       AND WorkItemIsInQueue        IsEqualTo   "Test"
Action:    RouteWorkItem -> queue "Verify"
           (Value = "Auto-routed by the Test queue contract")

Now completing the work is the move. The note explains why it moved, so the history reads honestly.

6.2 The gate (nothing leaves without its evidence)

Problem: items advance out of Review with no recorded verdict.

Trigger:   BeforeWorkItemRouted
Scenario:  WorkItemIsInQueue        IsEqualTo    "Code Review"
       AND Field "ReviewOutcome"    IsEqualTo    ""            (unset)
Action:    CancelAction  ("Set ReviewOutcome before leaving Code Review.")

The refusal message is what the caller sees — write it as an instruction, not an error code.

6.3 Always queue-scope a field rule

6.4 Directional gate (block one direction only)

Trigger:   BeforeWorkItemRouted
Scenario:  NextQueueIs              IsEqualTo    "Deploy"
       AND Field "DeployApproved"   IsNotEqualTo "true"
Action:    CancelAction  ("Deployment requires sign-off.")

Using NextQueueIs keeps the gate on entry to Deploy without freezing every other move.

6.5 Escalate by age

Trigger:   BeforeWorkItemSave
Scenario:  WorkItemCreatedDate      IsLessThan   {threshold}
       AND Field "Priority"         IsNotEqualTo "Critical"
Action:    SetPriority(Critical)  +  AddAutomaticNote("Auto-escalated on age.")

Store the threshold as a workflow variable so ops can tune it without editing rules.

6.6 Conditional requirement

Trigger:   OnFieldUpdate (RequestType)
Scenario:  Field "RequestType"      IsEqualTo    "Refund"
Action:    MakeFieldRequired(RefundAmount) + MakeFieldVisible(RefundAmount)

7. Projects

A workflow answers how work is done. A project answers what we're trying to accomplish — and it can span workflows.

• Membership — items from any workflow can belong to one project. Every item should belong to one; orphaned work is invisible to project reporting.
• Streams & board — group work into lanes and order it; the board is drag-to-reorder with execution order preserved.
• Stages — project-level phases, advanced independently of any single work item.
• Dependencies & critical path — declare that item B waits on item A. A blocked item is visibly blocked, and the critical path is computed.
• Templates — a reusable project shape (stages + transitions) instantiated for each new engagement.
• Priority & status — set at project level, visible on the item.

8. Security model

8.1 How access is decided

Permissions are granted to groups and scoped to a component — usually a queue, sometimes a work-item type or the workflow itself. Users get permissions by group membership. A workflow's owner holds every permission on their own workflow by construction; that seat can't be edited away.

Two identity-shaped rules worth knowing: a permission check that fails on a lookup returns 404, never 403 — the platform does not confirm that something exists to someone not entitled to see it. And every action records actor kind (human, ai, app), stamped from the authentication path.

8.2 Permission reference

8.3 The Golden Rule, mechanically

Mark a queue requires human approval and an agent cannot advance work out of it — not through the UI, not through the API, not by finishing the item instead of routing it (finishing is routing to the end point, and the same gate applies). An interactive human passes. This is architectural, not a setting someone remembers to check per workflow.

8.4 Secrets

Credentials for external systems live with the edge agent on your hardware. The cloud coordinates work and never holds plaintext. Organizations may opt into admin-recoverable secrets explicitly; the default is zero-knowledge.

9. Setting up the agent

The edge agent is a single self-contained binary (Windows, macOS, Linux). No database, no server — it holds your credentials and does the work that touches your systems.

9.1 Install

1. Download it from the Download Agent page in the app.
2. Create an API key on the API Keys page. The key acts as you — its actions are attributed to your identity in history.
3. Put the key in the agent's config, along with your API base URL.
4. Bind the agent to the queue(s) it should work.
5. Start it. Its dashboard shows what it's doing, what it's spent, and what it has claimed.

9.2 What the agent needs to succeed

• A queue with clear outputs. If a step's result isn't a field, the agent can't record it and the engine can't gate on it.
• A bound skill telling it how to do this step and the standard it's judged by (§9.3).
• Gates on the queues that matter. Don't rely on the agent's good judgement — encode the rule.
• A budget. The agent tracks spend per item; set the ceiling deliberately.

9.3 Skills — how you teach it

A skill is a markdown operating guide stored in the product and bound to a workflow, queue, or project. When work arrives, the skill travels with it. Write skills as you'd brief a competent new hire: what this step is for, what "done" means, what to do when the input is ambiguous, and what never to do.

Documents are the other kind of knowledge: reference material listed in the item's manifest and fetched on demand rather than pushed in full. Use skills for procedure, documents for reference.

10. What to expect on day one

Honest expectations, because a disappointed pilot is worse than a slow one.

10.1 Works well immediately

• Structured intake & triage — classify an incoming request, fill the form, route it by rule.
• Document extraction into fields — attach a PDF/scan, extract to structured data, hand a human a quick check rather than a retype.
• Enrichment — on arrival, query a system and attach the answer to the item.
• Drafting — replies, summaries, first-pass write-ups, held at a human approval gate.
• Governed hand-offs — moving work between teams with the evidence attached and the audit trail intact.

10.2 Needs a couple of iterations

• Judgement-heavy steps — the first version of a skill is rarely right. Expect to revise it after watching real items.
• Anything with an unwritten standard. If your team can't articulate what "good" means, the agent can't meet it. Writing the skill is often the first time the standard gets written down at all — that's a feature, but budget for it.

10.3 Don't start here

• Irreversible actions without a gate. Payments, external sends, deletions — put a human queue in front, always.
• Processes nobody agrees on. Automating a disputed process just makes the dispute faster.

11. Measurement & reporting

Everything the platform records is designed to answer four questions about work that has already happened.

Build your own views in Reports → Builder: filter, group by queue / status / priority / assignee / created-by / project / month, split by a second dimension, chart it, add workflow fields as columns, export CSV. Save it, and the report becomes a URL your BI tool can refresh — see the integration guide.