docs(factories): document factory agents - #518
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 agents documentation page alongside broader Factories navigation and rename-support updates. The main Factory agents content is close in structure, but the diff currently exposes placeholder-only Factories pages in the public sidebar and includes broken internal links.
Concerns
- Several new Factories sidebar entries point to pages whose rendered body is still
[STUB ...]planning text, so public docs would ship placeholders instead of usable launch content. src/content/docs/factories/factory-agents.mdxlinks twice to./factory-as-code, but the diff exposesconfigure-your-factoryinstead and does not add afactory-as-codepage.
Verdict
Found: 2 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
| { slug: 'factories', label: 'Overview' }, | ||
| { 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 ...] planning text. Public docs shouldn't expose placeholder content; remove the stub pages from the sidebar until launch-ready content lands or replace the stubs before merging.
|
|
||
| Use factory-wide defaults for common runtime and tool settings, then override them per role. Keep prompts focused, put reusable procedures in skills, and grant only the required MCP servers and secrets. | ||
|
|
||
| [Factory definitions as code](./factory-as-code) documents the version-controlled structure and exact configuration fields. |
There was a problem hiding this comment.
🚨 [CRITICAL] ./factory-as-code is not added by this diff, so this internal link will be broken.
| [Factory definitions as code](./factory-as-code) documents the version-controlled structure and exact configuration fields. | |
| [Configure your Factory](./configure-your-factory) documents the version-controlled structure and exact configuration fields. |
| ## Related pages | ||
|
|
||
| * [**How Warp Factories work**](./how-factories-work) - Follow the work-item lifecycle and foreman coordination model. | ||
| * [**Factory definitions as code**](./factory-as-code) - Configure factory-wide defaults, role-specific agents, automations, and runners. |
There was a problem hiding this comment.
🚨 [CRITICAL] This related-page link also points at the missing ./factory-as-code route.
| * [**Factory definitions as code**](./factory-as-code) - Configure factory-wide defaults, role-specific agents, automations, and runners. | |
| * [**Configure your Factory**](./configure-your-factory) - Configure factory-wide defaults, role-specific agents, automations, and runners. |
ee8dd21 to
dd72c8b
Compare
dd72c8b to
b86957c
Compare
b86957c to
ed986ce
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 Factory agents page with conceptual documentation for default factory roles, handoff boundaries, seeded context, model and harness choices, verification responsibilities, and human gates. I found one minor wording issue and no security or spec-alignment blockers.
Concerns
- The opening sentence uses a singular verb with the plural product name used elsewhere on the page.
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
| --- | ||
|
|
||
| Factory agent documentation will land in a follow-up PR. | ||
| Warp Factories uses role-specific agents to move a work item from intake to human handoff under the default seeded workflow. Each agent owns a defined responsibility, while the foreman coordinates the work and maintains one continuous conversation with the requester. |
There was a problem hiding this comment.
💡 [SUGGESTION] Make the subject and verb agree in the opening sentence.
| Warp Factories uses role-specific agents to move a work item from intake to human handoff under the default seeded workflow. Each agent owns a defined responsibility, while the foreman coordinates the work and maintains one continuous conversation with the requester. | |
| Warp Factories use role-specific agents to move a work item from intake to human handoff under the default seeded workflow. Each agent owns a defined responsibility, while the foreman coordinates the work and maintains one continuous conversation with the requester. |
ed986ce to
9b14f78
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 Factory agents page with a concise conceptual guide covering default roles, handoff boundaries, memory, model/harness selection, verification responsibilities, and human-gated permissions. I reviewed the attached diff, PR description, and spec context; no approved or repository spec context was available for implementation comparison.
Concerns
- No blocking concerns found.
- No security findings from the changed documentation.
- The diff adds no code comments or tests, so the comment/test guideline audit found nothing to flag.
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
9b14f78 to
ddc2421
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 Factory agents page with a concise role reference covering the default roster, seeded context and memory, role responsibilities, verification expectations, configuration boundaries, and human gates. The changed page follows the docs structure for a conceptual feature page, uses descriptive internal links, and does not introduce code, secrets, permissions changes, or other security-sensitive configuration.
Concerns
- No blocking concerns found in the annotated diff.
- Comment audit: no code comments or MDX comments were added or changed.
- Test audit: no tests were added or changed; the PR description reports build, typecheck, link-check, and style-lint validation.
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
|
/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 Factory agents page with a concise role reference covering the default roster, role responsibilities, seeded context and memory, verification ownership, configuration boundaries, model and harness selection, custom agents, and human gates. I reviewed the attached diff against the docs repository guidance, security checklist, and available spec context.
Concerns
No blocking concerns found. The diff adds documentation only, introduces no code or runtime configuration, and the provided spec context reports no approved or repository 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>
ddc2421 to
6afe7da
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 Factory agents page with a conceptual reference for default factory roles, seeded memory, model and harness selection, custom agents, verification ownership, and human gates.
Concerns
- No blocking concerns found in the changed lines.
- No approved spec context was available for an implementation-vs-spec comparison.
- The supplemental security pass did not identify unsafe guidance around secrets, runtime access, or human approval boundaries.
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
Remove undefined jargon that confused readers: 'intake' becomes plain descriptions of work entering the factory, 'seeded' becomes 'default', and phrases like 'advisory verdict', 'prompt appendix', 'parent-child lineage', and 'correlated mistakes' are rewritten to say what they mean. Same verified facts, human approval gates, and security caveats; clearer sentences, second-person voice, and simpler section names. Co-Authored-By: Warp <agent@warp.dev>
Drop 'specialists' wording in favor of plain 'agents', link computer use from the implement and verification sections, surface custom agents and automations in the default roles section, and call out that agent configuration can be stored as version-controlled code. Co-Authored-By: Warp <agent@warp.dev>
vorporeal
left a comment
vorporeal
left a comment
There was a problem hiding this comment.
generally lgtm; only a couple comments on places we could be a little more clear
| You configure each agent in two places: | ||
|
|
||
| * **In the control room** - Use the agent editor to set an agent's description, model, runner, host, MCP servers, secrets, and instructions. | ||
| * **In your factory definitions** - Set the harness, environment, and credential strategy in code. |
There was a problem hiding this comment.
is this highlighting the fact that, for a warp-managed factory repo, you can either use the visual UI to modify agents or Aloke's code-based editing flow? if so, i think that could be stated more clearly.
There was a problem hiding this comment.
Yes, that was the intent — made it explicit in 7d63039. The section now says it directly: for a Warp-managed repository you can edit agents in the agent editor or edit the definition files in the control room's Code tab, and both write to the same files; for a GitHub repository your team owns, the files are the only write path (PRs), and file-owned control room settings are read-only. (Verified against the write-through logic in warp-server, which only applies to Warp-managed code-storage sources.) Details live in the definitions-as-code page from #519.
| ## Choose models and harnesses by role | ||
|
|
||
| Each role can run on its own model and harness. Supported harnesses include the Warp Agent harness, Claude Code, and Codex, and any role can use any of them. A foreman running on Claude Code or Codex can still dispatch the factory's other agents, and the runs it starts are still tracked as its children. |
There was a problem hiding this comment.
multi-harness isn't available to all users; not sure if that's something we want to call out here (so people don't read this and assume it is an option for them)
There was a problem hiding this comment.
@warp-agent could you do a bit of research to find which plans support multi-harness (i.e. paid and above), and make a note here? would be nice to link out to warp.dev/pricing for more details
There was a problem hiding this comment.
Your Warp account is not a member of any team with access to this repository.
There was a problem hiding this comment.
Researched the entitlement in warp-server (logic/agent_entitlements.go → AgentHarnessesPolicy.ThirdPartyEnabled): the Free tier sets third_party_enabled: false, and every paid tier base (Build and up, including Enterprise) sets it to true. Added a note in 7d63039: third-party harnesses require a Build plan or higher, Free-plan roles run on the Warp Agent harness, with a link to warp.dev/pricing.
|
|
||
| ## Add custom agents and automations | ||
|
|
||
| The five default roles aren't a ceiling. Add custom agents for narrow jobs such as documentation, security analysis, migrations, or release checks. They don't have to become required steps for every work item. |
There was a problem hiding this comment.
The five default roles aren't a ceiling.
wording here feels a little LLM-y
There was a problem hiding this comment.
Reworded in 7d63039 — now reads: "Add custom agents for jobs the default roles don't handle, such as documentation, security analysis, migrations, or release checks. A custom agent doesn't have to be a required step for every work item."
…w feedback - Note that third-party harnesses require a Build plan or higher, with a link to warp.dev/pricing (verified against warp-server billing tiers: free.yaml sets third_party_enabled false; all paid bases set it true) - Rework 'Configure agent behavior' to state clearly that a Warp-managed factory repo supports both the visual agent editor and the code-based editing flow, while a team-owned GitHub repo is file-only with read-only control room settings - Reword the custom-agents opener to drop the 'aren't a ceiling' phrasing Co-Authored-By: Warp <agent@warp.dev>
2 participants
Summary
Documents the five default roles with a canonical responsibility table, concise handoff guidance, model/harness selection matrix, integrated verification, custom-agent boundary, and a clear separation between default workflow policy, repository permissions, and runtime access.
Plain-language revision
Rewrote the page in plain language based on reviewer feedback that the "intake" framing was confusing. "Intake" is gone (replaced by plain descriptions of how work enters a factory), "seeded" is now "default", and constructions like "advisory verdict", "prompt appendix", "sibling factory agents with parent-child lineage", and "correlated mistakes" now say what they mean. All verified behavior, human approval gates, and security caveats are preserved; the page is now in second person with simpler section names. Body word count is roughly unchanged (1,069 → 1,422 raw words, including tables) because compressed jargon expanded into plain sentences.
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 successfullystyle_lint.py --changed): 0 findings for this pageLatest source refresh
Adds per-agent Auto-memory, tracker-dependent seed composition, and current control-room model/runner/host versus definitions-only configuration boundaries.
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.
@vorporeal@johnturcoo@coolcom200Screenshots
Not included. The revision uses sourced tables and verified configuration details; no safe approved Factory UI assets exist yet.
Unverified claims
None — all UI labels, defaults, eligibility claims, and configuration details were verified against source or deliberately omitted.