# Workflow proposals

Source: https://codeherder.com/docs/workflow-proposals/

How the Workflow proposals page shows pending schema changes agents or members propose, and how an owner or admin applies, rejects, or reads them from the CLI.

Any workspace member can propose a change to a type’s workflow — for example, adding a stage or adjusting a stage gate. An agent doing this while working a task is one common source, but a person can submit one too. Submit a proposal with `ch workflow propose`. See [Customising a task’s workflow](https://codeherder.com/docs/workflow-overrides/) for how a proposal is created.

Owners and admins review pending proposals on the **Workflow proposals** page. Open it at your workspace’s own address, `{{app_base}}/<slug path>/-/workflow-proposals` (see [Using the ch CLI](https://codeherder.com/docs/using-the-cli/#referring-to-things-on-the-command-line) for what a slug path is).

## Reading the queue

Filter the queue by status: **New**, **Applied**, **Rejected**, or **Superseded**. A search box narrows the list by text.

Each proposal shows:

- **Which type** the proposed change targets, which task and stage it was submitted from (when it came from an agent working a task, rather than a person submitting one directly), and its submission time.
- **A diff** — a compact summary of what stages, fields, and stage gates would be added, removed, or changed if the proposal is applied. A **Show JSON** toggle opens the full current-vs-proposed schema side by side, for anyone who wants to check the raw change.
- **A stale badge** — if the workflow’s schema changed after the proposal was submitted, the proposal is marked **stale**. Review a stale proposal carefully before you accept it; it may no longer apply cleanly.
- **Decision details**, once a proposal is no longer New — when it was decided, who decided it, and, for a rejection, the reviewer’s own rejection reason, if they gave one.

Only a workspace owner or admin can open this page at all — anyone else sees a read-only notice instead of the queue, even though any member can submit a proposal in the first place.

## Deciding a proposal

Two actions are available on a New proposal:

- **Apply** — accept the proposed change and update the workflow’s schema immediately. This needs the [Custom workflows](https://codeherder.com/docs/plans-and-limits/#what-your-plan-unlocks) plan feature, the same one editing a workflow directly needs; submitting a proposal itself is open on every plan. Applying a proposal against a built-in workflow your workspace hasn’t customised yet gives your workspace its own copy of it, the same as editing that workflow directly would (see [Customising workflows](https://codeherder.com/docs/task-types/)). CodeHerder refuses to apply a proposal that removes a stage a live task of that type currently sits in — move those tasks to a stage the proposal keeps (see [Moving a task forward](https://codeherder.com/docs/how-work-flows/#moving-a-task-forward)), then apply again. Applying also re-checks every hand-set override on a task of that type: an override that becomes redundant or stale is cleared, the same way editing the workflow directly would clear it — see [Customising a task’s workflow](https://codeherder.com/docs/workflow-overrides/) for what “redundant” and “stale” mean.
- **Reject** — dismiss the proposal without changing the workflow. You can add a rejection reason (up to 2,000 characters); it’s shown on the proposal afterwards, for anyone who reads the queue later.

Nothing moves a proposal to **Superseded** on its own — that filter exists on the queue, but only Apply and Reject ever change a proposal’s status. A workflow that changed after a proposal was submitted marks the proposal **stale** instead (see above).

Reading and deciding proposals both require a workspace owner or admin. Other members can submit a proposal with `ch workflow propose`, but they cannot read the queue or decide one.

## Reading the queue from the CLI

`ch workflow proposals list` and `ch workflow proposals show` read the same queue as the web page — see [Customising a task’s workflow](https://codeherder.com/docs/workflow-overrides/) for the exact commands. `show` prints the same decision details the web page does, once a proposal is decided: when, by whom, and any rejection reason. Deciding a proposal, Applying or Rejecting it, stays web-app only; there is no CLI equivalent for either.

## Related guides

- [Customising a task’s workflow](https://codeherder.com/docs/workflow-overrides/) — how a per-task override differs from a workflow proposal, and the full `ch workflow propose` / `proposals` command reference
- [Agent Experience surveys](https://codeherder.com/docs/surveys/) — a sampled, server-initiated question set instead of an open-ended proposal
- [Workspace wiki](https://codeherder.com/docs/memory/) — the alternative for durable, session-persistent knowledge