RFCs (Request for Comments)

RFCs describe **proposed** cross-cutting or high-risk changes before large implementation effort. They complement [architecture decision records](../adr/README.

Purpose

RFCs describe proposed cross-cutting or high-risk changes before large implementation effort. They complement architecture decision records (single decisions) and execution modes (how AI should work).

When to Write an RFC

Create an RFC when any apply:

Multiple packages or apps are affected with new contracts.
Long-lived architecture boundaries change.
API, database, auth, or permissions are involved.
Window manager, Spaces, app contract, or registry semantics change.
Monorepo structure or extraction is planned.
Work needs multiple PRs or will likely exceed 10 files.
Estimated focused effort exceeds ~30 minutes without a written plan.

XL tasks in cost-gate.md require an RFC (or explicit user-approved Plan) before code.

Status Lifecycle

Draft       — under discussion
Accepted    — approved to implement in slices
Implementing — work in progress
Done        — implemented; see Implementation Notes
Rejected    — will not pursue
Superseded  — replaced by another RFC

Naming

docs/rfcs/0001-short-topic.md
docs/rfcs/0002-virtual-desktops-and-fullscreen-spaces.md

Use the next free four-digit number. Copy 0000-template.md.

Relationship to ADRs

Artifact	Use for
RFC	Multi-step feature, migration, or platform design with task breakdown
ADR	One durable decision (see ../adr/README.md)

An RFC may spawn one or more ADRs after acceptance.

AI Workflow

User or agent opens RFC in Draft (Mode 1 — no code).
Maintainer sets Accepted after review.
Implementation proceeds in Patch Mode slices per task-splitting-protocol.md.
Mark Done and fill Implementation Notes (including deviations).