docs: Factory file format v1alpha1 (REMOTE-2039) [auto-draft]

[rachaelrenk]

Auto-generated docs draft — REMOTE-2039

This is an auto-generated first-pass docs draft created by the scan-new-specs workflow, which detected a newly merged spec with no corresponding docs coverage.

Feature: Factory File Format v1alpha1 — Factory and Agent Resources
Spec: specs/REMOTE-2039/PRODUCT.md in warp-server
Spec PR: https://github.com/warpdotdev/warp-server/pull/13224

New page: platform/factory-file-format.mdx (proposed URL docs.warp.dev/platform/factory-file-format).

Docs outline (auto-generated)

The following outline was generated from the spec. /cc @zachbai — please review and check off each item, or leave a comment with corrections.

Content structure

• H1: Factory file format
• Opening paragraph: define a factory and its agents from files in a Git repository, with identity inferred from file paths.
• Key concepts: path-inferred identity, one main agent, deterministic sync, strict validation
• Source contract: factory.yaml fields and agents/<name>/agent.md structure
• Resolution and defaults: overrides, harness default, execution target, runner resolution, source-repo insertion; agent roles (foreman/custom)
• Validation and normalization
• Reconciliation and lifecycle
• Related pages: Software factory, Agents, Runners, Environments

Items needing engineer verification ⚠️

• Confirm the correct user-facing product name and casing for "factory" and for the projected roles the draft calls "foreman" and "custom" (spec uses FOREMAN / CUSTOM).
• Confirm the full list of factory.yaml and agent.md frontmatter fields is accurate and complete for v1alpha1.
• Confirm the "Warp Agent" harness default wording is correct.
• Confirm this is a customer-facing format worth documenting publicly (vs. internal-only), and whether v1alpha1 is stable enough to publish.
• Confirm the proposed sidebar placement under Oz → Orchestration (see [TODO: docs reviewer — confirm placement] in sidebar.ts).
• Add a concrete end-to-end factory.yaml + agent.md example if one is safe to publish.

Verified from spec ✅

• All content is drawn only from PRODUCT.md. No TECH.md-derived implementation internals were included (ambient-mode constraint).

Notes

• This spec has a TECH.md; per the ambient-mode drafting rules, no TECH.md content was used, since there was no engineer present to confirm what is safe to publish.
• The spec status is "Approved reduced scope for the first delivery branch," so a :::caution note flags the draft/early status at the top of the page.

Conversation: https://app.warp.dev/conversation/d7900d79-cac7-4014-8e34-6c872853a77a
Run: https://oz.warp.dev/runs/019fa44e-0a22-7a77-bbb1-8181a25360fb

This PR was generated with Oz.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Jul 27, 2026 4:11pm