Lifecycle, status, and gates

A card's lifecycle is governed by its status and gates. These markers track progress and enforce quality gates before code is written or merged.

Status values

A card is always in one of five states:

• todo: The task is defined but work has not started.
• active: An agent is actively executing an action against the card.
• needs_review: The agent has finished its run and is awaiting human review of the changes.
• done: The task is complete and changes are merged.
• archived: The card is archived and hidden from the active list.

Configuring gates

Each gate has two controls on the card detail panel: the Plan toggle and the Merge Request toggle. Use each toggle to require the gate, and the matching Approve action to approve it. The merge gate cannot be approved until the plan gate is approved.

A card's gates are represented by four fields:

{
  "gates": {
    "planRequired": true,
    "planApproved": false,
    "mergeRequestRequired": true,
    "mergeApproved": false
  }
}

Gate definitions

Gate	Description
planRequired	If true, the agent must submit a plan for approval before writing code.
planApproved	Set to true when you approve the agent's plan.
mergeRequestRequired	If true, the agent must request a merge review before completing the card.
mergeApproved	Set to true when you approve the code changes.

Advisory gates

Both the plan gate and the merge gate are advisory. They are checkpoints that prompt for your approval at the right moment — they do not hard-block a status transition.

• Plan gate (planRequired / planApproved): when a plan is required but not yet approved, an autonomous agent is expected to halt and ask for input before writing code.
• Merge gate (mergeRequestRequired / mergeApproved): when a merge review is requested but not yet approved, you are prompted to review and approve before completing the card.

Both gates are off by default, and you stay in control of whether to require them.

Approving a card's merge gate

To approve changes and complete a card:

1. Open the card in the VS Code Cards panel.
2. Review the code changes in the Attribution Tree (derived from the card's commits/ directory).
3. Click Approve Merge to approve the merge gate.
4. Transition the card's status to Done.