Warp Factory Files

Factory Files

A software factory can be defined by files in a repository. This skill covers authoring and editing those files, and validating them before you open a pull request.

warp-server owns the format. It publishes the schema for each version it supports and validates a tree with the same parser the apply path uses. This skill carries no copy of the format: a copy ships inside a Warp release, goes stale against the server, and then reports confident, wrong diagnostics. When the server cannot be reached, the answer is that the tree was not checked.

Use this skill for repository files. It is not the skill for operating a live factory: use factory-mcp to send work to a factory, inspect task status, or pull a task down locally. Playbooks under a factory's own skills/ directories tell that factory's agents how to do their job; editing one is a prompt change, not a schema change, so this skill's rules do not apply to their contents.

Locate the Factory root

Every Factory tree is rooted at the directory containing factory.yaml. All paths below are relative to that root. A repository may register a subdirectory as the root, so find factory.yaml rather than assuming the repository root. Do not follow symlinks while looking: the server parses the repository tree, where a symlink is stored as its target path rather than its target's content.

If there is no factory.yaml, this is not a Factory tree and nothing here applies. agents/<name>/agent.md and similar paths are also used by other agent tooling; stop and say so rather than imposing this schema on them.

factory.yaml                        required, exactly one
agents/<name>/agent.md              at least one; exactly one must be MAIN
agents/<name>/skills/**             skills only that agent can use
automations/<name>/automation.md    optional
runners/<name>.yaml                 optional
scorers/<name>/scorer.md            optional; Markdown body is the rubric
benchmarks/<name>/suite.yaml         optional; benchmark suite manifest
benchmarks/<name>/tasks/<name>.yaml  optional; benchmark suite task
webhooks/<name>.yaml                optional; custom webhook sources
skills/**                           skills every agent in the factory can use

Resource names come from the path, never from a field inside the file. Renaming an agent means moving its directory.

automations/<name>.md is a legacy flat form the parser still accepts. Create the directory form; when editing an existing flat file, leave it where it is unless the user asks you to normalize the tree.

Before you edit

1. Read the files you are about to change, plus factory.yaml, so you can see what is inherited and what is overridden.
2. Preserve fields and Markdown bodies you were not asked to change. The body after an Agent's or Automation's closing --- fence is its prompt; a Scorer's body is its rubric. Never fold either into frontmatter.
3. Prefer the smallest edit that satisfies the request.

Author against the server's schema

Read the tree's schemaVersion from factory.yaml; a tree that omits it is v1alpha1. Then fetch the schema for that version:

curl -s https://app.warp.dev/api/v1/factory-files/schemas
curl -s https://app.warp.dev/api/v1/factory-files/schemas/<schemaVersion>

The registry lists the versions the server supports. The version endpoint returns every document describing one version, keyed by file name: factory.schema.json for factory.yaml, agent.schema.json, automation.schema.json, runner.schema.json, scorer.schema.json and benchmark_suite.schema.json, benchmark_suite_task.schema.json, and webhook.schema.json for the corresponding resources, and common.schema.json for the definitions they share. Both endpoints are unauthenticated. They are exact for the version they describe: an unknown field is an error, and each enumerated value is one the server accepts today.

If the server does not publish the declared version, stop. Do not measure the tree against a version it does not claim to be, and never lower schemaVersion to make a check pass.

Read references/examples.md for worked examples of each resource, and references/scorers.md before writing or changing a Scorer. The field-by-field catalogue is not duplicated here any more; the fetched schema carries it, with a description on each field.

Validate before opening a pull request

Run the bundled validator with Python 3.8 or newer, using the host's command (python3, python, or py -3). Quote both paths because an app-bundle path can contain spaces.

python3 "{{skill_dir}}/scripts/validate_factory_files.py" "<factory-root>"

It selects the tree's resource files and submits them to the server, which runs the real parser. Add --json for machine-readable output and --server-root <url>, or WARP_SERVER_ROOT (or WARP_SERVER_ROOT_URL, the name an Oz sandbox exports), to point at a local, staging, or self-hosted server. No credential is required; WARP_API_KEY is forwarded when the environment already carries one, as an agent sandbox does, and dropped for a single retry if the server answers it with 401 or 403.

The exit code distinguishes three outcomes, and so must you:

• 0 the server checked the tree and found no problem.
• 1 the server checked the tree and reported diagnostics. Fix every one and re-run until it is clean.
• 2 the tree was not checked. This is not a pass and not a failure; it says nothing about the files at all.