plano/docs/peps/PEP-0000-process.md

PEP-0000: Plano Enhancement Proposal Process

Field	Value
PEP	0000
Title	Plano Enhancement Proposal Process
Status	Active
Authors	Plano Maintainers
Created	2026-04-07

What is a PEP?

A Plano Enhancement Proposal (PEP) is a design document that describes a significant change to the Plano project. PEPs provide a structured way to propose, discuss, and track major features, architectural changes, and process improvements.

PEPs are inspired by Kafka's KIP process, Kubernetes KEPs, and Envoy's design document process.

When is a PEP Required?

A PEP is required for changes that:

• Introduce a new user-facing feature or capability
• Change existing user-facing behavior in a breaking way
• Add a new subsystem or architectural component
• Modify the configuration schema in a significant way
• Add a new LLM provider with non-standard API patterns
• Change the project's processes or governance

A PEP is not required for:

• Bug fixes
• Documentation improvements
• Refactoring that doesn't change behavior
• Adding models to an existing provider
• Minor CLI improvements
• Test improvements
• Dependency updates

When in doubt, open a GitHub issue or Discussion first. A maintainer will let you know if a PEP is warranted.

PEP Lifecycle

Draft → Under Review → Accepted → Implementing → Complete
                  ↘ Declined
                  ↘ Deferred
                  ↘ Withdrawn

States

State	Description
Draft	Author is writing the proposal. Not yet ready for formal review.
Under Review	PR is open. Maintainers and community are discussing the design.
Accepted	Maintainers have approved the design. Implementation can begin.
Declined	Maintainers have decided not to pursue this proposal. The PEP remains in the repo for historical reference with an explanation of the decision.
Deferred	Good idea, but not the right time. Will be reconsidered later.
Withdrawn	Author has decided not to pursue this proposal.
Implementing	Accepted and actively being built. Linked to tracking issue(s).
Complete	Fully implemented and released.

How to Submit a PEP

1. Discuss First (Recommended)

Before writing a full PEP, validate the idea:

• Open a GitHub Discussion describing the problem and your proposed approach
• Or bring it up in a community meeting
• Or open a GitHub issue tagged enhancement

This step saves time by catching fundamental objections early.

2. Write the PEP

Copy docs/peps/PEP-TEMPLATE.md to docs/peps/PEP-XXXX-short-title.md (use the next available number). Fill in all sections. The template is deliberately structured — each section exists for a reason.

Key guidelines:

• Be specific. "Add caching" is too vague. "Add exact-match response cache with configurable TTL keyed by model + message hash" is actionable.
• Show the config. If the feature involves user-facing configuration, include the YAML snippet users would write.
• Address trade-offs. Every design has trade-offs. Acknowledging them strengthens the proposal.
• Include alternatives. Explain what other approaches you considered and why you chose this one.

3. Submit as a Pull Request

Open a PR adding your PEP file to docs/peps/. The PR title should be PEP-XXXX: Short Title. Set the status to Draft or Under Review depending on readiness.

4. Review and Discussion

• At least two maintainers must review the PEP
• Community members are encouraged to comment on the PR
• The author is expected to respond to feedback and revise the proposal
• Discussion should focus on the design, not implementation details (those belong in code review)
• Complex PEPs may be discussed in a community meeting

5. Decision

Maintainers aim to provide initial feedback within two weeks of a PEP entering Under Review. Complex proposals may take longer, but the author should never be left without a response.

A PEP is accepted when at least two maintainers approve the PR and there are no unresolved objections. The accepting maintainer merges the PR with the status set to Accepted.

A PEP is declined when maintainers determine the proposal doesn't align with the project's direction or has fundamental issues that can't be resolved. The PR is merged (not closed) with the status set to Declined and a rationale recorded — declined PEPs remain in the repo as a record.

Resolving disagreements: If maintainers disagree on a PEP, the proposal is discussed in a community meeting. If consensus still can't be reached, the project lead makes the final call and records the rationale in the PEP.

6. Implementation

Once accepted:

• Create a tracking GitHub issue (or issues) for the implementation
• Link the issue(s) in the PEP header
• Update the PEP status to Implementing
• Implementation PRs should reference the PEP number (e.g., "Part of PEP-0042")
• When all implementation work is merged and released, update status to Complete

PEP Numbering

• PEPs are numbered sequentially starting from 0001
• PEP-0000 is reserved for this process document
• The author picks the next available number when submitting

Roles

Role	Responsibility
Author	Writes the PEP, responds to review feedback, drives the proposal to a decision
Sponsor	A maintainer who shepherds the PEP through review. Required for PEPs from non-maintainers. Find a sponsor by asking in Discord or a community meeting.
Reviewers	Maintainers and community members who provide feedback on the design

Amending Accepted PEPs

If an accepted PEP needs material changes during implementation:

• For minor adjustments (implementation details, clarifications): update the PEP in-place via a PR
• For significant design changes: open a new PEP that supersedes the original, linking back to it

Index

PEP	Title	Status	Author
0000	Plano Enhancement Proposal Process	Active	Plano Maintainers