Skip to content
SHRINESHRINE

Governance

Keepers

Section titled “Keepers”

Keepers guide what becomes official. They surface direction and hold space for discussion.

Anything Can Be Proposed

Section titled “Anything Can Be Proposed”

Anything. If it shapes how we work with AI, it’s in scope: no idea is too small, too unconventional, or too half-formed. The categories below are common shapes, not boundaries:

  • Principles: Behavioral standards the org commits to
  • Patterns: Reusable techniques for working with AI
  • Stack choices: Tool, model, or integration recommendations
  • Governance changes: Amendments to this process

If your idea doesn’t fit neatly into one of these, propose it anyway. The Refine step exists to help raw ideas find their shape.

Before You Propose

Section titled “Before You Propose”

The questions below aren’t a checklist you must pass; they’re the questions the community will explore together, and the proposal template prompts you for them. Skim them, then propose anyway.

  • What’s the cost of keeping this current as tools and practices change?
  • What’s the impact of accepting it?
  • Is this already covered elsewhere?
  • Can I demonstrate this with a real example?
  • Does this scale across teams and clients?
  • Would I follow this myself?
  • Is this the right altitude: principle, pattern, or stack?

Proposal Lifecycle

Section titled “Proposal Lifecycle”

1. Propose

Section titled “1. Propose”
  • Open a Discussion in the “Proposals” category
  • The proposal form asks for:
Self-Assessment
Checkboxes for the questions in Before You Propose.


Proposal Type
Principle, Pattern, Stack Choice, or Governance Change.


The Proposal
One sentence. What are you proposing?


Why This Matters
What goes wrong without it? Cite real examples if possible.


Open Questions
What needs refinement before this solidifies?


Prior Art
Related patterns, external references, or internal docs.


Documentation PR
Link to the draft PR (added once refined).

2. Refine

Section titled “2. Refine”
  • The community discusses
  • The proposer updates the description as consensus emerges
  • Open questions get resolved or split into separate proposals

3. Draft PR

Section titled “3. Draft PR”
  • Once refined, the proposer opens a draft PR with the documentation update
  • The PR adds or updates the relevant page in docs/src/content/docs/
  • Link the PR in the discussion under “Documentation PR”
  • The PR remains in draft until ratification

4. Endorse

Section titled “4. Endorse”
  • At least two keepers must explicitly endorse the proposal
  • Endorsement via thumbs-up reaction or comment
  • Endorsement indicates agreement with both the proposal and the draft PR

5. Objection Window

Section titled “5. Objection Window”
  • Thirty days from the second keeper endorsement
  • Objections raised during this window must be addressed before ratification
  • A majority of keepers can override an objection
  • If an objection stands unresolved, the proposal returns to Refine or the discussion closes with a “Declined” label

6. Ratify

Section titled “6. Ratify”
  • The draft PR is marked ready and merged
  • The discussion closes with an “Accepted” label
  • The new page links back to the original discussion

Expedited Ratification

Section titled “Expedited Ratification”
  • The CTO or VP of Engineering can bypass the objection window
  • Every other step still applies, including the two keeper endorsements

Keeper Decision

Section titled “Keeper Decision”
  • A majority of keepers can ratify a page, or amend a ratified page, directly
  • They can waive the Discussion step
  • The PR or Discussion records the decision; the page’s proposal field links it

Amendments

Section titled “Amendments”
  • Ratified content remains open for adjustment
  • To propose a change, open a new Discussion referencing the existing page
  • Any route above applies

Page Status

Section titled “Page Status”

Every principle, pattern, and stack page shows its status under the title. Section overview pages, index pages, and the sidebar show no status.

Status Meaning Sections
Ratified Adopted by any route above; changed per Amendments Principles, Patterns
Draft Under refinement; use as guidance, expect changes without the full lifecycle Stack, Current Stack Roster
  • Set by the status frontmatter field: ratified or draft
  • Promoting a Draft page to Ratified follows any route above

Metadata

Section titled “Metadata”

Every ratified page carries the fields below. Section overview and index pages are exempt.

  • proposal: link to the original discussion
    • Keeper decisions link the PR or Discussion that records them
  • last-reviewed: date of most recent keeper review

Keepers periodically sweep pages whose last-reviewed date has gone stale, re-examining whether the guidance still holds.