RFCs (Request for Comments)
RFCs describe **proposed** cross-cutting or high-risk changes before large
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).
RFC Mode is manual opt-in only. Do not write an RFC during normal development unless the user explicitly asks for RFC-first work, planning-only work, or Opt-in Slicing Mode. Large task size alone is not enough to require an RFC.
When to Write an RFC
Recommend an RFC when any apply, but do not enter RFC Mode unless the user confirms:
- 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 and carries high coordination risk.
- The user explicitly asks for RFC-first, phase-gated, or planning-only work.
UI incubation, mock app surfaces, app cards, Storybook stories, copywriting, docs index cleanup, local mock UI, and non-destructive refactors should not create RFCs by default.
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 RFCNaming
docs/development/rfcs/0001-short-topic.md
docs/development/rfcs/0002-virtual-desktops-and-fullscreen-spaces.mdUse 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 explicitly opts into RFC Mode.
- User or agent opens RFC in Draft.
- Maintainer sets Accepted after review.
- Implementation proceeds in slices only when Opt-in Slicing Mode is active.
- Mark Done and fill Implementation Notes (including deviations).