---
title: "Prepare your actual application"
description: "Turn a discovered candidate into an executable, reviewed test bundle."
canonical: "https://agenttwin.si/docs/preparation/"
---

# Prepare your actual application

Turn a discovered candidate into an executable, reviewed test bundle.


Start with [project setup](/docs/quickstart/) for the guided dashboard and coding-agent path. This page explains what a test needs and how to prepare an explicit contract yourself.

## What every test needs

| Input | What to supply |
| --- | --- |
| Code to run | One supported entrypoint and its required arguments. |
| Starting data | Fake records that make the scenario meaningful. |
| Service behavior | The actual operations your code calls, within supported contracts. |
| Expected result | The records or outcomes that must exist afterward. |
| Unwanted changes | Writes or state changes the test should reject. |

## Discovery is the starting point

Run `npx agenttwin init` inside your application repository. Review `.agenttwin/inventory.json` and the workflow candidates. An entrypoint or dependency found in source is a candidate, not proof of provider access or a runnable test.

Choose one narrow workflow with observable effects. Identify its built Node entrypoint, required inputs, every service operation, synthetic starting records and expected outputs. Other coding agents can use `.agenttwin/AGENT-TASK.md`; discovery does not automatically supply a correct executable test.

## Choose a preparation path

**Guided callable preparation:** the local coding agent proposes a workflow-test-v1 contract for a supported JavaScript/TypeScript export. Preparation compiles the selected source and records its dependencies. You review the proposal before `npx agenttwin test` executes it in Docker. This is a bounded compiler path, not support for every framework or dependency.

**Explicit built-file preparation:** supply a Node entrypoint you have already built. The example below uses this path.

## Build and configure the entrypoint

For this built-file path, bundle TypeScript and application dependencies first and list the required output files. Execution does not install missing dependencies. `command` is an argv array beginning with `node`. Application file paths resolve relative to the world specification.

Configure test clients with generated `AGENTTWIN_<SERVICE>_URL` and `AGENTTWIN_<SERVICE>_TOKEN` values. A production SDK requires a supported base-URL override and supported operations; merely replacing a token is insufficient. Use synthetic IDs and avoid copying production credentials into the bundle.

## A preparation contract

Save this as `preparation.json` beside your built `workflow.mjs`. Replace both discovery IDs with the actual IDs in your inventory. This example prepares a Slack notification; it is not a complete Slack replica.

```json
{
  "schema": "agenttwin/preparation-v1",
  "workflowId": "YOUR_DISCOVERED_WORKFLOW_ID",
  "world": {
    "schema": "agenttwin/world-v1",
    "name": "notification",
    "files": ["workflow.mjs"],
    "command": ["node", "workflow.mjs"],
    "timeoutSeconds": 20,
    "services": [{
      "name": "slack",
      "adapter": "slack",
      "collections": [
        {"path": "/messages", "seed": []},
        {"path": "/channels", "seed": [{"id": "C_TEST", "name": "test"}]}
      ]
    }],
    "assertions": [{"service": "slack", "path": "/messages", "count": 1}]
  },
  "mappings": [{
    "toolId": "YOUR_DISCOVERED_SLACK_TOOL_ID",
    "service": "slack",
    "contract": "slack",
    "operations": ["chat.postMessage"],
    "reviewed": true
  }]
}
```

Your application must send a message to the seeded channel using the generated connection information. The assertion checks one recorded message; add stronger observable checks appropriate to your workflow. Include every recorded candidate operation in reviewed mappings. Preparation rejects missing or unsupported mappings, but cannot establish that static discovery found every behavior in arbitrary source.

## Prepare, review, execute

```sh
npx agenttwin prepare --file preparation.json --out .agenttwin/prepared/notification
npx agenttwin contracts --file .agenttwin/prepared/notification/agenttwin.world.json --json
npx agenttwin run --file .agenttwin/prepared/notification/agenttwin.world.json --json
```

Preparation copies unchanged listed source and writes the world spec, a SHA-256 manifest and `agenttwin.bundle.json`. It does not execute the application. Review the upload list, bundled source, fixtures and checks before running or uploading.

The `run` command above executes directly on your computer. Check [provider operations](/docs/provider-operations/) for the supported service subsets. For isolation, choose a compatible Docker or cloud runner explicitly. Docker supports bounded tagged-SQL PostgreSQL; Redis requires a supported cloud world. Source-bound callable bundles cannot be uploaded to hosted execution. See [execution boundaries](/docs/safety/).

## Retest the right files

For a one-shot prepared bundle, changing your original source does not update a previously copied bundle: rebuild and prepare again. For a reusable world, every run restages the files listed by that world's specification and resets its baseline. Confirm which files the spec references before patching.

Do not make a failing check pass by weakening the outcome or removing the fault. Inspect evidence, patch source and compare receipts under unchanged test conditions. [Understand the receipt](/docs/evidence/) before approving a repair.