propose-rfc

name

propose-rfc

description

Draft a community RFC (Request for Comments) for a non-trivial change to the Summoned AI Gateway — anything that touches the public contract, core architecture, or cross-cutting concerns. Trigger when the user says "I want to propose X", "let's RFC this", "design doc for Y", or when a change obviously needs broader discussion (breaking header change, new middleware ordering, new top-level config field).

Propose RFC

Open-source projects move faster when design decisions are written down before code. This skill generates a community-facing RFC so contributors can weigh in before implementation.

When is an RFC needed?

Required when the change:

• Adds/removes/renames an X-Summoned-* response header
• Adds/removes/changes a top-level config field
• Changes the provider/model slug format
• Adds a new route under /v1/, /admin/, or /ws/
• Alters middleware ordering
• Adds a new runtime dependency
• Breaks backward compatibility with either SDK

Not required for: new providers (just use add-provider), pricing updates, bug fixes, internal refactors.

Step 0: Gather info

• Title — short, imperative (e.g. "Unify cache backends behind a registry")
• Problem — what is broken or missing today?
• Proposal — one paragraph
• Alternatives considered
• Affected surfaces — which files/contracts?
• Breaking changes — yes/no + migration path

Step 1: Find the next RFC number

ls rfcs/ 2>/dev/null | grep -E '^[0-9]{4}' | sort | tail -1

If rfcs/ doesn't exist, create it with RFC-0001. Otherwise next zero-padded 4-digit number.

Step 2: Draft the RFC

File: rfcs/NNNN-<kebab-title>.md

# RFC <NNNN>: <Title>

- **Status:** Draft
- **Author:** <you>
- **Created:** YYYY-MM-DD
- **Target release:** <version or "next minor">

## Summary

One paragraph: what + why.

## Motivation

What is broken today? What can users NOT do? Cite issue numbers
(`#42`) and file paths when referencing current behavior.

## Detailed design

Describe the change at implementation level. Include:
- Before/after code or config snippets
- New/changed contracts (request shape, response header, env var)
- Interaction with existing features (cache, fallback, guardrails, rate-limit)

## SDK impact

- TypeScript SDK: <changes>
- Python SDK:     <changes>
- Both follow via `sdk-syncer` agent after implementation lands.

## Migration

How do existing users adopt the new behavior? Is it opt-in via config,
auto-upgraded, or a breaking change with a deprecation window?

## Alternatives considered

At least two:
- Option A: <describe> — rejected because…
- Option B: <describe> — rejected because…

## Open questions

- <question>
- <question>

## Unresolved security/privacy concerns

…

Step 3: Wire it in

• Add a row to rfcs/README.md (create the index file if it doesn't exist) with | NNNN | Title | Status | Author |.
• Reference the RFC in any tracking issue (gh issue comment <n> -b ...).

Step 4: Announce

Do NOT post to GitHub/Slack/Twitter yourself. Produce a ready-to-paste announcement snippet (one paragraph + a link) and hand it to the user.

Rules

• RFCs are prose, not decisions. Don't write "we will do X" — write "this proposes X".
• No code changes in the same commit as the RFC. Keep separate.
• Keep under 1000 words unless the change truly warrants more.
• Respect CLAUDE.md design principles — if the RFC violates one (e.g. adds a static model catalog), call that out explicitly in the Alternatives section.