docs(factories): document definitions as code - #519
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR adds the factory definitions-as-code reference, Factories IA/sidebar changes, and broad Oz-to-variable terminology updates across the docs. The spec context attachment was empty, so there was no approved spec material to compare against; I also found no security-specific findings.
Concerns
- Several new Factories pages are now sidebar-linked but still render internal
[STUB ...]launch notes instead of publishable content. - Slack and Linear trigger instructions now build literal
@...handles from{VARS.WARP_AUTOMATION_PLATFORM}, which is a product-name variable rather than a bot-handle variable and can render invalid instructions when the branding value changes.
Verdict
Found: 0 critical, 2 important, 0 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
| label: "Connect your Factory" | ||
| --- | ||
|
|
||
| [STUB — pending content from HYC/content team for the 8/18 closed-beta soft launch. Owner: HYC. |
There was a problem hiding this comment.
[STUB ...] placeholder text; the same issue appears on the new Factories overview, quickstart, how-it-works, and infrastructure pages. Replace these with launch-safe content or keep them unlisted until content is ready.
| ## 2. Tag the agent in Slack | ||
|
|
||
| In any channel or thread in your Slack workspace, tag @Oz with a task: | ||
| In any channel or thread in your Slack workspace, tag @{VARS.WARP_AUTOMATION_PLATFORM} with a task: |
There was a problem hiding this comment.
{VARS.WARP_AUTOMATION_PLATFORM} is a product-name variable, not a Slack/Linear bot handle; using it after @ will render invalid mention instructions when the value changes. Keep the actual integration handle literal or introduce a dedicated handle variable and update the other @{VARS.WARP_AUTOMATION_PLATFORM} replacements the same way.
3185e1e to
465b714
Compare
hongyi-chen
changed the title
465b714 to
309a0fd
Compare
309a0fd to
481224a
Compare
|
/oz-review |
|
I'm re-reviewing this pull request in response to a review request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
There was a problem hiding this comment.
Overview
This PR replaces the placeholder definitions-as-code page with a complete reference covering source modes, directory layout, resource fields, examples, and validation behavior for file-managed factories. I found no blocking correctness, security, or spec-alignment issues in the attached diff.
Concerns
- One table sentence is ambiguous enough to be worth clarifying before merge.
Verdict
Found: 0 critical, 0 important, 1 suggestions
Approve with nits
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
| | `secrets` | Lists Warp-managed secret names. | Optional. Added to every agent's effective access. | | ||
| | `mcpServers` | Maps names to Warp MCP server `warpId` values. | Optional. Added to every agent's effective access. | | ||
| | `providers` | Configures GCP or AWS access. | GCP accepts `projectNumber`, `workloadIdentityFederationPoolId`, `workloadIdentityFederationProviderId`, and `serviceAccountEmail`; AWS accepts `roleArn`. | | ||
| | `integrations` | Declares connected factory integrations. | Optional. `type` accepts `slack`, `linear`, or `jira`. Declare at most one issue tracker: `linear` and `jira` are mutually exclusive, and no tracker is valid. GitHub access comes from `repositories` and the connected GitHub App. | |
There was a problem hiding this comment.
💡 [SUGGESTION] Clarify that omitting an issue tracker is valid; no tracker is valid can read like no tracker configuration passes validation.
| | `integrations` | Declares connected factory integrations. | Optional. `type` accepts `slack`, `linear`, or `jira`. Declare at most one issue tracker: `linear` and `jira` are mutually exclusive, and no tracker is valid. GitHub access comes from `repositories` and the connected GitHub App. | | |
| | `integrations` | Declares connected factory integrations. | Optional. `type` accepts `slack`, `linear`, or `jira`. Declare at most one issue tracker: `linear` and `jira` are mutually exclusive, and omitting a tracker is also valid. GitHub access comes from `repositories` and the connected GitHub App. | |
481224a to
b39e882
Compare
|
/oz-review |
|
I'm re-reviewing this pull request in response to a review request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
There was a problem hiding this comment.
Overview
This PR replaces the placeholder Factories definitions-as-code page with a reference covering source modes, directory layout, resource fields, examples, validation, and synchronization behavior. I reviewed the attached diff against the docs conventions, supplemental security checklist, and available spec context.
Concerns
- No blocking concerns found in the attached diff. No approved or repository spec context was available, so there was no spec-drift issue to enforce.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
b39e882 to
415435f
Compare
|
I'm re-reviewing this pull request in response to a review request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
There was a problem hiding this comment.
Overview
This PR replaces the placeholder factory definitions-as-code page with a full reference for source modes, directory layout, resource fields, examples, and validation behavior. I checked the annotated diff against the docs style guidance, internal link targets, security-sensitive configuration language, and the empty spec context.
Concerns
- No blocking concerns found. The changed page has no tests to review, no added code comments to audit, and no approved spec context to compare against.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
Co-Authored-By: Warp Agent <agent@warp.dev>
415435f to
a66d456
Compare
|
/oz-review |
|
This is your last |
|
I'm re-reviewing this pull request in response to a review request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
There was a problem hiding this comment.
Overview
This PR replaces the placeholder Factories definitions-as-code page with a full reference covering source modes, directory layout, resource fields, examples, validation, and synchronization behavior. I reviewed the attached diff against docs conventions, internal link targets, security concerns, and available spec context; no approved/repository spec context was present.
Concerns
- No blocking concerns found.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
Editorial rewrite, no factual changes: - Define live-managed and file-managed in plain English before the comparison table, and present GitHub-backed and Warp-managed as the two homes for a file-managed definition - Translate jargon (compare-and-swap saves, effective access) into plain conflict-detection and inheritance language - Split combined inheritance rules into 'How access and defaults combine' and 'How workerHost resolves' subsections - Lead validation section with the all-or-nothing behavior readers need first; keep diagram, tables, examples, and all verified claims Co-Authored-By: Warp <agent@warp.dev>
- Fold the mode comparison table and Code-tab subsection into the mode bullets and sync section; each fact now appears once - State the workerHost rule once instead of four times - Drop per-surface control-room notes (cloud providers, Runners) covered by the general read-only/editable rule - Remove internal-leaning details: serialization aside, branch-review gating caveat, legacy-key rewrite timing, duplicate foreman rule Co-Authored-By: Warp <agent@warp.dev>
Address review feedback on the definitions-as-code page: - Link the control room on first mention and say what it is - Replace the 'operational state stays in the control room' jargon with a plain-English explanation of the files vs. control room split - Spell out that Warp-managed edits happen in the control room's Code tab Co-Authored-By: Warp <agent@warp.dev>
The CI link checker resolves relative links against the source file's directory, so ../control-room pointed outside the factories section. Use the root-absolute route like the rest of the docs. Co-Authored-By: Warp <agent@warp.dev>
| Every factory manages its configuration in one of two ways: | ||
|
|
||
| * **Live-managed** - You edit the factory directly in the [control room](/factories/control-room/), the web app for operating a factory. There are no definition files. | ||
| * **File-managed** - Definition files in a Git repository are the source of truth, and the control room reflects them. |
There was a problem hiding this comment.
This isn't true.
Every factory is file-backed. You have two options:
-
Warp managed (default). You can edit the factory definition directly in the product or change it by any change through the web app.
-
The factory lives in GitHub or GitLab (GL coming soon). The webapp is read only; the repo is the only way to edit the factory. Any change to the main branch updates the factory definition.
There was a problem hiding this comment.
Fixed in a8a2578 — rewrote the opening as "Where the definition lives" around this model: every factory is file-backed, with Warp-managed hosting as the default (edits in the control room are validated and committed to the files, so the definition can't go invalid) and GitHub as the bring-your-own-repo option where the web app is read-only and any change merged to the production branch updates the factory. Verified against the server's factory-creation and write-through paths. Left GitLab out until it ships.
| A definition is a small tree of YAML and Markdown files. Each resource takes its name from its path: `agents/reviewer/agent.md` defines an agent named `reviewer`. There are no `kind` or `apiVersion` fields. | ||
|
|
||
| ```text | ||
| factory.yaml | ||
| agents/ | ||
| foreman/ | ||
| agent.md | ||
| skills/ | ||
| incident-triage/ | ||
| SKILL.md | ||
| reviewer/ | ||
| agent.md | ||
| automations/ | ||
| labeled-issue/ | ||
| automation.md | ||
| runners/ | ||
| linux-build.yaml | ||
| skills/ | ||
| repository-conventions/ | ||
| SKILL.md | ||
| ``` |
There was a problem hiding this comment.
Would be nice if we linked to a sample factory repo that contains the full definition
There was a problem hiding this comment.
Agreed — but there's no public sample factory repo to link yet (every repo in the org containing a factory.yaml is private/internal). For now the page keeps a complete inline definition under "Example factory definition" and links the machine-readable schema endpoints. Happy to swap in a repo link as soon as we publish a public sample.
| #### How access and defaults combine | ||
|
|
||
| Two different rules decide what an agent ends up with: | ||
|
|
||
| * **Factory-wide access is additive.** Top-level `secrets` and `mcpServers` in `factory.yaml` are granted to every agent. An agent cannot opt out of them. | ||
| * **Defaults are replaceable.** Values in `agentDefaults` apply only when an agent omits the field. An agent that sets its own `secrets` or `mcpServers` replaces the `agentDefaults` value, but the factory-wide entries still apply. | ||
|
|
There was a problem hiding this comment.
this seems like it's talking about implementation details? what are you trying to say here
There was a problem hiding this comment.
Removed in a8a2578. The one rule readers actually need — agent-level secrets/mcpServers replace the agentDefaults value, while factory-wide grants always apply — now lives as a single line on the affected keys instead of a standalone concept section.
| #### How `workerHost` resolves | ||
|
|
||
| `workerHost` follows the same three-way rule wherever it appears: | ||
|
|
||
| * **Set a value** to choose a host: `warp` for Warp-hosted execution, or the ID of a connected self-hosted worker. | ||
| * **Omit the field** to inherit from the level above. | ||
| * **Set an empty or `null` value** to skip inheritance and use the workspace default. |
There was a problem hiding this comment.
Cut as well. workerHost is now one line where it appears: warp for Warp-hosted compute or the ID of a self-hosted worker, inherited unless overridden. The null/empty clearing semantics are gone from the page.
| * **Omit the field** to inherit from the level above. | ||
| * **Set an empty or `null` value** to skip inheritance and use the workspace default. | ||
|
|
||
| #### Choosing a model or harness |
There was a problem hiding this comment.
I feel like what we really want is really clear docs about the entire factory file format. Something like this https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax.
The way we're intermixing docs and trying to describe the factory file definition isn't super clear. We can probably autogenerate a lot of this from the jsonschmea
There was a problem hiding this comment.
Restructured the whole page in that format in a8a2578: one heading per key with short prose and a small example, GitHub workflow-syntax style (agentDefaults.model, triggers[].filter, etc.), written against the schema the server publishes at /api/v1/factory-files/schemas/v1alpha1 — the page now links those endpoints in a closing "Machine-readable schema" section, and autogenerating the skeleton from them later would be straightforward. Scorers are intentionally left out until Measure & improve ships. The trigger section enumerates every provider/event pair from the schema; per-event filter keys stay summarized to keep the page readable.
|
|
||
| For GitHub-backed sources, every pull request that targets the production branch receives a `warp/factory-config (<directory>)` check for each registered path. The check annotates invalid fields or references and summarizes the changes it would apply. A push to the production branch starts synchronization. | ||
|
|
||
| ### Warp-managed direct synchronization |
There was a problem hiding this comment.
the validation piece only really matters for github. No one should have to think about validation if you are using a warp managed repo (it's impossible to end up in a state where the definition is invalid)
There was a problem hiding this comment.
Reframed in a8a2578: validation now only appears as "Pull request checks for GitHub-backed factories", and the page says explicitly that Warp-managed factories skip all of it because every control-room save is validated — you can't end up with an invalid definition. The pipeline diagram and the rejection list are gone.
Address review feedback from @alokedesai: - Fix the source-of-truth model: every factory is file-backed. The page now describes the two hosting options (Warp-managed by default, or a GitHub repository you own with a read-only control room) and drops the incorrect live-managed/file-managed split. - Restructure the resource tables into a GitHub Actions-style syntax reference with one heading per key, modeled on workflow-syntax docs, generated against the published factory-files JSON Schema. - Cut implementation-detail sections (access/defaults combination rules, workerHost resolution modes, legacy providers key, validation pipeline diagram and rejection list), folding the user-relevant bits into the per-key entries. - Scope validation to GitHub-backed factories only; Warp-managed edits are validated on save and can't produce an invalid definition. - Point readers at the machine-readable schema endpoints. Co-Authored-By: Warp <agent@warp.dev>
Refer to the surface as the Warp Factories web app (via the FACTORY_WEB_APP content variable on first mention, then "the web app"), keeping the existing link target. Co-Authored-By: Warp <agent@warp.dev>
3 participants
Summary
Documents the factory definition file format as a syntax reference. Following review feedback, the page is modeled on GitHub Actions' workflow-syntax reference: one heading per key with short prose and a small example, written against the JSON Schema the server publishes at
/api/v1/factory-files/schemas/v1alpha1.Structure:
factory.yaml,agents/<name>/agent.md,automations/<name>/automation.md,runners/<name>.yaml, and skills.Implementation-detail sections from earlier revisions (inheritance rule deep-dives,
workerHostresolution modes, legacy key handling, validation pipeline diagram and rejection lists) are removed; the user-relevant rules live as single lines on the affected keys. Scorers and GitLab remain excluded until those surfaces ship.Foundation
Shared navigation, route placeholders, Early Access badge support, and guide migrations are merged in #537. This PR now contains only its feature-owned files and passes CI independently.
Validation
npm run typecheck: passed (0 errors)npm run build: 377 pages built successfullyLatest source refresh
Source model verified against warp-server
9e3649c4: factory creation provisions a Warp-managed (code.storage) definition source by default, web-app edits round-trip through the write-through commit path, GitHub-backed registrations get thewarp/factory-configPR check, and failed syncs keep the last valid definition. Field reference generated against the publishedv1alpha1schema documents.Proposed reviewers
Based on the Warp Factories Soft Launch (August 18th) tracker. For planning only; no review requests have been sent.
@alokedesai@captainsafia@vorporealScreenshots
Not included. The page is a text reference with verified code/config examples; no safe approved Factory UI assets exist yet.
Unverified claims
None — all defaults, key constraints, event lists, and behavior claims were verified against the published schema and warp-server source, or deliberately omitted.