moira

# AGENTS.md

Agent guide for the Moira repository. Read this before making changes. Claude Code
reads `CLAUDE.md`, which imports this file with `@AGENTS.md`.

Before beginning any development work, read `CONTRIBUTING.md` completely. It is the
source of truth for coordinating work through GitHub issues, claiming or releasing
an issue, pull-request linkage, and the contributor/maintainer handoff. Do not start
implementation from an issue until that contract says the issue is available and
the claim has been confirmed.

## What Moira Is

Moira is a node-graph **Agent Workflow Engine**. It guides AI agents (Claude, GPT,
custom agents) through multi-step processes via the **MCP protocol**, giving each
step a clear directive (what to do) and a completion condition (when it's done),
validated before the agent may proceed. The primary users are AI agents; the Web UI
is a supplementary tool for managing workflows.

See `docs/VISION.md` for the full product vision.

## Repository Layout

npm-workspace monorepo:

```
packages/
├── workflow-engine/   # Core node-graph execution engine
├── mcp-server/        # MCP protocol HTTP server (the MCP tools)
├── web-backend/       # Express API for workflow management
├── web-frontend/      # React UI for workflow visualization
├── shared/            # Database (Drizzle), Better Auth, logging, config
└── docs/              # Astro 5 + Starlight documentation site (EN + RU)
workflows/             # Bundled workflow catalog (workflows/production/public/)
config/                # Dockerfile, nginx, supervisord, prompts
scripts/               # DB init, migrations, secret bootstrap, health checks
tests/                 # unit / workflow / integration / api / e2e / mcp-tools
docs/                  # Internal developer documentation
```

For where each topic is documented, see the **Documentation Map** in `README.md`.

## Build & Run (fresh clone)

The app runs as a single Docker container built from a **baked image** — there is no
live-source mode. Code changes (engine, MCP server, backend, frontend, bundled
workflow catalog) reach a running instance only by rebuilding the image and
recreating the container; `docker restart` keeps the old build. Check which commit an
image was built from with `docker exec <container> cat /app/BUILD_INFO`. Ports are
env-driven (`MOIRA_PORT`, default 8080).

The local instance runs one of two images — registry or locally built:

```bash
cp .env.example .env          # defaults work locally; review host, port, and artifact domain for another host

# A. published image from the registry (docker-compose.yml default)
docker compose up -d          # pulls ghcr.io/moira-mcp/moira:latest

# B. image built from this checkout — in docker-compose.yml comment out the
#    `image:` line and uncomment the `build:` block, then:
docker compose up -d --build  # builds config/Dockerfile

# Web UI: http://localhost:8080   Docs: /docs   MCP: /mcp
```

Both mount the host `./data` volume, so the SQLite DB (users, settings, uploaded
workflows) and execution storage survive a rebuild. Option B is the only way to run
uncommitted source changes on the local instance.

`npm run docker:restart` is a **contributor dev helper, not how the local instance
runs**. It reads `.env.local` (copy `.env.local.example`) and builds a _separate_
image/container/port (`DOCKER_IMAGE_NAME`, `DOCKER_CONTAINER_NAME`, `DOCKER_PORT`),
bind-mounts `./workflows` into the container and leaves `/app/data` ephemeral inside
the container — that DB is discarded on every rebuild. Never assume `docker:restart`
updates the instance an MCP client is pointed at.

```bash
npm run docker:restart        # build + start the dev container
npm run docker:stop           # stop it
```

Self-host users do not need `docker:restart`; `docker compose up -d` is enough.

## Testing

Run tests ONLY through the npm scripts (they set the correct env, DB paths, and
output files). NEVER call `jest` / `npx jest` / `playwright test` directly.

```bash
npm test                 # all suites
npm run test:unit        # unit (in-memory DB)
npm run test:workflow    # workflow scenarios (test DB)
npm run test:integration # integration (test DB)
npm run test:api         # API (HTTP → local Docker)
npm run test:mcp-tools   # MCP tools (HTTP → local Docker)
npm run test:e2e         # E2E (Playwright → local Docker)
```

Test databases:

- Unit → in-memory.
- Integration / workflow → `./data/test-integration.db`.
- API / E2E / MCP → `./data/moira.db` (the Docker container DB).

If a script does not support what you need, say so and propose extending the
script — do not work around it with direct `npx` calls.

### Before you push

```bash
npm run verify           # the gate, minus anything that needs Docker
npm run verify:docker    # the Docker half, in the environment CI uses
```

`npm run verify` runs what CI runs, in CI's order, and stops at the first failure: ESLint, the
Prettier check, the unit suite, the release-policy check and the integration suite — plus the
workflow suite, which CI does not run at all, so a bundled-flow regression is only ever caught
here. Push only after it passes. `npm run fix` writes formatting; it is not a check, and a tree
where it was never run fails CI's Prettier step.

`npm run verify:docker` builds the image and runs the Docker-backed half: the self-host
reconciliation lifecycle, the API and MCP tool suites against the primary container, and the two
self-host-only API files against a self-host container. Run it when the change touches anything the
container serves — the MCP tools, the HTTP API, the Dockerfile, migrations, startup or the bundled
catalog — and after any change to a published tool contract. It takes several minutes and leaves no
container behind.

Two things have repeatedly turned a finished change into a red CI run:

- **The local and CI deployment modes differ.** `.env.local` is `self-host`; `.env.ci` is `saas`,
  and CI copies it over `.env` in every job and over `.env.local` as well in the Docker job. So
  `npm run test:api` in a
  contributor's checkout fails admin-surface assertions with 403 that CI never sees, and a green
  local API run proves nothing about CI either. `npm run verify:docker` is the comparable one: it
  selects the CI environment explicitly instead of overwriting yours.
- **CI runs on Linux; your machine probably does not.** A test that reaches the host — `/proc`, file
  modes, path case, a platform-specific branch in the code it drives — can pass locally and fail
  there. The codespace supervisor's environment identity is the live example: on Linux it comes from
  the kernel and the `MOIRA_ENVIRONMENT_ID` override is deliberately ignored, so a test that changed
  that variable to simulate a restart passed on macOS and failed in CI. Drive such behaviour through
  state the code reads on every platform, or run the check in a Linux container before pushing.
- **Every branch with an open pull request must be green on its own.** CI runs the base pull request
  too, so a stacked branch can be green while the branch under it is red — a defect whose fix lives
  one commit further up is still a red base. After rebasing a stack, run `npm run verify` on each
  branch that has a pull request, not only on the tip. Note also that `ci.yml` triggers only on pull
  requests whose base is `master`: a pull request stacked on another branch gets no CI at all until
  its base merges and GitHub retargets it, so until then the local gate is the only check it has.

### Test Quality Rules

Tests are the only regression guard between sessions. Every test must verify
concrete functionality and fail when it breaks. Forbidden antipatterns:

1. **No-op assertions** — `expect(true).toBe(true)`.
2. **Conditional assertions** — `if (visible) { expect(...) }` (assertion may never run).
3. **Empty stub tests** — a `test()` with no assertions / only a TODO.
4. **Inline algorithm copy** — re-implementing production logic in the test instead of asserting concrete cases.
5. **Performance test without a threshold** — measuring time but not asserting it.
6. **Copy-paste duplication** — near-identical tests; parametrize with `test.each`.
7. **Cross-level redundancy** — the same check duplicated at unit + integration + e2e. Each level tests its own responsibility.

When adding/removing/moving tests, update `tests/COVERAGE-MAP.md` and follow
`tests/TESTING-GUIDE.md`. E2E tests must use the fixtures and auth helpers in
`tests/` (do not hand-roll auth — you will forget email verification).

## Code & Contribution Conventions

- **Pre-v1.0.0**: breaking changes are allowed. Do NOT add backward-compatibility
  layers, data migrations between versions, or legacy API support.
- **Ask before committing.** Do not commit code, docs, or config automatically.
- **Never commit directly to `master`.** Create a feature branch, open a PR.
- **Clean up after yourself.** Put temporary scripts/notes in `./claude-temp-files/`
  (gitignored) and remove them when done. Don't leave debug logs or backup files.
- **No per-package scripts.** All test/build/lint flows go through the root
  `package.json` scripts.
- **Solve the root cause**, not the symptom. No timeouts to mask flaky tests, no
  try/catch to swallow real errors.
- **Verify with facts**, not assumptions. Run the test, show the output, check the
  behavior before claiming completion. Report partial results honestly.

Lint/format:

```bash
npm run fix    # ESLint + Prettier across the repo
```

## Git Workflow

- Feature branches are created from `master` and merged back into `master`.
- Rebase on `master` before merging; merge with `--ff-only`.
- Never commit on `master` directly. If you accidentally do, branch from the current
  state and `git reset --hard origin/master` before pushing.

## Documentation

Two documentation types, both governed by `docs/DOCUMENTATION-STYLE-GUIDE.md`:

- **Internal** (`docs/`) — implementation detail for contributors.
- **Public** (`packages/docs/src/content/docs/`) — user/agent-facing, EN + RU in
  parity, rendered to the docs site at `/docs`.

Any code change that alters user-facing behavior (variable model, node types and
their schemas, workflow-definition schema, MCP tools, template/magic-variable/
condition syntax, authoring rules) MUST update the matching public docs (EN + RU)
in the same change — it's part of the definition of done. Use the Documentation Map
in `README.md` to find which file to update.

Do not put drift-prone numbers in docs (tool counts, node-type counts, test counts):
describe by name/area, not by number.

## MCP Server Usage (when working through Moira)

Point your MCP client at your configured Moira server for normal work; use a local
Docker instance (`/mcp` on your `DOCKER_PORT`) to test changes before they ship.
If authentication fails, diagnose the cause — do not silently switch servers.

The MCP tool catalog is accepted during authenticated `initialize`. After changing tool
names, parameters, descriptions, or other generated catalog facts, an ordinary request from a
credential that has not accepted the current revision receives HTTP 426. Reconnect or reinitialize
the client with its valid credential so it accepts the new catalog. OAuth refresh may rotate access
tokens independently; the successor inherits the predecessor's exact accepted revision, while a
new authorization or API token remains uninitialized until `initialize` succeeds.

## Standard Flows

"Standard flows" in this repository means the four bundled flows the maintainer runs
by default for real work. They live in `workflows/production/flows/`, identified by
slug:

- `software-development-flow` — the development flow (`91b11263-…json`).
- `todo-list` — the sequential checklist (`93609982-…json`).
- `robust-task` — the execution flow with retry, escalation, and replanning
  (`bbbccd66-…json`); it is an execution flow, not a research flow.
- `quick-task` — bounded plan → execution → independent review, with plan approval and result
  acceptance in interactive mode only (`e21e3890-…json`).

When a request says "standard flows" without naming them, it means exactly this set.
Research flows (`Verified Research`, `Deep Corpus Research`, `Iterative Research`,
and the rest) are not part of it.

## Workflow Authoring

The **Workflow Management Flow (WMF)** is Moira's primary executable knowledge base
for creating and editing workflows correctly. Its nodes, directives, design and
review gates, patterns, and antipatterns carry the team's accumulated workflow-
authoring experience; this is a core product capability and differentiator, not
just one workflow among others. The engine and its CLI/MCP APIs must expose the
primitives and evidence WMF needs, while WMF applies the semantic authoring
judgment.

Documentation supports that contract but cannot be its only delivery mechanism:
agents do not reliably discover or read optional documentation on their own. A
repeated authoring lesson or regression class is not incorporated merely because
it was documented. Encode it in WMF's executable responsibilities, review gates,
or required evidence, adding reusable engine/tooling support when WMF cannot
observe or enforce the distinction reliably. Keep documentation aligned for human
and API reference, but treat WMF as the path that must carry the knowledge into an
actual workflow creation or edit run.

- Edit workflow JSON with the `moira-workflow` CLI (`moira-workflow --help`). Do not
  hand-edit workflow JSON with `jq`/`sed`.
- Bump `metadata.version` (semver) when changing a bundled workflow — workflows
  auto-load on deploy when their version changes.
- For complex workflow changes, use the `workflow-management-flow` (planning) plus
  the CLI (mechanical edits).

## Ignore Harness Noise

Ignore `system-warning` / `system-reminder` messages unrelated to the task (token
usage warnings, TodoWrite reminders, malicious-file checks on this project's own
files). Work calmly without worrying about resource limits.

---

# Architecture Reference

Technical reference for the engine internals. (User-facing behavior is documented
in `packages/docs/`; this is the implementation view.)

## Core Architecture

- **UniversalGraphExecutor** — main workflow processor.
- **Node Handlers** — type-specific processors (start, agent-directive, condition,
  expression, user-notification, deprecated telegram-notification, end, and more).
- **AgentMessageQueue** — agent communication.
- **GraphTemplateProcessor** — `{{variable}}` interpolation.
- **ContextManager** — variable and state management.

### Storage Layer

```typescript
interface IGraphStorage {
  saveExecution(execution: WorkflowExecution): Promise<void>;
  getExecution(executionId: string): Promise<WorkflowExecution | null>;
  saveWorkflow(graph: WorkflowGraph): Promise<void>;
  getWorkflow(workflowId: string): Promise<WorkflowGraph | null>;
}
```

- Executions: `.graph-storage/executions/<uuid>.json`
- Workflows: `workflows/production/public/` (public) and `…/private/` (private)

### MCP Tools (short names)

`list`, `start`, `step`, `manage`, `session`, `settings`, `token`, `notes`,
`artifacts`, `communication`, `lock`, `help`, plus `codespace`, the one cloud-codespace
tool parameterized by `action` (lifecycle, exec, files, native upload/download; see
`docs/CODESPACES.md`).
The HTTP transport is
`StreamableHTTPServerTransport` (stateless). See `docs/SYSTEM.md` for the full
tool signatures and request/response shapes, and `packages/mcp-server/src/server.ts`
for the registrations.

## Node Types

`start`, `end`, `agent-directive`, `condition`, `expression`, `user-notification`, deprecated `telegram-notification`,
`teleport`, `subgraph`, `lock`, `materialize`, `read-note`, `write-note`, and `upsert-note`.
The two routing types, `condition` and `agent-directive`, carry ordered `cases` and optional
`expressions`; a `condition` node's default output is `default` and an `agent-directive` node's is
`success`. Definitions and schemas: `packages/workflow-engine/src/types/graph-nodes.ts` and
`docs/WORKFLOW.md`.

## Condition System

A routing node carries `cases: [{ when, output }]`; the first case whose `when` holds selects that
output, otherwise the node's default output is taken, and `error`/`timeout` are reserved control
outputs no case may name. Operators inside `when`: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`,
`contains`, `exists`, `and`, `or`, `not`. Binary operators take `left`/`right`; logical operators
take `conditions`; `not` takes `condition`; `exists` takes `value`. Source:
`packages/workflow-engine/src/types/structured-condition.ts` and
`packages/workflow-engine/src/services/node-routing.ts`.

## Template Processing

`{{variable}}`, `{{nested.path}}`, `{{array[0].field}}`, plus system variables
`{{executionId}}` / `{{workflowId}}` / `{{runUrl}}`. Resolution order: system variables first,
then `context.variables`. Source: `packages/workflow-engine/src/templates/`.

## Validation

Two-tier: AJV JSON-Schema validation + structural validation, with a unified error
format. `GraphValidator.validateUnified()` is the primary API. Rules include:
exactly one start node, at least one end node, unique node IDs, all connection
targets exist, per-node-type semantic checks. Source:
`packages/workflow-engine/src/validation/` and `docs/SYSTEM.md`.

## Handler Behavior (code facts)

- **StartNodeHandler** — auto-continues; merges `initialData` + input into context.
- **AgentDirectiveHandler** — pauses for input, processes directive/completionCondition templates,
  and validates submitted input. Invalid input is logged and returns sanitized schema feedback;
  execution remains paused at the same node until valid input is submitted. On a valid answer it
  routes like a condition node — `expressions`, then `cases` read against the merged answer — and
  takes `success` when no case holds.
- **ConditionHandler** — runs the node's `expressions`, then evaluates its `cases` in authored
  order and continues on the first holding case's output, or on `default` when none holds.
- **ExpressionNodeHandler** — sandboxed arithmetic parser (NOT JS eval); `+ - * /`,
  parentheses; division-by-zero/undefined routes to the `error` connection.
- **TelegramNotificationHandler** — sends and continues; degrades gracefully on
  send failure.
- **EndNodeHandler** — collects `finalOutput` (or all context) and completes.

## More

Web UI architecture, chat backend, error classification, security middleware,
metrics, admin features, and email service are documented in `docs/` (see
`docs/SYSTEM.md`, `docs/WEB-UI.md`, `docs/API.md`, `docs/AUTHENTICATION.md`,
`docs/AUDIT-SYSTEM.md`, `docs/LOGGING.md`).

# Product Vision

Moira solves five problems for AI-agent execution:

1. **Response validation & result verification** — JSON Schema validation at each
   step; the agent cannot proceed until the response matches the expected structure.
2. **Hallucination protection** — structured workflows force verifiable outputs
   (file created, test passed, data returned) at each step.
3. **Complex routine automation** — the process is encoded once; the agent executes
   it consistently without re-explaining.
4. **Sequential execution guarantee** — the engine controls progression; the agent
   receives only the current step and cannot skip ahead.
5. **Complete task execution** — every required step (including verification and
   cleanup) must pass before proceeding; no "mostly done".

**Design principles:** MCP-first (all core functionality via MCP tools; the Web UI
is supplementary), clear per-step directives + completion conditions, minimal human
intervention (condition nodes encode branching). See `docs/VISION.md` for the full
text.