docs(factories): add concise overview and workflow - #516
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 Warp Factories documentation surface and reorganizes related platform/reference navigation while updating rename-sensitive terminology variables. The new factory overview/workflow content is substantial, but the PR still exposes placeholder pages and includes broken internal links to factory depth pages that are not present in the diff.
Concerns
- The Factories sidebar publishes four pages whose bodies are still visible
[STUB ...]placeholders. - The Factories overview and workflow pages link to factory depth pages such as
factory-agents,factory-as-code,factory-mcp, andmeasure-and-improvethat are not added by this PR, which will leave users on 404s.
Found: 2 critical, 1 important, 0 suggestions
Verdict
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
| { slug: 'factories/quickstart', label: 'Quickstart' }, | ||
| { slug: 'factories/how-factories-work', label: 'How Factories work' }, | ||
| { slug: 'factories/configure-your-factory', label: 'Configure your Factory' }, | ||
| { slug: 'factories/connect-your-factory', label: 'Connect your Factory' }, | ||
| { slug: 'factories/infrastructure-and-security', label: 'Infrastructure & security' }, |
There was a problem hiding this comment.
[STUB ...] placeholders (quickstart, configure-your-factory, connect-your-factory, and infrastructure-and-security); either replace the stubs with launch-ready content or keep them out of navigation until the content exists.
| * [**Factory agents**](./factory-agents) - Understand the default agent roles and how they collaborate. | ||
| * [**Configure your factory**](./configure-your-factory) - Configure agents, automations, integrations, and execution resources. | ||
| * [**Factory definitions as code**](./factory-as-code) - Define repositories, agents, automations, runners, skills, and MCP servers. | ||
| * [**Connect your factory**](./connect-your-factory) - Route work from engineering tools and coding agents. | ||
| * [**Factory MCP**](./factory-mcp) - Exchange work and context with a factory from an MCP client. | ||
| * [**Measure and improve**](./measure-and-improve) - Evaluate runs, compare configurations, and refine the factory. |
There was a problem hiding this comment.
🚨 [CRITICAL] These links include ./factory-agents, ./factory-as-code, ./factory-mcp, and ./measure-and-improve, but those pages are not added in this diff, so the overview will send readers to 404s; add the target pages or remove the links before publishing.
| 4. Teams identify a concrete change to the factory. | ||
| 5. The updated definition governs later work items. | ||
|
|
||
| The [factory definitions as code](./factory-as-code) page explains the declarative model. See [connect your factory](./connect-your-factory) for intake paths, [Factory MCP](./factory-mcp) for agent-to-factory exchange, and [measure and improve](./measure-and-improve) for the outer loop. |
There was a problem hiding this comment.
🚨 [CRITICAL] This related-links sentence points to missing ./factory-as-code, ./factory-mcp, and ./measure-and-improve pages, so users following the workflow page will hit 404s; link only to pages that exist in this PR or add the missing pages.
1fecf37 to
f84bace
Compare
hongyi-chen
changed the title
f84bace to
7d371d2
Compare
7d371d2 to
07008b2
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 Factory stubs with concise overview and workflow documentation, plus a platform overview cross-link. The new Factory pages are structured and scoped appropriately, but one changed platform paragraph introduces an unimported MDX variable that will break the page build.
Concerns
src/content/docs/platform/overview.mdxnow referencesVARS.WARP_AUTOMATION_PLATFORMwithout adding the requiredimport { VARS } from '@data/vars';, so MDX compilation will fail unless the import is added or the text is made static.
Verdict
Found: 1 critical, 0 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
| [Warp Factories](/factories/) give engineering teams open, flexible infrastructure for building and operating their own cloud software factories. A factory composes the primitives described on this page — triggers, tasks, environments, hosts, and integrations — into an automation loop around your development lifecycle. | ||
|
|
||
| Factories are in closed beta. See the [Factories](/factories/) tab for what a software factory is, how to configure and connect one, and how to apply. | ||
| [Warp Factories](/factories/) assembles the {VARS.WARP_AUTOMATION_PLATFORM} primitives described on this page into persistent, multi-agent software development workflows. A factory coordinates specialized cloud agents around work items as they move through stages such as triage, specification, implementation, review, and verification. |
There was a problem hiding this comment.
🚨 [CRITICAL] This page does not import VARS, so this new MDX expression will fail to compile; add import { VARS } from '@data/vars'; at the top of the file or keep this text static.
|
/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 Factories stub content with two concise conceptual pages and updates the platform overview to point at the new Factories workflow. The new Factories pages are generally structured and scoped appropriately, but one changed platform overview line appears to introduce an unresolved MDX variable reference that can break the docs build.
Concerns
src/content/docs/platform/overview.mdxnow usesVARS.WARP_AUTOMATION_PLATFORM, but the diff does not add the requiredVARSimport for that file. If the import is absent in the target branch, Astro/MDX rendering will fail.- No approved or repository spec context was provided, so no implementation-vs-spec drift findings were evaluated.
- No security-specific issues were found in the documentation changes beyond the build-blocking concern above.
Verdict
Found: 1 critical, 0 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
| [Warp Factories](/factories/) give engineering teams open, flexible infrastructure for building and operating their own cloud software factories. A factory composes the primitives described on this page — triggers, tasks, environments, hosts, and integrations — into an automation loop around your development lifecycle. | ||
|
|
||
| Factories are in closed beta. See the [Factories](/factories/) tab for what a software factory is, how to configure and connect one, and how to apply. | ||
| [Warp Factories](/factories/) assembles the {VARS.WARP_AUTOMATION_PLATFORM} primitives described on this page into persistent, multi-agent software development workflows. A factory coordinates specialized cloud agents around work items as they move through stages such as triage, specification, implementation, review, and verification. |
There was a problem hiding this comment.
🚨 [CRITICAL] This file now references VARS, but the diff does not add import { VARS } from '@data/vars'; after the frontmatter; add that import or this MDX page can fail at build/render time.
|
/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 Factories stubs with concise overview and execution-model documentation, then updates the platform overview to point readers toward the new Factories section. The spec context file says no approved or repository spec context was found, and the supplemental security pass found no security findings.
Concerns
src/content/docs/platform/overview.mdxnow referencesVARSwithout importing it, which should fail MDX compilation until the import is added.
Verdict
Found: 0 critical, 1 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
| [Warp Factories](/factories/) give engineering teams open, flexible infrastructure for building and operating their own cloud software factories. A factory composes the primitives described on this page — triggers, tasks, environments, hosts, and integrations — into an automation loop around your development lifecycle. | ||
|
|
||
| Factories are in closed beta. See the [Factories](/factories/) tab for what a software factory is, how to configure and connect one, and how to apply. | ||
| [Warp Factories](/factories/) assembles the {VARS.WARP_AUTOMATION_PLATFORM} primitives described on this page into persistent, multi-agent software development workflows. A factory coordinates specialized cloud agents around work items as they move through stages such as triage, specification, implementation, review, and verification. |
There was a problem hiding this comment.
VARS, but this file only imports VideoEmbed, so MDX compilation will fail until import { VARS } from '@data/vars'; is added after the frontmatter.
There was a problem hiding this comment.
The required import { VARS } from '@data/vars'; is already present immediately after the frontmatter on the current head. npm run typecheck and the full 377-page build both pass. Retriggering review so this stale finding can be cleared.
|
/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 Factories scaffolding with two concise conceptual pages and updates the platform overview to point readers at Factories. The docs content is mostly scoped and scannable, but one added MDX expression appears to be missing its import in the changed file.
Concerns
src/content/docs/platform/overview.mdxnow referencesVARS.WARP_AUTOMATION_PLATFORM, but the diff does not add theVARSimport in that file. This likely breaks the MDX build unless the import is added with the existing imports.- No approved spec context was supplied for this implementation PR, so there was no spec drift to evaluate.
Verdict
Found: 0 critical, 1 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
| [Warp Factories](/factories/) give engineering teams open, flexible infrastructure for building and operating their own cloud software factories. A factory composes the primitives described on this page — triggers, tasks, environments, hosts, and integrations — into an automation loop around your development lifecycle. | ||
|
|
||
| Factories are in closed beta. See the [Factories](/factories/) tab for what a software factory is, how to configure and connect one, and how to apply. | ||
| [Warp Factories](/factories/) assembles the {VARS.WARP_AUTOMATION_PLATFORM} primitives described on this page into persistent, multi-agent software development workflows. A factory coordinates specialized cloud agents around work items as they move through stages such as triage, specification, implementation, review, and verification. |
There was a problem hiding this comment.
VARS.WARP_AUTOMATION_PLATFORM, but the diff does not import VARS; add import { VARS } from '@data/vars'; with the existing imports or the MDX build will fail.
07008b2 to
d35fdde
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 Factories stub pages with concise conceptual documentation for the overview and execution model, and updates the platform overview cross-reference. I found one non-blocking docs style issue; there were no code/config security findings and no approved spec context to compare against.
Concerns
- One UI reference would better match the docs style guide if the UI label were bolded and the sentence oriented the reader before the action.
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
|
|
||
| The work-item stage is not an authoritative state machine. Run history is the detailed execution record across launches, revisions, and follow-up messages. | ||
|
|
||
| Use Activity in the [control room](./control-room) to locate, filter, and stop work items. |
There was a problem hiding this comment.
💡 [SUGGESTION] Bold the UI label and orient the reader before the action.
| Use Activity in the [control room](./control-room) to locate, filter, and stop work items. | |
| In the [control room](./control-room), use **Activity** to locate, filter, and stop work items. |
Co-Authored-By: Warp <agent@warp.dev> Co-Authored-By: Warp Agent <agent@warp.dev>
d35fdde to
0fc1a06
Compare
|
/oz-review |
|
You've used all 5 |
Rewrite the overview and How Factories work pages as a copyediting pass: - Define terms (foreman, work item) before using them - Replace the 9x5 stage table with a scannable stage list - Remove internal implementation phrasing (seeded policy, authoritative state machine, orchestration/write path, Complete-vs-Cancelled overwrite) - Consolidate repeated default-policy and eligibility hedges - Fix singular subject-verb agreement for Warp Factories in frontmatter - Tighten the Factories paragraph in the platform overview No factual claims added; all verified behavior and caveats preserved. Co-Authored-By: Warp <agent@warp.dev>
1 participant
Summary
Condenses the Factories overview and workflow into two focused conceptual pages. The overview defines the product, audience, capabilities, product boundaries, and sole Early Access note. How it works keeps the foreman lifecycle, reversible stage model, human-policy boundary, work-item/run distinction, and improvement loop in tables and one diagram.
Final size: 1,155 prose words across two pages. Across the section, the senior editorial pass reduced prose from about 14,600 to 7,649 words while preserving verified behavior and security caveats.
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: passednpm run build: 377 pages built successfullyLatest source refresh
Adds Cancelled/Stop semantics, top-level-run work-item creation, and a link to the Control room for Activity operations.
Verified against Warp
e72fd7aacand warp-server9be39e484b. Broken, placeholder, partial, and spec-only surfaces remain excluded.Proposed reviewers
Based on the Warp Factories Soft Launch (August 18th) tracker. For planning only; no review requests have been sent.
@johnturcoo@peicodes@vorporealScreenshots
Not included. The revision uses sourced tables, Mermaid diagrams, and verified code/config examples; no safe approved Factory UI assets exist yet.
Unverified claims
None — all UI labels, defaults, eligibility claims, diagrams, and configuration details were verified against source or deliberately omitted.