harald/zeroclaw
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 3

docs(agent-guides): align AGENTS and CLAUDE with new docs system

Browse source
This commit is contained in:
Chummy 2026-02-18 17:29:16 +08:00
parent f6cf004800
commit d7277a3b40
2 changed files with 139 additions and 17 deletions
Download patch file Download diff file Expand all files Collapse all files

77
AGENTS.md
View file

@ -144,9 +144,46 @@ Required:
- `src/tools/` — tool execution surface (shell, file, memory, browser) - `src/tools/` — tool execution surface (shell, file, memory, browser)
- `src/peripherals/` — hardware peripherals (STM32, RPi GPIO); see `docs/hardware-peripherals-design.md` - `src/peripherals/` — hardware peripherals (STM32, RPi GPIO); see `docs/hardware-peripherals-design.md`
- `src/runtime/` — runtime adapters (currently native) - `src/runtime/` — runtime adapters (currently native)
- `docs/` — architecture + process docs - `docs/` — task-oriented documentation system (hubs, unified TOC, references, operations, security proposals, multilingual guides)
- `.github/` — CI, templates, automation workflows - `.github/` — CI, templates, automation workflows
## 4.1 Documentation System Contract (Required)
Treat documentation as a first-class product surface, not a post-merge artifact.
Canonical entry points:
- root READMEs: `README.md`, `README.zh-CN.md`, `README.ja.md`, `README.ru.md`
- docs hubs: `docs/README.md`, `docs/README.zh-CN.md`, `docs/README.ja.md`, `docs/README.ru.md`
- unified TOC: `docs/SUMMARY.md`
Collection indexes (category navigation):
- `docs/getting-started/README.md`
- `docs/reference/README.md`
- `docs/operations/README.md`
- `docs/security/README.md`
- `docs/hardware/README.md`
- `docs/contributing/README.md`
- `docs/project/README.md`
Runtime-contract references (must track behavior changes):
- `docs/commands-reference.md`
- `docs/providers-reference.md`
- `docs/channels-reference.md`
- `docs/config-reference.md`
- `docs/operations-runbook.md`
- `docs/troubleshooting.md`
- `docs/one-click-bootstrap.md`
Required docs governance rules:
- Keep README/hub top navigation and quick routes intuitive and non-duplicative.
- Keep EN/ZH/JA/RU entry-point parity when changing navigation architecture.
- Keep proposal/roadmap docs explicitly labeled; avoid mixing proposal text into runtime-contract docs.
- Keep project snapshots date-stamped and immutable once superseded by a newer date.
## 5) Risk Tiers by Path (Review Depth Contract) ## 5) Risk Tiers by Path (Review Depth Contract)
Use these tiers when deciding validation depth and review rigor. Use these tiers when deciding validation depth and review rigor.
@ -170,11 +207,13 @@ When uncertain, classify as higher risk.
- Code/risky changes: full relevant checks and focused scenarios. - Code/risky changes: full relevant checks and focused scenarios.
5. **Document impact** 5. **Document impact**
- Update docs/PR notes for behavior, risk, side effects, and rollback. - Update docs/PR notes for behavior, risk, side effects, and rollback.
- If CLI/config/provider/channel behavior changed, update corresponding runtime-contract references.
- If docs entry points changed, keep EN/ZH/JA/RU README + docs-hub navigation aligned.
6. **Respect queue hygiene** 6. **Respect queue hygiene**
- If stacked PR: declare `Depends on #...`. - If stacked PR: declare `Depends on #...`.
- If replacing old PR: declare `Supersedes #...`. - If replacing old PR: declare `Supersedes #...`.
### 6.3 Branch / Commit / PR Flow (Required) ### 6.1 Branch / Commit / PR Flow (Required)
All contributors (human or agent) must follow the same collaboration flow: All contributors (human or agent) must follow the same collaboration flow:
@ -185,7 +224,7 @@ All contributors (human or agent) must follow the same collaboration flow:
- Merge via PR controls (squash/rebase/merge as repository policy allows). - Merge via PR controls (squash/rebase/merge as repository policy allows).
- Branch deletion after merge is optional; long-lived branches are allowed when intentionally maintained. - Branch deletion after merge is optional; long-lived branches are allowed when intentionally maintained.
### 6.4 Worktree Workflow (Required for Multi-Track Agent Work) ### 6.2 Worktree Workflow (Required for Multi-Track Agent Work)
Use Git worktrees to isolate concurrent agent/human tracks safely and predictably: Use Git worktrees to isolate concurrent agent/human tracks safely and predictably:
@ -195,7 +234,7 @@ Use Git worktrees to isolate concurrent agent/human tracks safely and predictabl
- Name worktrees clearly by scope (for example: `wt/ci-hardening`, `wt/provider-fix`) and remove stale worktrees when no longer needed. - Name worktrees clearly by scope (for example: `wt/ci-hardening`, `wt/provider-fix`) and remove stale worktrees when no longer needed.
- PR checkpoint rules from section 6.3 still apply to worktree-based development. - PR checkpoint rules from section 6.3 still apply to worktree-based development.
### 6.1 Code Naming Contract (Required) ### 6.3 Code Naming Contract (Required)
Apply these naming rules for all code changes unless a subsystem has a stronger existing pattern. Apply these naming rules for all code changes unless a subsystem has a stronger existing pattern.
@ -206,7 +245,7 @@ Apply these naming rules for all code changes unless a subsystem has a stronger
- Name tests by behavior/outcome (`<subject>_<expected_behavior>`) and keep fixture identifiers neutral/project-scoped. - Name tests by behavior/outcome (`<subject>_<expected_behavior>`) and keep fixture identifiers neutral/project-scoped.
- If identity-like naming is required in tests/examples, use ZeroClaw-native labels only (`ZeroClawAgent`, `zeroclaw_user`, `zeroclaw_node`). - If identity-like naming is required in tests/examples, use ZeroClaw-native labels only (`ZeroClawAgent`, `zeroclaw_user`, `zeroclaw_node`).
### 6.2 Architecture Boundary Contract (Required) ### 6.4 Architecture Boundary Contract (Required)
Use these rules to keep the trait/factory architecture stable under growth. Use these rules to keep the trait/factory architecture stable under growth.
@ -238,20 +277,29 @@ Use these rules to keep the trait/factory architecture stable under growth.
- Validate and sanitize all inputs. - Validate and sanitize all inputs.
- Return structured `ToolResult`; avoid panics in runtime path. - Return structured `ToolResult`; avoid panics in runtime path.
### 5.4 Adding a Peripheral ### 7.4 Adding a Peripheral
- Implement `Peripheral` in `src/peripherals/`. - Implement `Peripheral` in `src/peripherals/`.
- Peripherals expose `tools()` — each tool delegates to the hardware (GPIO, sensors, etc.). - Peripherals expose `tools()` — each tool delegates to the hardware (GPIO, sensors, etc.).
- Register board type in config schema if needed. - Register board type in config schema if needed.
- See `docs/hardware-peripherals-design.md` for protocol and firmware notes. - See `docs/hardware-peripherals-design.md` for protocol and firmware notes.
### 5.5 Security / Runtime / Gateway Changes ### 7.5 Security / Runtime / Gateway Changes
- Include threat/risk notes and rollback strategy. - Include threat/risk notes and rollback strategy.
- Add/update tests or validation evidence for failure modes and boundaries. - Add/update tests or validation evidence for failure modes and boundaries.
- Keep observability useful but non-sensitive. - Keep observability useful but non-sensitive.
- For `.github/workflows/**` changes, include Actions allowlist impact in PR notes and update `docs/actions-source-policy.md` when sources change. - For `.github/workflows/**` changes, include Actions allowlist impact in PR notes and update `docs/actions-source-policy.md` when sources change.
### 7.6 Docs System / README / IA Changes
- Treat docs navigation as product UX: preserve clear pathing from README -> docs hub -> SUMMARY -> category index.
- Keep top-level nav concise; avoid duplicative links across adjacent nav blocks.
- When runtime surfaces change, update related references (`commands/providers/channels/config/runbook/troubleshooting`).
- Keep multilingual entry-point parity for EN/ZH/JA/RU when nav or key wording changes.
- For docs snapshots, add new date-stamped files for new sprints rather than rewriting historical context.
## 8) Validation Matrix ## 8) Validation Matrix
Default local checks for code changes: Default local checks for code changes:
@ -275,7 +323,10 @@ Notes:
Additional expectations by change type: Additional expectations by change type:
- **Docs/template-only**: run markdown lint and relevant doc checks. - **Docs/template-only**:
- run markdown lint and link-integrity checks
- if touching README/docs-hub/SUMMARY/collection indexes, verify EN/ZH/JA/RU navigation parity
- if touching bootstrap docs/scripts, run `bash -n bootstrap.sh scripts/bootstrap.sh scripts/install.sh`
- **Workflow changes**: validate YAML syntax; run workflow lint/sanity checks when available. - **Workflow changes**: validate YAML syntax; run workflow lint/sanity checks when available.
- **Security/runtime/gateway/tools**: include at least one boundary/failure-mode validation. - **Security/runtime/gateway/tools**: include at least one boundary/failure-mode validation.
@ -376,6 +427,16 @@ Co-authored-by: <Name B> <login_b@users.noreply.github.com>
Reference docs: Reference docs:
- `CONTRIBUTING.md` - `CONTRIBUTING.md`
- `docs/README.md`
- `docs/SUMMARY.md`
- `docs/docs-inventory.md`
- `docs/commands-reference.md`
- `docs/providers-reference.md`
- `docs/channels-reference.md`
- `docs/config-reference.md`
- `docs/operations-runbook.md`
- `docs/troubleshooting.md`
- `docs/one-click-bootstrap.md`
- `docs/pr-workflow.md` - `docs/pr-workflow.md`
- `docs/reviewer-playbook.md` - `docs/reviewer-playbook.md`
- `docs/ci-map.md` - `docs/ci-map.md`

79
CLAUDE.md
View file

@ -1,6 +1,6 @@
# CLAUDE.md — ZeroClaw Agent Engineering Protocol # CLAUDE.md — ZeroClaw Agent Engineering Protocol
This file defines the default working protocol for claude code in this repository. This file defines the default working protocol for Claude agents in this repository.
Scope: entire repository. Scope: entire repository.
## 1) Project Snapshot (Read First) ## 1) Project Snapshot (Read First)
@ -144,9 +144,46 @@ Required:
- `src/tools/` — tool execution surface (shell, file, memory, browser) - `src/tools/` — tool execution surface (shell, file, memory, browser)
- `src/peripherals/` — hardware peripherals (STM32, RPi GPIO); see `docs/hardware-peripherals-design.md` - `src/peripherals/` — hardware peripherals (STM32, RPi GPIO); see `docs/hardware-peripherals-design.md`
- `src/runtime/` — runtime adapters (currently native) - `src/runtime/` — runtime adapters (currently native)
- `docs/` — architecture + process docs - `docs/` — task-oriented documentation system (hubs, unified TOC, references, operations, security proposals, multilingual guides)
- `.github/` — CI, templates, automation workflows - `.github/` — CI, templates, automation workflows
## 4.1 Documentation System Contract (Required)
Treat documentation as a first-class product surface, not a post-merge artifact.
Canonical entry points:
- root READMEs: `README.md`, `README.zh-CN.md`, `README.ja.md`, `README.ru.md`
- docs hubs: `docs/README.md`, `docs/README.zh-CN.md`, `docs/README.ja.md`, `docs/README.ru.md`
- unified TOC: `docs/SUMMARY.md`
Collection indexes (category navigation):
- `docs/getting-started/README.md`
- `docs/reference/README.md`
- `docs/operations/README.md`
- `docs/security/README.md`
- `docs/hardware/README.md`
- `docs/contributing/README.md`
- `docs/project/README.md`
Runtime-contract references (must track behavior changes):
- `docs/commands-reference.md`
- `docs/providers-reference.md`
- `docs/channels-reference.md`
- `docs/config-reference.md`
- `docs/operations-runbook.md`
- `docs/troubleshooting.md`
- `docs/one-click-bootstrap.md`
Required docs governance rules:
- Keep README/hub top navigation and quick routes intuitive and non-duplicative.
- Keep EN/ZH/JA/RU entry-point parity when changing navigation architecture.
- Keep proposal/roadmap docs explicitly labeled; avoid mixing proposal text into runtime-contract docs.
- Keep project snapshots date-stamped and immutable once superseded by a newer date.
## 5) Risk Tiers by Path (Review Depth Contract) ## 5) Risk Tiers by Path (Review Depth Contract)
Use these tiers when deciding validation depth and review rigor. Use these tiers when deciding validation depth and review rigor.
@ -170,11 +207,13 @@ When uncertain, classify as higher risk.
- Code/risky changes: full relevant checks and focused scenarios. - Code/risky changes: full relevant checks and focused scenarios.
5. **Document impact** 5. **Document impact**
- Update docs/PR notes for behavior, risk, side effects, and rollback. - Update docs/PR notes for behavior, risk, side effects, and rollback.
- If CLI/config/provider/channel behavior changed, update corresponding runtime-contract references.
- If docs entry points changed, keep EN/ZH/JA/RU README + docs-hub navigation aligned.
6. **Respect queue hygiene** 6. **Respect queue hygiene**
- If stacked PR: declare `Depends on #...`. - If stacked PR: declare `Depends on #...`.
- If replacing old PR: declare `Supersedes #...`. - If replacing old PR: declare `Supersedes #...`.
### 6.3 Branch / Commit / PR Flow (Required) ### 6.1 Branch / Commit / PR Flow (Required)
All contributors (human or agent) must follow the same collaboration flow: All contributors (human or agent) must follow the same collaboration flow:
@ -185,7 +224,7 @@ All contributors (human or agent) must follow the same collaboration flow:
- Merge via PR controls (squash/rebase/merge as repository policy allows). - Merge via PR controls (squash/rebase/merge as repository policy allows).
- Branch deletion after merge is optional; long-lived branches are allowed when intentionally maintained. - Branch deletion after merge is optional; long-lived branches are allowed when intentionally maintained.
### 6.4 Worktree Workflow (Required for Multi-Track Agent Work) ### 6.2 Worktree Workflow (Required for Multi-Track Agent Work)
Use Git worktrees to isolate concurrent agent/human tracks safely and predictably: Use Git worktrees to isolate concurrent agent/human tracks safely and predictably:
@ -195,7 +234,7 @@ Use Git worktrees to isolate concurrent agent/human tracks safely and predictabl
- Name worktrees clearly by scope (for example: `wt/ci-hardening`, `wt/provider-fix`) and remove stale worktrees when no longer needed. - Name worktrees clearly by scope (for example: `wt/ci-hardening`, `wt/provider-fix`) and remove stale worktrees when no longer needed.
- PR checkpoint rules from section 6.3 still apply to worktree-based development. - PR checkpoint rules from section 6.3 still apply to worktree-based development.
### 6.1 Code Naming Contract (Required) ### 6.3 Code Naming Contract (Required)
Apply these naming rules for all code changes unless a subsystem has a stronger existing pattern. Apply these naming rules for all code changes unless a subsystem has a stronger existing pattern.
@ -206,7 +245,7 @@ Apply these naming rules for all code changes unless a subsystem has a stronger
- Name tests by behavior/outcome (`<subject>_<expected_behavior>`) and keep fixture identifiers neutral/project-scoped. - Name tests by behavior/outcome (`<subject>_<expected_behavior>`) and keep fixture identifiers neutral/project-scoped.
- If identity-like naming is required in tests/examples, use ZeroClaw-native labels only (`ZeroClawAgent`, `zeroclaw_user`, `zeroclaw_node`). - If identity-like naming is required in tests/examples, use ZeroClaw-native labels only (`ZeroClawAgent`, `zeroclaw_user`, `zeroclaw_node`).
### 6.2 Architecture Boundary Contract (Required) ### 6.4 Architecture Boundary Contract (Required)
Use these rules to keep the trait/factory architecture stable under growth. Use these rules to keep the trait/factory architecture stable under growth.
@ -238,20 +277,29 @@ Use these rules to keep the trait/factory architecture stable under growth.
- Validate and sanitize all inputs. - Validate and sanitize all inputs.
- Return structured `ToolResult`; avoid panics in runtime path. - Return structured `ToolResult`; avoid panics in runtime path.
### 5.4 Adding a Peripheral ### 7.4 Adding a Peripheral
- Implement `Peripheral` in `src/peripherals/`. - Implement `Peripheral` in `src/peripherals/`.
- Peripherals expose `tools()` — each tool delegates to the hardware (GPIO, sensors, etc.). - Peripherals expose `tools()` — each tool delegates to the hardware (GPIO, sensors, etc.).
- Register board type in config schema if needed. - Register board type in config schema if needed.
- See `docs/hardware-peripherals-design.md` for protocol and firmware notes. - See `docs/hardware-peripherals-design.md` for protocol and firmware notes.
### 5.5 Security / Runtime / Gateway Changes ### 7.5 Security / Runtime / Gateway Changes
- Include threat/risk notes and rollback strategy. - Include threat/risk notes and rollback strategy.
- Add/update tests or validation evidence for failure modes and boundaries. - Add/update tests or validation evidence for failure modes and boundaries.
- Keep observability useful but non-sensitive. - Keep observability useful but non-sensitive.
- For `.github/workflows/**` changes, include Actions allowlist impact in PR notes and update `docs/actions-source-policy.md` when sources change. - For `.github/workflows/**` changes, include Actions allowlist impact in PR notes and update `docs/actions-source-policy.md` when sources change.
### 7.6 Docs System / README / IA Changes
- Treat docs navigation as product UX: preserve clear pathing from README -> docs hub -> SUMMARY -> category index.
- Keep top-level nav concise; avoid duplicative links across adjacent nav blocks.
- When runtime surfaces change, update related references (`commands/providers/channels/config/runbook/troubleshooting`).
- Keep multilingual entry-point parity for EN/ZH/JA/RU when nav or key wording changes.
- For docs snapshots, add new date-stamped files for new sprints rather than rewriting historical context.
## 8) Validation Matrix ## 8) Validation Matrix
Default local checks for code changes: Default local checks for code changes:
@ -275,7 +323,10 @@ Notes:
Additional expectations by change type: Additional expectations by change type:
- **Docs/template-only**: run markdown lint and relevant doc checks. - **Docs/template-only**:
- run markdown lint and link-integrity checks
- if touching README/docs-hub/SUMMARY/collection indexes, verify EN/ZH/JA/RU navigation parity
- if touching bootstrap docs/scripts, run `bash -n bootstrap.sh scripts/bootstrap.sh scripts/install.sh`
- **Workflow changes**: validate YAML syntax; run workflow lint/sanity checks when available. - **Workflow changes**: validate YAML syntax; run workflow lint/sanity checks when available.
- **Security/runtime/gateway/tools**: include at least one boundary/failure-mode validation. - **Security/runtime/gateway/tools**: include at least one boundary/failure-mode validation.
@ -376,6 +427,16 @@ Co-authored-by: <Name B> <login_b@users.noreply.github.com>
Reference docs: Reference docs:
- `CONTRIBUTING.md` - `CONTRIBUTING.md`
- `docs/README.md`
- `docs/SUMMARY.md`
- `docs/docs-inventory.md`
- `docs/commands-reference.md`
- `docs/providers-reference.md`
- `docs/channels-reference.md`
- `docs/config-reference.md`
- `docs/operations-runbook.md`
- `docs/troubleshooting.md`
- `docs/one-click-bootstrap.md`
- `docs/pr-workflow.md` - `docs/pr-workflow.md`
- `docs/reviewer-playbook.md` - `docs/reviewer-playbook.md`
- `docs/ci-map.md` - `docs/ci-map.md`