Platform/BMAD workflows
Run BMAD-methodology wizard workflows to produce briefs, PRDs and architecture documents, then generate tasks for AI agents.
BMAD is the methodology built into ForgeAI: a structured, step-by-step path from product idea to implementation. Instead of prompting an AI agent freeform, you walk through a guided wizard where each step has a defined goal — analysis, planning, solutioning — and produces reviewable artifacts such as a product brief, a PRD, or an architecture document. The AI conversation for each step runs on your own machine through the CLI, while the cockpit orchestrates the steps, stores the results, and turns the outcome into tasks on the live board.
Creating a workflow requires at least one CLI device registered in your organization — all AI work runs on a developer's machine, not in the cloud. If no CLI is registered, the new-workflow page shows a Connect a CLI to create workflows alert instead of the form. See Authenticating the CLI and Connecting projects, then run:
forge connectAny organization member can create workflows, view their artifacts and conversations, and generate tasks from completed ones. Interacting with the wizard — chatting with the agent, answering elicitation questions, starting, skipping or approving steps — and deleting workflows require admin permissions by default (see Organizations & members for the role model).
Workflow templates are not hardcoded: they come from published methodology skills managed by platform administrators. When you create a workflow you pick a Methodology (for example "BMAD Method" — a full-stack methodology from product brief to implementation) and, if that skill defines several workflows, the specific workflow to run. Each skill also defines the Kanban pipeline that its tasks will move through on the board.
Every workflow declares which contexts it applies to. The context also determines the git branch prefix:
| Context | Meaning | Branch prefix |
|---|---|---|
| Greenfield | New project from scratch | feature |
| Brownfield — Major | Significant architecture or feature changes | feature |
| Brownfield — Minor | Small feature additions or enhancements | improve |
| Brownfield — Patch | Bug fixes and hotfixes | fix |
Go to your project's Workflows page and click through to /orgs/<orgSlug>/projects/<projectSlug>/workflows/new. The form is a two-stage wizard:
If the project has a git repository URL, ForgeAI creates a dedicated branch for the workflow, named {prefix}/{workflow-slug}/base (for example feature/user-auth/base). Branch creation is performed by a connected CLI on a developer's machine; the wizard header shows the source branch, base branch, and a live branch status badge. Task branches later nest in the same namespace, e.g. feature/user-auth/setup-db.
Each workflow opens at /orgs/<orgSlug>/projects/<projectSlug>/workflows/<workflowSlug> with a clickable stepper, a chat panel, and an action bar. Steps are copied from the skill definition; the first non-optional step starts automatically and is dispatched to a connected CLI, which spawns the AI agent in a local container.
The step chat streams the agent's output live, including tool-activity indicators and token usage. Press Enter to send and Shift+Enter for a newline. The wizard is refresh-safe: reload the page mid-stream and the accumulated output is replayed.
After the agent finishes responding it stays available for a 5-minute idle window (the UI shows a live countdown) during which follow-up messages resume the same session with full context. After the window expires, your next message starts a fresh agent session that replays the full conversation history.
Agents can ask structured questions instead of free-form prompts. The wizard renders them as a paginated form (Question i/N) with single-select, multi-select, an "Other" free-text option, or pure free-text answers. Your answers are combined into a single formatted chat message, and pending questions survive page refreshes.
There is no manual "complete step" button — the agent signals completion and delivers its files. The cockpit then shows a Step Deliverables review dialog:
Optional steps show Start and Skip buttons; non-optional steps cannot be skipped. Completed steps stay browsable in the stepper in read-only mode with a View Files button.
Workflows are single-editor: interacting with the wizard takes a 10-minute lock tied to your membership. Other members see a "Workflow locked" banner naming the current editor. The lock is released when a step advances.
The branch status badge in the wizard header has three states: pending (waiting for a connected CLI to create the branch), created, and error (the CLI reported that branch creation failed). Status changes are pushed to the page live. The failure reason is stored server-side, but the cockpit currently shows only the error badge, not the message itself (beta limitation). While the branch is still pending and no CLI is connected, the wizard shows a "Connect a CLI to create the workflow branch" banner.
If a step dispatch fails or stalls — your message sits in the chat without an agent response starting — a Retry button appears in the chat. It resets the step's dispatch state and re-dispatches it to an available CLI, so the usual recovery is to bring a CLI back online with forge connect, then click Retry.
Once the workflow branch exists, the wizard toolbar has a copy button for the matching CLI command, so you can open the branch on your machine:
forge workflow open <workflowId>See the CLI command reference for details.
Each completed step produces artifacts — with the BMAD Method these are documents like the product brief, PRD, and architecture. The actual files are committed to the workflow branch on the developer's machine; the cockpit stores each artifact's file name, path, and (when the CLI includes it) a copy of the file content for inline viewing.
You can view artifacts in three places: the deliverables review dialog during a step, View Files on any completed step, and the artifact list on the workflow completion screen. Viewing is read-only; if the CLI did not upload the content, the viewer shows "File content not available." and the file itself lives on the branch.
Re-completing a step (after requesting changes) replaces that step's previous artifacts. There is currently no artifact download or export button in the cockpit — check out the workflow branch to get the files (beta limitation).
When the last step is approved or skipped, the workflow completes and shows a Workflow Complete screen. From there, Generate Tasks sends the workflow's artifacts to a connected CLI, where an AI agent analyzes them and proposes task groups and tasks with dependencies — the button is disabled with a warning if no CLI is connected, because the analysis runs on your machine.
The generated tasks are created in one transaction (dependency cycles are rejected), placed in the first pipeline column, broadcast live to the board, and unblocked tasks are automatically dispatched to CLI agents. Regenerate Tasks asks for confirmation first, then deletes all existing tasks and groups linked to the workflow before generating new ones. See Tasks & the live board for what happens next, and Releases & merge-back for merging a finished workflow branch back.
Wizard conversations are encrypted at rest with AES-256-GCM. Each workflow gets its own encryption key, derived via HKDF-SHA256 from the server's master key, so compromising one workflow's data does not expose others. Messages that cannot be decrypted render as "[Message could not be decrypted]" instead of failing the page.
Note that when a workflow completes, all of its conversations are permanently deleted from the database in the same transaction — chat history does not survive workflow completion, but artifacts do. See Security for the broader security model.
The project's Workflows page lists standard workflows with filter tabs All / Active / Completed and a search box (both persisted in the URL). Each card shows step progress, an indicator of how many steps produced artifacts, and — once the workflow is completed — the number of generated tasks.
Workflows move through statuses In Progress → Completed, then Merged or Released once handled by the release system. A workflow can be deleted while it is not completed; deletion removes its steps, conversations, and artifacts, but any generated tasks survive and are simply detached from the workflow.