Forge workflows

Governed paths, not blank prompts.

Instead of a blank prompt, Forge routes each request to a workflow — a set sequence of governed steps that runs the same way for every engineer, every session. Each one adapts to the task, so only the steps a job actually needs run. These are the built-in defaults — open any card to see its steps.

Every workflow — and every step inside it — can be enabled, disabled, reordered, or customized for your team in the Forge dashboard.

Out of the box

A built-in workflow for every stage.

These workflows ship with Forge — each one encodes industry best practices for its stage of the software development lifecycle. Use them as they come, or tailor every step, gate, and skill to the way your team works.

Planning

Shape and scope the work before any code is written — discovery, definition, PRDs, and readiness.

Product Discovery

Research an idea before it's a ticket — what already exists, whether it's worth doing, and roughly how big.

Steps

Check for existing work
Gather context from connected docs
Analyze roadmap fit
Frame the problem
Clarify the idea
Score impact (RICE)
Produce a rough estimate

Define a Feature

Take a raw idea to a ready-to-build ticket — clarified requirements, a PRD, and a clean handoff to engineering.

Steps

Check for existing work items
Gather background context
Clarify requirements
Collect non-functional requirements
Write the problem statement
Score impact (RICE)
Preview & create the tracker work item
Generate the PRD
Build the tech handoff plan

Design

Map the system and shape the technical approach for an existing work item.

Explore Architecture

Map the system and the key technical decisions for an existing work item — a codebase scan plus an interactive architecture discussion. Read-only: it explores, it doesn't create a ticket.

Steps

Scan the system architecture
Interactive architecture discussion — record decisions

Development

Turn a ready work item into shipped code, wave by wave.

Implement a Feature

Take a ready ticket all the way to merged code — planned, built wave by wave, and reviewed.

Steps

Receive the engineering handoff
Readiness check
Break the work into stories
Plan dependencies & implementation waves
Analyze change impact (blast radius)
Technical discovery
Define the test strategy
Implement wave by wave
Review the PR
Complete & summarize delivery

Testing

Verify quality before and after the change lands — test strategy and structured PR review.

QA Test Planning

Plan how a change will be tested — coverage and test types per acceptance criterion — without writing any code.

Steps

Fetch the work item
Readiness check
Check AC quality & testability
Review stories (INVEST)
Analyze change impact
Technical discovery
Define the test strategy

Review a Pull Request

A structured PR review — automated code analysis, requirement traceability, and a security scan.

Steps

Fetch the work item
Check branch freshness
AI-augmented PR review — analysis, AC traceability, OWASP scan
Customer impact analysis
Surface manual deploy tasks

Maintenance

Capture and resolve defects end to end.

Fix a Bug

From bug report to shipped fix — triage, ticket, fix, and review.

Steps

Capture the bug — severity, area, reproduction
Preview & create the ticket
Hand off to engineering
Implement the fix (optional)
Review the PR & surface deploy tasks (optional)

Track & manage

Stay on top of work already in flight — status, documentation, and edits.

Check Work Item Status

Read-only status snapshot of a tracked work item — progress, acceptance criteria, PR health, and prior Forge activity.

Steps

Fetch the work item
Report status — progress, acceptance criteria, PR health

Gather Work Item Documentation

Pull together every doc attached to a work item — PRDs, design docs, comments, and linked Confluence or Notion pages.

Update Work Item

Direct field edit on an existing tracked work item — title, description, acceptance criteria, priority, assignee, labels, and status.

The workflow editor

Every step, gate, and skill — yours to configure.

Every workflow is a list of steps you control. Each step carries a model tier, an approval gate, and the skills it must run — set once for the whole org, or forked for a single team.

Implement a Feature

Execute the engineering phase on a tracked work item — handoff, story breakdown, implementation waves, PR review, delivery.

"implement SHI-784"

# Step Ask to continue Skills Enabled

Fetch Work Itemfast

NeverAI decidesAlways

Story Breakdownbalanced

customized

NeverAI decidesAlways

Change Impact Analysiscapable

NeverAI decidesAlways

Technical Discoverycapable

customized

NeverAI decidesAlways

AI-Augmented PR Reviewcapable

NeverAI decidesAlways

Notify PM of Changesfast

NeverAI decidesAlways

In practice

One feature, start to finish.

Here's how a team uses Forge workflows to ship one complex feature — from a fuzzy idea to merged code — each person reaching for the right workflow, whether it's a Forge default or a version their team has customized.

Product Manager

Product DiscoveryBuilt-in

Pressure-tests the idea before anyone commits — checks for existing work, frames the problem, and RICE-scores it so only work worth doing moves forward.

"research demand for team-level saved views"

Product Manager

Define a FeatureBuilt-in

Turns the validated idea into a scoped work item (SHI-412) with a PRD and acceptance criteria, then hands off cleanly to the engineering lead.

"define a feature: team-level saved views"

Engineering Lead

Explore ArchitectureBuilt-in

Forge scans the codebase, then runs an interactive architecture discussion — surfacing the key technical questions and recording every decision before code begins.

"explore the architecture for SHI-412"

Shift-left — before the code lands

QA Engineer

QA Test PlanningBuilt-in

Maps a test strategy to every acceptance criterion — unit, integration, and end-to-end coverage — while the code is still being written, not after.

"plan the test strategy for SHI-412"

Engineer

Implement a FeatureBuilt-in

Builds the feature wave by wave against the agreed plan — briefed on the architecture up front, so the first pass holds up in review — and opens a pull request.

"implement SHI-412"

Running in parallel

QA Engineer

Review a Pull RequestQA · Customized

A QA-team fork adds extra code-quality and test-coverage scans, pausing the merge when coverage slips.

"review the PR for SHI-412"

DevOps Engineer

Review a Pull RequestDevOps · Customized

A DevOps-team fork checks the change's impact on infrastructure performance and cost before it ships.

"review the PR for SHI-412"

Anytime, throughout the build

Product Manager

Check Work Item StatusBuilt-in

Pulls a read-only snapshot whenever it's needed — progress, acceptance criteria, and PR health, written straight back to Jira, Linear, or Notion — so there's no standup chase.

"what's the status of SHI-412?"

Custom workflows

Your process, your workflows.

Need something the defaults don't cover? An admin invokes the forge-workflow skill in Claude Code, Codex, or Cursor and describes the change in plain English. Forge drafts it, shows exactly what changes, and saves it — across the org, or forked for a single team.

Claude Code v2.1.178

Opus 4.8 (1M context) · Claude Max

D:\Development\ShipToday\forge-mcp

>/forge-shiptoday:forge-workflow Create a new workflow for my DevOps team to review infrastructure cost impact of a work item

I'll start by loading the Forge catalog tools and fetching the catalog (which also tells me your role and what's available).

Read 1 file, called plugin:forge-shiptoday:forge

I need to read the full catalog to check my role, the field schema, and available skills.

Read 1 file

I have everything I need from the catalog. Quick reads:

- Role gate: you're org:admin with an org context ✅ — authoring is allowed.

- Intent: clear from your request — Create path, team-scoped to DevOps.

- Reusable skill found: your catalog already has an org-scoped skill infra_cost_impact_review — "Assesses the infrastructure cost impact of a pull request's changes… cloud resources, scaling/per-request cost, data egress, logging/observability volume, background-job frequency… flagging top cost drivers with estimated direction/magnitude and cheaper alternatives." That's exactly your ask, so I'll reuse it rather than synthesize a new skill.

One thing worth flagging before the draft: your DevOps team's review_pr workflow already includes infrastructure cost impact (alongside vendor cost). So what you're asking for is a lean, standalone workflow that runs just the cost review on demand, without the full PR-review pipeline. Here's my draft.

---

Proposed workflow (new, team-scoped → DevOps)

Workflow fields

Field	Value
id	review_infra_cost
name	Review Infrastructure Cost Impact
description	Standalone infrastructure cost-impact assessment for a work item's code changes — cloud resources, scaling/per-request cost, data egress, logging volume, and background jobs — flagging top cost drivers and cheaper alternatives.
team_name	DevOps
classifier_hint	Pick this when a DevOps user wants a standalone infrastructure cost-impact review of a work item's code changes (cloud resources, scaling, egress, logging, background jobs) — without running a full PR review.
example_invocation	review infra cost impact for PROJ-123
auto_classify	true · enabled true

Steps (from scratch — no baseline diff)

#: 0

Skill: resolve_work_item

Confirmation: auto (skill default)

applicable_expression: null (always)

Why: Lightweight lookup to anchor the work item by key, so the workflow runs from a bare PROJ-123.

#: 1

Skill: infra_cost_impact_review

Confirmation: ai_judgment (skill default)

applicable_expression: _has_local_code == true

Why: The reused skill's canonical gate — it analyzes changed code, so it only runs when local code is connected.

Notes on my choices:

- No new custom skills needed — both steps reuse existing catalog skills, so no display_text/SDLC-stage decisions to make.

- The _has_local_code == true gate on step 1 is the skill's canonical default (a runtime-set phase flag, not something a step sets — so it's reachable). The practical effect: if no local codebase is connected in the session, step 1 is skipped and the run is a no-op. If you'd rather it always attempt (set gate to true) or you only ever run this with code present, tell me.

Does this look right, or would you like to change anything? For example:

- Add a notification step at the end (e.g. notify_tech_lead posting the cost findings)?

- Anchor with the richer receive_epic_handoff (pulls child items + PRDs) instead of the lightweight resolve_work_item?

- Keep it org-scoped instead of DevOps-only?

I won't save until you confirm.

✳ Cooked for 1m 32s

>Looks good, save to DevOps only

You've given explicit approval, so I'll save it now — referential check passes (resolve_work_item is a system skill, infra_cost_impact_review is your org skill; no new skills needed) and the one gate (_has_local_code == true) is a runtime phase flag, so it's reachable.

Called plugin:forge-shiptoday:forge

✅ Saved. review_infra_cost ("Review Infrastructure Cost Impact") is now live at team scope → DevOps. No warnings returned.

It'll be picked by the AI classifier when a DevOps user asks for a standalone infra cost review — e.g. "review infra cost impact for SHI-512". The flow resolves the work item, then runs the infra_cost_impact_review skill (only when a local codebase is connected, per the _has_local_code gate).

Note it's distinct from your DevOps review_pr workflow, which still bundles infra cost + vendor cost into the full review pipeline — this new one is the lean, on-demand version.

A real forge-workflow session — plain-English request, a full keep/add plan, and an admin-confirmed save, scoped to one team.

What you can ask for

Run the forge-workflow skill and just say what you want — no config files, no YAML. Each example shows something you could type (left) and the governed workflow Forge builds in response (right): extend a default, fork it for one team, or create a brand-new path.

"Add an Infrastructure Cost Impact Review step to our PR Review workflow."

Extend a workflow

A new capable-tier step that scans Terraform, Kubernetes & cloud-config diffs and surfaces cost impact before the PR can merge.

"Create a PR Review workflow for the QA team with a Test Coverage Review step."

Fork for a team

A QA-scoped fork of PR Review with an added coverage gate set to Always ask — merge pauses when coverage drops.

"In Implement a Feature, add a step to update CLAUDE.md when the architecture changes."

Keep docs in sync

A fast-tier step that refreshes your CLAUDE.md / AGENTS.md so agent guidance never drifts from the code.

"Add a Security & Privacy Review to any workflow that touches auth or PII, and always require sign-off."

Add a compliance gate

An Always-pause checkpoint wired to your security-review skill, gated to runs that touch authentication or PII.

"Create a Database Migration workflow: schema review, backwards-compat check, and a required DBA approval."

New workflow from scratch

A brand-new governed path — three ordered steps ending in a mandatory human approval gate before anything ships.

Workflow changes are admin-only, versioned, and scoped to your org or a single team. Forge shows a clear keep / add / modify diff against the current workflow before saving — so policy keeps evolving without ever going ungoverned.