From 94fdd81a5cdff85e83d0e6791a2fab57d199f99e Mon Sep 17 00:00:00 2001 From: Roomote Date: Mon, 3 Aug 2026 19:36:35 +0000 Subject: [PATCH 1/2] docs: add cloud agent adoption recipe --- .../ease-your-team-into-cloud-agents.mdx | 93 +++++++++++++++++++ apps/docs/cookbook/index.mdx | 1 + apps/docs/docs.json | 6 +- 3 files changed, 99 insertions(+), 1 deletion(-) create mode 100644 apps/docs/cookbook/ease-your-team-into-cloud-agents.mdx diff --git a/apps/docs/cookbook/ease-your-team-into-cloud-agents.mdx b/apps/docs/cookbook/ease-your-team-into-cloud-agents.mdx new file mode 100644 index 000000000..d1e34ea24 --- /dev/null +++ b/apps/docs/cookbook/ease-your-team-into-cloud-agents.mdx @@ -0,0 +1,93 @@ +--- +title: Ease your team into cloud agents +description: Build trust in Roomote through small, visible, low-risk team habits. +contributor: Bruno Bergher +contributor_url: https://github.com/brunobergher +contributor_company: Roomote +contributor_company_url: https://roomote.dev +--- + +## Overview + +Cloud agents can feel uncomfortable at first, especially when using one means +asking a question in public or letting it comment on a teammate's work. Do not +start by automating everything. Give the team a few low-risk ways to watch +Roomote work, understand what it can do, and see leaders review its output. + +The goal is familiarity, not maximum usage. Begin with questions and code +reviews, keep the work visible, and add more autonomy only after the team trusts +the results. + +- **Trigger**: Channel activity and pull request updates +- **Setup time**: About 20 minutes +- **Requires**: Admin access, Slack, a source-control connection, a healthy environment +- **Serves**: Engineers, Leads +- **Cooked By**: [Bruno Bergher](https://github.com/brunobergher) from [Roomote](https://roomote.dev) + +## Ingredients + +- A healthy [environment](/environments) for the team's main repositories +- Two Slack channels, such as `#factory` and `#ask-roomote`, with Roomote invited +- The **Custom Emoji Reaction** automation +- The **Review Code** automation +- One or two leaders willing to use Roomote where the team can watch + +## Steps + +1. Create a `#factory` channel for visible examples. Have leaders bring real, + small tasks there, include the context Roomote needs, and review the result + in the thread. Leave corrections visible too; showing how to steer an agent + is more useful than showing only perfect outcomes. +2. Create an `#ask-roomote` channel for codebase questions. Start with explicit + mentions, or configure [auto-response](/automations#channel-automations) once + the channel's purpose is clear. Encourage questions such as where a behavior + lives, how a flow works, or which tests cover a change. +3. Enable **Custom Emoji Reaction** with an unmistakable emoji. Let leaders use + it first on a few well-scoped messages so teammates can see what the reaction + starts and where the result appears before trying it themselves. +4. Enable **Review Code** for pull requests from authors other than Roomote. + Keep automatic draft reviews off at first. Roomote adds a second opinion + without taking control of the pull request, which lets engineers compare its + comments with their own review and build trust gradually. +5. Keep the first tasks read-only. Ask for explanations, investigation, and + review before asking Roomote to change code. When the team is comfortable, + let a leader demonstrate one small implementation and walk through the diff, + checks, and pull request. +6. Close the loop in public. When Roomote helps, say what was useful. When it + misses, reply with the missing context and show the corrected result. This + teaches the team that agent output is reviewable work, not a verdict. +7. Offer direct messages as a rehearsal space for anyone who is not ready to + ask publicly. Invite people to share useful answers back in `#ask-roomote` so + the team's shared confidence still grows. + +## Starter prompts + +Use questions that are easy for an engineer to verify: + +```text +Where is authentication handled in this codebase? Link the important files and +explain the request flow. Do not change code. +``` + +```text +Which tests cover this pull request's behavior, and what important case might +still be missing? Do not change code. +``` + +```text +Explain why this service exists and which other parts of the system call it. +Keep the answer short and link to the relevant code. +``` + +## Variations + +- Start `#ask-roomote` with office hours led by one champion, then leave it open all week once the questions become routine. +- Ask leaders to post one useful Roomote thread in an existing engineering channel each week instead of creating `#factory` permanently. +- Begin **Review Code** with a small set of repositories before enabling it across the organization. + +Avoid adoption targets such as a required number of agent tasks per engineer. +Watch for better signals: more people asking verifiable questions, teammates +replying naturally in Roomote threads, and engineers acting on review comments +they checked themselves. + +**Pairs well with:** [scheduled housekeeping](/cookbook/scheduled-housekeeping) diff --git a/apps/docs/cookbook/index.mdx b/apps/docs/cookbook/index.mdx index d2172a276..5d68fcc28 100644 --- a/apps/docs/cookbook/index.mdx +++ b/apps/docs/cookbook/index.mdx @@ -13,6 +13,7 @@ and the quality of your output. | Recipe | Use to | | --- | --- | | [Draft product updates](/cookbook/product-updates-newsletter) | Turn recent product work into a customer-ready draft | +| [Ease your team into cloud agents](/cookbook/ease-your-team-into-cloud-agents) | Build trust in Roomote through small, visible, low-risk team habits. | | [Evaluate outage impact](/cookbook/vendor-outage-triage) | Filter vendor status noise by comparing each incident with your real code, regions, and feature usage. | | [Fix CI failures](/cookbook/ci-failure-auto-fix) | Keep the build green by having Roomote verify and fix CI breakages automatically. | | [Schedule maintenance](/cookbook/scheduled-housekeeping) | Turn flaky-test scans, feature-flag audits, and dependency reviews into recurring Roomote work. | diff --git a/apps/docs/docs.json b/apps/docs/docs.json index c369d0646..bf294e94c 100644 --- a/apps/docs/docs.json +++ b/apps/docs/docs.json @@ -50,7 +50,11 @@ }, { "group": "Cookbook", - "pages": ["cookbook/index", "cookbook/template"] + "pages": [ + "cookbook/index", + "cookbook/ease-your-team-into-cloud-agents", + "cookbook/template" + ] }, { "group": "Provider Configuration", From 975999bd4033178f5a9ca1c90de284bbf66d2119 Mon Sep 17 00:00:00 2001 From: Roomote Date: Tue, 4 Aug 2026 10:39:41 +0000 Subject: [PATCH 2/2] docs: clarify cookbook recipe workflow --- apps/docs/AGENTS.md | 15 +++++++++++++- .../ease-your-team-into-cloud-agents.mdx | 20 +++++++++++-------- apps/docs/docs.json | 6 +----- apps/docs/scripts/generate-cookbook-index.mjs | 4 +++- 4 files changed, 30 insertions(+), 15 deletions(-) diff --git a/apps/docs/AGENTS.md b/apps/docs/AGENTS.md index 5a9f3841d..dacfd36c2 100644 --- a/apps/docs/AGENTS.md +++ b/apps/docs/AGENTS.md @@ -80,10 +80,23 @@ Provider ids and documentation slugs can differ (for example, `google` maps to `google-gemini`), so make that mapping explicit and cover it with the setup docs tests. +### Cookbook recipes + +Add each Cookbook recipe as a standalone `cookbook/.mdx` file using +`cookbook/template.mdx` as the structural guide. After adding or changing a +recipe, run `pnpm --filter @roomote/docs generate-cookbook-index` so the table in +`cookbook/index.mdx` stays alphabetized by frontmatter title. Do not edit the +generated table between its `cookbook-recipes` markers by hand. + +Never add individual Cookbook recipe pages to `docs.json`. Only +`cookbook/index` and `cookbook/template` belong in the Cookbook sidebar group; +readers discover recipes through the generated index. + ## Working notes - `docs.json` is the navigation and branding source of truth. When you add, - rename, or remove a page, update its `navigation` entry in the same change. + rename, or remove a page, update its `navigation` entry in the same change, + except for individual Cookbook recipes as described above. - Pages are MDX files referenced by file name (without extension). - Internal links use root-relative paths (`/environments`, not `/docs/...`). - Brand assets (`roomote.css`, `logo/`, `favicon.svg`, `fonts/`) live in this diff --git a/apps/docs/cookbook/ease-your-team-into-cloud-agents.mdx b/apps/docs/cookbook/ease-your-team-into-cloud-agents.mdx index d1e34ea24..49ca549ba 100644 --- a/apps/docs/cookbook/ease-your-team-into-cloud-agents.mdx +++ b/apps/docs/cookbook/ease-your-team-into-cloud-agents.mdx @@ -28,7 +28,6 @@ the results. - A healthy [environment](/environments) for the team's main repositories - Two Slack channels, such as `#factory` and `#ask-roomote`, with Roomote invited -- The **Custom Emoji Reaction** automation - The **Review Code** automation - One or two leaders willing to use Roomote where the team can watch @@ -42,13 +41,14 @@ the results. mentions, or configure [auto-response](/automations#channel-automations) once the channel's purpose is clear. Encourage questions such as where a behavior lives, how a flow works, or which tests cover a change. -3. Enable **Custom Emoji Reaction** with an unmistakable emoji. Let leaders use - it first on a few well-scoped messages so teammates can see what the reaction - starts and where the result appears before trying it themselves. -4. Enable **Review Code** for pull requests from authors other than Roomote. - Keep automatic draft reviews off at first. Roomote adds a second opinion - without taking control of the pull request, which lets engineers compare its - comments with their own review and build trust gradually. +3. Have a leader ask Roomote to add an unmistakable custom emoji reaction to a + specific Slack message. This small, visible action shows that Roomote can help + with more than code without asking the team to configure another automation. +4. Enable **Review Code**, then turn on **Review PRs not created by Roomote** so + it includes pull requests opened by engineers. Keep automatic draft reviews + off at first. Roomote adds a second opinion without taking control of the pull + request, which lets engineers compare its comments with their own review and + build trust gradually. 5. Keep the first tasks read-only. Ask for explanations, investigation, and review before asking Roomote to change code. When the team is comfortable, let a leader demonstrate one small implementation and walk through the diff, @@ -79,6 +79,10 @@ Explain why this service exists and which other parts of the system call it. Keep the answer short and link to the relevant code. ``` +```text +Add the :eyes: reaction to the message linked below. Do not post a reply. +``` + ## Variations - Start `#ask-roomote` with office hours led by one champion, then leave it open all week once the questions become routine. diff --git a/apps/docs/docs.json b/apps/docs/docs.json index bf294e94c..c369d0646 100644 --- a/apps/docs/docs.json +++ b/apps/docs/docs.json @@ -50,11 +50,7 @@ }, { "group": "Cookbook", - "pages": [ - "cookbook/index", - "cookbook/ease-your-team-into-cloud-agents", - "cookbook/template" - ] + "pages": ["cookbook/index", "cookbook/template"] }, { "group": "Provider Configuration", diff --git a/apps/docs/scripts/generate-cookbook-index.mjs b/apps/docs/scripts/generate-cookbook-index.mjs index dd85ff042..daf11dcd1 100644 --- a/apps/docs/scripts/generate-cookbook-index.mjs +++ b/apps/docs/scripts/generate-cookbook-index.mjs @@ -60,7 +60,9 @@ async function readRecipe(fileName) { function renderTable(recipes) { const rows = recipes - .sort((left, right) => left.title.localeCompare(right.title)) + .sort((left, right) => + left.title.localeCompare(right.title, 'en', { sensitivity: 'base' }), + ) .map((recipe) => { return `| [${escapeTableCell(recipe.title)}](${recipe.slug}) | ${escapeTableCell(recipe.description)} |`; });