diff --git a/.agents/references/terminology.md b/.agents/references/terminology.md index 4b9e956a2..d0b91fdc4 100644 --- a/.agents/references/terminology.md +++ b/.agents/references/terminology.md @@ -182,10 +182,10 @@ catches the literal, `platform-determiner` catches a missing article. *Example:* With the Automation Platform, you can orchestrate multiple agents to automate and parallelize complex workflows. - **cloud agent dashboard** — The app surface to manage all runs, unified across the Warp app and web. - *Usage note:* Platform-level default (HYC, 2026-08-17). Use `{VARS.DASHBOARD}`. On pages specifically about a factory, write "Factory dashboard" directly. Lowercase common noun, so capitalize only at the start of a sentence or bullet — which the variable cannot do, so reword rather than leading a bullet with it. + *Usage note:* Platform-level default (HYC, 2026-08-17). Use `{VARS.DASHBOARD}`. On pages specifically about a factory, write "factory dashboard" directly. Both are lowercase common nouns, so capitalize only at the start of a sentence or bullet — which the variable cannot do, so reword rather than leading a bullet with it. - **cloud agent run** — A single execution lifecycle of an agent, including actions, outputs, and logs. Always cloud-based. - *Usage note:* This is the platform-level default (HYC, 2026-08-17). Use `{VARS.PLATFORM_RUN}`, or "Warp cloud agent run" when you need to disambiguate from another vendor's runs. On pages that are specifically about a factory, write "Factory run" directly instead — the variable holds the general term, so it cannot carry that distinction. + *Usage note:* This is the platform-level default (HYC, 2026-08-17). Use `{VARS.PLATFORM_RUN}`, or "Warp cloud agent run" when you need to disambiguate from another vendor's runs. On pages that are specifically about a factory, write "factory run" directly instead — the variable holds the general term, so it cannot carry that distinction. - **Oz web app** — The web app for configuring agents and managing runs. *Usage note:* Holds the Oz name until 2026-09-15. Use `{VARS.WEB_APP}`. @@ -278,8 +278,30 @@ Not every "Oz" in the docs is stale. These are deliberate and correct until ## Warp Factories terminology -- **Warp Factories** — Warp's product for deploying and operating cloud software factories: automation loops around the SDLC where cloud agents triage, spec, implement, review, and verify work, with humans in the loop at key decision points. Launches in closed beta ~2026-08-18. - *Usage note:* Capitalize both words as the product name; plural "Factories." Distinct from "software factory" (see below), the generic industry term for the pattern. +### The product/instance rule + +This works like GitHub Actions. **Warp Factories** is the product and is always +written in full. An individual **factory** is a common noun and is always +lowercase. A bare capitalized **Factory** is never a proper noun — there is no +such product. + +- ✅ "Warp Factories is in Early Access" (the product) +- ✅ "your factory", "each factory's agents", "set up a factory" (an instance) +- ✅ "factory dashboard", "factory run", "factory agents", "factory definition" +- ❌ "the Factory", "your Factory", "Factory runs", "Factory metrics" +- ❌ "Factories" on its own to mean the product — write "Warp Factories" + +Sentence-initial capitals are positional, not proper nouns: a heading, sidebar +label, or page title may begin "Factory agents" or "Factory dashboard" for the +same reason it would begin "Cloud agents." The rule governs mid-sentence prose. + +Verbatim product strings are quoted as they ship, even when they break the rule. +The setup wizard currently renders **Factory name**, **Add your Factory to your +team**, and "Factory running!", and the sidebar renders **Factory definition**. +Docs match the screen; the fix belongs in the app. + +- **Warp Factories** — Warp's product for deploying and operating cloud software factories: automation loops around the SDLC where cloud agents triage, spec, implement, review, and verify work, with humans in the loop at key decision points. Launched in Early Access 2026-08-18. + *Usage note:* Capitalize both words as the product name; plural "Factories." Always write it in full — never a bare "Factory" or "Factories." Distinct from "software factory" (see below), the generic industry term for the pattern. - **software factory** — The generic, lowercase industry term for an automation loop around the SDLC (triage, spec, implement, review, verify). Warp Factories is Warp's product implementation of this pattern. *Usage note:* Lowercase when used generically ("a software factory," "cloud software factories"). Capitalize only when part of the product name "Warp Factories." @@ -294,10 +316,10 @@ Not every "Oz" in the docs is stale. These are deliberate and correct until - **foreman agent** — The orchestrator agent that receives a work item's triggering context and dispatches subagents to move it through the factory, choosing model, harness, and context for each step. - **Factory MCP** — The MCP server that lets any coding agent or MCP client interact with a factory: push work in, pull status, or guide sessions. - *Usage note:* Capitalize as a feature/proper-noun name. + *Usage note:* The one sanctioned exception to the product/instance rule above, because it is the feature's own shipped name — the server registers as `warp-factory` and its skill calls itself "the Warp Factory MCP." Capitalize both words; do not generalize the exception to other phrases. -- **control room** — The web app view showing all factory agent runs, work item status, automations, and configuration for a given factory. - *Usage note:* Lowercase common noun unless referring to a specific labeled UI element. +- **factory dashboard** — The web app surface for operating a single factory: its work items, runs, agents, automations, and settings. + *Usage note:* Lowercase common noun. Distinct from **Dashboard**, the metrics page inside it, which is also the factory's landing page — bold **Dashboard** when you mean that page, and leave "factory dashboard" unbolded when you mean the surface. Replaced "control room," a docs-only coinage that appeared nowhere in the product. - **AI sovereignty** — Warp Factories' positioning around customer ownership and control of inference, hosting, and data exhaust (agent conversations, evals, memories) for their factory. diff --git a/.agents/skills/style_lint/SKILL.md b/.agents/skills/style_lint/SKILL.md index ae442c1f3..94c45f25f 100644 --- a/.agents/skills/style_lint/SKILL.md +++ b/.agents/skills/style_lint/SKILL.md @@ -60,6 +60,7 @@ python3 .agents/skills/style_lint/style_lint.py --all --fix --create-pr - **Deprecated terminology**: "whitelist" (→ "allowlist"), "blacklist"/"blocklist" (→ "denylist") - **External product names**: "Github" (→ "GitHub"), "github actions" (→ "GitHub Actions"), "MacOS" (→ "macOS"), "A.I." (→ "AI") - **Unrecognized terms** (warning): Bolded terms that look like product names but aren't in `terminology.md`. Flags candidates for glossary addition — not errors, just suggestions. +- **Warp Factories naming**: A bare capitalized "Factory" used as a proper noun. "Warp Factories" is the product and is written in full; an individual "factory" is lowercase. Sentence-, heading-, bullet-, quote-, and cell-initial capitals are positional and stay, as do frontmatter titles and labels, the shipped feature name "Factory MCP", and verbatim UI strings such as **Factory name** and **Add your Factory to your team**. Regression cases live in `test_factory_proper_noun.py`. - **Hardcoded product name strings**: Product name strings that have a corresponding key in `src/data/vars.ts` but appear as literal text rather than variable syntax. Reports instances of known strings like "Oz CLI", "Oz web app", "oz.warp.dev", "Oz dashboard", "Oz run" (any value currently in `src/data/vars.ts`) in body prose and frontmatter. These are flagged as `⚠️ [IMPORTANT]` in PR context and reported (not auto-fixed) — they should use `{VARS.KEY}` in prose and `{{TOKEN}}` in frontmatter. ## Auto-fix behavior @@ -72,6 +73,16 @@ When run with `--fix`: This skill checks broader formatting and terminology. The `validate_ui_refs` skill validates UI paths and Command Palette names against the warp-internal codebase. They complement each other with no overlap. Both can run in scheduled cloud agent workflows. +## Tests + +Two checks have regression suites, because both are narrow rules where the hard +part is not firing on legitimate text. Run them after touching either check: + +```bash +python3 .agents/skills/style_lint/test_platform_determiner.py +python3 .agents/skills/style_lint/test_factory_proper_noun.py +``` + ## Dependencies Requires Python 3.7+. Optional: `requests` (for Slack notifications), `gh` CLI (for PR creation). diff --git a/.agents/skills/style_lint/style_lint.py b/.agents/skills/style_lint/style_lint.py index dc5441517..7b685bc39 100644 --- a/.agents/skills/style_lint/style_lint.py +++ b/.agents/skills/style_lint/style_lint.py @@ -1163,6 +1163,101 @@ def check_platform_determiner(lines: List[str], filepath: str) -> List[Issue]: return issues +# "Warp Factories" is the product; a "factory" is an instance. A bare +# capitalized "Factory" is never a proper noun, with two classes of exception: +# the feature's own name (Factory MCP) and verbatim product strings the docs +# quote from the app. Both are matched on the word that FOLLOWS "Factory". +FACTORY_ALLOWED_NEXT_WORDS = { + # Feature name, shipped as such: the server registers as `warp-factory`. + "MCP", + # Verbatim UI strings. Changing these would make the docs disagree with the + # screen, so they are quoted as-is until the app copy changes. + "name", # **Factory name** field in the setup wizard + "definition", # **Factory definition** sidebar tab + "integrations", # **Factory integrations** section in Settings + "running", # "Factory running!" on the setup summary screen +} +# Whole phrases that are correct despite containing a bare "Factory": verbatim +# UI strings the docs quote, and references to unrelated products that happen to +# be named Factory. +FACTORY_ALLOWED_PHRASES = ( + "Add your Factory to your team", # verbatim setup wizard heading + "Factory's CLI coding agent", # Factory.ai, the company behind Droid +) +FACTORY_BARE = re.compile(r"\bFactory\b") +# Markup that can sit between the start of a sentence and the word itself: +# heading hashes, list bullets, blockquotes, emphasis, link text, quotes, and +# table cell pipes. Stripped before deciding whether the position is initial. +FACTORY_LEADING_MARKUP = re.compile(r"[\s*_\[\(\"'|>#\-\u2014\u2013]+$") + + +def check_factory_proper_noun(lines: List[str], filepath: str) -> List[Issue]: + """Flag a bare capitalized "Factory" used as a proper noun. + + The rule works like GitHub Actions: "Warp Factories" is the product and is + always written in full, an individual "factory" is a lowercase common noun, + and there is no product called "Factory". See AGENTS.md -> Warp Factories + terminology. + + Quiet by construction, because most capitalized "Factory" occurrences are + legitimate: + * "Warp Factories" and "Warp Factory" -- the product name + * sentence-, heading-, bullet-, link-, quote-, and cell-initial position, + where the capital is positional rather than a proper noun + * fenced code blocks, inline code, link targets, and HTML attributes + * frontmatter, whose titles and sidebar labels are headline-style + * the exceptions in FACTORY_ALLOWED_NEXT_WORDS and + FACTORY_ALLOWED_PHRASES + """ + issues = [] + in_code_block = False + in_frontmatter = False + for i, line in enumerate(lines, 1): + stripped = line.strip() + if i == 1 and stripped == "---": + in_frontmatter = True + continue + if in_frontmatter: + if stripped == "---": + in_frontmatter = False + continue + if stripped.startswith("```"): + in_code_block = not in_code_block + continue + if in_code_block or "Factory" not in line: + continue + if any(phrase in line for phrase in FACTORY_ALLOWED_PHRASES): + continue + # Strip inline code, link targets, and HTML/JSX attributes: a slug like + # `/factories/factory-as-code/` or an `alt="..."` value is not prose. + prose = re.sub(r"`[^`]*`", "", line) + prose = re.sub(r"\]\([^)]*\)", "]", prose) + prose = re.sub(r'\w+="[^"]*"', "", prose) + for m in FACTORY_BARE.finditer(prose): + before = prose[:m.start()] + after = prose[m.end():] + if before.rstrip().endswith("Warp"): + continue # "Warp Factories" / "Warp Factory" + # Strip the markup between the sentence start and the word, then ask + # whether anything is left. Nothing left means the capital is + # positional; a preceding clause means it is being used as a name. + prefix = FACTORY_LEADING_MARKUP.sub("", before) + if not prefix or prefix.endswith((".", "!", "?", ":", "|", "—")): + continue + nxt = re.match(r"\s+(\w+)", after) + if nxt and nxt.group(1) in FACTORY_ALLOWED_NEXT_WORDS: + continue + issues.append(Issue( + filepath, i, "factory-proper-noun", + 'Bare "Factory" used as a proper noun. "Warp Factories" is the ' + 'product and is written in full; an individual factory is ' + 'lowercase. Write "factory" (or "Warp Factories" if you mean ' + "the product).", + "warning", + )) + return issues + + # Cache glossary terms once at module level _glossary_cache: Optional[set] = None @@ -1193,6 +1288,7 @@ def run_all_checks(filepath: Path) -> List[Issue]: issues.extend(check_deprecated_terms(lines, str(filepath))) issues.extend(check_hardcoded_vars(lines, str(filepath))) issues.extend(check_platform_determiner(lines, str(filepath))) + issues.extend(check_factory_proper_noun(lines, str(filepath))) issues.extend(check_unrecognized_terms(lines, str(filepath), _get_glossary())) return issues diff --git a/.agents/skills/style_lint/test_factory_proper_noun.py b/.agents/skills/style_lint/test_factory_proper_noun.py new file mode 100644 index 000000000..43fab69be --- /dev/null +++ b/.agents/skills/style_lint/test_factory_proper_noun.py @@ -0,0 +1,100 @@ +#!/usr/bin/env python3 +"""Regression cases for check_factory_proper_noun. + +Run from the repo root: + python3 .agents/skills/style_lint/test_factory_proper_noun.py + +The rule is narrow: "Warp Factories" is the product, an individual "factory" is +a lowercase common noun, and a bare capitalized "Factory" is never a proper +noun. Almost all of the difficulty is in NOT firing, because a capital F is +usually positional rather than a name -- headings, sidebar labels, bullets, +table cells, quoted terms, and link text all start with one legitimately. + +The first draft of this check produced 9 hits across the docs and 8 of them +were wrong: heading-initial ("## Factory-definition pull request checks"), +list-initial link text ("* [Factory dashboard](...)"), frontmatter labels, a +quoted term at the start of a sentence, a verbatim UI string ("Add your Factory +to your team"), and a reference to Factory.ai, the company behind Droid. Each +of those is a case below. If you touch the check, run this first. +""" +import importlib.util +import pathlib +import sys + +HERE = pathlib.Path(__file__).parent +spec = importlib.util.spec_from_file_location("style_lint", HERE / "style_lint.py") +style_lint = importlib.util.module_from_spec(spec) +spec.loader.exec_module(style_lint) + +CASES = [ + # (text, should_flag, description) + # --- genuine proper-noun uses --- + ("See [Factory agents](/factories/factory-agents/) for the roles.", True, + "mid-sentence link text"), + ("Every Factory gets its own Slack app.", True, + "mid-sentence, standing in for the product"), + ("Runs started by the Factory are tracked.", True, + "definite article plus a capital"), + ("Review the Factory metrics before deciding.", True, + "mid-sentence attributive use of the banned form"), + # --- the product name, written correctly --- + ("Warp Factories is in Early Access.", False, "the product name"), + ("Connect Warp Factories to your repository.", False, "product name mid-sentence"), + # --- positional capitals --- + ("## Factory-definition pull request checks", False, "heading-initial"), + ("### Factory agents", False, "subheading-initial"), + ("* [Factory dashboard](/factories/factory-dashboard/) - the surface.", False, + "list-initial link text"), + ("Factory setup doesn't choose models for you.", False, "sentence-initial"), + ('"Factory dashboard" names the whole surface.', False, "quoted term, sentence-initial"), + ("| **Factory definition** | The definition files |", False, "table-cell-initial"), + ("The tab is read-only. Factory owners can still edit it.", False, + "initial after a sentence boundary"), + # --- sanctioned exceptions --- + ("Send work through the Factory MCP.", False, "Factory MCP is the shipped feature name"), + ("Enter a **Factory name**, such as `Payments`.", False, "verbatim UI field label"), + ("The **Factory definition** tab lists the files.", False, "verbatim UI tab label"), + ("1. In factory setup, go to **Add your Factory to your team**.", False, + "verbatim UI string, allowlisted as a phrase"), + ("* **Droid** — Factory's CLI coding agent", False, + "Factory.ai, an unrelated company"), + # --- non-prose --- + ("Fetch `/api/v1/Factory/source` for the definition.", False, "inline code"), + ('Factory settings page', False, "HTML attribute"), +] + +FRONTMATTER_CASE = ( + ['---', 'title: Factory dashboard', 'sidebar:', ' label: "Factory agents"', '---', + 'The factory dashboard is the web app for one factory.'], + False, + "frontmatter titles and labels are headline-style", +) + + +def main() -> int: + failures = 0 + for text, should_flag, description in CASES: + flagged = bool(style_lint.check_factory_proper_noun(text.split("\n"), "test.mdx")) + ok = flagged == should_flag + if not ok: + failures += 1 + print(f" [{'PASS' if ok else 'FAIL'}] {description:<48} flagged={flagged}") + + lines, should_flag, description = FRONTMATTER_CASE + flagged = bool(style_lint.check_factory_proper_noun(lines, "test.mdx")) + ok = flagged == should_flag + if not ok: + failures += 1 + print(f" [{'PASS' if ok else 'FAIL'}] {description:<48} flagged={flagged}") + + total = len(CASES) + 1 + print() + if failures: + print(f"{failures} of {total} cases regressed.") + return 1 + print(f"All {total} cases behave correctly.") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/AGENTS.md b/AGENTS.md index f2b52050c..b22336adb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -686,9 +686,9 @@ Write the name as `{VARS.WARP_AUTOMATION_PLATFORM}` in body prose or `{{WARP_AUT - **subagent** - A child agent created by a parent agent to parallelize or delegate work - **conversation** - An interactive execution lifecycle within the Warp Terminal, regardless of whether it's local or in the cloud - **Automation Platform** - Warp's programmable platform for running and coordinating agents at scale -- **cloud agent run** - A single execution lifecycle of an agent, including actions, outputs, and logs. Always cloud-based. Use `{VARS.PLATFORM_RUN}`. On factory-specific pages, write "Factory run" directly. +- **cloud agent run** - A single execution lifecycle of an agent, including actions, outputs, and logs. Always cloud-based. Use `{VARS.PLATFORM_RUN}`. On factory-specific pages, write "factory run" directly. - **Environment** - The execution context for an agent, including repo access, dependencies, secrets, compute, and runtime configuration -- **cloud agent dashboard** - The app surface to manage all runs, unified across the Warp app and web. Use `{VARS.DASHBOARD}`. On factory-specific pages, write "Factory dashboard" directly. +- **cloud agent dashboard** - The app surface to manage all runs, unified across the Warp app and web. Use `{VARS.DASHBOARD}`. On factory-specific pages, write "factory dashboard" directly. - **Oz web app** - The web app for configuring agents and managing runs. Holds the Oz name until 2026-09-15; use `{VARS.WEB_APP}`. #### Oz CLI commands @@ -724,6 +724,21 @@ The platform is not something you address — it runs and coordinates agents, an - ❌ A bare "Automation Platform" in a referential position → Add "the". See [The article rule](#the-article-rule). - ❌ The literal string "Automation Platform" in prose → Use `{VARS.WARP_AUTOMATION_PLATFORM}` / `{{WARP_AUTOMATION_PLATFORM}}`. +### Warp Factories terminology + +This works like GitHub Actions. **Warp Factories** is the product and is always written in full. An individual **factory** is a common noun and is always lowercase. A bare capitalized **Factory** is never a proper noun. + +- ✅ "Warp Factories is in Early Access" (the product) +- ✅ "your factory", "each factory's agents", "factory dashboard", "factory run", "factory agents" +- ❌ "the Factory", "your Factory", "Factory runs", "Factory metrics" +- ❌ "Factories" on its own to mean the product → write "Warp Factories" + +Sentence-initial capitals are positional, not proper nouns — a heading or sidebar label may begin "Factory agents" for the same reason it would begin "Cloud agents." The rule governs mid-sentence prose. `style_lint` enforces it with the `factory-proper-noun` check. + +**Exceptions, quoted as they ship:** **Factory MCP** is the feature's own name (the server registers as `warp-factory`). Verbatim UI strings — **Factory name**, **Foreman name**, **Factory integrations**, **Add your Factory to your team**, "Factory running!", and the **Factory definition** sidebar label — are quoted as the app renders them. + +See `.agents/references/terminology.md` → "Warp Factories terminology" for the full glossary. + ### Technical terms - **AI** (not "A.I.") - **allowlist** / **denylist** (not "whitelist" / "blocklist") diff --git a/src/content/docs/factories/automation-filters.mdx b/src/content/docs/factories/automation-filters.mdx index dd899e5cf..6a64b4419 100644 --- a/src/content/docs/factories/automation-filters.mdx +++ b/src/content/docs/factories/automation-filters.mdx @@ -30,13 +30,11 @@ Filters are still your main control over who starts runs. On GitHub and GitLab, Every source filters on where the event happened — a repository, project, conversation, or team. The remaining filters vary by source and event type: -{/* TODO: link the GitLab row to /factories/integrations/gitlab/ once the GitLab integration page lands (PR #549). */} - | Source | Filters | | --- | --- | | [Slack](/factories/integrations/slack/) | Conversations, authors or members, keywords, emoji, and reacted-message authors | | [GitHub](/factories/integrations/github/) | Repository, branches, base branches, paths, labels, authors, assignees, mentioned users or teams, reviewers, review states, workflows, and conclusions | -| GitLab | Project, actions, and base branch | +| [GitLab](/factories/integrations/gitlab/) | Project, actions, and base branch | | [Linear](/factories/integrations/linear/) | Teams, labels, project, workflow state, assignee, mentioned user, and, for comment events, a specific issue | | [Jira](/factories/integrations/jira/) | Jira projects and assignment keywords | @@ -44,9 +42,9 @@ Each integration guide lists which filters appear on which event types. ## Edit filters on an automation -1. In the factory's control room, open **Automations**, then create an automation or edit an existing one. +1. In the factory's dashboard, open **Automations**, then create an automation or edit an existing one. 2. Under **Triggers**, open a trigger and set the filters shown for its event. Click **More filters** for the event-specific options. -3. Click **Save**. To confirm the routing works, send a matching test event, such as opening a test issue, and check that a work item starts in the control room. +3. Click **Save**. To confirm the routing works, send a matching test event, such as opening a test issue, and check that a work item starts in the factory dashboard. Review the default automations Warp creates when you connect a provider, too: their filters are starting points, not fixed rules. @@ -78,6 +76,6 @@ The same matching rules apply: every key must match, any listed value within a k ## Related pages * [Connect your factory](/factories/connect-your-factory/) - Choose the sources that route work into the factory. -* [Slack](/factories/integrations/slack/), [GitHub](/factories/integrations/github/), [Linear](/factories/integrations/linear/), and [Jira](/factories/integrations/jira/) integration guides - Per-source setup, events, and filter details. +* [Slack](/factories/integrations/slack/), [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), [Linear](/factories/integrations/linear/), and [Jira](/factories/integrations/jira/) integration guides - Per-source setup, events, and filter details. * [Definitions as code](/factories/factory-as-code/) - Manage automations, triggers, and filters as version-controlled files. -* [Control room](/factories/control-room/) - Create and edit automations in the factory's **Automations** view. +* [Factory dashboard](/factories/factory-dashboard/) - Create and edit automations in the factory's **Automations** view. diff --git a/src/content/docs/factories/connect-your-factory.mdx b/src/content/docs/factories/connect-your-factory.mdx index 8626c7ba3..100eb419e 100644 --- a/src/content/docs/factories/connect-your-factory.mdx +++ b/src/content/docs/factories/connect-your-factory.mdx @@ -17,6 +17,7 @@ Pick the sources that match where work starts for your team. You can connect mor | --- | --- | --- | | [Slack](/factories/integrations/slack/) | Chat and support requests | The Slack thread or DM | | [GitHub](/factories/integrations/github/) | Issues, pull requests, reviews, and CI | The issue, pull request, or review thread | +| [GitLab](/factories/integrations/gitlab/) | Merge request activity and bot mentions | The merge request thread | | [Linear](/factories/integrations/linear/) | Planned issues | The Linear issue and its agent session | | [Jira](/factories/integrations/jira/) | Work items assigned to Warp | The Jira agent session | | [Factory MCP](/factories/factory-mcp/) | Sending work from a local coding agent | The factory work item | @@ -50,6 +51,7 @@ Every request then lands with the foreman agent, the factory's orchestrator. The When you create a factory through the setup wizard, Warp adds default automations for each tool you connect, so common requests work immediately: * **GitHub** - Starts work when the factory is mentioned or assigned, and follows up when pull requests close or merge, completing a linked tracker issue when it can. See the [GitHub integration guide](/factories/integrations/github/). +* **GitLab** - Starts work when someone mentions the factory's bot in a merge request comment. See the [GitLab integration guide](/factories/integrations/gitlab/). * **Jira** - Starts work when someone assigns or mentions Warp on a work item in one of the Jira projects you selected. See the [Jira integration guide](/factories/integrations/jira/). * **Linear** - Starts work when a new agent session arrives from one of the Linear teams you selected. See the [Linear integration guide](/factories/integrations/linear/). * **Slack** - Starts work from mentions and messages, as described in the [Slack integration guide](/factories/integrations/slack/). @@ -60,6 +62,7 @@ These defaults are starting points. Review each automation's filters, agent, and * [Slack](/factories/integrations/slack/) - Route chat requests, direct messages, and thread follow-ups through a dedicated factory app. * [GitHub](/factories/integrations/github/) - Route repository events with issue, pull request, review, or CI context. +* [GitLab](/factories/integrations/gitlab/) - Route merge request events and bot mentions through a per-factory service account. * [Linear](/factories/integrations/linear/) - Route planned issues through issue activity and agent sessions. * [Jira](/factories/integrations/jira/) - Route Jira work items assigned to Warp into factory work. diff --git a/src/content/docs/factories/factory-agents.mdx b/src/content/docs/factories/factory-agents.mdx index c5e9bd6aa..9cfcbb537 100644 --- a/src/content/docs/factories/factory-agents.mdx +++ b/src/content/docs/factories/factory-agents.mdx @@ -62,12 +62,12 @@ Each default agent also has its own [Auto-memory store](/agents/agent-memory/). ## Configure agent behavior -Use the agent editor in the [control room](/factories/control-room/) to change an agent's description, model, runner, host, MCP servers, secrets, and instructions. +Use the agent editor in the [factory dashboard](/factories/factory-dashboard/) to change an agent's description, model, runner, host, MCP servers, secrets, and instructions. You can also manage the whole factory as version-controlled code, with [factory definition files](/factories/factory-as-code/) in a Git repository, where changes get the same review, history, and rollback as any other code. A few agent settings can only be set in the files: harness, environment, and credential strategy. Where the repository lives determines how the two editing paths work together: -* **Warp-managed repository** - Edit agents in the agent editor, or edit the definition files directly in the control room's **Code** tab, whichever fits the change. Both write to the same files, so the editor and the code always agree. -* **A GitHub repository your team owns** - The files are the only way to change the factory. Edits go through pull requests, and the file-owned settings in the control room are read-only. +* **Warp-managed repository** - Edit agents in the agent editor, or edit the definition files directly in the factory dashboard's **Factory definition** tab, whichever fits the change. Both write to the same files, so the editor and the code always agree. +* **A GitHub repository your team owns** - The files are the only way to change the factory. Edits go through pull requests, and the file-owned settings in the factory dashboard are read-only. Factory setup doesn't choose models for you. To change the model a role uses, edit that agent. diff --git a/src/content/docs/factories/factory-as-code.mdx b/src/content/docs/factories/factory-as-code.mdx index 3563a3e58..c9ee726f2 100644 --- a/src/content/docs/factories/factory-as-code.mdx +++ b/src/content/docs/factories/factory-as-code.mdx @@ -17,7 +17,7 @@ Definition files are YAML and Markdown. Keys are case-sensitive. You choose who hosts the definition repository when you create a factory: -* **Warp-managed (default)** - Warp hosts the repository for you. You edit the factory in the [{VARS.FACTORY_WEB_APP}](/factories/control-room/), and every change is validated, committed to the files, and applied in one step. You never interact with the repository directly, and the definition can't end up in an invalid state. +* **Warp-managed (default)** - Warp hosts the repository for you. You edit the factory in the [{VARS.FACTORY_WEB_APP}](/factories/factory-dashboard/), and every change is validated, committed to the files, and applied in one step. You never interact with the repository directly, and the definition can't end up in an invalid state. * **GitHub** - The definition lives in a repository you own. The repository is the only way to change the factory: the web app shows the configuration read-only and links back to the files. Open a pull request, and any change merged to the production branch (`main` by default) updates the factory. See [Pull request checks](#pull-request-checks-for-github-backed-factories). Both modes use the same files, so everything on this page applies to either. You can also link a GitHub repository to a Warp-managed factory later. @@ -78,7 +78,7 @@ Optional. What the factory is for. ### `alias` -Optional. The handle used to @-mention the factory's foreman on connected platforms like Slack and Linear; the control room labels this field **Foreman name**. Up to 60 characters: letters, numbers, spaces, `.`, `_`, and `-`. Must be unique across your workspace (compared case-insensitively). +Optional. The handle used to @-mention the factory's foreman on connected platforms like Slack and Linear; the factory dashboard labels this field **Foreman name**. Up to 60 characters: letters, numbers, spaces, `.`, `_`, and `-`. Must be unique across your workspace (compared case-insensitively). ### `credentialStrategy` @@ -86,7 +86,7 @@ Optional. Whose credentials the factory's runs execute with: `EXECUTOR` (the pri ### `repositories` -Required. The GitHub repositories the factory works in, as `owner` and `name` pairs. +Required. The repositories the factory works in, as `owner` and `name` pairs. On a GitLab-backed factory these are the projects you selected under the connected group. ```yaml repositories: @@ -218,7 +218,7 @@ The frontmatter accepts: ### `agentType` -The agent's role: `CUSTOM` (the default), `FOREMAN` (alias `MAIN`), `TRIAGE`, `SPEC`, `IMPLEMENT`, `REVIEW`, or `VERIFY`. Every definition declares exactly one foreman — the factory's entry point and the default target for automations. See [Factory agents](/factories/factory-agents/) for what each role does. +The agent's role: `CUSTOM` (the default), `FOREMAN` (alias `MAIN`), `TRIAGE`, `SPEC`, `IMPLEMENT`, `REVIEW`, or `VERIFY`. Every definition declares exactly one foreman — the factory's entry point and the default target for automations. See [factory agents](/factories/factory-agents/) for what each role does. ## `automations//automation.md` @@ -254,13 +254,14 @@ Required. One or more events that start runs. Each trigger declares a `provider` The providers and their events: * `github` - `issue_created`, `issue_labeled`, `issue_assigned`, `issue_mentioned`, `pull_request_opened`, `pull_request_closed`, `pull_request_merged`, `pull_request_labeled`, `pull_request_assigned`, `pull_request_mentioned`, `pull_request_ready`, `pull_request_reopened`, `pull_request_synchronized`, `pull_request_review_requested`, `pull_request_review_submitted`, `push`, `check_suite_completed`, `check_run_rerequested`, `check_suite_rerequested`, `workflow_run_completed` +* `gitlab` - `merge_request`, `bot_mentioned` * `linear` - `issue_created`, `issue_labeled`, `issue_assigned`, `issue_state_changed`, `comment_created`, `agent_session_created` * `jira` - `issue_created`, `issue_labeled`, `status_changed`, `agent_session_created` * `slack` - `app_mention`, `message_posted`, `message_dm`, `message_im`, `message_mpim`, `member_joined_channel`, `reaction_added` * `schedule` - `cron_fired` * `factory` - `work_item_stage_changed` -Slack, Linear, and Jira triggers require the matching [integration](/platform/integrations/) to be connected. GitHub triggers work through the factory's `repositories`. +Slack, Linear, and Jira triggers require the matching [integration](/platform/integrations/) to be connected. GitHub triggers work through the factory's `repositories`, and GitLab triggers through the group connected to your workspace — see the [GitLab integration](/factories/integrations/gitlab/). ### `triggers[].filter` diff --git a/src/content/docs/factories/control-room.mdx b/src/content/docs/factories/factory-dashboard.mdx similarity index 76% rename from src/content/docs/factories/control-room.mdx rename to src/content/docs/factories/factory-dashboard.mdx index 04cc0e875..db9059ff2 100644 --- a/src/content/docs/factories/control-room.mdx +++ b/src/content/docs/factories/factory-dashboard.mdx @@ -1,13 +1,17 @@ --- -title: Factory control room +title: Factory dashboard description: >- Track work items, inspect runs, read factory metrics, and manage agents, - automations, and settings from the control room. + automations, and settings from the factory dashboard. sidebar: - label: "Control room" + label: "Factory dashboard" --- -The control room is the web app for operating a single factory. Use it to track the work your agents are doing, inspect the runs and pull requests they produce, and manage the agents, automations, and settings the factory owns. +The factory dashboard is the web app for operating a single factory. Use it to track the work your agents are doing, inspect the runs and pull requests they produce, and manage the agents, automations, and settings the factory owns. + +:::note +"Factory dashboard" names the whole surface. **Dashboard**, in bold, is one page inside it — the metrics page a factory opens on. +::: ## Pages at a glance @@ -15,7 +19,7 @@ Select a factory in the sidebar to open its pages. **Runs**, **MCPs and apps**, | Page | What it shows | What you do there | | --- | --- | --- | -| **Dashboard** | Factory metrics: autonomy, PR cycle time, cost, and run volume | Compare periods and find work worth investigating | +| **Dashboard** | The factory's metrics: autonomy, PR cycle time, cost, and run volume | Compare periods and find work worth investigating | | **Activity** | Work items grouped by stage | Search, filter, open, and stop work items | | **Agents** | The factory's agent roster | Create and edit agents | | **Automations** | Triggers that start runs | Create, edit, and delete automations | @@ -23,9 +27,11 @@ Select a factory in the sidebar to open its pages. **Runs**, **MCPs and apps**, | **Scorers** | Scorer definitions and results | Define rubrics and review classifications | | **Self-improvement** | Pull requests filed to fix Scorer-detected failures | Review fix PRs and open the runs behind them | | **Benchmarks** | Benchmark suites and their runs | Compare harness, model, and runner configurations | -| **Code** | The factory's definition files | Browse and edit a Warp-managed definition | +| **Factory definition** | The factory's definition files | Browse and edit a Warp-managed definition | | **Settings** | Configuration the factory owns | Change identity, repos, runners, and the integrations the factory can access | +**Dashboard** is where a factory opens. **Factory definition** appears only on Warp-managed factories, since a factory whose definition lives in your own repository is edited there instead. + ## Track work items on Activity **Activity** shows the factory's work items grouped by stage: Triage, Planning, Building, and Reviewing. Finished work items move to two terminal stages, Complete and Cancelled. @@ -48,9 +54,9 @@ Click **New** on a factory's **Runs** page to send a prompt to the factory's for Run pages don't include a chat input, but you can still steer a run: **View session** opens its [shared agent session](/platform/viewing-cloud-agent-runs/), where you follow the agent in real time and send follow-up instructions while the run's environment is active. After the environment shuts down, the same button opens the conversation transcript. ::: -## Read dashboard metrics +## Read metrics on the Dashboard page -**Dashboard** summarizes the factory over a date range you choose: +**Dashboard** is the factory's landing page. It summarizes the factory over a date range you choose: * **Autonomy** - The share of the factory's merged PRs that needed no human input beyond an approving review and the merge itself. * **PR cycle time** - The median time the factory's merged PRs took from run kickoff through PR, first review, and merge, with a median for each stage. @@ -64,15 +70,15 @@ The page also charts opened versus merged PRs and a breakdown of runs, and the * Environment is set in the factory definition, not the agent editor, and automations never override execution settings. When the factory's definition lives in an external repository, Agents, Automations, and Scorers are read-only; make changes there through pull requests. -## Edit definitions in the Code tab +## Edit definitions in the Factory definition tab -**Code** is the control room's view of the factory's definition files, which [Factory definitions as code](/factories/factory-as-code/) describes in full. What the tab offers depends on where the definition lives: +**Factory definition** is the factory dashboard's view of the definition files that [definitions as code](/factories/factory-as-code/) describes in full. Where the definition lives decides what you get: * **Warp-managed** - Browse and edit the definition files. Saving validates the definition and commits all changes together. -* **Managed in GitHub** - Links to the repository; edit the definition through pull requests there. +* **Managed in GitHub** - The tab doesn't appear. Edit the definition through pull requests in your repository, and **Settings** links back to it. * **Live-managed** - The factory is managed through the API, so there are no definition files to browse. -When an agent proposes a change to a Warp-managed definition, its work item on **Activity** links to a review of the branch inside the control room. From there, comment on the diff, use **Request changes** to send feedback back to the agent, or **Approve & merge**. +When an agent proposes a change to a Warp-managed definition, its work item on **Activity** links to a review of the branch inside the factory dashboard. From there, comment on the diff, use **Request changes** to send feedback back to the agent, or **Approve & merge**. ## Score and benchmark @@ -89,5 +95,7 @@ For a file-managed factory, `runners/*.yaml` in the repository is the source of ## Next steps * [How Warp Factories work](/factories/how-factories-work/) - The lifecycle behind Activity's stages and where humans stay in the loop. -* [Factory definitions as code](/factories/factory-as-code/) - Define agents, automations, runners, and source ownership in code. -* [Measure and improve a factory](/factories/measure-and-improve/) - Configure the Scorers and benchmarks behind the Dashboard. +* [Definitions as code](/factories/factory-as-code/) - Define agents, automations, runners, and source ownership in code. +* [Factory agents](/factories/factory-agents/) - What each default role does and how to configure it. +* [Measure and improve a factory](/factories/measure-and-improve/) - Configure the Scorers and benchmarks behind the **Dashboard** page. +* [Troubleshooting Warp Factories](/factories/troubleshooting/) - Fixes for setup problems, work that doesn't start, and stuck runs. diff --git a/src/content/docs/factories/factory-mcp.mdx b/src/content/docs/factories/factory-mcp.mdx index 3556b65dd..e0fb37a8d 100644 --- a/src/content/docs/factories/factory-mcp.mdx +++ b/src/content/docs/factories/factory-mcp.mdx @@ -10,7 +10,7 @@ topic: factories Factory MCP is a hosted Model Context Protocol (MCP) server that connects coding agents to your Warp Factories. With it, the agent you already work with, in Warp or in any MCP-capable tool, can send work to a factory, pick up a factory task to continue locally, and hand the finished work back. -The factory keeps a single record of each task throughout. Whether a change happens in the cloud or on your machine, it lands on the same task with the same history and conversation. A task is the factory's work item: the same unit of work that appears in the control room's [Activity view](/factories/control-room/#track-work-items-on-activity). +The factory keeps a single record of each task throughout. Whether a change happens in the cloud or on your machine, it lands on the same task with the same history and conversation. A task is the factory's work item: the same unit of work that appears in the factory dashboard's [Activity view](/factories/factory-dashboard/#track-work-items-on-activity). ## What you can use it for @@ -19,7 +19,7 @@ The factory keeps a single record of each task throughout. Whether a change happ * **Stay in sync** - List and search tasks, read a task's conversation, and message its [foreman](/factories/factory-agents/), the agent that orchestrates each task inside the factory. * **Create a factory** - Set up a new factory when you know the team, repositories, and source-control details. -Factory MCP is one of several ways work enters a factory, alongside Slack, Linear, Jira, and GitHub. See [connect your factory](/factories/connect-your-factory/) for all intake paths and [how Warp Factories work](/factories/how-factories-work/) for how tasks move through a factory. +Factory MCP is one of several ways work enters a factory, alongside Slack, GitHub, GitLab, Linear, and Jira. See [connect your factory](/factories/connect-your-factory/) for all intake paths and [how Warp Factories work](/factories/how-factories-work/) for how tasks move through a factory. ## Connect and authenticate @@ -106,7 +106,7 @@ Sending work to a factory means you're no longer watching it. To be notified whe ## Tool reference -Factory MCP exposes these ten tools. Your MCP client fetches the full input schemas from the server, and tool results include links that open the corresponding task or run in the factory's [control room](/factories/control-room/). +Factory MCP exposes these ten tools. Your MCP client fetches the full input schemas from the server, and tool results include links that open the corresponding task or run in the factory's [factory dashboard](/factories/factory-dashboard/). | Tool | What it does | | --- | --- | @@ -123,7 +123,7 @@ Factory MCP exposes these ten tools. Your MCP client fetches the full input sche ## Related pages -* [Connect your factory](/factories/connect-your-factory/) - Every way work can enter a factory, including the Slack, Linear, Jira, and GitHub integrations. +* [Connect your factory](/factories/connect-your-factory/) - Every way work can enter a factory, including the Slack, GitHub, GitLab, Linear, and Jira integrations. * [Factory agents](/factories/factory-agents/) - The foreman and the other agents that carry out a factory's tasks. * [How Warp Factories work](/factories/how-factories-work/) - The task lifecycle and the agents that move work through it. * [Warp Factories quickstart](/factories/quickstart/) - Create a factory and send it its first work item. diff --git a/src/content/docs/factories/how-factories-work.mdx b/src/content/docs/factories/how-factories-work.mdx index 9dabcb127..6f4ea36f8 100644 --- a/src/content/docs/factories/how-factories-work.mdx +++ b/src/content/docs/factories/how-factories-work.mdx @@ -54,7 +54,7 @@ A work item and an agent run track different things. The work item is the single The work item's **stage** shows progress at a glance. It reflects the most recently active role, so it can move backward during a revision or skip ahead. Run history is the complete execution record. -In the [control room](/factories/control-room/), use the **Activity** view to find, filter, and stop work items. Activity groups these stages under its own names: Triage, Planning (specification), Building (implementation), and Reviewing. +In the [factory dashboard](/factories/factory-dashboard/), use the **Activity** view to find, filter, and stop work items. Activity groups these stages under its own names: Triage, Planning (specification), Building (implementation), and Reviewing. ## What humans decide diff --git a/src/content/docs/factories/index.mdx b/src/content/docs/factories/index.mdx index eb05f3372..9ea6910c8 100644 --- a/src/content/docs/factories/index.mdx +++ b/src/content/docs/factories/index.mdx @@ -11,7 +11,7 @@ import { VARS } from '@data/vars'; Warp Factories lets engineering teams define and operate **software factories**, cloud workflows where specialized agents move engineering work from intake to a reviewed pull request. Your team sets the policy and makes the final decisions; the factory does the repetitive work and records the evidence you need to improve it. :::note -Warp Factories is in **Early Access** and available to a limited set of teams. +Warp Factories is in **Early Access** and available to a limited set of teams. [Request access](https://www.warp.dev/factories/request-access) to use it with your team. ::: ## What is a software factory? @@ -31,10 +31,10 @@ Warp Factories is designed for engineering teams with repeatable work that exten ## What you get with Warp Factories * **Coordinated specialist agents** - A team of [factory agents](/factories/factory-agents/) runs each work item. A coordinating foreman routes it through the triage, spec, implement, and review roles, skipping stages that don't apply. You can add custom agents and automations to handle work the default roles don't cover. -* **Factory definitions as code** - [Version-controlled definition files](/factories/factory-as-code/) describe your repositories, agents, automations, runners, skills, and MCP servers, so factory changes get the same review, history, and rollback as code changes. -* **Integrations and the Factory MCP** - Work flows in from [Slack](/factories/integrations/slack/), [Linear](/factories/integrations/linear/), [Jira](/factories/integrations/jira/), and [GitHub](/factories/integrations/github/), plus direct runs and schedules. The [Factory MCP](/factories/factory-mcp/) connects coding agents and other MCP clients. +* **Definitions as code** - [Version-controlled definition files](/factories/factory-as-code/) describe your repositories, agents, automations, runners, skills, and MCP servers, so factory changes get the same review, history, and rollback as code changes. +* **Integrations and the Factory MCP** - Work flows in from [Slack](/factories/integrations/slack/), [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), [Linear](/factories/integrations/linear/), and [Jira](/factories/integrations/jira/), plus direct runs and schedules. The [Factory MCP](/factories/factory-mcp/) connects coding agents and other MCP clients. * **Model and harness choice** - Each agent role can use a different model and [supported harness](/platform/harnesses/), including the Warp Agent, Claude Code, and Codex. -* **Measurement and self-improvement** - The [control room](/factories/control-room/) shows work-item status, runs, automations, costs, and benchmarks. [Scorers](/factories/measure-and-improve/) grade completed work, and [Self-improvement](/factories/measure-and-improve/#configure-and-review-self-improvement) turns repeated failures into follow-up work the factory proposes for review. +* **Measurement and self-improvement** - The [factory dashboard](/factories/factory-dashboard/) shows work-item status, runs, automations, costs, and benchmarks. [Scorers](/factories/measure-and-improve/) grade completed work, and [Self-improvement](/factories/measure-and-improve/#configure-and-review-self-improvement) turns repeated failures into follow-up work the factory proposes for review. * **Infrastructure control** - Run on Warp-hosted infrastructure, or self-host execution on an eligible Enterprise plan. Teams can also connect supported inference providers, scope secrets, and (if eligible) store transcripts, artifacts, and run attachments in their own S3 or GCS buckets. See [infrastructure and security](/factories/infrastructure-and-security/) for the available controls. ## How Warp Factories relates to other Warp products diff --git a/src/content/docs/factories/infrastructure-and-security.mdx b/src/content/docs/factories/infrastructure-and-security.mdx index 76f1b43d6..b65465d73 100644 --- a/src/content/docs/factories/infrastructure-and-security.mdx +++ b/src/content/docs/factories/infrastructure-and-security.mdx @@ -40,10 +40,10 @@ Two configurations define where and how a factory's agents work: You don't manage a factory's environment directly: each factory implicitly manages one based on the repositories configured in its [definition](/factories/factory-as-code/). Runners are the choice you make. When a run starts, Warp resolves its compute in a fixed order: the runner the run selects explicitly, then the environment's execution defaults, then the system default. See [environments](/platform/environments/) for the underlying workspace model and the [runner reference](/platform/runners/) for compute options and resolution behavior. -The **Runners** page in the [control room](/factories/control-room/) shows each runner's operating system and architecture, setup commands, size, and whether it's the default. Where you edit runners depends on where the factory's source lives: +The **Runners** section of a factory's **Settings** page in the [factory dashboard](/factories/factory-dashboard/) shows each runner's operating system and architecture, setup commands, size, and whether it's the default. Where you edit runners depends on where the factory's source lives: * **Externally managed source** - The `runners/*.yaml` files in the connected repository are the source of truth, and edits open in that repository. -* **Warp-managed source** - Authorized users create and edit runner files directly in the control room. +* **Warp-managed source** - Authorized users create and edit runner files directly in the factory dashboard. Your team's plan sets the default instance shape (vCPUs and memory) for Warp-hosted runners. The same maximum shape applies on every plan, and Warp rejects hosted shapes above it. Enterprise teams that need more can request a higher maximum. Managed self-hosted runners are exempt from the hosted maximum because your team supplies the compute. diff --git a/src/content/docs/factories/integrations/github.mdx b/src/content/docs/factories/integrations/github.mdx index b6e43201d..d037948fc 100644 --- a/src/content/docs/factories/integrations/github.mdx +++ b/src/content/docs/factories/integrations/github.mdx @@ -1,8 +1,8 @@ --- title: Connect GitHub to your factory description: >- - Connect a factory to GitHub so issues, pull requests, reviews, and CI events - start factory work and results post back to GitHub. + Connect GitHub to your factory so issues, pull requests, reviews, and CI + events start factory work and results post back to GitHub. sidebar: label: "GitHub" topic: factories @@ -20,11 +20,11 @@ When you connect a factory to GitHub, repository activity starts work in your fa 1. In the {VARS.FACTORY_WEB_APP} at platform.warp.dev, click **+** next to **Factories** to open the setup wizard, then choose **I want to use repos from GitHub** under **Connect your code host**. 2. Under **Select your repos**, choose the repositories to provide code and context for the factory. -3. In the factory's [control room](/factories/control-room/), click **Automations**. Create an automation or edit a default one, choose the receiving agent, and add any **Additional instructions**. +3. In the factory's [dashboard](/factories/factory-dashboard/), click **Automations**. Create an automation or edit a default one, choose the receiving agent, and add any **Additional instructions**. 4. Under **Triggers**, click **Add trigger**. 5. Choose **GitHub**, then choose an event. 6. Select a repository, then use **More filters** to narrow which activity matches. -7. Click **Save**. To confirm the automation works, trigger a matching event in GitHub, such as opening a test issue, and check that a work item starts in the control room. +7. Click **Save**. To confirm the automation works, trigger a matching event in GitHub, such as opening a test issue, and check that a work item starts in the factory dashboard. Managed GitHub factories start with two editable default automations. The first handles agent mentions and assignments (see [Mention the factory](#mention-the-factory)). The second runs when a pull request closes or merges: on a merge it finds the work items linked from the pull request and moves each one to its tracker's completed state, and on a close without a merge it does nothing. diff --git a/src/content/docs/factories/integrations/gitlab.mdx b/src/content/docs/factories/integrations/gitlab.mdx index 1d4671d5e..feafc5252 100644 --- a/src/content/docs/factories/integrations/gitlab.mdx +++ b/src/content/docs/factories/integrations/gitlab.mdx @@ -1,7 +1,7 @@ --- -title: Connect a factory to GitLab +title: Connect GitLab to your factory description: >- - Connect a factory to GitLab so merge request events and bot mentions start + Connect GitLab to your factory so merge request events and bot mentions start factory work and results post back as comments and merge requests. sidebar: label: "GitLab" @@ -32,10 +32,10 @@ The connected group's webhook delivers merge request and comment events to Warp, 2. Choose **I want to use repos from GitLab** under **Connect your code host**, then authorize with GitLab when prompted. 3. Under **Connect a GitLab group**, pick a top-level group you own and click **Next**. Warp creates the manager service account and installs the group webhook. A group that is already connected shows a **Connected** badge, and the selection is locked to it. 4. Under **Select your repos**, choose the projects to provide code and context for the factory. Projects anywhere under the connected group, including subgroups, are available. -5. In the factory's [control room](/factories/control-room/), click **Automations**. GitLab factories start with an editable default automation, **gitlab-bot-mentions**, that fires when the factory's bot is mentioned. +5. In the factory's [dashboard](/factories/factory-dashboard/), click **Automations**. GitLab factories start with an editable default automation, **gitlab-bot-mentions**, that fires when the factory's bot is mentioned. 6. To route merge request events too, create an automation and click **Add trigger**. 7. Choose **GitLab**, then choose **Merge request**. -8. To confirm the connection works, comment on a merge request in a selected project and mention the factory's bot. A work item starts in the control room, and the factory replies in the same thread. +8. To confirm the connection works, comment on a merge request in a selected project and mention the factory's bot. A work item starts in the factory dashboard, and the factory replies in the same thread. ## Supported triggers @@ -70,7 +70,7 @@ Each GitLab factory has its own bot account, so the mention itself routes the re 1. Open a merge request in one of the factory's projects. 2. Post a comment that mentions the factory's bot username and includes an instruction. -The **gitlab-bot-mentions** automation starts a work item, and the factory replies in the same thread. To find the bot's username, check that automation's trigger in the [control room](/factories/control-room/). +The **gitlab-bot-mentions** automation starts a work item, and the factory replies in the same thread. To find the bot's username, check that automation's trigger in the [factory dashboard](/factories/factory-dashboard/). Mentions count only in new comments. Edits and activity from Warp's own service accounts never trigger work, so a factory can't re-trigger itself or a sibling factory. @@ -113,7 +113,9 @@ triggers: Triage newly opened merge requests and post an initial review. ``` -A `bot_mentioned` trigger takes only a `repos` filter. Leave `mentioned` out. Warp seeds it with the factory's bot username and rejects definitions that set it. Factory definitions hosted in GitLab repositories sync the same way GitHub-hosted ones do. +A `bot_mentioned` trigger takes only a `repos` filter. Leave `mentioned` out. Warp seeds it with the factory's bot username and rejects definitions that set it. + +A GitLab-backed factory can still be managed as code, but the definition itself lives either in Warp or in a GitHub repository — GitLab is not yet available as a definition host. See [where the definition lives](/factories/factory-as-code/#where-the-definition-lives). ## Troubleshooting diff --git a/src/content/docs/factories/integrations/jira.mdx b/src/content/docs/factories/integrations/jira.mdx index f01dc4776..1ec29369d 100644 --- a/src/content/docs/factories/integrations/jira.mdx +++ b/src/content/docs/factories/integrations/jira.mdx @@ -1,8 +1,8 @@ --- title: Connect Jira to your factory description: >- - Connect Jira Cloud to a factory so work items assigned to Warp start factory - runs and return results in Jira. + Connect Jira Cloud to your factory so work items assigned to Warp start + factory runs and return results in Jira. sidebar: label: Jira topic: factories @@ -28,7 +28,7 @@ Connect Jira Cloud to your factory so your team can start factory work without l 3. Connect Jira to your factory. Connecting the workspace in step 2 makes Jira available to every factory in it, but each factory still needs its own connection: in the factory's **Settings** tab, find **Jira** and click **Connect** (or **Install** if the workspace itself isn't connected yet). Select the Jira projects that should trigger this factory, then click **Enable**. This declares the `jira` integration for the factory. Without it, **Jira** in the automation editor's **Add trigger** menu stays a disabled "not connected" entry that links back to this step. -4. Add a Jira trigger to an automation. In the control room, open the factory's **Automations** tab, then open an automation (or create a new one). Click **Add trigger**, choose **Jira**, and select **Agent session created**. Set **Projects** and, optionally, **Keywords** to scope which sessions start a run, then set the automation's agent to the one that should handle matching requests. +4. Add a Jira trigger to an automation. In the factory's dashboard, open **Automations**, then open an automation (or create a new one). Click **Add trigger**, choose **Jira**, and select **Agent session created**. Set **Projects** and, optionally, **Keywords** to scope which sessions start a run, then set the automation's agent to the one that should handle matching requests. If you selected Jira projects when you created the factory, Warp already added an automation scoped to those projects; edit that automation instead of creating a second one. diff --git a/src/content/docs/factories/integrations/linear.mdx b/src/content/docs/factories/integrations/linear.mdx index dabd6b147..fd9533f80 100644 --- a/src/content/docs/factories/integrations/linear.mdx +++ b/src/content/docs/factories/integrations/linear.mdx @@ -1,7 +1,7 @@ --- title: Connect Linear to your factory description: >- - Connect Linear to a factory so issues flow into your software factory and + Connect Linear to your factory so planned issues flow in automatically and progress flows back to the issue. sidebar: label: "Linear" diff --git a/src/content/docs/factories/integrations/slack.mdx b/src/content/docs/factories/integrations/slack.mdx index 2eec09303..695695efe 100644 --- a/src/content/docs/factories/integrations/slack.mdx +++ b/src/content/docs/factories/integrations/slack.mdx @@ -1,7 +1,7 @@ --- title: Connect Slack to your factory description: >- - Connect a factory to Slack so your team can start work with mentions, + Connect Slack to your factory so your team can start work with mentions, direct messages, and automations, and get results back in the same thread. sidebar: label: "Slack" @@ -57,7 +57,7 @@ Automations don't run as a requester: they run as the factory agent selected und Use a factory automation to start work from Slack activity automatically, without anyone mentioning the app. For example, an automation can act on every message posted in a triage channel or on a specific emoji reaction. -1. In the factory's control room, open **Automations**, then create or edit an automation. +1. In the factory's dashboard, open **Automations**, then create or edit an automation. 2. Under **Triggers**, click **Add trigger** > **Slack**, then choose an event. 3. Select the conversations and people that the event must match. Click **More filters** to add the event's available content filters. 4. Choose the receiving agent under **Agents**, add any **Additional instructions**, then click **Save**. @@ -78,7 +78,7 @@ A single Slack message can match more than one automation. For example, if one a The Slack thread where work started is also where you follow it: the factory posts progress and the final response there. Reply in the thread to add information or attachments while work is active, or to pick the same work item back up later. -For an overview of the factory's work items, open the app's **Home** tab in Slack. It groups them by the same stages as the control room's [Activity view](/factories/control-room/#track-work-items-on-activity) (Triage, Planning, Building, Reviewing, Completed, and Cancelled), offers stage and date filters, and links each work item back to its Slack thread, factory run, issue, or pull request when available. +For an overview of the factory's work items, open the app's **Home** tab in Slack. It groups them by the same stages as the factory dashboard's [Activity view](/factories/factory-dashboard/#track-work-items-on-activity) (Triage, Planning, Building, Reviewing, Completed, and Cancelled), offers stage and date filters, and links each work item back to its Slack thread, factory run, issue, or pull request when available. A factory can create issues, branches, and pull requests, but your repository's review and merge rules still apply. Work that starts in Slack doesn't bypass required human review. diff --git a/src/content/docs/factories/measure-and-improve.mdx b/src/content/docs/factories/measure-and-improve.mdx index b7b5ea7c1..2f3c4f3e6 100644 --- a/src/content/docs/factories/measure-and-improve.mdx +++ b/src/content/docs/factories/measure-and-improve.mdx @@ -17,9 +17,9 @@ Warp Factories tracks what your factory produces and how well it performs, so yo | Benchmarks | How different configurations perform on the same tasks. | | Self-improvement | Which repeated failures get investigated and turned into follow-up work. | -## Read dashboard metrics +## Read metrics on the Dashboard page -The control room dashboard shows activity, cost, autonomy, and evaluation results: +The **Dashboard** page shows activity, cost, autonomy, and evaluation results: | Metric | What it shows | | --- | --- | diff --git a/src/content/docs/factories/quickstart.mdx b/src/content/docs/factories/quickstart.mdx index e8eb29506..ace6e7db4 100644 --- a/src/content/docs/factories/quickstart.mdx +++ b/src/content/docs/factories/quickstart.mdx @@ -1,49 +1,74 @@ --- title: Warp Factories quickstart description: >- - Set up a factory, connect GitHub, and submit your first work item in about - 10 minutes. + Set up a factory, connect your repositories, and take your first work item + from prompt to pull request in about 10 minutes. sidebar: label: "Quickstart" --- import { VARS } from '@data/vars'; -A factory is a team of cloud agents: a foreman you talk to, plus the subagents it dispatches. Together they turn incoming requests into pull requests for your team to review. In this quickstart, you will create a factory, connect a GitHub repository, and take one small work item from prompt to pull request in about 10 minutes. +A factory is a team of cloud agents: a foreman you talk to, plus the subagents it dispatches. Together they turn incoming requests into pull requests for your team to review. In this quickstart, you will create a factory and take one small work item from prompt to pull request in about 10 minutes. + +## What you'll decide + +Warp walks you through factory setup in a wizard, so the work is deciding four things rather than learning a form: + +* **Which code the factory works on** - the code host and the set of repositories. +* **What it's called** - the factory's name, and the handle your team @-mentions to reach its foreman. +* **Which agents it runs** - the subagents the foreman can dispatch. +* **Where work comes from** - optionally, a chat tool and an issue tracker. + +Every one of these is editable afterward, so pick something reasonable and keep moving. ## Prerequisites +* **Warp Factories access** - Warp Factories is in Early Access. [Request access](https://www.warp.dev/factories/request-access) if your team doesn't have it yet. * **A Warp team with credits** - A factory belongs to a [Warp team](/knowledge-and-collaboration/teams/). Factory agents consume the team's [credits](/support-and-community/plans-and-billing/platform-credits/). -* **GitHub repository access** - Authorize GitHub and choose repositories during setup. If your organization restricts app installations, ask a GitHub organization owner to approve the connection. See the [GitHub integration](/platform/integrations/github/) for details. +* **Repository access** - You authorize a code host during setup and choose which repositories the factory can reach. If your organization restricts app installations, ask an owner to approve the connection. See the [GitHub](/factories/integrations/github/) and [GitLab](/factories/integrations/gitlab/) integration guides. -## Create your factory +## Set up your factory _~5 minutes_ -1. Go to the {VARS.FACTORY_WEB_APP} at platform.warp.dev and sign in. -2. On the welcome screen, click **Let's get started** to open the setup wizard. +Sign in to the {VARS.FACTORY_WEB_APP} at platform.warp.dev and start a new factory. Setup asks you for the following. + +### Connect a code host and choose repositories + +Authorize GitHub or GitLab, then select the repositories the factory works in. + +Start with one or two. Every agent in the factory shares this repo set, so a focused set keeps their context tight, and you can add more later. Warp provisions a default [environment](/platform/environments/) for what you select. + +### Name the factory and its foreman + +**Factory name** identifies the factory in the app. **Foreman name** is the handle your team @-mentions to reach its foreman from connected tools like Slack and Linear, so keep it short and recognizable. Warp derives one from the factory name if you don't set it yourself. + +### Confirm the agent roster - If your team already has a factory, you land in the app instead of the welcome screen. In the sidebar, click **+** next to **Factories** to open the same wizard. +The foreman is always there — it's the agent you talk to. You choose which subagents it can dispatch: -3. Click **I want to use repos from GitHub** and complete the GitHub authorization. -4. Choose the repositories the factory will work in and click **Add repos**. Start with one or two repositories. Every agent in the factory shares this repo set, so a focused set keeps their context tight. +| Subagent | What it does | +| --- | --- | +| **Triage** | Accepts work from issue trackers and establishes scope | +| **Spec** | Iterates with your team to produce a spec | +| **Code** | Implements the change and opens the pull request | +| **Review** | Inspects the result and reports findings | - Warp provisions a default [environment](/platform/environments/) for the selected repos. +All four start enabled and a factory needs at least one, so this step is about turning off what you don't want yet. Leave **Code** on so this quickstart can end in a pull request. -5. Enter a **Factory name**, such as `Payments services`. Warp derives a matching **Foreman name**, the handle teammates use to @-mention the factory's foreman from connected tools like Slack and Linear. Keep it short and recognizable. -6. The next screen offers to connect Slack. Click **Next** to skip it for now. See [Connect your factory](/factories/connect-your-factory/) to add integrations later. -7. Toggle the subagents the foreman can dispatch: **Triage**, **Spec**, **Code**, and **Review**. Keep **Code** on so this quickstart's work item can end in a pull request. +See [factory agents](/factories/factory-agents/) for what each role does in depth; the roster's **Code** toggle is the Implement role on that page. - See [Factory agents](/factories/factory-agents/) for what each role does. The wizard's **Code** toggle corresponds to the Implement role on that page. +### Optionally connect Slack and an issue tracker -8. Skip the issue tracker screen the same way as Slack: click **Next**. Warp creates the factory. +Setup offers to connect a chat tool and an issue tracker, so teammates can hand work to the factory from where they already work. Skip both if you want to finish quickly — [connect your factory](/factories/connect-your-factory/) covers adding them later. - When the startup screen reports "Factory running!", click **Go to dashboard**. +Warp then creates the factory and opens its [dashboard](/factories/factory-dashboard/). -## Submit your first work item +## Send your first work item _~5 minutes_ -1. In the sidebar under your factory, open **Runs** and click **New**. +1. On your factory's **Runs** page, start a new run. 2. Describe one small, verifiable change and submit it: ```text title="Example first request" @@ -54,14 +79,14 @@ _~5 minutes_ Adapt the pattern to your repository: name the file, the change you expect, and the command that verifies it. A narrow, explicit request makes the first run easy to judge. - The foreman picks up the request as a run and dispatches your subagents as child runs. + The foreman picks up the request and dispatches your subagents as child runs. -3. Follow progress from two pages in the factory's [control room](/factories/control-room/) sidebar: +3. Follow it from two places in the factory's [dashboard](/factories/factory-dashboard/): - * **Runs** - The foreman's run and the child runs it dispatches. - * **Activity** - The work item as it moves through its stages. Open it to see its event history and pull request artifacts. + * **Runs** - the foreman's run and the child runs it dispatches. + * **Activity** - the work item as it moves through its stages. Open it for the event history and pull request artifacts. -4. When the Code agent finishes, the work item links a pull request in GitHub. Review and merge it following your normal process. +4. When the Code agent finishes, the work item links a pull request. Review and merge it the way you would any other: a factory hands off at the pull request and never merges for you. ## Next steps diff --git a/src/content/docs/factories/troubleshooting.mdx b/src/content/docs/factories/troubleshooting.mdx index 939906b65..c5e87a234 100644 --- a/src/content/docs/factories/troubleshooting.mdx +++ b/src/content/docs/factories/troubleshooting.mdx @@ -1,27 +1,33 @@ --- title: Troubleshooting Warp Factories description: >- - Fix missing GitHub repositories and agent limits during factory creation, - and stop an active factory run. + Fix factory setup problems, events that don't start work, and runs that + stall or need stopping. sidebar: label: "Troubleshooting" --- import { VARS } from '@data/vars'; -Solutions for common issues when creating and operating a factory in the {VARS.FACTORY_WEB_APP}. +Fixes for the problems teams hit most often when setting up a factory and running their first work through it. Each entry names the symptom you'd see in the {VARS.FACTORY_WEB_APP}. -For issues with a specific intake source, see the troubleshooting sections of the [Slack](/factories/integrations/slack/#troubleshooting-and-reconnection), [Linear](/factories/integrations/linear/#troubleshooting), and [Jira](/factories/integrations/jira/#troubleshooting) integration guides. For events that match but don't start work, see [automation filters](/factories/automation-filters/#troubleshooting). +## Setting up a factory -## A GitHub repository doesn't appear in the picker +### You don't have access to Warp Factories -**Cause:** The GitHub installation doesn't cover the repository. +**Cause:** Warp Factories is in Early Access and enabled per team. + +**Fix:** [Request access](https://www.warp.dev/factories/request-access) for your team. If a teammate already has it, ask a team admin to confirm you're on that team. + +### A repository doesn't appear in the picker + +**Cause:** The code host connection doesn't cover the repository. **Fix:** -1. Confirm the installation includes the repository and the intended organization. See the [GitHub integration](/platform/integrations/github/) for how the connection works. -2. If you can't update the installation yourself, ask a GitHub organization owner or a Warp team admin to update the connection. +1. Confirm the connection includes the repository and the intended organization or group. See the [GitHub](/factories/integrations/github/) and [GitLab](/factories/integrations/gitlab/) integration guides for how each connection is scoped. +2. If you can't update it yourself, ask a GitHub organization owner, a GitLab group owner, or a Warp team admin to extend the connection. -## Factory creation stops at an agent limit +### Setup stops at an agent limit **Cause:** Your team's plan limits how many factory agents it can run. @@ -30,11 +36,59 @@ For issues with a specific intake source, see the troubleshooting sections of th 1. Ask a team admin to confirm the team's capacity. 2. If the team needs more agents, [contact sales](https://www.warp.dev/contact-sales). -## You need to stop a run +## Work isn't starting + +### An event that should start work doesn't + +**Cause:** Nearly always an automation that doesn't match the event, rather than a broken connection. + +**Fix:** + +1. Confirm the automation is enabled and its trigger's event type matches what happened. +2. Check every filter on the trigger. Filters combine with AND, so a single mismatched repository, label, author, or state stops the routing. See [automation filters](/factories/automation-filters/#troubleshooting). +3. Confirm the source is connected to *this* factory. Connecting a provider to your workspace doesn't attach it to every factory in that workspace. + +Then check the causes specific to where the work came from: + +| Source | Common causes | +| --- | --- | +| [Slack](/factories/integrations/slack/#troubleshooting-and-reconnection) | The app isn't in the channel, installation is pending admin approval, or your Slack account isn't linked to a Warp team member | +| [GitHub](/factories/integrations/github/#troubleshooting) | The app installation doesn't cover the repository, or the factory's routing label is missing | +| [GitLab](/factories/integrations/gitlab/#troubleshooting) | The mention was an edit rather than a new comment, or your plan doesn't include the group webhooks that deliver events | +| [Linear](/factories/integrations/linear/#troubleshooting) | The agent session needs a linked Warp account, or teams and filters don't match | +| [Jira](/factories/integrations/jira/#troubleshooting) | The Warp app isn't connected to your workspace, or project and keyword filters don't match | + +### One action starts two runs + +**Cause:** Two automations match the same event — commonly an app-mention trigger and a channel-message trigger pointed at the same place. + +**Fix:** Narrow or remove one of the overlapping triggers so a single path owns each kind of request. See [how matching works](/factories/automation-filters/#how-matching-works). + +## Runs and work items + +### You need to stop a run + +**Fix:** Open **Activity** in your factory's [dashboard](/factories/factory-dashboard/), select the work item, and click **Stop task**. It takes effect immediately, with no confirmation prompt. + +### A work item looks stuck + +**Cause:** The factory is often waiting on a person rather than failing. By default it pauses for spec approval, for answers to clarifying questions, and at the pull request. + +**Fix:** + +1. Open the work item on **Activity** and read its event history to see which agent ran last. +2. Use **View agent** to open that agent's session, where a question waiting on a human is visible and answerable. +3. If the run's environment is still active, you can steer it directly. See [cloud agent session sharing](/platform/viewing-cloud-agent-runs/). + +### No pull request appears + +**Cause:** The factory can't push, or the work never reached implementation. -In the {VARS.FACTORY_WEB_APP}, open **Activity** in your factory's sidebar, select the work item, and click **Stop task** to stop its active run. +**Fix:** Confirm the **Code** agent is enabled on the factory, that the code host connection still grants write access to the target repository, and that the work item actually reached the implementation stage. Branch protection rules apply to everything the factory pushes. ## Related pages * [**Warp Factories quickstart**](/factories/quickstart/) - Create a factory and submit your first work item. * [**Connect your factory**](/factories/connect-your-factory/) - Route work in from Slack threads, Linear issues, and other intake paths. +* [**Automation filters**](/factories/automation-filters/) - The matching rules that decide which events start work. +* [**Factory dashboard**](/factories/factory-dashboard/) - Where to watch work items, runs, and their outputs. diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 09920dc46..8565714d8 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -81,7 +81,7 @@ The **{VARS.WARP_AUTOMATION_PLATFORM}** is Warp's programmable system for runnin A single cloud agent handles one task. **Warp Factories**, now in Early Access, lets your team run a software factory: a repeatable process where cloud agents triage, spec, implement, review, and verify work, and humans approve key decisions. -→ [Learn about Warp Factories](/factories/) +→ [Learn about Warp Factories](/factories/) or [request access](https://www.warp.dev/factories/request-access) --- diff --git a/src/content/docs/platform/overview.mdx b/src/content/docs/platform/overview.mdx index d22d0c3f6..b4f315516 100644 --- a/src/content/docs/platform/overview.mdx +++ b/src/content/docs/platform/overview.mdx @@ -55,7 +55,7 @@ In practice: **triggers create tasks; tasks execute on a host (optionally in an ### Warp Factories -[Warp Factories](/factories/) builds on the primitives described on this page to run persistent, multi-agent development workflows. A factory coordinates specialized cloud agents that move each work item through triage, specification, implementation, and review. +[Warp Factories](/factories/) builds on the primitives described on this page to run persistent, multi-agent development workflows. A factory coordinates specialized cloud agents that move each work item through triage, specification, implementation, and review. It's in Early Access — [request access](https://www.warp.dev/factories/request-access) to use it with your team. --- diff --git a/src/data/vars.ts b/src/data/vars.ts index e729085ef..eea706942 100644 --- a/src/data/vars.ts +++ b/src/data/vars.ts @@ -21,8 +21,10 @@ export const VARS = { WEB_APP: "Oz web app", // legacy Oz v1 webapp (oz.warp.dev) — holds until 9/15 WEB_APP_URL: "https://oz.warp.dev", // holds until 9/15, then "https://app.warp.dev" // Renamed per HYC (8/17), same shape as PLATFORM_RUN below: a plain - // platform-level term, with "Factory dashboard" written directly on pages - // that are specifically about a factory. + // platform-level term, with "factory dashboard" written directly on pages + // that are specifically about a factory. Lowercase: "Warp Factories" is the + // product, a "factory" is an instance, and a bare capitalized "Factory" is + // never a proper noun (AGENTS.md -> Warp Factories terminology). // // "Runs page" was the other candidate and reads better in isolation, but it // names a single page in the web app. This surface is defined as unified @@ -34,7 +36,7 @@ export const VARS = { DASHBOARD: "cloud agent dashboard", // Renamed per HYC (8/17): the platform-level default is the plain // descriptive phrase, not a branded one. Factory-specific pages should write - // "Factory run" directly rather than reaching for this variable. + // "factory run" directly rather than reaching for this variable. // // Kept singular so `{VARS.PLATFORM_RUN}s` pluralizes correctly at the call // sites that do that. diff --git a/src/sidebar.ts b/src/sidebar.ts index 43b87ec3e..d25119f0a 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -444,15 +444,21 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { // Same label as the Automation Platform tab's group for watching and // steering runs, because it covers the same ground one level up: the - // control room is where you watch a factory, and scorers are how you - // measure it. + // factory dashboard is where you watch a factory, and scorers are how + // you measure it. label: 'Management & observability', items: [ - { slug: 'factories/control-room', label: 'Control room' }, + { slug: 'factories/factory-dashboard', label: 'Factory dashboard' }, { slug: 'factories/measure-and-improve', label: 'Measure and improve' }, - { slug: 'factories/troubleshooting', label: 'Troubleshooting' }, ], }, + // Troubleshooting sits outside the groups, last in the tab. It was in + // 'Management & observability' next to the dashboard and Scorers pages, + // which read as a sibling of the measurement surfaces rather than as + // the place you go when something is broken. A bare trailing item is + // the same shape the Automation Platform tab uses for its leading + // 'Overview'. + { slug: 'factories/troubleshooting', label: 'Troubleshooting' }, ], }, {