Skip to main content

Core workflows

How a project moves through Bloom, from the owner's seat: create a project, approve the plan, watch the build and review loop run, and take the deployment live. Everything here describes the app as it behaves today; the deeper mechanics live in Coordination & the engineer swarm and Engineering engine.

Create a project​

On the web dashboard, click New project in the sidebar. That opens a draft chat - nothing is created yet. Your first message creates the project and seeds requirement discovery, so the empty drafts you abandon never clutter the sidebar.

On Telegram, link your account first: the dashboard's Telegram linking flow mints a one-time code and shows its t.me/<bot>?start=<code> deep link; sending that /start to the bot binds your Telegram account to your dashboard account. Bloom only answers registered, linked users. One Telegram chat carries all your projects through an active-project pointer, while the web addresses each project directly - both drive the same per-project conversation, so you can switch surfaces mid-project.

A project can also start from an existing codebase - see Adopting an existing repository.

Discovery to an approved PRD​

Bloom interviews you until the essential facets are covered - objective, target users, core features, success criteria, and how users will reach the finished product (the app type). When facets are still open, Bloom tells you which; you can defer ("draft it anyway") and the gaps are recorded as explicit assumptions rather than invented.

The result is a living PRD draft that revises as you talk. When Bloom asks for approval, reply with a plain approval - approve, yes, lgtm, and kin - or keep requesting changes. On approval Bloom freezes the PRD revision, creates the project repository (greenfield) or uses the adopted one, and commits it as PRD.md.

The milestone plan​

From the approved PRD, Bloom plans milestones and tickets: each ticket carries a description, acceptance criteria, dependencies, an estimated complexity, and a MoSCoW priority; the dependency graph is validated (no dangling references, cycles, or duplicates) before anything syncs. The plan always includes a deployment ticket in the MVP milestone, and design work is classified as tickets of its own kind that gate only what depends on them.

The plan then syncs to GitHub as real milestones and issues - GitHub is the source of truth for engineering execution from here on. You can watch it all from the Project View's Details tab (PRD status and revision, milestones, tickets, repo link) and the Workflow tab, the live SDLC graph updating in real time.

Build​

With a collaborator roster configured (BLOOM_COLLABORATORS), Bloom's coordinator delegates each ready ticket to the least-loaded eligible collaborator and tracks it through a single status:* label per issue - status:ready, status:in-progress, status:in-review, status:changes-requested, status:blocked, status:needs-attention, status:awaiting-client - with eng:<name> naming the assignee. The full label contract is in Coordination & the engineer swarm.

Who does the work is pluggable (BLOOM_ENGINEER_ENGINE): disabled (the default - an external swarm or human engineers pick up delegated issues), simulator (offline stub deliverables for demos and tests), or claude_code - Bloom's production engineer, which implements each issue in an isolated feat/issue-<n> workspace and opens exactly one pull request per issue. Design tickets route to the Bloom Designer instead and deliver reviewable design studies on the issue rather than a PR.

Review​

When a PR opens or updates, Bloom reads the actual diff and reviews it against the ticket's acceptance criteria: a review summary plus code-anchored findings posted on the PR (inline on the diff where possible). In the default strict mode (BLOOM_REVIEW_MODE), Bloom merges only when no blocking or major findings remain; otherwise it requests changes and the engineer reworks the same PR.

The loop is bounded: after BLOOM_REVIEW_MAX_ROUNDS failed rounds (default 3) the ticket parks at status:needs-attention and Bloom asks you for input instead of looping forever. Client-facing deliverables (design, UX, content) go one gate further - Bloom's own approval moves them to status:awaiting-client, and your sign-off in chat finalizes them. When several deliverables await you, target one by number: approve #24. Opt-in specialist reviewers (architecture, security, QA) can add advisory findings beside the Product-Owner review; they never gate the merge.

Engineering detail stays on the PR; chat gets the product-level headline. Routine churn (a review round bouncing) is not notified at all - it shows in the Project View's Timeline tab.

Deploy​

The MVP deployment ticket follows the review flow with one twist: the engineer scaffolds the deployment pipeline (a real CI deploy workflow is required - a deployment PR without one is rejected) with no live credentials in the repo. When the pipeline PR passes review, the ticket parks at status:awaiting-client and Bloom points you at the dashboard's Credentials tab.

Credentials are write-only: values are stored encrypted and can never be read back through the app; the project's CI pipeline fetches them at deploy time via OIDC. A project-local credential overrides a same-named one from your Global Credentials Store. Once every secret the deployment scheme requires is in, Bloom nudges you exactly once that go-live is one approve #<n> away - your approval merges the pipeline PR, and Bloom messages you the live URL.

Steer, track, and evolve​

  • Ask for status any time in chat ("what's the current project status?") - Bloom answers from live GitHub state, surfacing blocked, escalated, and in-review work.
  • Watch it live: Details, Workflow (the SDLC graph), and Timeline tabs update in real time over a server event stream.
  • Change the plan by conversation: a post-planning change request makes Bloom draft a new PRD revision and the delta against the current plan - what gets added, updated, or retired, including any in-flight work a removal would close - and apply it only after you re-approve.
  • On its own cadence, Bloom self-heals coordination (recovering work a missed webhook left behind), flags stalled tickets, and sends a periodic digest - suppressed when nothing changed.
  • Wind down from the Project View's Settings tab (rename, archive, delete - with confirmation) or by asking in chat.