docs(factories): document Slack integration - #525
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
9bb5910 to
6901bca
Compare
Co-Authored-By: Warp Agent <agent@warp.dev>
6901bca to
e481ca2
Compare
|
/oz-review |
|
I'm re-reviewing this pull request in response to a review request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR replaces the placeholder factory Slack integration page with documentation for connection, intake behavior, requester identity, automations, outputs, and troubleshooting. The changes are documentation-only and the attached spec context reports no approved or repository spec context for this PR.
Concerns
- No blocking concerns found in the changed documentation.
- No comments or tests were added or changed.
- No security-sensitive code or configuration changes were introduced.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
There was a problem hiding this comment.
Overview
This PR replaces the placeholder factory Slack integration page with documentation for connection, intake behavior, requester identity, automations, outputs, and troubleshooting. The changes are documentation-only and the attached spec context reports no approved or repository spec context for this PR.
Concerns
- No blocking concerns found in the changed documentation.
- No comments or tests were added or changed.
- No security-sensitive code or configuration changes were introduced.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
|
/oz-review |
|
I'm re-reviewing this pull request in response to a review request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
There was a problem hiding this comment.
Overview
This PR replaces the placeholder factory Slack page with factory-specific setup, intake, automation, continuity, output, and troubleshooting guidance. I reviewed the attached diff for documentation structure, link quality, terminology, security-sensitive statements, and implementation-vs-spec drift; no approved spec context was available for this PR.
Concerns
- No blocking concerns found in the changed diff.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
There was a problem hiding this comment.
Overview
This PR replaces the placeholder Slack factory integration page with a complete feature/procedural doc covering prerequisites, setup, Slack intake behavior, identity, automations, App Home tracking, writeback, and troubleshooting. The page stays scoped to factory-specific behavior and points readers to the existing Slack platform integration page for provider-level installation details.
Concerns
- No blocking concerns found.
- No approved or repository spec context was provided, so there is no implementation-vs-spec drift to report.
- Security pass: no code, configuration, secrets, or permission-changing implementation was introduced in the diff; the authorization boundary language is documented explicitly.
- Comment audit: no code comments or doc comments were added or changed.
- Test audit: no tests were added or changed; this documentation-only PR reports typecheck, build, and link-check validation in the PR description.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
Replace internal jargon (intake, continuity point, execution credential scope, 'conversations become work') with plain descriptions of what the reader does and what the factory does in response. No factual changes: triggers, filters, identity linking, authorization boundary, App Home stages, and writeback behavior are unchanged. Co-Authored-By: Warp <agent@warp.dev>
The dedicated app carries the factory's name and avatar and follows factory renames (FactoryAppReconciler in warp-server), so teams running several factories see a distinct Slack persona per factory and pick which one to mention in a channel. Co-Authored-By: Warp <agent@warp.dev>
- Drop the unhelpful note that the factory is still created when Slack install fails; keep only the action the user needs to take - Rename "Configure Slack automations" to "Configure factory automations for Slack" to clarify these are factory automations - Rewrite the overlapping-triggers warning to spell out how one message can match two automations and start duplicate runs Co-Authored-By: Warp <agent@warp.dev>
There was a problem hiding this comment.
[lilis agent] Reviewed against Slack's Marketplace landing-page requirements (this page is slated to become the app's landing URL) and against warp-server source.
Verified accurate against warp-server: automation event list + filters (SLACK_EVENTS), App Home stages and filters (slack_app_home.go), install-on-create with Add to Slack fallback, and the 👀 ack.
Remaining gap not covered by inline suggestions: no screenshots/GIFs. Slack expects visuals of in-Slack behavior on the landing page — at minimum a mention + ack + threaded reply, ideally the App Home tab. Suggest adding commented-out <figure> placeholders now so assets drop in before Marketplace submission.
| --- | ||
|
|
||
| Slack integration documentation for Warp Factories will land in a follow-up PR. | ||
| Connect a factory to Slack so your team can send it work without leaving their conversations. Each factory gets its own dedicated Slack app: mention the app in a channel or send it a direct message, and the factory picks up the request with the conversation as context, then posts progress and results back into the same thread. You can also set up automations that start work from Slack events without a mention. |
There was a problem hiding this comment.
[lilis agent] Slack's landing-page requirements say the page must give a clear overview of the app and the problem it solves to someone with no prior context. Right now the page assumes the reader knows what a factory is. One sentence + link makes it stand alone:
| Connect a factory to Slack so your team can send it work without leaving their conversations. Each factory gets its own dedicated Slack app: mention the app in a channel or send it a direct message, and the factory picks up the request with the conversation as context, then posts progress and results back into the same thread. You can also set up automations that start work from Slack events without a mention. | |
| Connect a factory to Slack so your team can send it work without leaving their conversations. Each factory gets its own dedicated Slack app: mention the app in a channel or send it a direct message, and the factory picks up the request with the conversation as context, then posts progress and results back into the same thread. You can also set up automations that start work from Slack events without a mention. If you're new to factories, see [How factories work](../how-factories-work) for what a factory is and how it runs work. |
|
|
||
| You need permission to update the factory and install apps in the target Slack workspace. Workspace policy can require administrator approval. | ||
|
|
||
| Installing the app grants the Slack permissions shown on the authorization screen. Filters on automations only control which events start work; they don't limit what the app can access. For workspace-level installation and removal behavior, see the [Slack platform integration](../../platform/integrations/slack). |
There was a problem hiding this comment.
[lilis agent] Users authorize Warp's manager app (the Oz app) and then see a second app (the factory's) appear, and admins get two approval surfaces. Worth a short explanation of the managed-apps model — it also helps Slack Marketplace review, which rewards transparency about what the manager does.
Verified against slack/slack_provision.go + slack/managed_apps/client.go: manager auth is once per workspace; each factory app is created on connect and auto-install falls back to the Add to Slack link when admin approval is required.
| Installing the app grants the Slack permissions shown on the authorization screen. Filters on automations only control which events start work; they don't limit what the app can access. For workspace-level installation and removal behavior, see the [Slack platform integration](../../platform/integrations/slack). | |
| Installing the app grants the Slack permissions shown on the authorization screen. Filters on automations only control which events start work; they don't limit what the app can access. For workspace-level installation and removal behavior, see the [Slack platform integration](../../platform/integrations/slack). | |
| ### How the Slack connection works | |
| Warp uses Slack's managed apps model: Warp's main Slack app acts as the manager. The first time you connect a factory, you authorize the manager once for your workspace. That authorization lets Warp create and install Slack apps on your behalf, but nothing is created until you connect a factory. Each time you click **Add to Slack**, Warp creates that factory's dedicated app, installs it, and manages it from then on: the app's name, icon, and configuration stay in sync with the factory. The manager's permissions apply only to apps it created. Depending on your workspace's app-approval settings, a Slack administrator may need to approve the manager authorization once, and each factory's app before it installs. |
| - **Installation is pending** - Ask a Slack workspace administrator to approve the app, then finish the installation. | ||
| - **Two runs start for one mention** - Remove or narrow overlapping app-mention and channel-message triggers. | ||
|
|
||
| Removing the app from your Slack workspace stops new requests from Slack for that factory; to reconnect it, return to factory setup and click **Add to Slack** again. Deleting the factory also removes its Slack connection. To route work into the factory from other tools, see [Connect your factory](../connect-your-factory). |
There was a problem hiding this comment.
[lilis agent] Two Slack landing-page requirements are missing from the page, both fit naturally here:
- Privacy policy link — Slack explicitly requires a clear link to the privacy policy. Blocker for Marketplace review.
- Uninstall steps — the page says removal stops new requests but never says how to remove the app. Two paths: delete the factory from its settings page in the web app (removes its Slack app from the workspace), or remove the app from the Slack side.
| Removing the app from your Slack workspace stops new requests from Slack for that factory; to reconnect it, return to factory setup and click **Add to Slack** again. Deleting the factory also removes its Slack connection. To route work into the factory from other tools, see [Connect your factory](../connect-your-factory). | |
| Removing the app from your Slack workspace stops new requests from Slack for that factory; to reconnect it, return to factory setup and click **Add to Slack** again. To route work into the factory from other tools, see [Connect your factory](../connect-your-factory). | |
| To remove the factory's app entirely, delete the factory from its settings page in the web app. Deleting the factory removes its Slack app from your workspace and its Slack connection. | |
| You can also remove the app from the Slack side: | |
| 1. In Slack, go to **Apps** in the sidebar and search for the factory's name. | |
| 2. Select the app, open the **About** tab, then click **Configuration**. This opens your workspace's app configuration page in the browser. | |
| 3. Scroll to the bottom, select **Remove App**, and confirm the removal. | |
| ## Privacy | |
| The factory's app reads messages only where it's mentioned, directly messaged, or subscribed by an automation you configured. Message content and supported attachments are used to run the factory's work, and your Slack profile email is used to map you to your Warp account. Data is handled per the [Warp Privacy Policy](https://www.warp.dev/privacy). |
* docs(factories): fix relative links and non-rendering mermaid on merged pages Convert all 31 relative internal links across factory-agents, factory-mcp, measure-and-improve, and the Jira/Slack integration pages to root-absolute paths with trailing slashes. Relative links resolve against Starlight's trailing-slash page URLs (../platform/x becomes /factories/platform/x) and 404 in the browser, while the file-path-based CI link checker stays green — the same breakage bnavetta flagged on the infrastructure page in #523. Also remove the mermaid flowchart from measure-and-improve: the docs site has no mermaid renderer, so the block displayed as a raw code fence. The numbered improvement-loop list directly below it already narrates every node and edge, so no information is lost. Only pages whose owning PRs (#518, #521, #522, #525, #528) have already merged are touched; open factory PRs own different files. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): restore improvement-loop mermaid diagram Mermaid rendering shipped on main in c35aab4 (#515) after hyc/factory-launch forked, so the diagram only failed to render because the launch branch predates the renderer. Restore it; this PR now only converts relative links to root-absolute paths. Co-Authored-By: Warp <agent@warp.dev> --------- Co-authored-by: Warp <agent@warp.dev>
Add how-factories-work link, managed-apps model explanation, uninstall steps, and privacy section from PR #525 review. Co-authored-by: Warp <agent@warp.dev>
2 participants
Summary
Adds factory-specific Slack documentation covering the dedicated app, authorization boundary, app mentions and DMs, background event automations, thread continuity, attachments, acknowledgments, App Home, writeback, channel scope, and troubleshooting.
Final size: 897 prose words. Generic provider installation details remain in the existing platform integration page; this PR focuses only on factory-specific behavior.
Foundation
Shared navigation, route placeholders, Early Access badge support, and guide migrations are merged in #537. This PR now contains only its feature-owned files and passes CI independently.
Validation
npm run typecheck: 0 errorsnpm run build: 377 pages builtLatest source refresh
Adds best-effort Slack install-on-create with Add to Slack fallback and stage-based App Home grouping.
Verified against Warp
e72fd7aacand warp-server9be39e484b. Broken, placeholder, partial, and spec-only surfaces remain excluded.Proposed reviewers
Based on the Warp Factories Soft Launch (August 18th) tracker. For planning only; no review requests have been sent.
@liliwilson@moirahuang@captainsafiaScreenshots
Not included. The page uses a compact trigger/context/output table and links to the existing provider setup page; no approved factory-specific UI assets exist yet.
Unverified claims
None — UI labels, event classes, filters, authorization boundaries, continuity, and writeback behavior were verified against source.
Conversation: https://staging.warp.dev/conversation/5ff89820-2d80-4518-981e-178845029de1
Plans: https://staging.warp.dev/drive/notebook/7ZPKWz7hM5I59o4Gg2ptYi and https://staging.warp.dev/drive/notebook/DpRWhMQ0DLCajPPMggXw5e
Co-Authored-By: Warp Agent agent@warp.dev