docs: clarify factory, foreman, and Factory MCP terminology - #618
docs: clarify factory, foreman, and Factory MCP terminology#618rachaelrenk wants to merge 14 commits into
Conversation
Customers conflate a factory, its foreman agent, and the Factory MCP server, partly because setup gives a factory and its foreman the same name by default. - Add a Key terms section to the Factories overview defining factory, foreman, Foreman name, work item, and Factory MCP together - Document Foreman name in the factory agents page, and flag the name-collision consequence at the point quickstart creates it - Clarify that the warp-factory MCP client key is user-chosen and unrelated to any factory or foreman name - Note that Factory MCP's "task" is the same thing as a work item - Align factory stage names (Planning, Building, Reviewing) with the factory dashboard's Activity view - Fix two docs pages using the incorrect singular "a Warp Factory" - Narrow style_lint's factory-proper-noun check so it catches the singular "Warp Factory" instead of exempting it - Add terminology.md entries for Foreman name/alias, task, stages, and warp-factory Co-Authored-By: Warp <agent@warp.dev>
|
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 |
There was a problem hiding this comment.
Overview
This PR clarifies Warp Factories terminology across the overview, factory agents, Factory MCP, lifecycle, and related reference pages, and tightens the docs style linter around singular “Warp Factory” usage.
Concerns
- The new canonical terms list still capitalizes generic terms such as “Factory,” “Foreman,” and “Work item,” which conflicts with the lower-case terminology rule the PR is trying to reinforce.
- The Foreman name example says
@paymentsis the factory name, but the@form is the Slack/Linear mention handle; the factory name itself would bepayments. - The
factory-proper-nounlinter behavior changes without adding regression coverage to the existingtest_factory_proper_noun.pycases.
Verdict
Found: 0 critical, 3 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
| nxt = re.match(r"\s+(\w+)", after) | ||
| if nxt and nxt.group(1) in FACTORY_ALLOWED_NEXT_WORDS: | ||
| continue | ||
| if preceded_by_warp: |
There was a problem hiding this comment.
Warp Factory, but the existing test_factory_proper_noun.py regression suite is not updated. Add positive coverage for Warp Factory plus allowed Factory MCP/UI-label cases before relying on this new branch.
Co-authored-by: warp-for-oss[bot] <277970191+warp-for-oss[bot]@users.noreply.github.com>
Co-authored-by: warp-for-oss[bot] <277970191+warp-for-oss[bot]@users.noreply.github.com>
The wording fixes for the Key terms list and the Foreman name example were already applied via accepted GitHub suggestions. This adds the remaining review item: positive test coverage in test_factory_proper_noun.py for the new singular "Warp Factory" branch, including the Warp Factory MCP exemption. Co-Authored-By: Warp <agent@warp.dev>
… pass - Trim the Key terms section on the overview to only the concepts not already defined in prose above (foreman, Foreman name, Factory MCP), cutting redundant Warp Factories/factory/work item bullets - Relabel the Key terms diagram's edge from the literal '@foreman name' to '@handle', since the field name isn't what you actually type - Standardize on '@-mentions in Slack and Linear' (was 'from Slack and Linear' in quickstart) - Update how-factories-work.mdx's frontmatter description to the renamed stages (was still 'specification, implementation') - Fix a run-on sentence and restore parallel stage-name phrasing in the stage summary ('works the Reviewing stage', not 'works Reviewing') - Fix inconsistent capitalization where 'building' was used as a lowercase verb alongside the capitalized 'Planning' stage, in both how-factories-work.mdx and factory-agents.mdx - Align troubleshooting.mdx's two stage references, which still said 'implementation' after the rest of the site was renamed to Building Co-Authored-By: Warp <agent@warp.dev>
…rrenk/factory-terminology
| - **task** (Factory MCP) — Factory MCP's name for a work item. The MCP tools are named for it (`send_task`, `get_task`, `complete_task`), so the term is unavoidable on that page. | ||
| *Usage note:* Not a second concept. Use "task" only where the MCP surface forces it, and say once on the page that a task is the factory's work item. Never introduce "task" as a distinct unit of work. | ||
|
|
||
| - **stages** — The phases a work item moves through, named as the factory dashboard's **Activity** view names them: **Triage**, **Planning**, **Building**, and **Reviewing**, plus the terminal stages **Complete** and **Cancelled**. |
There was a problem hiding this comment.
i started a thread to ask about this, unsure about what the best practices here are: https://warpdev.slack.com/archives/C0BKN323MPA/p1787681929335989
- Drop Factory MCP from the Key terms glossary: it's a developer
surface for exchanging work with a factory, not a conceptual
primitive alongside factory/foreman, per Slack discussion with
Hong Yi and Rachael. Factory MCP still gets its own dedicated page
and its warp-factory naming note stays there, where it's relevant.
- Move Key terms from right after the opening concept section down to
just before Next steps, so it reads as a closing reference rather
than the first thing a new reader hits
- Rewrite the section's lead sentence to be more direct and less
hedgy ('Setup names a factory and its foreman the same thing by
default, so it's easy to read them as one entity. They're not:')
- Leave the stage-name vs. agent-name question untouched per Hong
Yi's open Slack thread; the existing explicit mapping stays as-is
until that's resolved
Co-Authored-By: Warp <agent@warp.dev>
…rrenk/factory-terminology
There was a problem hiding this comment.
Overview
This PR aligns Factory activity terminology with the dashboard and extends the style-lint rule for singular "Warp Factory" usage. The stage labels and new linter coverage are correct, but the change cannot be accepted while active human review questions remain unresolved.
Concerns
The PR changes rendered documentation but includes no attached visual proof: its verification text refers to a screenshot without embedding a screenshot or video artifact. Attach current proof of the rendered documentation surface to the PR and task record.
Three unresolved threads from hongyi-chen require human resolution before merge: terminology guidance under discussion in Slack, the new prose's editorial tone, and the Key terms section's information architecture. This review does not resolve or decide those questions.
Verdict
Checks: CI ✅ · typecheck ✅ · build ✅ · internal links ✅ · style-lint regressions ✅ · local Trunk lint unavailable (CI passed)
Found: 0 critical, 1 important, 0 suggestions
Request changes
Prior bot concern: the linter coverage gap is addressed on the current head by explicit singular "Warp Factory" regression cases; its thread remains for the author to resolve.
Review run
https://oz.staging.warp.dev/runs/01a03b34-e82f-7bcd-9944-d733fbdbaa5c
There was a problem hiding this comment.
Overview
This re-review confirms that the Key terms section is now concise and placed near the end of the overview, and that the terminology and linter changes pass their deterministic checks. The current PR still lacks the required visual-proof artifact for its rendered user-facing documentation changes.
Concerns
The PR description does not embed a screenshot or video demonstrating the rendered Factory overview and Foreman name changes. Attach current visual proof to the PR that shows the revised Key terms section and the Foreman name guidance before merge.
Verdict
Checks: CI ✅ · typecheck ✅ · build ✅ · internal links ✅ · style-lint regression ✅ · rendered preview ✅ · PR visual proof ❌
Found: 0 critical, 1 important, 0 suggestions
Request changes
Prior concerns: the editorial-tone and Key terms-placement threads are resolved; the stage-name discussion remains deliberately open.
Review run
https://oz.staging.warp.dev/runs/01a03b3e-473a-74d9-8bd3-473006773142
|
Visual verification: Rendered Key terms section and Mermaid diagram from the locally served PR head. |
There was a problem hiding this comment.
Overview
The revised Key terms content is concise, renders correctly immediately before Next steps, and the attached local screenshot verifies the rendered Mermaid diagram. The stage-name discussion remains deliberately open and does not block this review.
Verdict
Checks: CI ✅ · typecheck ✅ · build ✅ · internal links ✅ · style-lint regression ✅ · rendered preview ✅ · visual proof ✅
Found: 0 critical, 0 important, 0 suggestions
Approve
Review run
https://oz.staging.warp.dev/runs/01a03b3e-473a-74d9-8bd3-473006773142
Summary
Customers are conflating three related but distinct things: a factory, its foreman agent, and the Factory MCP server. This is partly self-inflicted — factory setup gives a factory and its foreman the same name by default — and partly because no page defines the three terms together, so a reader who lands on any single Factories page only sees one piece of the picture.
This PR adds a canonical definition point and fixes the specific spots where the confusion is created or reinforced, without introducing a new standalone glossary page.
Changes
src/content/docs/factories/index.mdx
src/content/docs/factories/factory-agents.mdx
src/content/docs/factories/quickstart.mdx
src/content/docs/factories/factory-mcp.mdx
warp-factoryis a name the reader chooses in their own MCP client config, unrelated to any factory's name or foreman handlesrc/content/docs/factories/how-factories-work.mdx
src/content/docs/platform/mcp.mdx, src/content/docs/reference/cli/mcp-servers.mdx
.agents/skills/style_lint/style_lint.py
check_factory_proper_noun's "preceded by Warp" exemption so it only protects "Warp Factories" (the plural product name is never matched by the\bFactory\bregex in the first place) instead of also silently allowing the incorrect singular "Warp Factory".agents/references/terminology.md
alias, task (Factory MCP's term), stages (dashboard names), andwarp-factory(the MCP client key)Content design plan
Audience and JTBD: A team evaluating or onboarding to Warp Factories who needs to know what a "factory" is versus its "foreman" versus "Factory MCP" before they can talk about their setup without ambiguity.
Problem: Customer feedback reported confusion between foreman, factory, and
@warp-factory. The docs never defined the three terms in one place, and factory setup deliberately makes a factory's name and its foreman's @-mention handle identical without flagging that they're different things.Goals:
warp-factoryis a name they chose, not a factory identifier.Purpose and value: Directly addresses reported customer confusion; reduces support burden from users misusing @-mentions or misreading MCP config examples as factory-specific.
Content type: Feature documentation (combined) — the Key terms section is conceptual, the Foreman name and Factory MCP notes are procedural clarifications on existing task-oriented pages.
Skill and template:
draft_feature_doc— existing pages updated in place; no new pages created.High-impact scenarios:
warp-factoryMCP key, task vs. work item terminology, and stage-name alignment with the dashboard.aliasfield's interaction with GitHub-backed vs. Warp-managed factories — not part of the reported confusion and already covered by the existing factory-as-code reference.Unverified claims
warp-internal/warp-serversource.factory-dashboard.mdxpage (**Identity** - The factory's name, avatar, and Foreman name), not independently re-verified against a live build in this session.aliasdefinition key, Factory MCP tool names, MCP client config format) were carried over verbatim from existing, previously-shipped docs content rather than newly sourced.Co-Authored-By: Warp agent@warp.dev