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 new file mode 100644 index 000000000..49ca549ba --- /dev/null +++ b/apps/docs/cookbook/ease-your-team-into-cloud-agents.mdx @@ -0,0 +1,97 @@ +--- +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 **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. 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, + 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. +``` + +```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. +- 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/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)} |`; });