Understand the model and get started.

Code samples and example data are preserved in their original language so that identifiers and technical contracts remain unchanged.

What is Erin?

A work platform where part of the team consists of AI agents. People prepare and decide, agents execute, and every decision is recorded from requirement to delivery.

Think of a familiar task board, with one difference: you can assign a task to a person or an agent in the same way. The agent does the work, an independent reviewer evaluates it, and the deliverable stops at a human decision point before acceptance. Everything that happens becomes a record no one rewrites.

Erin is organized into three layers: Structure (org, teams, people, and agents), Work (the board), and Execution (what runs when a task is assigned to an agent).

What you can do

Erin is not a chat assistant. You delegate a complete unit of work, with a contract and acceptance criteria, and get a deliverable backed by evidence. These are the use cases teams run today.

A complete cycle, from request to golden case

The example below shows a real Flywheel cycle. Notice who acts at each step: when it is you, when it is the agent, and what gets recorded.

From zero to your first delivery

The path every team takes. Each step corresponds to a product screen.

1. Set up your space.On first access, create the founder and follow the wizard to set up the Org, Workspace, Team, and Project.
2. Prepare the team.Add people with their roles and explore the native agents: Planner, Researcher, Executor, and Reviewer.
3. Provide knowledge.Create or link a domain KB. The agent consults it before acting, and each consultation is recorded.
4. Create and refine work.Epic, story, task. The refinement agent reads the KB and proposes the Spec (the contract); you approve it at the gate.
5. Assign it to an agent.Assignment is the execution trigger. The executor does the work, the validator reviews in a fresh context, and the loop corrects it if needed.
6. Decide at the gate.The deliverable awaits your verdict, with the output and evidence alongside it. Approve it or send it back with guidance.
7. Scale with Factory Shift.Once you trust the agents, create batches that run overnight with a cost limit. In the morning, the gates await you.

Structure and roles

The hierarchy organizes who works on what: Org contains Workspaces, which contain Teams, which have Projects. People and agents are members of a team.

Roles define what each person can do in a workspace. Ready-made presets include Admin, Manager, Approver, Executor, and Reader, and you can create your own. A role in use cannot be removed before its members are reassigned. Gate approval permission (gate.approve) separates decision-makers from observers.

Work on the board

Work follows a hierarchy: epic, story, task and subtask. Only tasks and subtasks can be executed by an agent; epics and stories are organizational containers.

A task moves through well-defined states: rascunho, pronta, na fila, executando, suspensa, bloqueada por gate and concluída or falhou. Only allowed transitions can occur, and changing state during execution is blocked.

Discovery, refinement, and the Spec

There are two ways to develop work until it is ready for execution.

Discovery (decomposition)

A large epic can be assigned to a discovery agent, which proposes a tree of work items. Review it at the decomposition gate, edit it if needed, and approve it to create the child items. Proposed priorities, dependencies, and criteria are preserved.

Refinement (producing the Spec)

The Spec is the contract for a specific task: scope, output contracts, and acceptance criteria. A refinement agent consults the KB and drafts a domain-grounded Spec. You approve it at the gate. A good Spec enables reliable execution: it is the most important task before any agent runs.

Knowledge (KB)

The domain knowledge collection an agent consults before acting. It is the product's moat.

A KB is a collection of structured documents (concepts, patterns, references) about a technology or domain. Native KBs are curated and shared by Erin; workspace KBs belong to you. An agent can only see KBs visible to its tenant.

• Real consultation. When an agent consults the KB, the cited document is recorded with its hash and relevance. This proves which knowledge informed the deliverable.
• Assisted authoring. An agent can draft KB documents from verifiable sources, with citations and verification.
• Publication and freshness. A KB version is published through human approval and becomes an immutable snapshot. Aging content is marked as stale and blocks publication until reviewed.

Agents

Agents are team members that execute tasks autonomously under your rules.

There are four native functions. Each agent declares its behavior, limits, stop conditions, and output contract.

Immutability, versions, and promotion

• Native agents are immutable. To adapt a native agent, fork it. The original never changes.
• Every change creates a version. The version and model are recorded in the chain. You can see each version's history and performance.
• Evidence-based promotion. A candidate version cannot be dispatched. It is promoted when evaluations and gate signals demonstrate its value.
• Composition. An agent definition can declare the subagents it orchestrates (for example, executor and reviewer). Invoking the agent triggers this composition deterministically.

Providers and BYOK

Use your own AI provider (BYOK, bring your own key). Each agent defines its provider and model, with an optional fallback chain for provider failures.

• Multiple connections (keys) per provider, with friendly labels. Support for Anthropic, OpenAI, Gemini, Groq, DeepSeek, Moonshot, OpenRouter, and more.
• The key stays in the vault. The interface receives only a safe reference, never the secret.
• Inference costs are charged to your account, transparently broken down by agent, model, and task.

The single trigger

There is only one way to trigger execution: assign a task to an agent. No accidental execution, hidden scheduling, or agents deciding to run themselves. This keeps operations predictable and auditable.

The execution engine

When a task is assigned to an agent, a deterministic engine (not an LLM deciding control flow) coordinates the cycle:

1. The executor produces.The assigned agent works against the Spec, consulting linked KBs.
2. The validator reviews.A reviewer evaluates the output in a fresh context, separate from the producer. The executor never reviews itself.
3. Corrective retry.If the reviewer rejects it, the review becomes feedback for the next attempt. The default is 2 attempts, configurable.
4. Cost limit.Every run has a mandatory limit. The loop continues until approval, the cost limit is exceeded, or attempts are exhausted.
5. The gate opens.Once internally validated, the deliverable stops at the gate and awaits a human decision.

Gates and decisions

A gate is a human decision point. An agent or the system may open a gate; the decision always belongs to a human with permission. An agent never approves.

• Evidence Summary. At the gate, you see a verifiable summary of what happened: the output, reviewer score, cost, consulted KBs, and chain integrity. The same evidence you would download in the complete dossier.
• Maker-checker. N-of-M approval policies and separation of duties can be required by workspace. Violations are recorded.
• Effects by type. Approving a Spec makes the task ready; approving decomposition creates the child items; approving a deliverable completes the task. Rejection sends it back with guidance for the next assignment.

Factory Shift

Autonomous batch execution, once you trust your agents.

Instead of assigning one task at a time, create a batch: choose the project, select ready tasks, choose the executor agent, and dispatch. Execution respects your configured overnight window and limits.

The Flywheel

The cycle that builds trust with every turn.

Build easily, execute well, decide with evidence, learn from golden cases and evaluations, promote the version that proves its value, then trust and delegate more. The north-star metric is first-pass approval: the fraction of deliverables approved at the gate without retry or rejection. It measures confidence in delegating at scale.

• Golden cases come from good gate decisions harvested from the chain. They become the evaluation baseline.
• Evals run against golden cases. They fail closed: without reliable evidence, they do not inflate the score.
• Promotion requires evidence. Regressions block it; an override requires a recorded justification.

The audit chain

The foundation that keeps the flywheel honest.

Every human or agent action becomes an event in an append-only record. Events are hash-linked and ordered, so nothing is rewritten afterward. Golden cases, evaluations, costs, and the trust scorecard are all derived from it.

• Reproducible. “Why did we decide this way?” is answered by consulting the chain, not digging through disconnected histories.
• Exportable. Export the verifiable chain and a hash-sealed Evidence Pack containing the Spec, gates, actors, versions, KB references, and cost.
• Integrity. The server can recompute the hash chain at any time to prove it has not been tampered with.

Security

• Tenant isolation. A workspace never sees another workspace's data. Sensitive tables have two layers of isolation.
• Secrets in the vault. The BYOK key is encrypted in a vault, never exposed in logs, the database, or plain text.
• Immutable record. The chain is protected against modification and deletion at the database level, not just in the application.
• Scanning before writing. Content is scanned for secrets and personal information before it becomes a chain event.

Guide: build an agent

An agent is more than a name, prompt, and model. It is a versioned behavior contract.

Fork a native agent or start from scratch. Each version declares:

Guide: build a KB

A good KB separates an agent that gets things right from one that guesses. This guide builds one from scratch, with real content from end to end.

1. Create the KB.Set a slug, technology, and domain. Native (shared by Erin, read-only) or owned by your workspace.
2. Add documents.The content types are concept, pattern, reference and spec. An index and a quick_reference provide navigation.
3. Write the charter.Boundaries, discovery questions, and scope limits. This is what you see when making a decision.
4. Author with sources.For assisted authoring, the agent needs an authorized source connector. The content is cited and verified, not generated from model memory alone.
5. Pass readiness checks.A minimum structure (index, concept, and pattern) and sufficient coverage. An incomplete KB can still be queried, but can only be published when ready.
6. Publish.A version is published through human approval and becomes an immutable snapshot. A stale document blocks publication.
7. Link it to the agent.A KB is actually consulted only when it is bound to the agent version and the search tool is enabled.

Example: the “LGPD: Retention and Deletion” KB

Let's build a compliance KB that a research agent will consult before writing any Spec about personal data.

1. The anatomy. A KB is a Markdown tree. The directory defines the document type, so the structure is also the taxonomy:

kb_lgpd_retencao/
  index.md                          # navegação: o mapa da KB
  quick-reference.md                # navegação: a cola de consulta rápida
  concepts/
    direito-esquecimento.md         # concept: o que é e por que importa
  patterns/
    expurgo-com-trilha.md           # pattern: como se faz na prática
  reference/
    bases-legais-retencao.md        # reference: a tabela que se consulta

2. A real document. Each file starts with a header the system reads. The Purpose has twice the weight of the body in search ranking, second only to the title, so write it carefully:

# Bases legais de retenção por tipo de dado

> **Purpose**: Quanto tempo cada categoria de dado pode ser retida e sob que base legal
> **Confidence**: 0.92
> **Fonte**: Lei 13.709/2018, arts. 7 e 16

## Overview

Retenção segue a finalidade e a base legal. Dados fiscais e contábeis
seguem prazos setoriais próprios. Dados de marketing caem com a
revogação do consentimento.

## Regra prática

| Categoria   | Prazo mínimo | Base legal                    |
|-------------|--------------|-------------------------------|
| Fiscal      | 5 anos       | obrigação legal (art. 7, II)  |
| Cadastral   | vigência     | execução de contrato          |
| Marketing   | nenhum       | consentimento (revogável)     |

3. The charter. This is the part most people skip, and the one that pays off most. The charter is not an execution-blocking guardrail: it is the context you see when approving, and what forces refinement to resolve open questions before proposing a contract.

4. Proof it worked. When an agent consults the KB during work, a chain event is created. It stores the question and the exact reference, never the document body:

{
  "event_type": "kb.consulted",
  "payload": {
    "query": "prazo de retencao dado fiscal expurgo",
    "refs": [{
      "kb_slug":      "lgpd_retencao",
      "doc_slug":     "bases-legais-retencao",
      "kind":         "reference",
      "content_hash": "9f2c...",     // reconstrói o que ele leu
      "snapshot":     3,             // a versão publicada
      "score":        0.61,
      "confidence":   0.92
    }]
  }
}

Guide: write a good Spec

The Spec is the contract. A well-defined Spec makes a reliable loop. A vague Spec guarantees rework.

A strong Spec has three parts, all verifiable:

• Scope: what is included and what is excluded. Ambiguity here leads to rejection at the gate.
• Output contracts: the format and guarantees of the result (what the deliverable must contain and how it will be checked).
• Acceptance criteria: an objective checklist the reviewer uses to evaluate. If a human cannot determine pass or fail from a criterion, it is too weak.

The same request, written two ways

Let refinement consult the KB and ground every part of the Spec in the domain. Where the KB imposes a blocking constraint, make it explicit in the contract: AC 1 above turns the LGPD KB boundary into a verifiable criterion. Producing the best possible Spec is the refinement agent's central task.

Guide: configure Factory Shift

Configure each workspace in Settings, under the Factory Shift tab:

# exemplo de política noturna
Janela        22:00 → 06:00   # fuso do workspace; pode cruzar a meia-noite
Orçamento     US$ 20 / dia     # estourou, pausa até amanhã
Auto-pausa    ≥ 30% de erro    # amostra mínima antes de agir
Re-enfileirar 1x               # teto de tentativas por task
Digest        webhook assinado # resumo matinal do que rodou
Concorrência  configurável     # quantas tasks em paralelo

Then create the batch at /lote: choose the project, select ready tasks and the executor agent, and optionally set a “not before” time. Each task keeps its own assignment record; nothing in a batch approves a deliverable.

Guide: gate policies

The gate is always human, but you define the rigor for each workspace.

• Maker-checker. Require N distinct approvers and separation of duties (the executor cannot approve). Violations are recorded.
• Assignment preflight. Before the trigger, the system anticipates issues (required Spec, KB, connection/key, provider/model, judge, composition). Warnings do not block by default.
• Policy-based blocking. The workspace can turn selected warnings into hard blocks. For example, preventing assignment without a KB.

Best practices

Technical reference

Task states and transitions

Execution states follow an allow-listed state machine. Planning transitions (rascunho and pronta) have their own authority and do not go through it.

rascunho  → na fila           # atribuição (gatilho único)
pronta    → na fila           # atribuição pós-refino
na fila   → executando        # o worker reivindica
executando→ bloqueada por gate # abre o gate
bloqueada → concluída          # humano aprova
bloqueada → pronta / na fila   # recusa ou reatribuição
qualquer terminal → na fila    # re-disparo é re-atribuir

Chain event types

Each action creates a typed event. The main types:

• task.assigned, task.started: the trigger and the start.
• kb.consulted: KB consultation, with the cited document, hash, and relevance.
• agent.model_invoked: a model invocation, with cost re-derived by the server.
• agent.tool_called: a tool call, with arguments and result.
• agent.executed, agent.validated: the output and the reviewer's assessment.
• gate.opened, gate.decided: opening the gate and the human decision.
• work_items.materialized: the child items created when a decomposition is approved.

Stack

Python backend with FastAPI and PostgreSQL. Orchestration uses a Postgres queue and an asynchronous worker, without Temporal or Celery in v1. Agents use a custom harness with native provider tool calling, rather than orchestration frameworks as the backbone. Secrets stay in a vault. Database triggers protect the chain, providing defense in depth beyond the application.

The invariants

The rules the system guarantees. Each has a test that fails if it is violated.

Glossary

Frequently asked questions