docs(factories): document Factory MCP - #521
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 Factory MCP documentation, scaffolds the new Factories section, updates platform terminology variables, and adjusts docs tooling/navigation around the launch IA. The main Factory MCP page is useful, but several merge-blocking issues remain: visible stub pages are being published, the primary Factory MCP page is not discoverable from the new sidebar, pending naming is hardcoded in top-level navigation, and the new security-sensitive handoff guidance needs clearer warnings.
Concerns
- The new
/factories/landing page and related Factories pages publish internal placeholder notes while the redirect sends existing/platform/software-factory/traffic there. - The PR's primary new
factory-mcppage is missing from the Factories sidebar. - The top-level navigation hardcodes a pending product name instead of using the variable/current approved label.
- The style lint change permits any non-empty JSX expression title to bypass VideoEmbed title validation.
- No approved repository spec context was provided, so there was no implementation-vs-spec drift to evaluate.
Security
- The Factory MCP page documents local-to-cloud workspace snapshots and broad artifact transfer without warning readers to review and redact sensitive files, screenshots, or other private context before transfer.
Verdict
Found: 0 critical, 6 important, 1 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: "Overview" | ||
| --- | ||
|
|
||
| [STUB — pending content from HYC/content team for the 8/18 closed-beta soft launch. Owner: HYC. This page is the Factories tab landing page (`/factories/`). |
There was a problem hiding this comment.
/factories/ landing page as a visible stub with internal launch/owner notes, and vercel.json redirects /platform/software-factory/ here. Replace the scaffold with launch-ready content, or keep the page/sidebar/redirect hidden until the real content lands.
| { 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.
src/content/docs/factories/factory-mcp.mdx page is not listed in the Factories sidebar, so the PR's primary page is hard to discover. Add a factories/factory-mcp entry to this group.
| // ZL naming sign-off -- see .agents/references/terminology.md). Reorganized | ||
| // from 10 subsections into HYC's 6-group IA; all page slugs unchanged. | ||
| id: 'platform', | ||
| label: 'Automation Platform', |
There was a problem hiding this comment.
Automation Platform even though the terminology entry says final naming is pending and VARS.WARP_AUTOMATION_PLATFORM still resolves to Oz. Use the variable/current approved label consistently in navigation and the matching topic-icon logic, or defer the visible rename until the variable value is approved.
|
|
||
| ### Send new work to a factory | ||
|
|
||
| For new intake, provide a `factory_uid`, a short `title`, and a `note` that states the requested outcome and relevant constraints. You can also include the source ticket reference and URL so the factory can preserve the relationship to the originating system. When the originating client supports local-to-cloud workspace transfer, new intake can include an initial workspace snapshot for work in progress. |
There was a problem hiding this comment.
|
|
||
| For handback, provide the existing `factory_task_uid` and a `note` that explains what changed, what you validated, and what remains. Include the pushed branch and pull request URL when available. The handback continues the task's existing foreman conversation instead of creating a second work item. | ||
|
|
||
| Factory MCP can also transfer eligible artifacts from a source conversation. User-facing artifacts include plans, confirmed files, and screenshots. You can transfer all eligible artifacts from the conversation or select specific artifact identifiers. The receiving foreman gets an artifact manifest and access to the transferred materials. |
There was a problem hiding this comment.
| # evaluable, so skip the generic-title check but still confirm a | ||
| # non-empty title prop is present. | ||
| expr_match = VIDEO_EMBED_TITLE_EXPR.search(tag) | ||
| if expr_match and expr_match.group(1).strip(): |
There was a problem hiding this comment.
VideoEmbed titles such as title={''} or title={genericTitle} bypass the missing/generic-title lint. Constrain this skip to the intended VARS-backed template-literal pattern or add validation/tests so expression titles cannot mask docs lint issues.
| @@ -0,0 +1,18 @@ | |||
| --- | |||
| title: Configure your Factory | |||
There was a problem hiding this comment.
💡 [SUGGESTION] The glossary says individual factories are lowercase unless referring to the product name Warp Factories. Update visible titles and labels like Configure your Factory, Connect your Factory, and Create a Factory to lowercase factory.
a161319 to
193521a
Compare
193521a to
669a3e2
Compare
669a3e2 to
dc357ad
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 MCP placeholder with a full documentation page covering authentication, local task pickup and handback, notifications, and the ten-tool reference. I found one clarity improvement around defining MCP on first use; no security issues or spec drift were identified from the supplied artifacts.
Concerns
- Define MCP before relying on the acronym in the opening paragraph.
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 MCP documentation will land in a follow-up PR. | ||
| Factory MCP connects compatible coding agents and MCP clients to Warp Factories. It lets a local agent find work, inspect context, coordinate with the foreman, and return changes to the same work item. |
There was a problem hiding this comment.
💡 [SUGGESTION] Expand MCP on first use so the page is self-contained for readers who land here directly.
| Factory MCP connects compatible coding agents and MCP clients to Warp Factories. It lets a local agent find work, inspect context, coordinate with the foreman, and return changes to the same work item. | |
| Factory MCP connects compatible coding agents and Model Context Protocol (MCP) clients to Warp Factories. It lets a local agent find work, inspect context, coordinate with the foreman, and return changes to the same work item. |
dc357ad to
fcb3041
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 MCP placeholder with a substantive docs page covering connection and authentication, local task pickup, coordination, handback, notification routes, and the ten-tool reference. I reviewed the provided annotated diff, the docs style guidance, local source context for the built-in Factory MCP attachment path, the supplemental security checklist, and the empty spec context.
Concerns
- No blocking concerns found. The changed docs page uses clear structure, links to existing or dependency-provided Factory pages, and includes appropriate credential-safety guidance; no security findings apply to this docs-only diff.
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>
fcb3041 to
f4d50a5
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 MCP placeholder with a complete feature documentation page covering authentication, local task pickup, coordination, handback, notifications, and the ten-tool reference. I reviewed the supplied annotated diff against the docs style guide, security review checklist, and available spec context; the spec context explicitly states that no approved or repository spec context was found.
Concerns
- No blocking correctness, docs-structure, style, link, security, or spec-alignment concerns found in the supplied diff.
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 Factory MCP placeholder with a focused documentation page covering when to use Factory MCP, authentication options, local pickup and handback flow, notification routing, and the ten exposed MCP tools. I reviewed the attached diff for docs structure, link/terminology concerns, technical accuracy risks visible from the local context, security guidance, and spec alignment.
Concerns
- No blocking concerns found. The provided spec context states that no approved or repository spec context was found, so there was no material spec commitment 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
1 participant
Summary
Combines a concise local pickup/coordinate/push/handback sequence with authentication and nine-tool reference tables. It preserves task identity, non-locking pickup, least-privilege credential guidance, read-only conversation access, and push-before-handback behavior.
Final size: 959 prose words. Across the section, the senior editorial pass reduced prose from about 14,600 to 7,649 words while preserving verified behavior and security caveats.
Dependency
Depends on #513, which provides the Factories section scaffold and targets
hyc/factory-launch. Until #513 merges, its shared commits appear in this PR; afterward the diff reduces to this feature's content. Branch-local CI can report missing sibling-page links (and #519 can report #513's removed hub slug) until the dependent content and shared IA branch land; the full nine-page integration build is green.Validation
npm run typecheck: passednpm run build: 377 pages built successfullyLatest source refresh
Updates the public contract to ten tools, notification routes, reference-based task lookup, required integrations, factory-selection safety, and Cancelled completion behavior.
Verified against Warp
3d4ee7236363and warp-server2c864b0b8404. Broken, placeholder, partial, and spec-only surfaces remain excluded.Proposed reviewers
For planning only; no review requests have been sent.
@ianhodge@kevinyang372@johnturcooScreenshots
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.
Follow-ups
A dependent shared IA PR will add the grouped nine-page sidebar, desktop/mobile Early Access badge, and legacy generic-page cleanup after the content pages land.
Conversation: https://staging.warp.dev/conversation/5ff89820-2d80-4518-981e-178845029de1
Plan: https://staging.warp.dev/drive/notebook/7ZPKWz7hM5I59o4Gg2ptYi
Co-Authored-By: Warp Agent agent@warp.dev