Proposals
Proposals are Supaspec's equivalent of pull requests. They let AI agents suggest changes to your specs that you can review, comment on, and accept or reject.
How Proposals Work
When an agent uses update_section with mode: "propose", the section content stays unchanged. Instead, Supaspec creates a proposal containing the suggested changes for your review.
1. Agent creates proposal
The agent sends the full proposed content. Supaspec computes a diff against the current version.
2. Review period
The proposal is open for comments. You can review the changes in the editor or proposals dashboard.
3. Agent revises (optional)
If you leave comments, the agent can push revisions addressing your feedback.
4. Accept or reject
Accepting applies the changes and creates a new version. Rejecting leaves the content unchanged.
Accepting a Proposal
When you accept a proposal:
- • Section content is replaced with the proposed content
- • A new version is created with full attribution
- • The proposal status changes to “accepted”
Rejecting a Proposal
When you reject a proposal:
- • Section content remains unchanged
- • Optional rejection reason is recorded as a comment
- • The proposal status changes to “rejected”
Comments & Revisions
Proposal comments support:
- • Threading — reply to existing comments
- • Line references — anchor comments to specific line ranges
- • Resolution — mark comments as resolved
Agents can read comments via get_proposal, push updated content via update_proposal, and resolve addressed comments via resolve_comment.
MCP Tools for Proposals
The following MCP tool actions are available:
section update (mode: propose) | Create a proposal from full proposed content |
proposal list | List all pending proposals in a project |
proposal get | Get proposal details with changes and comments |
proposal accept | Accept and apply a proposal |
proposal reject | Reject a proposal with optional reason |
proposal update | Push a new revision to address feedback |
comment add | Add a comment on a proposal |
comment resolve | Mark a comment as resolved |
When to Use Proposals vs Commits
Use proposals when:
- • You want to review agent output before applying
- • Comparing suggestions from multiple agents
- • Working with untested or new agents
- • You prefer a PR-style workflow
Use direct commits when:
- • Working with trusted agents on routine updates
- • Speed is more important than review
- • You'll review via version history instead
- • Making quick, small changes