Bloom Documentation
Bloom is an AI Product Owner that turns conversations into software projects. Users chat with Bloom through Telegram or the web dashboard; Bloom discovers requirements, maintains a living PRD, plans milestones, manages GitHub issues, reviews pull requests, and keeps the user informed across the software development lifecycle. Bloom is in Public Beta; the documentation map below records, per area, what is implemented, what is opt-in, and what is still planned.
This is the documentation entry point. Start here and follow the links out. It is also published
as a browsable site at docs.dev.bloom.hiddenclaw.org,
rebuilt and deployed on every push to main (see ci.md and
deployment.md).
Start here
- What is Bloom? - the product in five minutes, condensed from the PRD and README.
- Quickstart - clone, install, and run the apps locally via the repo's Make/pnpm targets.
- Core workflows - drive a project through Bloom: create -> milestone plan -> build -> review -> deploy.
- Admin console basics - the grant-gated operations surface.
- Product Requirements Document - vision, goals, functional requirements, and the target technical architecture. The source of truth for what Bloom does.
- Project README - repository overview and getting started.
- Running locally - install, run the API offline, and wire real credentials.
- AGENTS.md - contributing workflow (milestones, issues, branches, PRs) and the quality bar every change must clear. The contract for human and AI contributors.
Architecture
Bloom's SDLC process is defined as data, not code - a stack-agnostic workflow spec that
any orchestration engine compiles to. The Public Beta ships a small built-in interpreter of
that spec (so there is no heavy engine dependency); LangGraph remains one possible future
adapter behind the same Engine seam.
- Architecture overview - layers, request flow, and the key design seams.
- OpenClaw orchestration runtime design - the M9 boundary between Bloom's product control plane and OpenClaw runtime execution.
- Workflow to OpenClaw execution mapping - how Bloom workflow nodes, reducers, triggers, and tools map to the OpenClaw pilot runtime and future expansion paths.
- The decision graph - Phase 1 (capture) implemented (M14, FR-25); later phases proposed. Making decisions first-class, repo-owned artifacts linked to the milestones, issues, PRs, and code they affect, so the project accumulates its own rationale and blast-radius questions become queries.
- GitHub App setup - registering the App and the bloom-hosted vs client-owned repository model.
- Adopting an existing repository (brownfield) - bind a pre-existing repo as the project target (M44); planning grounds on a read-only codebase snapshot and yields change-tickets (no scaffold), and PRs open against the repo's own default branch.
- GitLab setup - config keys, per-project webhook wiring, and access-token storage for running a project on GitLab (M23 platform-agnostic VCS).
- Coordination & the engineer swarm - the label contract, delegation loop, and the swarm simulator used to test Bloom's Product-Owner coordination end-to-end.
- Engineering engine - the seam behind which Bloom executes a delegated ticket (one issue -> one PR); the contract, run lifecycle, and engine-mode configuration.
- ADR 0001: engine-runner stays on a dedicated VM - why the Claude Code execution worker is the one deliberate exception to the M24 Kubernetes-native deploy model, and how api pods keep reaching it over the tailnet.
- ADR 0002: child-flow runtime - proposed; the gate for #471.
When TRUE per-work-item child flow instances are executed rather than projected, they run on
the built-in engine's own reserved
subworkflownode - not LangGraph subgraphs, Temporal, or an actor framework - per the #470 spike (throwaway prototypes) against the hierarchical-supervisor design's G1-G3 gate criteria. - TypeScript migration feasibility verdict - M29
decision record, extended by the M30 write-slice, M31 LLM-slice, M32 streaming-slice,
M33 domain-layer, M34 persistence+auth, M35 integrations, M36 agents, M37
services+engine, M38 HTTP-routes, and M39 orchestrator/langgraph-core addenda, closing with
the M40 cutover plan. The
measured per-slice cost of the Python->TS feasibility spike (
apps/server+ differential parity harness), the parity gaps found, dual-runtime + shared-Postgres coexistence findings, and the verdict against the ~1-dev-week/slice gate: keep strangling toward all-TS - re-affirmed by the first write slice (M30-3), the first LLM/agent slice (M31-4), the first streaming (SSE) slice (M32-4), and finally the orchestrator/workflow/ langgraph core (M39-9) gate re-measurements, then extended by the M33 domain-layer port (M33-5), the M34 persistence + auth port (M34-6), the M35 integrations port (M35-8), the M36 agents port (M36-7), the M37 services+engine port (M37-8), and the M38 HTTP-routes port (M38-5), which land the wholebloom.domain,bloom.persistence,bloom.integrations,bloom.agents/bloom.skills, andbloom.enginelayers plusbloom.auth.oidc, the shared infra utils, the orchestrator-independentbloom.services, the deferredopenclaw_harness+ migration bundle, and the orchestrator-independent slice ofbloom.api.routes(dashboard + admin auth, admin aggregator reads,/metrics, and the account-scoped credentials/telegram-link routers) within the measured envelope, and finally the M39 orchestrator/workflow/langgraph core (theworkflow/langgraph runtime + OpenClaw adapters, theservices.orchestratordecision/lifecycle/review cores, the M37-deferred orchestrator-coupled services, and the M38-deferred orchestrator-coupled routes) - the last mandatory gate, cleared UNDER by ~1.5-2x with no new serializer (the control-flow spike hit 37/37 reusingpyjson.ts), so the freeze-core fallback is retired; record the cross-provider, agent, services+engine, route, and control-flow parity findings (webhook signature bytes, VCS abstraction fidelity, cache-stable prompt composition, pinnedmodel_json_schema()documents, seam-isolated subprocess/git execution, Starlette cookie byte-parity, the pure-core/async-wrapper split and Python evaluation-semantics fidelity), and set the roadmap - with every shape measured and every layer ported, the M40 cutover then landed (flipserver.enabled, point the gateway routes atapps/server, prove parity, re-derive the pooler budget, and finally decommissionapps/api- completed in #808; the Python oracle stays recoverable at gitd69f789), preceded by the small M39-8 deferral slices it inherited. - Knowledge skills - the authoring + governance contract for vendored
SKILL.mdknowledge: front-matter fields, and the proprietary vs third-party provenance rules (M22); third-party imports go through the pinned-ref importer and the vetting checklist. - Cross-platform project migration - export a project's SDLC state to a neutral, versioned bundle and re-materialize it on another VCS platform (M23), with an explicit report of anything not 1:1 transferable.
- Persistence - durable run-state storage on Supabase Postgres.
- Observability - structured logging, run/thread correlation ids, and the log event-name taxonomy.
- CI/CD pipeline (DevOps) - the whole pipeline: security -> test -> build -> deploy -> e2e, the two e2e lanes (pre-merge ephemeral + post-deploy), gating, and merge rules.
- Deployment - GitHub Actions CD to an exe.dev VM (Docker, stable HTTPS via the exe.dev edge, restart-on-failure).
- Preview environments (per-PR) - the M16 per-PR preview stack,
starting with the isolated Supabase branch database each PR to
maingets. - Workflow specs overview - the abstraction, core concepts, and how the spec maps onto LangGraph / Temporal / XState.
- Workflow format (JSON Schema) - the contract every workflow definition must satisfy.
- Bloom SDLC workflow - the concrete end-to-end process instance.
Running locally
See Running locally under Getting started: install once at the repo root, run the API offline with the fake LLM provider, and wire real credentials when you need them.
Documentation map
| Area | Where | Status |
|---|---|---|
| Product requirements | PRD.md | Drafted |
| User guide (getting started + core workflows) | docs/getting-started/, docs/core-workflows.md, docs/admin-console.md | Written (M45-3) |
| Architecture overview | docs/architecture.md | Implemented |
| Workflow engine + spec | apps/server/workflows/, apps/server/src/workflow/ | Implemented |
| Backend API (Express) | apps/server/src/ | Implemented |
| Agents (Product Owner, Reviewer) | apps/server/src/agents/ | Implemented |
| Integrations (LLM, Telegram, GitHub, GitLab) | apps/server/src/integrations/, apps/server/src/llm/ | Implemented |
| Engineering engine (build the software) | docs/engineering-engine.md, apps/server/src/engine/ | Implemented (M6; disabled by default, opt-in simulator/claude_code) |
| GitHub repo wiring (App auth, bloom-hosted + client-owned) | docs/github-app.md | Implemented (needs App registration) |
| Repository adoption (brownfield onboarding) | docs/repo-adoption.md | Implemented (M44) |
| GitLab wiring (webhook intake + access tokens) | docs/gitlab.md | Implemented (M23; needs per-project webhook + stored token) |
| Knowledge skills (authoring + governance) | docs/skills.md, docs/skill-vetting.md, apps/server/src/skills/ | Implemented (M11 registry; M22 provenance + third-party import) |
| Persistence (state store) | apps/server/src/persistence/, docs/persistence.md | Implemented (in-memory + Supabase) |
| Cross-platform migration (export/import) | docs/migration.md, apps/server/src/migration/ | Implemented (M23) |
| Observability (structured logs, correlation ids) | docs/observability.md, apps/server/src/logger.ts | Implemented (M21) |
| CI/CD pipeline (DevOps) | docs/ci.md, .github/workflows/ | Implemented |
| Deployment & operations | docs/deployment.md, apps/server/Dockerfile, deploy/helm/bloom/, .github/workflows/ | Implemented |
| Milestones | Delivered docs under docs/milestones/: M3, M4, M5, M7, M9, M10, M11. Planned as GitHub milestones (the reviewable plan is the milestone + its issues): M12 - End-to-End Testing, M13 - Sharper Planning, M14 - Decision Graph (Capture), M15 - Immutable Deploys & Rollback, M6 - Production-Grade Engineering Engine, M18 - Deployment-Aware Planning, M19 - Client Credential Store, M20 - Dashboard UX Redesign: Project Workspace & Web Chat, M24 - Cloud Infra: Kubernetes-Native Dev & Staging Readiness, M25 - Staging Provisioning & Go-Live (deferred, paid), M26 - In-app project creation (web), M27 - Admin Dashboard (design of record: admin-dashboard-milestone-plan-fable.md; threat-model verification: admin-threat-model.md), M45 - Documentation app (the apps/docs Docusaurus site renders this docs/ tree in place; docs/ stays canonical), M47 - Adopted-repo backlog import (+ landing 404) (plan-time import of an adopted repository's open issues, described in repo-adoption.md; the landing site's real 404 page), M56 - Project rename (stored display name, dashboard + chat) (an owner-editable display_name in run state, written by PATCH /api/projects/{thread_id} or the /rename <name> chat command (Telegram + web chat, handled out-of-band like /archive) and leading the title everywhere - dashboard overview, admin list, Telegram project list - without touching the GitHub repo). | M3-M11, M18, M19 delivered; M12-M15, M6 planned as GitHub milestones; M20 in delivery |
Conventions
- New documentation lives under
docs/(or alongside the code it describes, linked from the map above). Add a row to the map when you introduce a new area. - Keep this page as the single entry point - it should always link to everything a new reader needs, one hop away.