Brainforge Knowledge

cloud-agent-runbook

4 min read

Cloud Agent runbook — Brainforge Slack Assistant modernization

Status: Active
Owner: Uttam Kumaran
Last updated: 2026-03-28
Related: slack-bot-modernization-plan.md · ROADMAP.md · brainforge-assistant app · ARCHITECTURE.md · architecture entries
Linear: Brainforge Slack Assistant Modernization · meta ticket PLT-1247 (delegate: Cursor)

Purpose

This runbook is the single source of truth for Cursor Cloud Agent (or any agent with equivalent tools) to execute, verify, and update Linear for the Slack assistant modernization without replacing the ticket graph. Child issues remain the unit of ship; this doc defines the loop and stop conditions.

Aligns with internal harness thinking: knowledge/plans/engineering/cloud-agent-automation-backlog.md, knowledge/plans/engineering/cloud-agent-data-environment-report.md.

Execution graph (do not collapse)

Work these issues in dependency order (respect blockedBy in Linear):

IDTitle (short)
PLT-1237Finalize Railway-first v2 architecture / ADR
PLT-1238v2 TypeScript scaffold on Railway
PLT-1239Test vs prod Slack app isolation
PLT-1240AI SDK + Azure + tools
PLT-1241Fixture replay tests + CI gating
PLT-1242Durable state + idempotency
PLT-1243Vertical slice on test assistant app
PLT-1244HITL approval path
PLT-1245Shadow run + metrics
PLT-1246Production cutover (human-heavy)

Rule: Do not open one PR that claims multiple unrelated issues unless the team explicitly agrees; prefer one primary issue per PR with links in the description.

Standard agent loop (each issue)

  1. Pick the next unblocked issue in the project (or the one the human names in the Cloud Agent prompt).
  2. Branch using Linear’s suggested branch name (e.g. uttam/plt-1238-...).
  3. Implement per acceptance criteria; keep scope tight.
  4. Run local checks (TypeScript, tests) as appropriate for touched paths.
  5. Open PR with required body sections (Summary / Changes / Impact / Related) and Linear ID in title for integration.
  6. Update Linear: comment with PR link, what changed, what’s left; move state per team norms.
  7. Verify (when the issue requires runtime checks):
    • Test Slack app only until cutover ticket.
    • Use Slack MCP (or test channel) to confirm behavior when applicable.
  8. Stop at any human gate (below); leave a Linear comment: Blocked: human gate — <exact step>.

Human-only gates (hard stops)

Agent must not silently bypass these; request human action and pause.

  • Slack app manifest changes, Event Subscriptions URLs, Assistant settings, OAuth reinstall in workspaces where the agent lacks admin.
  • Production bot token / signing secret rotation or Railway prod env changes (unless org policy explicitly allows agent automation).
  • Production cutover timing and approval (PLT-1246).
  • GitHub settings the agent cannot change: branch protection, required reviewers, auto-merge policy.
  • 1Password / secrets retrieval if Cloud Agent has no op or approved secret store access.

Tools Cloud Agent should have (target)

ToolWhy
Linear MCPIssues, states, comments, dependencies, project visibility
GitHub (CLI or MCP)Branch, commit, PR, read checks
Slack MCPPost/read test channel; validate assistant behavior
Railway MCP (or CLI + token)Deploy test service, logs, env for test environment
Repo checkoutDefault for Cloud Agent

If Railway MCP is missing or read-only, agent documents exact human steps for deploy and still ships code + PR.

Kickoff prompt template (paste into Cursor Cloud Agent)

Use the repo path and first ticket:

Follow knowledge/engineering/brainforge-slack-assistant/cloud-agent-runbook.md.
 
Project: Brainforge Slack Assistant Modernization (Linear).
Start with PLT-1237 (architecture/ADR). If 1237 is done, follow blockedBy order for PLT-1238 and PLT-1239 in parallel only if safe.
 
Railway-first; test Slack app only until PLT-1246.
Comment on each touched Linear issue with PR link and verification notes.
Stop at any human gate and comment "Blocked: human gate" with the exact step.

Owner checklist (human) — get Cloud managing the project

  1. Wire MCPs on Cloud Agent — Same capabilities as local where possible: Linear, Slack, GitHub, Railway (test scope).
  2. Confirm secrets policy — What Cloud Agent may read (e.g. Railway test token in approved store); prod stays gated.
  3. Move PLT-1237 to “ready” and start Cloud Agent with the kickoff prompt above (or delegate from PLT-1247).
  4. Merge policy — Decide: required human review vs auto-merge when CI green + label; document in PLT-1247 or here.
  5. Slack test app — Ensure test app request URL points at test Railway service before agent runs live verification tickets.

After this runbook ships

Close PLT-1247 when:

  • This file exists in repo and is linked from the modernization plan.
  • Human gates and loop are agreed (update this doc if policy changes).

Graph View

Backlinks