Skip to content

Proposals, plans and review

Agents stage revisions into a workstream's proposal, grouped into plans, and a person accepts them one by one, all at once or as a group (or the agent, with Agent autonomy on).

The proposal

A workstream has at most one open proposal, opened by the first staging. Its states are Draft and Ready (the agent says a review pass can start with proposal_ready, and may keep staging), then Completed or Discarded. A proposal completes itself when nothing is left pending after an accept or a withdraw; the agent's next staging opens a new one.

Staged revisions

Each document an agent stages with spec_apply is a revision:

StateWhat it means
PendingWaiting for a person to decide.
SupersededThe agent staged the same artefact again.
AcceptedA person accepted it into the workstream.
WithdrawnIt was dropped without being accepted.

A pending revision needs attention while a thread is open on its artefact.

Accepting

Accept is a person's act, for an Editor or above, or an agent's with proposal_accept in a project with Agent autonomy on. It merges the staged document onto the workstream's current version: fields nobody touched since the agent read apply; an overlap is refused as stale, and the agent stages again. A revision that refers to another pending revision is accepted with it, in dependency order.

  • Accept all accepts every pending revision matching the kinds you see (and, by default, without open threads) in one step. It skips plans and their members, and revisions held by a change request or by a blocking question of their agent.
  • A revision in a plan is accepted only with its plan, with Accept group.
  • A revision held by a change request, or by a blocking question its agent asked, cannot be accepted until the thread ends.

An agent's merge of a conflict, staged with task_resolveConflict, is a revision too. Accepting it resolves the conflict with that merge, as long as Main and the workstream did not move since the agent merged.

Withdraw and discard

Withdraw drops one pending revision. Discard drops the whole proposal, and its pending revisions become Withdrawn. An agent may discard only a proposal whose pending revisions are all its own; otherwise it withdraws its own with proposal_withdraw. Withdrawing a plan withdraws only the plan: its pending revisions leave it and stay pending.

Plans and accept group

An agent groups what it stages into plans, one per intended task:

  • spec_apply with a plan: a label and the task, either a new one with its name, description and key, or an open task of the workstream by number;
  • proposal_plan creates a plan or changes its task;
  • proposal_assign moves the agent's own revisions into or out of a plan.
spec_apply, plan argumentJSON
{
  "plan": {
    "label": "Reserve stock",
    "task": { "mode": "new", "name": "Reserve stock", "externalKey": "KAN-43" }
  }
}

A revision staged again stays in its plan, an agent's conflict merge included. A person can move any pending revision between plans with Move to plan. Plans show first on the Proposals page, with their members. Accept group:

  • accepts every member in dependency order;
  • creates the task (Draft, with the plan's name, description and key) or uses the existing one;
  • scopes the accepted changes into it;
  • ends the change requests on the accepted artefacts (outcome changed), and resolves the conflict of a staged merge it carries;
  • optionally marks the task Ready in the same step (Accept group and Ready), with Ready's own checks.

Accept group is refused:

  • when the plan changed since you looked (you see what was added or removed);
  • when a member is held by a change request or by a blocking question of its agent (the plan says which);
  • when a member depends on a pending revision outside the plan;
  • when another open task already covers one of its artefacts;
  • for a task past Draft, until you confirm that its agreement changes.

Warning

Accept group and Ready is all or nothing

When Ready refuses, for example because of a person's blocking question on one of the changes, nothing is accepted. An Admin can go on with a reason, which is recorded on the task.

Change requests

Instead of accepting, a reviewer can open a change request on a pending revision. It is a thread that holds that revision's accept, alone or in its plan, until the agent stages the artefact again and a revision of it is accepted, which resolves the request (outcome changed). Withdrawing the revision, or discarding the proposal, ends it as withdrawn.

Next steps