docs(factories): Skills primitive page, Automations rename, factory sizing guidance - #632
Conversation
…sizing guidance - Add automation, runner, and scorer entries to the Warp Factories glossary in terminology.md. - State the 'one factory per product surface, not per workflow' sizing guidance explicitly on the Factories overview, cross-linked from the quickstart and Connect your factory pages. - Add a new Factory skills page covering skills/** vs. agents/<name>/skills/** scoping, built-in skills, and when to add a custom one. - Rename Automation filters to Automations and reposition it under Factory configuration as that primitive's conceptual home (was nested under Integrations); update the sidebar, cross-references, and add a redirect. 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 |
![warp-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR adds a Factory skills page, renames Automation filters to Automations, updates Factories IA/sidebar placement, and adds sizing guidance for when to create separate factories. The rename, redirect, and cross-linking approach mostly fits the docs structure, and I did not find security issues in the content/config changes.
Concerns
- The new Factory skills page says GitLab-backed definitions can be edited by opening a pull request, but the existing factory-as-code and GitLab integration docs say definition repositories are Warp-managed or GitHub-hosted only, with GitLab not yet supported as a definition host.
Verdict
Found: 0 critical, 1 important, 0 suggestions
Request changes
Comment /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
Co-authored-by: warp-for-oss[bot] <277970191+warp-for-oss[bot]@users.noreply.github.com>
![warp-agent-staging[bot]](https://avatars.githubusercontent.com/in/2196476?s=60&v=4){kind=small}
There was a problem hiding this comment.
Review
Reviewed the Factory skills page, Automations rename, navigation move, redirect, glossary additions, and all updated cross-links against the factory definition schema and existing factory documentation.
Validation passed: GitHub CI is green, npm run build completed successfully, and the internal-link checker found 0 broken links across 3,927 internal links. The full style lint currently reports 1,368 repository-baseline findings; its PR-scoped output contained only a pre-existing meta-opener in a touched file and known glossary false positives, with no new actionable finding in this diff.
Approve
- factory-skills.mdx: correct definition-repo editing to GitHub-backed only;
GitLab is not yet a supported definition host.
- integrations/github.mdx: remove unnecessary bold on 'GitHub' in prose.
- automations.mdx: reword frontmatter description ('from a trigger'); fix
the automation.md heading anchor to #automationsnameautomationmd, verified
against the deployed preview.
- index.mdx: split the overloaded sizing-guidance sentence into two.
- quickstart.mdx: move the sizing-guidance addition into a :::note callout.
Co-Authored-By: Warp <agent@warp.dev>
…to rrenk/factory-primitive-docs
…s primitives Each DIY guide already pointed to the Warp Factories overview as the managed alternative. Add more specific cross-links to the primitive page that parallels what each guide teaches: - build-a-triage-agent.mdx: Factory agents (Triage role) and the new Factory skills page. - write-product-and-tech-specs-with-agents.mdx: Factory agents (Spec role). - set-up-a-software-factory.mdx: Automations (the label-based state machine's managed equivalent) and Factory agents (all four roles). - run-a-software-factory-in-the-cloud.mdx: Infrastructure and security. build-a-self-improving-agent.mdx already links to the specific Self-improvement anchor, so it's left unchanged. No sizing-guidance callouts added to these guides -- they build one role/repo at a time, so factory-sizing isn't a relevant concept at that scope. Co-Authored-By: Warp <agent@warp.dev>
slugify_heading() stripped anything matching <...> before unwrapping code spans, so a heading like `automations/<name>/automation.md` lost its <name> placeholder and produced #automationsautomationmd instead of the anchor Starlight actually renders. Verified against the deployed preview's real heading id attributes: agents/<name>/agent.md -> #agentsnameagentmd automations/<name>/automation.md -> #automationsnameautomationmd runners/<name>.yaml -> #runnersnameyaml This was failing CI on this PR (the link-check job runs this exact script) even though the link in automations.mdx was already correct. Also fixes a pre-existing broken link in factory-as-code.mdx that used the old, incorrect #runnersyaml anchor -- unrelated to this PR's diff, found while investigating the same root cause. Co-Authored-By: Warp <agent@warp.dev>
…nability Per HYC's review feedback on the PR, plus a broader top-to-bottom pass over every new/touched file for the same issues: - factories/index.mdx: replaced the dense sizing paragraph with a new 'Sizing a factory' subheading and a bulleted list of concrete examples, instead of one long sentence stacking an em-dash clause and a parenthetical. - factories/quickstart.mdx: added a concrete example to the sizing callout. - factories/connect-your-factory.mdx: rewrote two AI-sounding passages (semicolon-heavy 'X; Y' construction, 'Filters route work, not access: ...' aphorism) into plainer sentences, cutting a point already covered in full on the Automations page. - factory-skills.mdx: tightened three more passages (nominalizations, redundant parentheticals) beyond the earlier review-comment fixes. - The 4 DIY guides: removed the repeated 'the manage- The 4 DIY guides: removed the repeated 'the manage- The 4 DIY guides: removed the repeated 'the manage- The 4 DIY guides: removed the repeated 'the muthored-By: Warp <agent@warp.dev>
| ## Configure Linear triggers | ||
|
|
||
| Agent sessions cover explicit requests. To start work automatically from issue and comment activity too, add an automation with a **Linear** trigger for one of these events: **Issue created**, **Issue labeled**, **Issue state changed**, **Issue assigned**, or **Comment created**. [Automation filters](/factories/automation-filters/#edit-filters-on-an-automation) covers the steps. | ||
| Agent sessions cover explicit requests. To start work automatically from issue and comment activity too, add an automation with a **Linear** trigger for one of these events: **Issue created**, **Issue labeled**, **Issue state changed**, **Issue assigned**, or **Comment created**. [Automation filters](/factories/automations/#edit-filters-on-an-automation) covers the steps. |
There was a problem hiding this comment.
Let's not use "covers the steps" language. Either be specific, "To learn how to [blank], see [article]" or be generic but consistent, "To learn more, see [article]".
| description: >- | ||
| Automation filters decide which events from connected tools start factory | ||
| runs: matching rules, per-source filters, and what filters don't control. | ||
| An automation starts factory runs from a trigger, routes them to an agent, |
There was a problem hiding this comment.
"filters which events qualify" sounds awkward. What about "..filters by qualifying events". Does that make sense/is that accurate to say?
There was a problem hiding this comment.
i wonder if we can just not call them filters externally? is there a better name for this perhaps? we can fix in a separate PR as well
| --- | ||
|
|
||
| Automation filters decide which events from your connected tools start factory work. Every trigger on a [factory automation](/factories/connect-your-factory/) carries filters — conditions such as a repository, channel, team, project, label, or author — and an event starts a run only when it matches them. Filters let a factory watch busy channels and repositories without acting on everything in them. | ||
| An **automation** is a factory resource that starts runs: it declares one or more triggers (an event from a connected tool, or a schedule), the agent that handles the run, and, for connected-tool triggers, the filters that decide which events qualify. Every default automation Warp creates when you connect a provider, and every custom one you add, is this same resource. See [`automations/<name>/automation.md`](/factories/factory-as-code/#automationsnameautomationmd) for the full schema. |
There was a problem hiding this comment.
Does this align with marketing language on the marketing website and blog? Is this the most plain language and direct way of defining an automation in the first sentence? I ask because "factory resource" sounds a bit vague, but maybe that's standard and easily understood by our audience? Is it necessary to say ", for connected-tool triggers," --or can we remove that and simplify the sentence?
| Automation filters decide which events from your connected tools start factory work. Every trigger on a [factory automation](/factories/connect-your-factory/) carries filters — conditions such as a repository, channel, team, project, label, or author — and an event starts a run only when it matches them. Filters let a factory watch busy channels and repositories without acting on everything in them. | ||
| An **automation** is a factory resource that starts runs: it declares one or more triggers (an event from a connected tool, or a schedule), the agent that handles the run, and, for connected-tool triggers, the filters that decide which events qualify. Every default automation Warp creates when you connect a provider, and every custom one you add, is this same resource. See [`automations/<name>/automation.md`](/factories/factory-as-code/#automationsnameautomationmd) for the full schema. | ||
|
|
||
| Automation filters decide which events from your connected tools start factory work. Every trigger on an automation carries filters — conditions such as a repository, channel, team, project, label, or author — and an event starts a run only when it matches them. Filters let a factory watch busy channels and repositories without acting on everything in them. |
There was a problem hiding this comment.
How about this?
| Automation filters decide which events from your connected tools start factory work. Every trigger on an automation carries filters — conditions such as a repository, channel, team, project, label, or author — and an event starts a run only when it matches them. Filters let a factory watch busy channels and repositories without acting on everything in them. | |
| Automation filters decide which events from your connected tools start factory work. Every trigger on an automation carries filters (e.g., a repository, channel, team, project, label, or author) and an event starts a run only when it matches them. Filters let a factory watch busy channels and repositories without acting on everything in them. |
There was a problem hiding this comment.
| An event starts an automation only when it matches the trigger's provider, event type, and filters: |
There was a problem hiding this comment.
Revise this H2. Make it shorter and remove the semicolon, should just be one direct, descriptive header. To do this we should really identify what the core goal and purpose is of this section: what's the key takeaway, and how can we say that most briefly so that the pertinent information is immediately obvious?
There was a problem hiding this comment.
Revise to remove em dash.
| @@ -9,6 +9,8 @@ sidebar: | |||
|
|
|||
| Connect your factory to the tools where your team already discusses, tracks, and reviews work. Wherever work starts, the factory keeps the original context — the thread, issue, or pull request — and posts results back to the same place. | |||
There was a problem hiding this comment.
Let's make the clause within em dashes a parenthetical clause instead. Also introduce the word "source" so that it ties to the next paragraph. Something like, "the factory keeps original context from that source (the thread, issue, or pull request), and posts results in the same place."
|
|
||
| Connect your factory to the tools where your team already discusses, tracks, and reviews work. Wherever work starts, the factory keeps the original context — the thread, issue, or pull request — and posts results back to the same place. | ||
|
|
||
| Every source below feeds into this factory's repositories. If the work belongs to a different product surface, [start a new factory](/factories/#sizing-a-factory) for it instead. |
There was a problem hiding this comment.
Since it's referencing the
| Every source below feeds into this factory's repositories. If the work belongs to a different product surface, [start a new factory](/factories/#sizing-a-factory) for it instead. | |
| Each source feeds into this factory's repositories. If the work belongs to a different product surface, [start a new factory](/factories/#sizing-a-factory) for it instead. |
There was a problem hiding this comment.
"Where follow-ups continue" is awkward. What are we really trying to say here, as plainly as possible? Where the foreman conversation happens?
| --- | ||
| title: Factory skills | ||
| description: >- | ||
| Skills give a factory's agents repeatable, version-controlled procedures, |
There was a problem hiding this comment.
might flow better as:
"Skills give a factory's agents repeatable, version-controlled procedures that can be shared across every agent or scoped to just one."
| label: "Factory skills" | ||
| --- | ||
|
|
||
| A skill is a reusable, version-controlled procedure an agent can follow. It tells an agent what to check, how to classify results, what to produce, and when to escalate. In a factory, skills are how you extend or override what the [default agents](/factories/factory-agents/) already know how to do, without editing their prompts directly. |
There was a problem hiding this comment.
First line is almost a direct repeat of the description.
Description: "Skills give a factory's agents repeatable, version-controlled procedures,"
Line 10: "A skill is a reusable, version-controlled procedure"
Also "already know how to do" is a bit wordy. Is there another more concise, but accurate, way to say this? Maybe even:
"In a factory, skills are how you extend or override default agents, without editing their prompts directly"
|
|
||
| A skill is a reusable, version-controlled procedure an agent can follow. It tells an agent what to check, how to classify results, what to produce, and when to escalate. In a factory, skills are how you extend or override what the [default agents](/factories/factory-agents/) already know how to do, without editing their prompts directly. | ||
|
|
||
| :::note |
There was a problem hiding this comment.
Move this note to the very top of the page, just after the front matter. To be consistent with this same note placement in the other factory docs.
|
|
||
| A skill changes what an agent knows how to do, not what it can reach. To scope access, configure the agent's [secrets](/platform/secrets/) and [MCP servers](/platform/mcp/) — see [factory agents](/factories/factory-agents/#configure-agent-behavior) and [infrastructure and security](/factories/infrastructure-and-security/#credential-boundaries). | ||
|
|
||
| ## Add or edit a skill |
There was a problem hiding this comment.
Should we swap the order of this section ## Add or edit a skill and the previous section, ## When to add a custom skill? Seems you would want to learn how to add first then understand when to use that functionality.
| 3. On **Select your repos**, search for and select the repositories the factory works in, then click **Add repos**. 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. | ||
|
|
||
| :::note | ||
| Group repositories by product surface, not by team or task — for example, all the repos behind one application. See [sizing a factory](/factories/#sizing-a-factory) before adding a repository another factory already covers. |
There was a problem hiding this comment.
Is there another way to say "...a repository another factory already covers". "Covers" is an odd verb. Isn't it really a repo associated with a factory, or added to a factory?
| Group repositories by product surface, not by team or task — for example, all the repos behind one application. See [sizing a factory](/factories/#sizing-a-factory) before adding a repository another factory already covers. | |
| Group repositories by product surface, not by team or task. For example, group all the repos behind one application. See [sizing a factory](/factories/#sizing-a-factory) before adding a repository another factory already covers. |
- Simplify integration guide phrasing pointing to Automations - Rewrite automations.mdx opening, filters paragraph, and H2 heading for clarity and brevity (em dash and semicolon cleanup) - Tighten connect-your-factory.mdx wording and rename a table column - Rewrite factory-skills.mdx description/intro, move Early Access note right after frontmatter - Apply reviewer-suggested sizing callout text in quickstart.mdx - Add cross-reference to factory sizing guidance from how-factories-work.mdx - Fix stale anchor in jira.mdx after automations.mdx heading rename Co-Authored-By: Warp <agent@warp.dev>
Replace em dash with a colon in the "What each source can filter on" intro sentence, per review feedback. Co-Authored-By: Warp <agent@warp.dev>
The Slack, GitHub, and Linear integration pages describe triggers by prose/UI label only, with no pointer to the exact `event:` value each one maps to in an automation.md file. Add a one-line cross-link from each page's trigger section to the existing event-slug list in factory-as-code.mdx, rather than duplicating those slugs on every page. Jira and GitLab already state their event slugs inline, so they are unchanged. Co-Authored-By: Warp <agent@warp.dev>
|
While adding cross-links from the Slack/GitHub/Linear integration pages to the canonical
Could someone with product/engineering context confirm these two mappings? Once confirmed, I can add the exact slugs inline on those two pages instead of just linking out. |
2 participants
Summary
A pass through the Warp Factories docs to close two gaps flagged by HYC: the glossary and page structure didn't fully reflect the primitive-based product philosophy (Factory, Agents, Skills, Automations, Runners, Scorers), and no page stated the team's settled "one factory per product surface, not per workflow" sizing guidance. Scope was narrowed after research showed the Factories tab (launched 2026-08-18) already documents most primitives in depth — this PR closes the remaining, specific gaps rather than reworking the section.
Changes
.agents/references/terminology.mdfactory-as-code.mdx,infrastructure-and-security.mdx, andmeasure-and-improve.mdx.src/content/docs/factories/index.mdxsrc/content/docs/factories/factory-skills.mdx(new)skills/**) vs. per-agent (agents/<name>/skills/**) scoping, built-in skills every default agent ships with, when to add a custom skill, and how self-improvement can propose skill changes.src/content/docs/factories/automations.mdx(renamed fromautomation-filters.mdx)vercel.jsonredirect from/factories/automation-filtersto/factories/automations.src/content/docs/factories/quickstart.mdx,connect-your-factory.mdxsrc/content/docs/factories/factory-agents.mdx,factory-as-code.mdxsrc/content/docs/factories/troubleshooting.mdx,integrations/{slack,github,linear,jira}.mdxsrc/sidebar.tssrc/content/docs/guides/agent-workflows/{build-a-triage-agent,write-product-and-tech-specs-with-agents,set-up-a-software-factory,run-a-software-factory-in-the-cloud}.mdxbuild-a-self-improving-agent.mdxalready linked to a specific anchor, so it's unchanged..agents/skills/check_for_broken_links/check_links.pyslugify_heading()that stripped placeholder text like<name>in headings such as`automations/<name>/automation.md`as if it were live JSX/HTML, even inside a backtick code span. Verified against the deployed preview's actual renderedidattributes, which retain the placeholder (e.g.automationsnameautomationmd). This was failing this PR's CI "Build, link-check, audit" job on an otherwise-correct link.factory-as-code.mdx(#runnersyaml→#runnersnameyaml) found via the same root cause, unrelated to this PR's original diff.Language pass (factories/index.mdx, quickstart.mdx, connect-your-factory.mdx, factory-skills.mdx, and the 4 DIY guides)
index.mdxbecame a "Sizing a factory" subheading with a bulleted example list instead of one long sentence; a repeated "the managed product's X" formula was removed from every guide's Next steps bullets, not just the one flagged; and a couple of semicolon-heavy "X; Y" / "X, not Y: Z" constructions were rewritten more plainly.Copy-editing pass (automations.mdx, connect-your-factory.mdx, factory-skills.mdx, quickstart.mdx, how-factories-work.mdx, integrations/{slack,github,linear,jira}.mdx)
automations.mdx's frontmatter description, opening paragraph, filters paragraph, and "How matching works" intro for brevity; renamed the "Filters route work; they don't restrict access" heading to "Filters don't control access" and converted an em dash to a colon.connect-your-factory.mdx's opening and "Each source feeds into..." passages; renamed a table column from "Where follow-ups continue" to "Continues in".factory-skills.mdx's frontmatter description and opening paragraph so they don't repeat each other, and moved the Early Access note to immediately after the frontmatter.quickstart.mdxsizing callout.how-factories-work.mdx, since it previously didn't mention sizing at all.jira.mdxleft over from theautomations.mdxheading rename.Event-slug cross-links (integrations/{slack,github,linear}.mdx)
event:value list infactory-as-code.mdx, closing a gap where the per-integration pages named triggers by prose/UI label only, with no way to find the exact value to write in anautomation.mdfile.jira.mdxandgitlab.mdxalready state their event slugs inline, so they're unchanged.Open questions
event:slug from the docs alone, so I linked to the existing reference table instead of restating it per page. Two spots are worth a second pair of eyes: ongithub.mdx, whether "a re-run of a Warp check" corresponds tocheck_run_rerequested,check_suite_rerequested, or both; and onslack.mdx, which ofmessage_dm,message_im, andmessage_mpim"Direct message received" is meant to cover. Flagging here rather than guessing at the mapping.Unverified claims
None — this PR only reorganizes and adds glossary/conceptual content grounded in already-published Factories docs (
factory-as-code.mdx,factory-agents.mdx,factory-dashboard.mdx,measure-and-improve.mdx). No new UI labels, Settings paths, CLI flags, or plan-eligibility claims were introduced.Additional context
style_lint.py --all(zero errors in touched files),npm run build(clean), andcheck_for_broken_links/check_links.py --internal-only(zero broken links across all 380 pages) after each round of edits.Co-Authored-By: Warp agent@warp.dev