Architecture and Contribution Map
Use this page when a change is larger than a typo and you are not sure which architecture, foundation, contributor, or maintainer documents apply.
This page is only a map. The linked files remain the source of truth.
Start Here
- Read the repo-root
AGENTS.mdfirst. It contains the current risk tiers, protected files, anti-patterns, localization rules, and agent-specific workflow contracts. - Read How to contribute for the PR mechanics, validation expectations, and review process.
- Use the tables below to choose the architecture and foundation documents that match the change.
- If the change crosses subsystem, config, security, workflow, governance, or release boundaries, check the RFC process before implementing.
Common Change Paths
| Change | Read first | Why |
|---|---|---|
| New provider | Architecture overview, Crates, Custom providers, Provider configuration | Providers are edge adapters behind the provider trait, with config and routing contracts. |
| New channel | Architecture overview, Crates, Channels overview, existing implementations in crates/zeroclaw-channels/ | Channels are user-visible boundaries; validate both inbound and outbound behavior. |
| New tool or tool policy | Tools overview, Plugin protocol, Security overview, Tool receipts | Tools execute actions for the agent, so security, approval, audit, and receipts matter. |
| Runtime, agent loop, cron, SOP, memory, or streaming behavior | Request lifecycle, Crates, FND-001, Testing | Runtime changes often affect multiple user paths and need boundary-level tests. |
| Gateway, web API, webhooks, or dashboard behavior | Gateway HTTP API, Request lifecycle, Security overview, Reviewer playbook | Gateway changes can affect auth, public exposure, pairing, webhooks, and review risk. |
| Config schema, environment variables, or defaults | Environment variables, Provider configuration, FND-001, RFC process | Config changes affect upgrade paths and may require migration or RFC discussion. |
| CI, release, GitHub Actions, or allowed actions | CI & Actions, FND-004, PR workflow | Infrastructure changes are high-risk when they alter what code can run or ship. |
| Docs structure, contributor guidance, or knowledge organization | FND-002, Docs & Translations, this page | Documentation changes should reduce search cost and preserve the decision trail. |
| Governance, labels, board workflow, or contribution process | FND-003, RFC process, Labels, Reviewer playbook | Process changes affect maintainers and contributors; keep them durable and explicit. |
| AI-assisted contribution, superseding, or review culture | FND-005, Superseding PRs, PR review protocol | AI-assisted work is welcome, but the human sponsor owns accuracy, attribution, and review response. |
| Production code health, error handling, or dead-code cleanup | FND-006, Testing, repo-root AGENTS.md | Error discipline, unused code, and production readiness are review gates, not style preferences. |
Foundation Documents In One Screen
| Foundation | Read when the change asks… |
|---|---|
| FND-001: Intentional architecture | Does this fit the microkernel/runtime direction? Which layer should own it? |
| FND-002: Documentation standards | Where should knowledge live? How should docs stay navigable and durable? |
| FND-003: Governance | Who decides? Which labels, project board, or RFC process should carry the state? |
| FND-004: Engineering infrastructure | How should CI, release automation, or GitHub Actions behave? |
| FND-005: Contribution culture | How should contributors, maintainers, and AI-assisted work communicate and review? |
| FND-006: Zero compromise in practice | What quality bar applies to production code, errors, dead code, and release readiness? |
Coding Agent Entry Points
Coding agents should use the same public docs as humans, plus the repository-local agent contracts.
- Follow the repo-root
AGENTS.mdand the matching in-repo skill listed there when one applies. - Treat foundation documents as decision context. They explain why a review may ask for a split, an RFC, stronger validation, or a different owner.
- Keep private workflow mechanics out of public PR bodies, issue comments, and reviews. Public text should cite concrete behavior, source paths, commands, validation evidence, linked issues, and user-visible risk.
- If a generated or skill-authored draft conflicts with source code, current
AGENTS.md, or a ratified foundation document, stop and reconcile before posting or implementing.
RFC And PR Checkpoints
This map does not replace the RFC process or the PR template; it only helps you find the right doc. The RFC process carries the canonical “is this RFC-shaped?” table, so check it rather than guessing from a restated list here. After RFC #6808 policy slices are promoted, follow FND-003, Labels, PR workflow, and Reviewer playbook.
- If a change is ambiguous but not clearly RFC-shaped, ask a maintainer or narrow the PR before implementation.
- Before opening a PR, answer the prompts in the PR template (
.github/pull_request_template.md). If those answers are not clear, write the design note or RFC first.