mcpctl/docs/proposals.md

Resource Proposals

A proposal is a pending change to a Prompt or Skill, submitted by either a Claude Code session (via the propose_prompt / propose_skill MCP tools) or a human (via the web UI / CLI). Reviewers triage the queue and either approve — at which point the proposal becomes a real prompt or skill — or reject with a note.

This is the path by which Claude proposes back to mcpd: things the session learned that future sessions would benefit from. The propose-learnings global skill (seeded by mcpd at startup) explains the discipline to Claude.

Model

ResourceProposal shares the schema's discriminator pattern with ResourceRevision — single table, resourceType field disambiguates prompts vs skills.

Field	Purpose
resourceType	'prompt' | 'skill'.
name	Proposed resource name.
body	Proposed body ({ content, priority?, metadata?, … }).
projectId / agentId	Scope of the proposal (XOR; null/null = global).
createdBySession	mcplocal session that proposed (when from Claude).
createdByUserId	User who proposed (when via UI/CLI).
status	'pending' → 'approved' | 'rejected'.
reviewerNote	Set on approval or rejection.
approvedRevisionId	Set when approved — points at the resulting revision.

Two unique constraints — (resourceType, name, projectId) and (resourceType, name, agentId) — mirror the Prompt / Skill scoping rules. The same ?? '' workaround for nullable-FK lookups applies.

Reviewer flow

CLI

mcpctl review pending                          # list pending
mcpctl review next                             # show oldest pending
mcpctl review show <id>                        # full detail
mcpctl review diff <id>                        # before/after diff
mcpctl review approve <id>                     # POST /proposals/:id/approve
mcpctl review reject <id> --reason "explain"   # rejected with note

Web UI

/proposals shows a Pending / Approved / Rejected tab view; the sidebar nav badge polls every 30 s and shows the pending count in amber. Click a row to see the full body, the diff against the current resource (if any), and approve / reject controls.

Approval is atomic

Approval runs in a single Prisma transaction:

1. Look up the pending proposal.
2. Dispatch by resourceType to the registered handler (PromptService or SkillService registers itself at construction).
3. Handler upserts the underlying resource — creating it if new, or updating + auto-bumping patch semver if it exists.
4. Handler records a ResourceRevision linking back to the proposal.
5. Proposal status flips to approved, approvedRevisionId set.

If any step fails, the transaction rolls back and the proposal stays pending. There is no half-approved state.

Claude side: propose_prompt and propose_skill

Both tools are registered by the gate plugin in mcplocal. They post to /api/v1/proposals with the appropriate resourceType.

The propose-learnings global skill (seeded by mcpd) tells Claude when to use them:

• propose_prompt for project-specific knowledge — gotchas, conventions, hidden constraints. Cheap to add, easy to reject.
• propose_skill for cross-cutting knowledge — debugging discipline, release hygiene, security review style. Larger blast radius; lean toward propose_prompt unless you have a clear cross-project reason.

The gate-encouragement-propose system prompt (priority 10, sits in the gating bundle) is the trigger that makes Claude actually consider proposing. Without that, the tools exist but Claude rarely engages.

Backwards compat

PR-1 / PR-2 deferred the cutover from the prompt-only PromptRequest table to ResourceProposal. Both run side-by-side today:

• mcplocal's propose_prompt still POSTs to the legacy /api/v1/projects/:name/promptrequests URL.
• mcplocal's propose_skill (newer) POSTs to /api/v1/proposals directly.
• The legacy /api/v1/promptrequests* routes remain in mcpd.
• mcpctl approve promptrequest <name> still works.

A focused follow-up PR will:

1. Migrate existing PromptRequest rows into ResourceProposal (resourceType=prompt).
2. Rename PromptRequest to _PromptRequest_legacy.
3. Update mcplocal's propose_prompt to use /api/v1/proposals.
4. Keep the legacy URL as a thin translation shim through one release.
5. Drop _PromptRequest_legacy after that.

This stays separate so the cutover is reviewable independently of the larger Skills + Revisions + Proposals work.

RBAC

Proposals piggyback on the prompts permission for now — anyone with view:prompts can read the queue, anyone with edit:prompts can approve or reject. Splitting out a dedicated proposals permission (or a "reviewer" role) is straightforward if granularity becomes useful.

Audit emission

Proposal create / approve / reject events flow through the existing audit pipeline. Approval events also reference the resulting revision id, so you can join "proposal approved at T" against "revision X created at T" without polling.