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
| 更改 | Read first | Why |
|---|---|---|
| 新的提供商 | Architecture overview, Crates, Custom providers, Provider configuration | Providers are edge adapters behind the provider trait, with config and routing contracts. |
| 新频道 | 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 exists to make architecture and contribution scope easier to find. After RFC #6808 policy slices are promoted, follow FND-003, Labels, PR workflow, and Reviewer playbook.
- Check or open an RFC first when the RFC page says the change is RFC-shaped: established default changes, breaking config or schema migration, new subsystem or protocol, cross-cutting refactor, governance, release, or contribution-model changes.
- 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 template’s summary, validation, compatibility, and rollback prompts. If those answers are not clear, write the design note or RFC first.