botgumi

Start here

Overview

Status: pre-v1 skeleton. Interfaces, no-op adapters and contract tests are in place; vendor adapters, runtimes and the runner are stubs. Private until v1.

The studio at a glance

Japanese builders are named -gumi (組, "crew"): the firm that assembles a building from its parts. Botgumi is a crew of bots that assembles apps from shared parts, with you as the client who signs off.

Botgumi packages a way of shipping apps that already worked for one app, so the next app starts where the last one finished, not from scratch. It has three parts:

  1. A template (templates/app). Every new app starts with the same tracks (backend, iOS, Android, landing, dashboard, design, docs), the same contract-first docs, and the same CI. botgumi new <app> generates it.
  2. Shared packages (packages/). Swift, Kotlin and TypeScript building blocks that apps use by version. Each third-party service sits behind an interface, so a vendor can be swapped without touching app code.
  3. An agent team (agents/). An orchestrator plans and routes the work. One worker per track builds it. A reviewer on a different runtime checks every PR. The agents run on Claude or Codex.

How work flows

This diagram is interactive on the home page.这张图在首页可以交互演示。

Watch the flow run →看流程跑一遍 →
  • Tasks arrive as GitHub issues. Words from you in chat or botgumi task "…" become issues too. The local runner (botgumi run) hears about new events within seconds through a Cloudflare relay, and catches up with gh after sleep. It never opens a port on your Mac.
  • Trust. Issue and comment text counts as instructions only from you (or authors you allowlist). Anyone else's text is data.
  • Review follows fixed rules: the contract and ADRs, all four states (loading, empty, error, offline), strings in en and zh-Hans, no placeholder numbers, tests for changed behaviour, a complete PR description. High-risk PRs get two reviewers. After 2 rounds with open blocking findings, you decide.
  • Merging. The author never merges its own PR. The orchestrator may merge low-tier PRs when every check is green, nothing protected is touched and the diff is small. Everything else waits for you.
  • Human gates stay human: brand and name, design system, lo-fi, hi-fi, pricing, screenshot direction, store submission (App Store, Google Play).

What is fixed and what is swappable

The opinionated core is fixed for now: Cloudflare backend (Workers, D1, R2, KV, Access), TanStack Start on Cloudflare Pages, native iOS with XcodeGen and the asc CLI for the App Store, and native Android with Kotlin, Jetpack Compose and Gradle for Google Play (ADR-0002). An app picks its platforms (platforms in botgumi.config.ts: iOS, Android or both). More backends are on the roadmap.

Everything else sits behind an interface with a no-op version and a contract test suite that every adapter must pass. App code imports the interface, never the vendor SDK.

Concern Interface Default
Analytics Analytics Amplitude
Feature flags Flags Amplitude
Crash and errors Crash Sentry
Purchases Purchases RevenueCat
Email Mailer Cloudflare
Domain check DomainLookup Cloudflare
Agent runtime AgentRuntime Claude, Codex
Task intake TaskSource GitHub Issues + chat/CLI
Task board TaskBoard GitHub Projects
Event delivery EventRelay Cloudflare relay + polling
Code host and merge CodeHost GitHub

An app picks its platforms, providers, agent runtimes and models, trust list and merge rules in one file, botgumi.config.ts. See docs/providers.md to add an adapter.

Where it stands

Part State
Provider interfaces, no-ops, contract suites (TS, Swift and Kotlin) Done; no-ops pass their contracts
Config schema (botgumi.config.ts) Done, typed
Runner trust filter Done, tested
Agent roles, review rules, merge policy, intake docs Written
Vendor adapters (Amplitude, Sentry, RevenueCat, Cloudflare email, GitHub, asc, Google Play) Stubs
Agent runtimes (Claude, Codex), relay Worker, runner, merge decision Stubs
botgumi new, task, run Stubs
templates/app track scaffolds Placeholders

Layout

botgumi/
  botgumi.config.ts      # defaults: providers, agents, runner trust, merge policy
  Package.swift             # the Swift package (sources under packages/swift)
  docs/decisions/           # ADR-0001 foundations, ADR-0002 Android
  AGENTS.md  CLAUDE.md      # this repo's agent instructions (CLAUDE.md only imports AGENTS.md)
  templates/app/            # the scaffold a new app is generated from
  packages/
    swift/                  # SwiftPM modules, consumed by git tag
      BotgumiAuth  BotgumiAPIClient  BotgumiDesignTokens
      BotgumiAnalytics  BotgumiAnalyticsAmplitude
      BotgumiCrash  BotgumiCrashSentry
      BotgumiPurchases  BotgumiPurchasesRevenueCat
      BotgumiContracts    # contract suites every Swift adapter must pass
    kotlin/                 # one Gradle build, consumed as dev.botgumi:<module> Maven artifacts
      botgumi-auth  botgumi-api-client  botgumi-design-tokens
      botgumi-analytics  botgumi-analytics-amplitude
      botgumi-crash  botgumi-crash-sentry
      botgumi-purchases  botgumi-purchases-revenuecat
      botgumi-contracts     # the same contract suites, for every Kotlin adapter
    ts/                     # pnpm workspace, @botgumi/*
      cli  runner  relay  worker-kit  spend-guard  i18n  design-tokens  dashboard-ui
      providers/            # analytics flags crash purchases mailer domain-lookup
                            # agent-runtime task-source task-board event-relay code-host
      adapters/             # amplitude sentry revenuecat cloudflare-email asc google-play github
                            # claude-runtime codex-runtime
  site/                     # botgumi.com: landing, docs (rendered from this repo's Markdown), releases
  scripts/                  # verify, release, asc signing/upload, play upload, ios and android ci, go-live checks
  agents/                   # AGENTS.md for apps, roles, review rules, merge policy, intake, runtimes
  docs/                     # ADRs, templates, checklists, GitHub App setup

Develop

Requirements: Node 22+, pnpm 10, Xcode with Swift 6, a JDK 17 or newer (the Gradle wrapper fetches Gradle).

pnpm install
pnpm verify

pnpm verify runs the TS typecheck and tests, swift build and swift test, and ./gradlew build in packages/kotlin. GitHub CI runs the TS and Kotlin checks on Linux; Swift runs locally.

Use in an app

.package(url: "https://github.com/xieweizhi/botgumi", from: "0.1.0")
// Android: Maven artifacts from packages/kotlin, versioned by the same git tag
implementation("dev.botgumi:botgumi-analytics:0.1.0")

Publishing the Kotlin artifacts lands with the first tagged release; until then an app uses includeBuild on a checkout of packages/kotlin.

botgumi new <app> (not implemented yet) will generate an app from templates/app with the choices in botgumi.config.ts. To let the agents work on a repo, set up the GitHub App first: docs/github-app-setup.md.

Roadmap

  • Support more backends besides Cloudflare, starting with Supabase. The backend is part of the fixed core today (ADR-0001, decision 5), so this needs a backend interface first: auth, database, storage, functions and secrets, with a contract test suite every backend passes.

Versioning

Semver with Changesets. Each app records the template version it came from; an upgrade bot will open a PR in each app when a new version ships. How a release goes out: docs/releasing.md.

License

MIT