Proposals

How the propose mode works — agents suggest changes, humans review and accept or reject.

Overview

When an AI agent updates a section, it can choose between two modes:

  • Commit (default) — the change is applied immediately
  • Propose — the change is saved as a proposal for human review

Proposals let you stay in control while still leveraging AI agents for generating and improving spec content.

How It Works

Creating a Proposal

When an agent calls update_section with mode: "propose":

  1. A new version is created with type: "proposal" and proposalStatus: "pending"
  2. The section's current content is NOT changed
  3. The proposal appears in the revision log and the proposals page

Example prompt:

"Review the Architecture section in Optimus and suggest improvements, but don't overwrite it directly."

The agent will call:

{
  "tool": "update_section",
  "params": {
    "project": "optimus",
    "section": "architecture",
    "content": "... improved content ...",
    "message": "Suggest WebSocket layer for real-time sync",
    "description": "Current architecture misses real-time collaboration...",
    "mode": "propose",
    "agent_name": "cursor"
  }
}

Reviewing Proposals

Proposals appear in two places:

  1. Section sidebar — a badge showing "2 proposals" next to sections with pending proposals
  2. Proposals page — a dedicated view listing all pending proposals across the project

Each proposal shows:

  • Which agent suggested it
  • The commit message and description
  • A diff against the current section content
  • Accept / Reject buttons

Accepting a Proposal

When you accept a proposal:

  1. The proposal's content replaces the section's current content
  2. The proposal's proposalStatus changes to "accepted"
  3. An activity entry is logged

You can also Edit & Accept — modify the proposed content before applying it.

Rejecting a Proposal

When you reject a proposal:

  1. The section content remains unchanged
  2. The proposal's proposalStatus changes to "rejected"
  3. You can optionally provide a reason
  4. An activity entry is logged

Proposals in the Revision Log

Proposals live in the same timeline as commits. The revision log shows both:

v5 | Cursor      | "Suggest WebSocket layer" [PROPOSAL - pending]
v4 | Claude Code | "Add caching strategy"
v3 | Claude Code | "Restructure components"
v2 | Cursor      | "Add deployment diagram"
v1 | Yurii       | "Initial draft"

This unified timeline means you see the complete history of a section — every change, whether committed or proposed — in one place.

Via MCP Tools

Agents can interact with proposals through these MCP tools:

  • update_section with mode: "propose" — create a proposal
  • list_proposals — list all pending proposals in a project
  • accept_proposal — accept a pending proposal
  • reject_proposal — reject a pending proposal with optional reason

When to Use Proposals

Proposals are useful when:

  • You want to review agent output before it takes effect
  • Multiple agents are working on the same section and you want to compare suggestions
  • You're using an agent you haven't tested yet and want a safety net
  • You want to maintain a review workflow similar to pull requests

For trusted agents doing routine updates, direct commits are usually faster.