docs: clarify factory, foreman, and Factory MCP terminology

[rachaelrenk]

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

• Added a Key terms section defining factory, foreman, Foreman name, work item, and Factory MCP together, with a small diagram showing the foreman living inside one factory and Slack/Linear mentions and Factory MCP as two separate ways in
• De-duplicated the work item/factory definitions that previously lived in "What is a software factory?" now that Key terms owns them

src/content/docs/factories/factory-agents.mdx

• Added a Foreman name subsection under Foreman explaining the @-mention handle, that setup copies it from the factory's name, and that the two are still separate concepts
• Updated stage names in prose to match the dashboard (Planning/Building instead of spec/implementation stage)

src/content/docs/factories/quickstart.mdx

• Step 4 now states the consequence of naming collision explicitly at the point it's created, instead of only noting that Foreman name gets set

src/content/docs/factories/factory-mcp.mdx

• Added a note clarifying that warp-factory is a name the reader chooses in their own MCP client config, unrelated to any factory's name or foreman handle
• Added a note reconciling "task" (this page's term) with "work item" (the term everywhere else)

src/content/docs/factories/how-factories-work.mdx

• Renamed stages in the diagram and prose to match the factory dashboard's Activity view: Specification → Planning, Implementation → Building, Review and verification → Reviewing

src/content/docs/platform/mcp.mdx, src/content/docs/reference/cli/mcp-servers.mdx

• Fixed the incorrect singular "a Warp Factory" (bare capitalized) to "a factory" in both places it appeared

.agents/skills/style_lint/style_lint.py

• Narrowed 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\b regex in the first place) instead of also silently allowing the incorrect singular "Warp Factory"

.agents/references/terminology.md

• Added entries for Foreman name / alias, task (Factory MCP's term), stages (dashboard names), and warp-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:

• A reader can state the difference between a factory, its foreman, and Factory MCP after reading the overview.
• A reader who names their factory during setup understands they're also naming (by default) their foreman's handle.
• A reader connecting Factory MCP understands warp-factory is 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:

• Covers: the factory/foreman name collision at setup, the warp-factory MCP key, task vs. work item terminology, and stage-name alignment with the dashboard.
• Excludes: the Factory MCP alias field'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

• Dashboard stage names (Triage, Planning, Building, Reviewing, Complete, Cancelled) — confirmed directly from a screenshot of the live Activity page filter provided during this task, not from warp-internal/warp-server source.
• Settings > Identity menu path for Foreman name — taken from the existing factory-dashboard.mdx page (**Identity** - The factory's name, avatar, and Foreman name), not independently re-verified against a live build in this session.
• All other claims (the alias definition 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

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 25, 2026 4:01pm

[warp-for-oss]

@rachaelrenk

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 /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[warp-for-oss]

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 @payments is the factory name, but the @ form is the Slack/Linear mention handle; the factory name itself would be payments.
• The factory-proper-noun linter behavior changes without adding regression coverage to the existing test_factory_proper_noun.py cases.

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

[warp-for-oss]

⚠️ [IMPORTANT] This changes the linter to flag singular 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.