docs/book/src/foundations/fnd-003-governance.md
Starting v0.7.0 · Type: Governance · Rev. 5
Canonical reference · Ratified by the team · Rev. 5 Original governance discussion: #5577 Follow-up work-lane and label-governance policy: #6808
A note to the team before you read this.
Software projects do not fail because the code is bad. They fail because the people writing the code cannot coordinate. Features get built twice. Bugs get lost. Good ideas evaporate because nobody wrote them down. New contributors show up wanting to help and cannot find where to start. This RFC is about building the lightweight scaffolding that prevents those failures, not so the project feels organized, but so the team can move faster, with more confidence, and with less friction. Every recommendation here is chosen specifically for a small, growing, student-led open source team. Nothing here requires a project manager, a Scrum Master, or a formal committee.
| Rev | Date | Summary |
|---|---|---|
| 1 | 2026-04-09 | Initial draft |
| 2 | 2026-04-09 | Added §6.4 Architectural Compliance: Human Review, AI Support; added Discussion Question on AI automation of architecture reviews |
| 3 | 2026-05-24 | Added #6808 operational-label-policy pointers; current label behavior lives in maintainer docs |
| 4 | 2026-05-24 | Added #6808 community-pickup and issue-risk/PR-risk operational pointers |
| 5 | 2026-05-25 | Promoted #6808 feature-facing work-lane and label-governance policy into FND-003; clarified durable source boundaries, Discussions stewardship, Discord-to-GitHub handoff, and where operational gate questions live |
Every project without an intentional coordination system develops an accidental one. The accidental system for most open source projects looks like this:
This is not a criticism of anyone's effort. It is a description of what happens by default. The solution is not more process. It is the right process, applied at the right level for the size and maturity of the team.
ZeroClaw needs three things:
These are three distinct concerns. Conflating them, putting everything in one board, or relying on informal chat for decisions, is what creates the chaos the team is trying to escape.
| Concern | Tool | Why This Tool |
|---|---|---|
| Work pipeline (backlog → release) | GitHub Projects v2 | Custom fields, multiple views, Kanban + roadmap, built-in automation, milestone tracking |
| Community discussion and idea incubation | GitHub Discussions | Community-visible, no PR required, separates early conversation from committed work, promotes concrete outcomes into the owning tracked surface |
| Governance and decision authority | RFC process + Team Tiers + CODEOWNERS | Already partially established via docs/proposals/; needs formalization and close loop |
The key principle: the Project board contains only work the team has committed to thinking about. Early community discussion, ideas, Q&A, and showcases can live in Discussions when the lane is maintained. Work that has been evaluated, accepted, and scoped lives in the Project. This distinction is what keeps the board useful.
FND-003 is the durable governance source for work-lane and contribution-pipeline policy. RFC #6808 was the staging discussion for feature-facing work lanes, label governance, issue triage, and maintainer routing; after its policy slices are promoted, their durable rules live in this foundation document plus the maintainer operational pages linked below. Do not treat the RFC issue as a competing governance document after its policy has been promoted here.
Operational details intentionally live close to the workflow that uses them:
| Durable decision | Operational home |
|---|---|
| Project board purpose and stage gates | This document |
| PR lanes and merge/review queue discipline | Maintainer PR workflow |
| Label definitions, ownership boundaries, and cleanup protocol | Maintainer labels guide |
| Reviewer intake, risk depth, issue triage, and queue hygiene | Reviewer playbook |
| Mechanical issue-triage procedure and stale pass details | Maintainer skills guide and Reviewer playbook |
| Contributor-facing filing and PR mechanics | Issue templates, PR template, and How to contribute |
| Contributor communication, Discussions stewardship, and Discord-to-GitHub handoff | Communication and §4.5 below |
| RFC-shaped contribution routing before implementation | Architecture and contribution map and RFC process |
The Project board has a single Status field with seven values. Each value is a stage in the pipeline. The sequence is linear but items can be moved back:
💡 Idea
↓ Gate: Vision alignment check
📋 Backlog
↓ Gate: Architecture fit + acceptance criteria
🎯 Defined
↓ Gate: Assignee, size, risk tier confirmed
🚧 In Progress
↓ Gate: Tests written, CI passing
👀 In Review
↓ Gate: Correct reviewer tier approved, docs updated
✅ Done
Plus one terminal state that can be reached from anywhere:
🚫 Won't Do ← explicit decision not to pursue; never silently closed
The board-level Won't Do state is a durable closure decision. Current closure-label spelling and replacement-process rules live in the maintainer label guide and superseding guide.
Every transition has a gate question. The question must be answered "yes" before the item moves forward. This is the project board made operational: the Vision → Architecture → Design → Implementation → Testing → Documentation hierarchy becomes a checklist at each stage.
| Transition | Gate Question | Who Checks |
|---|---|---|
| Idea → Backlog | Does this align with the Vision statement? Does it fit the target architecture? | Core Team triage |
| Backlog → Defined | Is there a clear acceptance criteria? Does it need an ADR or design note? Is the risk tier assigned? | Assignee + reviewer |
| Defined → In Progress | Is there an assignee? Is it sized? Are the related ADRs or docs identified? | Assignee |
| In Progress → In Review | Do tests exist for the new behavior? Is CI passing? Is the PR description complete? | Author (self-check) |
| In Review → Done | Has the correct reviewer tier approved? Is documentation updated? Is the CHANGELOG entry written? | Reviewer |
| Any → Won't Do | Has the decision not to pursue been explained in the item's comments? | Core Team |
Why explicit gates matter for a student team: Without gates, cards move because someone feels done, not because done has a definition. This is the single most common source of "done" work that is not actually done. The gates make the definition visible and shared.
These gate questions are governance prompts, not another checklist to duplicate in every PR body or issue comment. The operational forms live in the artifacts that maintainers already touch:
If an old FND-003 gate question seems missing, first check those operational homes before adding another copy here.
Create these fields in the GitHub Project settings:
| Field | Type | Values |
|---|---|---|
| Status | Single select | 💡 Idea · 📋 Backlog · 🎯 Defined · 🚧 In Progress · 👀 In Review · ✅ Done · 🚫 Won't Do |
| Type | Single select | Feature · Bug · Refactor · ADR · Docs · Security · Infrastructure · RFC |
| Priority | Single select | 🔴 Critical · 🟠 High · 🟡 Medium · 🟢 Low |
| Size | Single select | XS · S · M · L · XL |
| Risk Tier | Single select | Low · Medium · High (mirrors AGENTS.md risk tiers) |
| Component | Single select | Kernel · Gateway · Channels · Tools · Memory · Security · Hardware · Docs · Infrastructure |
| Milestone | Milestone | v0.7.0 · v0.8.0 · v0.9.0 · v1.0.0 · Icebox |
On sizing (T-shirt sizes): Story points require calibration and historical data the team does not have yet. T-shirt sizes are immediately intuitive and good enough for a team at this stage:
| Size | What It Means | Approximate Scope |
|---|---|---|
| XS | Under 2 hours | A typo fix, a config tweak, a one-line change |
| S | Half a day | A small bug fix, a minor feature addition, a docs update |
| M | 1–3 days | A meaningful feature, a refactor of one module, a new test suite |
| L | 1–2 weeks | A significant feature, a new crate extraction, a cross-cutting change |
| XL | More than 2 weeks | An architectural change; should be broken into smaller items |
XL items should almost always be broken down before they enter In Progress. If you cannot break it down, the design is not complete enough.
Create four named views in the Project:
GitHub allows up to six pinned issues per repository. Use them for high-signal, always-visible communication:
good first issue items)Pinned issues are a promise to the community: these are the things that matter most right now. Update them when priorities shift.
Work-lane policy keeps the board, labels, PRs, and issues from trying to answer the same question in different places.
Use this split:
| Surface | Owns | Does not own |
|---|---|---|
| Labels | durable classification: type, scope, risk, size, contributor tier, stale/triage policy | per-push review state, active CI status, personal task lists |
| Project board | planning state: readiness, routing evidence, roadmap grouping, dependency/blocker state, stale-exemption reason when a field exists | authoritative PR review queue, mergeability, required checks |
| Native PR state | review decision, required checks, branch freshness, conflicts, mergeability, draft/ready state | long-term roadmap ownership |
| Issues/RFCs | durable discussion record, acceptance state, user need, linked implementation trail | live replacement for maintainer docs after policy promotion |
PR lanes, contributor-pickup labels, stale-exemption labels, and label migration are durable governance concepts, but their exact operational criteria live in maintainer docs. FND-003 owns the split: labels classify durable work, project boards plan work, native PR state owns live review and merge state, and issues/RFCs preserve decisions. The Maintainer PR workflow owns PR lane definitions, the Labels guide owns exact label meanings and cleanup rules, and the Reviewer playbook owns how reviewers apply those signals during triage and review. Treat live label migration as a separate maintainer-approved cleanup, not ordinary PR review.
Stale exemptions are governance exceptions, not permanent label shields. The target policy is that status:no-stale is valid only when the lane's operational source records why the issue is exempt and what visible routing evidence carries the next decision. The maintainer docs define where those facts live and how stale automation or stale sweeps enforce the rule.
Treat GitHub Discussions as a maintained community surface. Discussions are useful for questions, ideas, polls, announcements, showcases, project or integration demos, and exploratory threads that need more permanence than Discord but are not yet tracked work.
Exact categories, category descriptions, and review cadence are operational details. They belong in the contributor communication guide and maintainer workflow docs, and they may evolve without revising this foundation document.
Discussions do not become backlog work just because a thread exists. Promote a Discussion when it produces a concrete tracked outcome. Contributor-facing trigger examples live in Communication.
The target depends on the result. Confirmed bugs and accepted feature scopes move to issues. Architecture decisions move through the RFC process. PR-specific details move to PR comments. Durable operating rules move to maintainer or contributor docs.
Close the loop in the originating Discussion. If the category supports answers, mark the summary or tracked-work link as the answer when that is appropriate. If it does not, add a final summary comment with the issue, RFC, PR, or docs link.
Some items bypass Discussions and enter the tracked surface directly:
Architecture exploration can start in Discussions when the question is community-facing and not yet ready for a formal RFC. This lowers the barrier to raising design concerns without turning every early thought into tracked policy.
When the thread reaches a concrete architecture proposal, open the RFC issue and move the durable proposal into the RFC surface. The Discussion can then link to the RFC and stop being the source of truth.
Discord is for fast conversation. GitHub is the durable record. Discussions are one maintained GitHub surface for community-facing conversation that needs more permanence than Discord but is not yet tracked work.
Discussions are active only when someone owns the lane. That ownership can be a named steward or a documented review cadence. Without ownership, Discussions are a passive archive, not a required intake path.
Use Discussions for exploratory, community-facing, or broad-feedback threads. Use an issue, RFC issue, PR comment, or maintainer doc when the outcome is already concrete or authoritative. The contributor-facing trigger list and category examples live in Communication.
The handoff does not need to copy the whole chat. Capture the outcome and enough context for another maintainer to continue. If a Discussion later produces tracked work or durable policy, promote that result into the surface that owns it.
Open source projects run on meritocracy: influence and authority come from demonstrated contribution, not from seniority, title, or who you know. This is one of the things that makes open source different from corporate software, and it is worth teaching explicitly.
The three tiers reflect increasing demonstrated commitment to the project:
Anyone. No approval required.
What they can do:
What they cannot do:
Community members who have had at least two PRs merged into the master branch.
How to become one: Have two PRs merged. A Core Team member adds you to the Contributors team in GitHub and to CONTRIBUTORS.md.
What they gain beyond Community:
What they still cannot do:
Why this tier exists: It creates a visible, achievable first milestone for new contributors. "How do I get more involved?" has a clear answer: get two PRs merged. This motivates good early contributions and gives the team a way to recognize contributors publicly.
Contributors who have demonstrated consistent, high-quality contributions over time and have been invited by existing Core Team members.
How to become one: Invitation from existing Core Team members, announced publicly in Discussions. There is no formal threshold; it is a judgment call based on the quality, consistency, and alignment of past contributions.
What they gain beyond Contributor:
Responsibilities:
For routine decisions, adding a label, closing a stale issue, updating documentation, Core Team members operate under lazy consensus: if you announce your intention in the relevant issue and no Core Team member objects within 48 hours, you proceed. This prevents the paralysis of requiring explicit approval for everything while maintaining visibility.
Lazy consensus does not apply to:
These always require explicit Core Team votes.
Team membership is recorded in two places:
CONTRIBUTORS.md at the repository root: a public record of everyone who has contributed, organized by tier. Updated by Core Team members as contributors are recognized.
GitHub Teams in the organization settings: zeroclaw-core and zeroclaw-contributors teams, referenced in CODEOWNERS and used for notification routing.
The CODEOWNERS file makes governance automatic. It defines which paths require review from which team before a PR can merge. GitHub enforces this as a required review: the PR cannot be merged until the requirement is satisfied.
Create .github/CODEOWNERS:
# CODEOWNERS — Automatic review routing by risk tier
# See AGENTS.md for risk tier definitions.
# See docs/proposals/project-governance.md for team tier definitions.
# ── High Risk: requires Core Team approval ──────────────────────────────────
src/security/** @zeroclaw-labs/zeroclaw-core
src/gateway/** @zeroclaw-labs/zeroclaw-core
src/runtime/** @zeroclaw-labs/zeroclaw-core
src/tools/shell.rs @zeroclaw-labs/zeroclaw-core
src/tools/file_write.rs @zeroclaw-labs/zeroclaw-core
src/tools/security_ops.rs @zeroclaw-labs/zeroclaw-core
# ── Governance and configuration: requires Core Team approval ───────────────
.github/** @zeroclaw-labs/zeroclaw-core
CODEOWNERS @zeroclaw-labs/zeroclaw-core
Cargo.toml @zeroclaw-labs/zeroclaw-core
deny.toml @zeroclaw-labs/zeroclaw-core
# ── Architecture documents: requires Core Team review ───────────────────────
docs/proposals/** @zeroclaw-labs/zeroclaw-core
docs/architecture/decisions/** @zeroclaw-labs/zeroclaw-core
AGENTS.md @zeroclaw-labs/zeroclaw-core
# ── Default: any Contributor or Core Team member can review ─────────────────
* @zeroclaw-labs/zeroclaw-contributors
As specific Core Team members take ownership of components, add their individual handles alongside the team handle. Specificity wins in CODEOWNERS: a more specific path rule overrides a more general one.
Configure the following branch protection rules for master:
| Rule | Setting | Reason |
|---|---|---|
| Require a pull request before merging | Enabled | No direct pushes to master, ever |
| Require approvals | 1 for Low/Medium risk; 2 for High risk | CODEOWNERS enforcement handles the "who" |
| Require status checks to pass | cargo fmt, cargo clippy, cargo test | CI must be green before merge |
| Require branches to be up to date | Enabled | Prevents merging stale code |
| Require conversation resolution | Enabled | All review comments must be resolved |
| Do not allow bypassing the above settings | Enabled | Applies to everyone, including admins |
| Allow force pushes | Disabled | Preserve commit history |
| Allow deletions | Disabled | Protect the branch |
Why admins cannot bypass: One of the most common mistakes in small team projects is treating branch protection as "for other people." When an admin can bypass, they will, under time pressure, in an emergency, "just this once." Then it becomes the norm. The rule must apply to everyone for it to mean anything. If there is a genuine emergency, the right response is to follow the process faster, not to skip it.
The CI checks that must pass before any PR can merge:
build (stable) ← cargo build --release
test ← cargo test
fmt ← cargo fmt --all -- --check
clippy ← cargo clippy --all-targets -- -D warnings
As the workspace decomposes into crates (per the architecture RFC), add per-crate checks. A change to crates/zeroclaw-api should run that crate's test suite independently.
This section exists because the question will come up (it already has) and it deserves a clear, documented answer rather than a debate on every PR.
The question: Should we add an automated gate that checks whether a PR conforms to the architecture and design patterns defined in the RFCs?
The answer: No. And understanding why is important.
There are two fundamentally different kinds of quality enforcement, and they require different mechanisms.
The first kind is structural compliance: does this code violate a mechanical rule? Does zeroclaw-kernel import TelegramChannel? Do the dependency graph edges point the wrong way? Are there clippy warnings? These are binary questions. Either the code violates the rule or it does not. The compiler, cargo deny, and cargo clippy --workspace already enforce this. No human is needed. No AI is needed. The machine is authoritative, fast, and never wrong about a factual violation.
The second kind is architectural intent: does this decision belong here? Is this abstraction at the right layer? Does this trade-off align with the vision? Is this coupling going to be painful in Phase 3? Will this PR create a maintenance burden that isn't visible in the diff today? These questions require judgment, context, and an understanding of why the architecture exists, not just what the rules are. No automated tool can answer them reliably, because the answer depends on information that is not in the diff: the roadmap, the team's current priorities, the contributor's intent, and the long-term cost of the decision.
The failure modes of automating architectural judgment are both bad.
A gate that passes subtle architectural violations creates false confidence. The developer sees ✅ and assumes their decision was validated. The most damaging architectural drift, the kind that takes years to untangle, looks structurally correct. It compiles. It passes lint. The dependency graph is fine. The problem is that it violated the spirit of the design in a way that only becomes apparent later, when the cost of unwinding it is high.
A gate that flags valid architectural decisions because the tool misread the context teaches developers to dismiss the gate entirely. Once a team learns to click past a noisy automated check, the check is gone in practice even if it is still running in CI. The project has spent CI minutes to achieve negative value.
CODEOWNERS is the architectural compliance gate. The reviewer is the tool.
The CODEOWNERS configuration in §6.1 already enforces that PRs touching high-risk paths, crate boundaries, trait definitions, the dependency graph, src/security/, .github/, require review from a Core Team member. That Core Team member, equipped with the RFCs as their reference framework, is the architectural compliance check. They bring the contextual judgment that no automation can replicate.
This is why the RFCs, the AGENTS.md files, and the documentation standards exist: not so a machine can parse them and produce a score, but so a human reviewer has a consistent, documented framework to apply. The RFC answers "why does this architecture exist." The reviewer answers "does this PR serve or undermine that why."
AI belongs in the development loop, not the merge gate.
AI tools, Claude, Copilot, Cursor, and whatever comes next, are genuinely useful for architectural work when they are used in the right place. The right place is during development, not during the merge gate.
During development, an AI assistant equipped with the RFC and the crate's AGENTS.md can help a contributor understand which crate a new piece of functionality belongs in before they write it, flag a potential dependency inversion while the code is still being shaped, explain why a design pattern exists, and suggest whether a new abstraction is at the right layer. This is additive. It makes contributors more capable.
During a review, an AI assistant can help a human reviewer draft structured feedback, cross-reference a change against the RFC, and identify which discussion questions in the RFC are relevant to the PR. This is also additive. The reviewer brings the judgment; the AI brings speed and recall.
What AI cannot do is replace the judgment. "AI helps me assess this PR" and "AI automatically gates this PR" are categorically different, and only the first one works for architectural decisions. The day the project routes architectural compliance through an automated gate, however sophisticated, is the day the architecture starts drifting in ways nobody notices until it is too late.
The practical policy, stated plainly:
.github/workflows/ without a documented decision.This policy is not a limitation on AI or on automation. It is a recognition that different problems require different tools, and using the right tool in the right place is exactly what the architecture RFC is asking of the codebase.
Issue templates route incoming reports to the right process before they reach a human. A well-written template gathers the information needed for triage automatically. A missing or ignored template results in issues that take three comment exchanges to understand.
The operational source of truth is .github/ISSUE_TEMPLATE/. Do not duplicate full template YAML here. When template wording changes, update the issue form itself and keep this section at the level of durable intent.
Current intake lanes:
| Template | Purpose | Intake signals collected |
|---|---|---|
bug_report.yml | Reproducible defects | Component, severity, reproduction, expected behavior, environment, privacy check |
support_config.yml | Setup, configuration, and usage help | Goal, observed behavior, redacted config or commands when relevant |
feature_request.yml | Ordinary feature ideas | User problem, proposed solution, non-goals, architecture/risk hints, expected routing |
rfc_design.yml | Architecture, governance, default, release, or contribution-model proposals | Problem, proposal, risks, breaking-change assessment, decision/revisit surface |
roadmap_tracker.yml | Active release, roadmap, RFC, implementation, cleanup, or audit trackers | Purpose, scope, linked work, routing evidence, close criteria, stale-exemption request |
docs_issue.yml | Missing, wrong, confusing, or outdated docs | Location, problem, expected documentation, related source of truth |
contributor_task.yml | Maintainer-scoped work intended for external contributors | Context, acceptance criteria, likely files, pickup fit, mentor or review contact |
Security vulnerabilities do not get a public issue template. config.yml links to the private security policy, Discord, GitHub Discussions, the contribution guide, the RFC process, and the maintainer PR workflow so contributors can choose the right surface before creating a tracked issue.
Issue templates collect evidence; they do not decide final labels by themselves. Maintainers still apply judgment-only labels such as status:accepted, status:no-stale, help wanted, and good first issue after checking the body, discussion, and linked work. In particular, status:no-stale should not be applied automatically from a template. A tracker, RFC, or long-lived accepted issue must record both the stale-exemption reason and the visible next decision or revisit surface before stale protection is added or kept.
The RFC process was established in the documentation RFC and the architecture RFC. This section defines the close loop: how an RFC moves from proposal to decision to action.
1. AUTHOR writes proposal → docs/proposals/<slug>.md
↓
2. AUTHOR opens PR with the proposal document
↓
3. AUTHOR opens RFC issue using the RFC issue template
linking to the PR
↓
4. DISCUSSION PERIOD — minimum 7 days
Anyone can comment. Core Team members engage substantively.
Discussions happen on the issue, not the PR.
↓
5. CORE TEAM VOTE on the issue
Format: comment with one of:
✅ APPROVE — with brief rationale
❌ REJECT — with specific objections
🔄 REVISE — with specific requests
↓
┌── Majority APPROVE ──────────────────────────────────────┐
│ RFC is accepted │
│ PR is merged │
│ Issue labeled rfc:accepted │
│ Author writes ADR(s) in docs/architecture/decisions/ │
│ ADR issue(s) linked back to RFC issue │
│ RFC issue closed │
└──────────────────────────────────────────────────────────┘
↓
┌── Any REJECT ────────────────────────────────────────────┐
│ RFC is rejected │
│ PR is closed (not merged) │
│ Issue labeled rfc:rejected │
│ Rejecting members document specific objections │
│ RFC issue closed with rejection summary comment │
└──────────────────────────────────────────────────────────┘
↓
┌── REVISE requested ──────────────────────────────────────┐
│ RFC is not voted on until revisions are complete │
│ Issue labeled rfc:revision-requested │
│ Author revises proposal document │
│ Author re-requests review via issue comment │
│ Process returns to step 4 │
└──────────────────────────────────────────────────────────┘
| Change Type | Vote Required | Rationale |
|---|---|---|
| Documentation, tooling, non-breaking features | Simple majority of active Core Team members | Low stakes, fast iteration |
| API changes, new subsystems, behavioral changes | Two-thirds majority of Core Team | Moderate stakes, needs real consensus |
| Architecture changes, security model changes, breaking changes | Unanimous agreement of all Core Team members | High stakes, affects everyone |
"Active" Core Team members are those who have participated in at least one vote in the past 90 days. Inactive members do not count against majority thresholds but are notified of votes.
Every accepted RFC must produce at least one ADR before the corresponding implementation can begin. The ADR is not a summary of the RFC: it is the permanent record of the specific decision made, in the Nygard format defined in the documentation RFC. The RFC can be long and exploratory. The ADR is short and definitive.
RFCs are proposals. ADRs are decisions. Both are necessary. Neither replaces the other.
The following RFCs have been filed as of this writing and should be converted to formal RFC issues immediately:
| RFC Document | Issue to create | Priority |
|---|---|---|
docs/proposals/microkernel-architecture.md | Microkernel Architecture RFC (v0.7.0+) | High |
docs/proposals/documentation-standards.md | Documentation Standards and i18n RFC | High |
docs/proposals/project-governance.md | Team Organization and Governance RFC | Medium |
Labels are the metadata layer on issues and PRs. A consistent, well-designed label system makes filtering, reporting, and automation possible. An inconsistent label system (the common case, labels added ad hoc by whoever creates an issue) creates noise.
Use a namespaced label system. Each label has a prefix that identifies its category:
type: What kind of work is this?| Label | Color | Use |
|---|---|---|
type:feature | #0075ca Blue | New capability or enhancement |
type:bug | #d73a4a Red | Something is not working correctly |
type:refactor | #e4e669 Yellow | Code restructuring without behavior change |
type:docs | #0075ca Blue | Documentation changes only |
type:security | #e11d48 Dark red | Security-related changes |
type:infrastructure | #6366f1 Purple | CI, tooling, build system |
type:adr | #a855f7 Light purple | Architecture Decision Record |
type:rfc | #f59e0b Amber | Request for Comments / proposal |
priority: How urgent is this?| Label | Color | Use |
|---|---|---|
priority:critical | #b91c1c Dark red | Blocking release or causing data loss |
priority:high | #f97316 Orange | Important, should be in next milestone |
priority:medium | #eab308 Yellow | Normal priority |
priority:low | #22c55e Green | Nice to have, low urgency |
size: How large is this work item?| Label | Color | Use |
|---|---|---|
size:XS | #dcfce7 Light green | Under 2 hours |
size:S | #bbf7d0 Green | Half a day |
size:M | #86efac Medium green | 1–3 days |
size:L | #4ade80 Dark green | 1–2 weeks |
size:XL | #16a34a Deep green | More than 2 weeks; should be broken down |
component: Which part of the system?component:kernel · component:gateway · component:channels · component:tools · component:memory · component:security · component:hardware · component:docs · component:infra
Use #f1f5f9 (light gray) for all component labels to distinguish them visually from other categories.
risk: What is the risk tier? (mirrors AGENTS.md)| Label | Color | Use |
|---|---|---|
risk:low | #dcfce7 | Docs, tests, minor changes |
risk:medium | #fef9c3 | Most src/** changes |
risk:high | #fee2e2 | Security, gateway, runtime, CI |
status: Where is this in the process?This table records governance intent and historical taxonomy shape. For current live label semantics and automation behavior, use the maintainer label guide as the operational reference; maintainer docs carry later label-policy corrections from #6808.
| Label | Color | Use |
|---|---|---|
status:needs-triage | #f8fafc White | Newly opened, not yet reviewed |
status:accepted | #0e8a16 Green | RFC or work item ratified; not stale-exempt by itself |
status:blocked | #b60205 Red | Waiting on a recorded unresolved external dependency, maintainer decision, or linked prerequisite |
status:in-progress | #0075ca Blue | Open PR is actively targeting the issue; verify live PR state during stale passes |
status:stale | #e4e669 Yellow | No original-author activity for the stale threshold window |
status:no-stale | #0e8a16 Green | Explicit stale exemption for accepted or otherwise long-lived work; target policy requires a recorded reason and visible routing evidence in the operational source |
status:help-wanted | #059669 Green | Looking for a contributor |
status:good-first-issue | #059669 Green | Suitable for new contributors |
status:discussion | #a78bfa Purple | Needs team discussion before work begins |
The live community-pickup labels are the unprefixed good first issue and help wanted; the status:* pickup rows above are historical taxonomy. Current operational risk labels also distinguish issue risk (likely fix blast radius from the report) from PR risk (the actual diff under review). See the maintainer label guide for the live policy.
Terminal closure labels are operational policy, not part of the historical status:* taxonomy in this foundation document. Use the maintainer label guide for current resolution labels and the superseding guide for replacement-process rules.
rfc: RFC-specific statusrfc:accepted · rfc:rejected · rfc:revision-requested
"Done" means something specific. If you do not define it, everyone will have a different definition, and the disagreements will surface at the worst possible time: during review, during release, or after a user files a bug.
An item is Done when all of the following are true:
cargo fmt, cargo clippy, cargo testmaster branchstatus fieldDone status or explicitly moved to the next milestone with a comment explaining whyThere is a concept in software teams of work that is "done" but not "done done." Done means the code is written. Done done means it is tested, documented, reviewed, merged, and released. The Definition of Done above describes done done. Nothing should be called done until it meets the full definition.
GitHub Projects v2 and GitHub Actions together enable significant automation that reduces manual coordination overhead. Here is what to implement, ordered by value-to-effort ratio.
Configure these in the Project's built-in automation settings:
| Trigger | Action |
|---|---|
| Issue opened | Add to Project; set Status = 💡 Idea |
Issue labeled type:bug | Set Priority = 🟠 High (if no priority set) |
| PR opened that references an issue | Set linked issue Status = 👀 In Review |
| PR merged | Set linked issue Status = ✅ Done; close linked issue |
| Issue closed as not planned | Set Status = 🚫 Won't Do |
Auto-label by changed files:
The active path labeler applies scope labels to PRs based on changed files. Risk and size labels are currently maintainer-applied; the maintainer label guide is the live source for label names, automation status, and risk semantics.
Auto-request CODEOWNERS review (built into CODEOWNERS: no Action needed):
GitHub enforces CODEOWNERS automatically when the file exists and branch protection requires it. No Action required.
Stale issue management (.github/workflows/stale.yml):
Issues with no activity for 45 days are labeled status:stale and a comment is posted asking if the issue is still relevant. Issues with no activity for 15 days after the stale label is applied are closed. This prevents the backlog from accumulating hundreds of issues that are months old and no longer relevant. Exclude priority:p0, type:rfc, issues with open linked PRs, and issues with status:blocked while a recorded blocker remains unresolved. The intended status:no-stale follow-up is to exclude it only while the operational source records both the stale-exemption reason and contributor-visible routing evidence. The maintainer label guide and issue-triage protocol carry the current operational details.
PR size labeling (future/optional):
If size automation is added later, it should follow the maintainer label guide's live names (size:XS through size:XL) and recalculate on pushed updates so the label describes the diff under review. Until then, size labels are maintainer-applied.
Milestone check on PR merge (.github/workflows/milestone-check.yml):
Warn (not block) if a PR is merged without a linked issue that has a milestone assigned. This is a gentle nudge, not a hard gate: the goal is to prevent work from happening without being tracked to a release.
Governance and tooling must be introduced incrementally. Introducing everything at once creates overhead before the team understands why each piece exists.
The minimum viable governance setup. Gets the team coordinating immediately.
CODEOWNERS file (Section 6.1)master (Section 6.2)Success signal: New issues automatically appear in the Project. The team knows where to look for active work and where to post ideas.
Establish the full workflow and populate the backlog from the accepted RFCs.
CONTRIBUTORS.md file with current team members in their tierszeroclaw-core and zeroclaw-contributors GitHub TeamsSuccess signal: The team is using the board daily. Items move through stages with visible gate checks. The RFC for the microkernel architecture has a recorded vote outcome.
As the plugin system becomes usable, external contributors will start arriving. The contribution infrastructure must be ready.
good first issue items (minimum 5) for the plugin SDK workGood First Issue Index as a pinned issue with links to current good first issuesSuccess signal: At least one external contributor (not on the current team) submits a PR via a good first issue. The Discussions Ideas category has active community participation.
By v1.0.0, the governance model should be self-sustaining: the team should not need to think about it, it should just work.
Success signal: The last six months of development history shows consistent use of the pipeline. Issues are triaged within 3 days. PRs are reviewed within 5 days. The CHANGELOG is updated on every merge.
Backlog grooming: A regular team activity (typically weekly or bi-weekly) in which the team reviews the backlog, reprioritizes items, closes stale ones, and ensures that the top items are "Defined" and ready to be picked up.
Branch protection: A GitHub feature that prevents direct pushes to protected branches and enforces requirements (reviews, CI checks) before merging.
CODEOWNERS: A GitHub file that automatically requests reviews from specified individuals or teams when files they own are changed in a PR.
Definition of Done: A shared checklist that specifies exactly what "done" means for a work item. Without a shared definition, "done" means something different to everyone.
Lazy consensus: A decision-making approach in which a proposed action proceeds unless someone objects within a defined time period. Reduces the overhead of requiring explicit approval for routine decisions.
Meritocracy: A governance model in which authority and influence are earned through demonstrated contribution, not through seniority or title. Standard in open source projects.
Milestone: A GitHub feature that groups issues and PRs by release target. A milestone represents a version of the software.
T-shirt sizing: An estimation technique that uses abstract sizes (XS, S, M, L, XL) rather than numeric story points. Easier to use without historical calibration data and sufficient for teams at an early stage.
Triage: The process of reviewing new issues to confirm they are valid, assign labels and priority, link them to milestones, and determine whether they belong in the backlog or should be closed.
good first issue documentation improvement workflow.This proposal was developed in the context of ZeroClaw v0.6.8 and the two preceding architecture and documentation RFCs. The governance model proposed here is intentionally lightweight for a student-led project at an early stage of community growth. It is designed to scale: adding process as the team grows, not all at once.
The best governance model is the simplest one the team will actually follow. Start here. Adjust based on what you learn.