docs(factories): document integrations and intake - #520
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 Factories intake documentation and performs a broad rename/IA update from Oz-facing terminology to variable-backed platform names. The new intake page is close, but the published navigation still exposes placeholder Factories pages and the intake page contains two links to missing Factories docs.
Concerns
- The new Factories sidebar entries publish multiple pages whose body content is still
[STUB — pending content...], including the overview and quickstart pages. connect-your-factory.mdxlinks to./factory-mcpand./factory-as-code, neither of which exists in the diff or local docs tree.
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
|
|
||
| The Factory MCP connects local coding agents and other MCP clients to a factory. Use it when work begins in a local development session, needs local-only context, or requires a developer to take over part of an existing factory work item. | ||
|
|
||
| An MCP client can find factory work, inspect its context, coordinate with the foreman, and return notes or completed artifacts to the same work item. This preserves the factory's workflow record while letting the developer use the local agent and environment suited to the task. See the [Factory MCP guide](./factory-mcp) for setup, workflows, and the tool reference. |
There was a problem hiding this comment.
🚨 [CRITICAL] ./factory-mcp does not exist in this diff or the docs tree, so this link will 404; add the target page or link to an existing Factory MCP doc before publishing.
|
|
||
| 1. Create or select the factory that will own the work. Follow the [Warp Factories quickstart](./quickstart) if the factory is not running yet. | ||
| 2. Connect the provider and scope its access. Use the setup guide for [Slack](../platform/integrations/slack), [GitHub](../platform/integrations/github), [Linear](../platform/integrations/linear), or [Jira](../platform/integrations/jira). | ||
| 3. Define an automation with an enabled receiving agent, run configuration, event subscriptions, and the narrowest useful filters. Add a schedule only for recurring work. See [factory definitions as code](./factory-as-code) for the declarative configuration model. |
There was a problem hiding this comment.
🚨 [CRITICAL] ./factory-as-code does not exist in this diff or the docs tree, so this link will 404; add the target page or link to an existing factory definitions doc before publishing.
| { 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 — pending content...] placeholders. Replace those pages with launch-ready content or keep them out of navigation before merge.
1f1aca3 to
54826e6
Compare
54826e6 to
65f8d82
Compare
65f8d82 to
51e513d
Compare
51e513d to
58cfec9
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 intake stub with a scannable overview that explains source choices, intake flow, intake boundaries, integration guides, Factory MCP, and direct or scheduled automation. I did not find correctness, security, or spec-alignment blockers in the attached diff.
Concerns
- One wording suggestion: avoid introducing "foreman" in the verification steps before defining it.
- No approved or repository spec context was provided, so there were no spec-drift findings.
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
|
|
||
| 1. Select a factory. Follow the [Warp Factories quickstart](./quickstart) if needed. | ||
| 2. Authorize the provider at its narrowest scope, or configure the Factory MCP, a direct run, or a schedule. | ||
| 3. For provider events, configure the automation's agent, run settings, subscriptions, and filters. Configure recurring work with a schedule; manual requests start the foreman directly. |
There was a problem hiding this comment.
💡 [SUGGESTION] Avoid introducing "foreman" before the page explains what it is; keep this verification step focused on the user-facing action.
| 3. For provider events, configure the automation's agent, run settings, subscriptions, and filters. Configure recurring work with a schedule; manual requests start the foreman directly. | |
| 3. For provider events, configure the automation's agent, run settings, subscriptions, and filters. Configure recurring work with a schedule; start one-off work with a manual factory run. |
58cfec9 to
b291fe9
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 intake stub with a scannable overview covering intake sources, connection steps, routing boundaries, provider-specific guide links, Factory MCP, and direct or scheduled automation. I reviewed the attached diff against the docs style guide, link structure visible in the diff, the provided spec context, and security-sensitive permission wording; no blocking correctness, security, or spec-drift issues surfaced.
Concerns
- One non-blocking clarity issue: the page introduces
Foreman runin the intake flow before defining what a foreman is. Consider defining the term or replacing it with a more user-facing label.
Verdict
Found: 0 critical, 0 important, 1 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
| Integration --> Match["Subscription and<br/>filter matching"] | ||
| Match --> Automation["Configured automation"] | ||
| Schedule["Schedule tick"] --> Automation | ||
| Automation --> Foreman["Foreman run"] |
There was a problem hiding this comment.
💡 [SUGGESTION] Foreman run is introduced before the page defines foreman; use a user-facing term here or define the role on first mention so the intake flow is self-contained.
b291fe9 to
5fe436e
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 connection stub with an overview of intake sources, routing, verification, and provider-specific integration links. I reviewed the attached diff, PR description, and spec context; there is no approved spec context to compare against and no security-sensitive code or configuration changes in this docs-only diff.
Concerns
- The new provider-guide links target pages that the PR description says are supplied by separate dependent PRs. If this PR lands or is validated without those pages present on the base branch, the docs page will ship broken links and branch-local validation can fail.
Review audit
- Added or changed comments: none.
- Added or changed tests: none; this is a docs-only content change.
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
| * [Slack](./integrations/slack) - Route chat requests, direct messages, and thread follow-ups through a dedicated factory app. | ||
| * [GitHub](./integrations/github) - Route repository events with issue, pull request, review, or CI context. | ||
| * [Linear](./integrations/linear) - Route planned issues through issue activity and agent sessions. | ||
| * [Jira](./integrations/jira) - Route Jira Rovo assignments through an agent-session automation. |
There was a problem hiding this comment.
🚨 [CRITICAL] These provider links point to pages that are not included in this diff and are described as separate dependent PRs, so merging or validating this PR alone leaves broken docs links; include the linked pages in this stack before this lands, or temporarily link to existing provider docs until the targets exist.
There was a problem hiding this comment.
The four provider routes are present in the merged Foundation #537 as valid placeholders, specifically so this focused overview PR can link to separately reviewed provider PRs while passing independently. Current #520 CI and Vercel both pass, and the internal-link check reports 0 broken links. The placeholders are replaced by #525–#528.
|
/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 intake stub with a concise overview page covering source selection, intake flow, boundaries, integration guides, Factory MCP, and direct or scheduled automation. I reviewed the supplied annotated diff against the docs style guidance, security checklist, and the provided spec context; no blocking issues were found.
Concerns
- No blocking concerns. The provider integration links depend on sibling PRs noted in the PR description; keep merge ordering tied to those pages so the links resolve before publication.
Comment and test audit
- Added or changed comments: none.
- Added or changed tests: none; this docs-only diff has no test files.
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
5fe436e to
33640c5
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 factory connection stub with an intake overview covering source choices, connection steps, routing, intake boundaries, integration guide links, Factory MCP, and direct or scheduled automation.
Concerns
- No blocking correctness or security concerns found in the attached diff.
- The page relies on dependent provider guide pages; merge after those dependencies land so the internal links remain valid.
Verdict
Found: 0 critical, 0 important, 2 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
| Route work into your factory from Slack, Linear, GitHub, and local | ||
| coding agents via the Factory MCP. |
There was a problem hiding this comment.
💡 [SUGGESTION] The frontmatter description omits Jira, direct runs, and schedules even though the page covers those intake paths. Match the metadata to the page scope.
| Route work into your factory from Slack, Linear, GitHub, and local | |
| coding agents via the Factory MCP. | |
| Route work into your factory from Slack, GitHub, Linear, Jira, local | |
| agents, direct runs, and schedules. |
|
|
||
| 1. Select a factory. Follow the [Warp Factories quickstart](./quickstart) if needed. | ||
| 2. Authorize the provider at its narrowest scope, or configure the Factory MCP, a direct run, or a schedule. | ||
| 3. For provider events, configure the automation's agent, run settings, subscriptions, and filters. Configure recurring work with a schedule; start one-off work with a manual factory run handled by the foreman agent, which coordinates the factory workflow. |
There was a problem hiding this comment.
💡 [SUGGESTION] This step mixes provider, schedule, and manual setup in one instruction. Rephrase it around the source the reader chose so the procedure stays path-specific.
| 3. For provider events, configure the automation's agent, run settings, subscriptions, and filters. Configure recurring work with a schedule; start one-off work with a manual factory run handled by the foreman agent, which coordinates the factory workflow. | |
| 3. Configure the intake path you chose. For provider events, set the automation's agent, run settings, subscriptions, and filters. For recurring work, configure a schedule. For one-off work, start a manual factory run handled by the foreman agent. |
33640c5 to
76abcba
Compare
|
/oz-review |
|
You've used all 5 |
Co-Authored-By: Warp Agent <agent@warp.dev>
76abcba to
82cb6ee
Compare
|
/oz-review |
|
You've used all 5 |
|
/oz-review |
|
You've used all 5 |
… page Rewrites Connect your factory so external readers don't need internal vocabulary to follow it: - Drop 'intake' everywhere (intake paths, intake boundaries, how intake works); use plain framing like 'how work reaches your factory'. - Dissolve the 'Intake boundaries' grab-bag table into a 'Good to know' list scoped to user-facing behavior, and move provider authorization mechanics to the per-provider integration guides. - Remove internal implementation details: seeded tracker skill and prompt appendix, retry-safety guidance for receiving workflows, subscription-matching plumbing, and the unexplained 'managed factory' qualifier. - Simplify the flow diagram and setup steps; gloss 'foreman agent' and 'work item' on first mention per the terminology glossary. Validated with npm run build (377 pages), the style_lint skill (--changed, no findings for this page), and the broken-links checker (0 broken links). Co-Authored-By: Warp <agent@warp.dev>
Link Slack, GitHub, Linear, Jira, and Factory MCP from the source table, the default-automation bullets, and the tracker-selection note so readers can jump straight to the relevant guide from wherever a provider is mentioned. Validated with the style_lint skill (no findings for this page) and the broken-links checker (0 broken links). Co-Authored-By: Warp <agent@warp.dev>
The agent users assign or mention in Jira is Warp (the rovo:agentConnector module named 'Warp' in forge-jira/manifest.yml), not a generic Rovo agent. Rovo is Atlassian's framework that surfaces it; the conversation still happens in a Rovo agent session (A2A agent_session_created ingress). Reword the source table, Jira default-automation bullet, and integration guides bullet accordingly, and align 'Rovo agent session' phrasing with the Jira integration guide. Co-Authored-By: Warp <agent@warp.dev>
Lead with what matters to the reader: Jira work items are assigned to Warp. Drop the remaining Rovo mentions from the source table, the Jira integration-guides bullet, and the follow-ups note — the Jira guide covers the Rovo session mechanics. Co-Authored-By: Warp <agent@warp.dev>
1 participant
Summary
Reframes Connect your factory as the plain-language overview of how work reaches a factory. It keeps the source-choice table, setup and verification steps, flow diagram, default automations, and a "Good to know" list of user-facing behavior (follow-ups, one-tracker limit, filter scope, write-back control), while moving provider-specific detail into dedicated Slack, GitHub, Linear, and Jira pages.
Internal vocabulary was removed after review feedback: no "intake" framing, no seeded-skill/prompt-appendix or retry-safety implementation details, and provider authorization mechanics now live in the per-provider guides.
Final size: ~820 prose words.
Dependencies
hyc/factories-shared-ialists those pages under Connect > Integrations after they land.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: 0 errorsnpm run build: 377 pages builtLatest source refresh
Documents tracker-optional setup, one-tracker maximum, tracker-driven seed composition, and the current Jira Rovo intake model.
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.
@advait-m@liliwilson@captainsafiaScreenshots
Not included. The page uses a compact intake flow, source table, and concern matrix; no approved factory-specific UI assets exist yet.
Unverified claims
None — the documented sources, routing behavior, continuation, duplicate handling, and verification steps were verified against source.
Conversation: https://staging.warp.dev/conversation/5ff89820-2d80-4518-981e-178845029de1
Plans: https://staging.warp.dev/drive/notebook/7ZPKWz7hM5I59o4Gg2ptYi and https://staging.warp.dev/drive/notebook/DpRWhMQ0DLCajPPMggXw5e
Co-Authored-By: Warp Agent agent@warp.dev