RFC Process

Substantial changes to ZeroClaw's architecture, user-facing surface, or core policies go through an RFC before implementation. The process exists to surface design trade-offs, give maintainers and contributors a chance to push back early, and leave a searchable record of why a decision was made.

Governance, RFC ratification rules, and voting thresholds are defined in RFC #5577.

When to file an RFC vs. just a PR

Rule of thumb: if you'd want a second opinion before writing the code, it's an RFC. If it's obvious what to build, it's a PR.

Filing an RFC

RFCs are GitHub Issues tagged type:rfc. Title format:

RFC: <short description of the proposal>

Body structure — adapt to the size of the proposal:

1. Problem — what user pain or system deficiency motivates this?
2. Proposal — what are you proposing to do?
3. Design — the details; code sketches, schema shapes, migration plans
4. Alternatives considered — what else did you evaluate, and why not?
5. Non-goals — what this proposal explicitly isn't trying to solve
6. Risks and mitigations — what could go wrong, and what's the rollback story
7. Rollout — feature-flagged? schema-versioned? breaking change window?

Filed RFCs go through a discussion window (default 7 days, longer for larger proposals). Anyone can comment. Maintainers weigh in. The RFC author iterates on the body in response.

Ratification

Per RFC #5577, RFCs are ratified by a two-thirds maintainer majority. The outcomes:

• Accepted — issue closed with the status:accepted label and a maintainer comment summarising the final shape. Implementation PRs can then proceed.
• Rejected — issue closed with status:rejected label and a rationale. The record lives; re-proposing requires a materially different take.
• Deferred — issue stays open with status:deferred; revisit later.
• Withdrawn — the author pulls it. Closed without prejudice.

Implementing an accepted RFC

Implementation PRs should:

• Reference the RFC issue number (Implements #5574 phase 1)
• Fit within the accepted design — if a detail changes during implementation, update the RFC body or file a follow-up clarification issue
• Ship behind a feature flag if the RFC calls for gradual rollout
• Include migration paths for users affected by breaking changes

Large RFCs often ship across multiple PRs over several releases. The RFC's tracking comment gets updated as phases land.

Current open RFCs

Open RFCs are the best primary source for "what's coming next" in ZeroClaw. Browse:

gh issue list --repo zeroclaw-labs/zeroclaw --label type:rfc --state open

As of writing, notable open RFCs:

• #5787 — Replace TOML i18n with Mozilla Fluent (this branch is the implementation)
• #5890 — Multi-agent UX flow design
• #5626 — Observability defaults (policy question: Prometheus on/off in v0.8 defaults)
• #5934 — Documentation implementation tracking (multi-phase rollout of RFC #5576)

Ratified foundational RFCs

These shape everything else. Read them before proposing cross-cutting changes:

• #5574 — Microkernel transition: crate split, feature-flag taxonomy, v1.0 path
• #5576 — Documentation standards and knowledge architecture
• #5577 — Project governance: core team, voting thresholds, this document's authority
• #5579 — Engineering infrastructure: CI pipelines, release automation
• #5615 — Contribution culture: human/AI co-authorship norms
• #5653 — Zero Compromise: error handling, dead-code policy, release-readiness bar

AI-authored RFCs

RFC authorship by AI assistants (with a human sponsor) is explicitly permitted per RFC #5615. If an RFC was drafted with AI help:

• Mark it clearly in the body ("drafted with Claude, reviewed by @singlerider")
• The sponsoring human is responsible for accuracy and for responding to review
• The human takes the ratification vote, not the AI

This has worked well so far — treat AI drafts as first-class but remember the sponsor is accountable.

See also

• How to contribute
• Communication
• Philosophy