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.
- Read the repo-root
AGENTS.mdfirst. It contains the compact, always-loaded safety and contribution contract. - Read How to contribute for PR mechanics, validation expectations, and the review process.
- Use the tables below to choose the architecture and foundation documents that match the change.
- Consult Coding agent guidelines when an AI coding task needs detailed source-of-truth examples, risk and stability policy, skill discovery, or protected operational documents.
- If the change crosses subsystem, config, security, workflow, governance, or release boundaries, check the RFC process before implementing.
| Change | Read first | Why |
|---|---|---|
| New provider | Architecture overview, Crates, Custom providers, Provider configuration | Providers are edge adapters behind the provider trait, with config, factory, attribution, and routing contracts. |
| New channel | Architecture overview, Crates, Channel runtime lifecycle, Channels overview, existing implementations in crates/zeroclaw-channels/ |
Channels are user-visible trust boundaries; validate inbound, outbound, pairing, authorization, dispatch, and reply lifecycle behavior. |
| Channel dispatch, webhook ingress, reply intent, streaming drafts, listener lifecycle, or channel reload behavior | Channel runtime lifecycle, Request lifecycle, Gateway HTTP API, Plugin protocol, Testing | Channel lifecycle changes need a single dispatch and turn path instead of one-off adapter or gateway mini-orchestrators. |
| New built-in tool or tool policy | Tools overview, Built-In Tool Inventory, Tool execution lifecycle, ADR-004: Tool shared state ownership, Plugin protocol, Security overview, Tool receipts | Tools execute actions for the agent. First check whether the capability belongs in core, then validate registration, approval, dispatch, audit, receipts, localization, attribution, and shared-state ownership. |
| Runtime, agent loop, state, provider token streaming, or tool-loop behavior | Request lifecycle, Runtime state and persistence, Tool execution lifecycle, Crates, FND-001, Testing | Runtime changes often affect multiple user paths and need boundary-level tests. Provider token streaming stays runtime-owned; channel draft or typing-indicator streaming follows the channel lifecycle row. Tool-loop changes should name whether they affect approval, dispatch, receipts, observer events, history, or cancellation. |
| Cron, SOP, delegation, subagent, goal-mode, waiting, cancellation, or restart-recovery behavior | Background work lifecycle, Delegation & SubAgents, Testing | Background execution is not one lifecycle. Name the current owner and status surfaces, distinguish durable records from restart-resumable work, and verify cancellation and recovery at the changed boundary. |
| Memory, session history, prompt context, tool results, files/media payloads, or context trimming | Memory and payload lifecycle, Runtime state and persistence, History management, Runtime internals, Testing | Payload changes need clear owner, scope, durability, privacy, and truncation boundaries. |
| Logging, observability, runtime trace persistence, log pagination, retention, or schema migration | Logging architecture, Logs & observability, Runtime state and persistence, Gateway HTTP API, Security overview, Testing | One canonical event is offered independently to live broadcast and persisted JSONL; an optional typed Observer projection runs only when bound. Verify projection fields, active-file cursor lifetime, rewrite and retention behavior, migration compatibility, and privacy at the changed destination. |
| Gateway, web API, or dashboard behavior | Gateway HTTP API, Building the web dashboard, Request lifecycle, Security overview, Reviewer playbook | Gateway changes can affect auth, public exposure, generated API contracts, dashboard consumers, and review risk. Use the channel lifecycle row for webhook dispatch or reply behavior. |
| User-visible behavior or validation evidence for a command, terminal, daemon, browser, channel, provider, tool, background job, or install path | User-boundary proof, Testing, and the architecture or feature document for the changed surface | Match each behavior claim to the smallest credible proof that reaches the boundary where a user observes it. Add manual or environment-specific evidence only for a named gap in automated coverage. |
| Config schema, environment variables, defaults, or reload behavior | Config lifecycle, Environment variables, Runtime state and persistence, Provider configuration, FND-001, RFC process | Config changes affect upgrade paths, reload behavior, source-of-truth boundaries, and may require migration or RFC discussion. |
| Generated references, mdBook preprocessors, docs snippets, or docs deployment | Generated documentation pipeline, Building the docs locally, and Config lifecycle when config references change | Name the canonical source, materializer, tracked or build-only output, consumer, and drift check. |
| Fluent/gettext catalogs, locale registry, translation fallback, or catalog release pins | Localization catalog lifecycle, Docs & Translations, Generated documentation pipeline | A catalog present in the repository is not proof that a runtime or site build consumes it. Verify the loader, materializer, or pin path. |
| 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 | 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 agents should use the same public docs as humans, plus the repository-local agent contracts.
- Follow the repo-root
AGENTS.md. Inspect.claude/skills/*/SKILL.mdand use the matching in-repo skill when one applies; the skill file is authoritative. - 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.
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.