Skip to content

AGENTS.md

Latest commit

ย 

History

History
122 lines (94 loc) ยท 6.02 KB

AGENTS.md

File metadata and controls

122 lines (94 loc) ยท 6.02 KB

AGENTS.md โ€” ZeroClaw

Cross-tool agent instructions for any AI coding assistant working on this repository.

Commands

cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo test

Full pre-PR validation (recommended):

./dev/ci.sh all

Docs-only changes: run markdown lint and link-integrity checks. If touching bootstrap scripts: bash -n install.sh.

Project Snapshot

ZeroClaw is a Rust-first autonomous agent runtime optimized for performance, efficiency, stability, extensibility, sustainability, and security.

Core architecture is trait-driven and modular. Extend by implementing traits and registering in factory modules.

Key extension points:

  • crates/zeroclaw-api/src/provider.rs (Provider)
  • crates/zeroclaw-api/src/channel.rs (Channel)
  • crates/zeroclaw-api/src/tool.rs (Tool)
  • crates/zeroclaw-api/src/memory_traits.rs (Memory)
  • crates/zeroclaw-api/src/observability_traits.rs (Observer)
  • crates/zeroclaw-api/src/runtime_traits.rs (RuntimeAdapter)
  • crates/zeroclaw-api/src/peripherals_traits.rs (Peripheral) โ€” hardware boards (STM32, RPi GPIO)

Stability Tiers

Every workspace crate carries a stability tier per the Microkernel Architecture RFC.

Crate Tier Notes
zeroclaw-api Experimental Stable at v1.0.0 (formal milestone)
zeroclaw-config Beta Stable at v0.8.0
zeroclaw-providers Beta โ€”
zeroclaw-memory Beta โ€”
zeroclaw-infra Beta โ€”
zeroclaw-tool-call-parser Beta Stable at v0.8.0
zeroclaw-channels Experimental Plugin migration at v1.0.0
zeroclaw-tools Experimental Plugin migration at v1.0.0
zeroclaw-runtime Experimental Agent runtime (agent loop, security, cron, SOP, skills, observability)
zeroclaw-gateway Experimental Separate binary at v0.9.0
zeroclaw-tui Experimental TUI onboarding wizard
zeroclaw-plugins Experimental WASM plugin system โ€” foundation for v1.0.0 plugin ecosystem
zeroclaw-hardware Experimental USB discovery, peripherals, serial
zeroclaw-macros Beta Tightly coupled to config schema

Tiers: Stable = covered by breaking-change policy. Beta = breaking changes permitted in MINOR with changelog notes. Experimental = no stability guarantee.

Tiers are promoted, never demoted, through deliberate team decision.

Repository Map

  • src/main.rs โ€” CLI entrypoint and command routing
  • src/lib.rs โ€” module re-exports and CLI command enum definitions
  • crates/zeroclaw-api/ โ€” public trait definitions (Provider, Channel, Tool, Memory, Observer, Peripheral)
  • crates/zeroclaw-config/ โ€” schema, config loading/merging
  • crates/zeroclaw-macros/ โ€” Configurable derive macro
  • crates/zeroclaw-providers/ โ€” model providers and resilient wrapper
  • crates/zeroclaw-channels/ โ€” messaging platform integrations (30+ channels)
  • crates/zeroclaw-channels/src/orchestrator/ โ€” channel lifecycle, routing, media pipeline
  • crates/zeroclaw-tools/ โ€” tool execution surface (shell, file, memory, browser)
  • crates/zeroclaw-runtime/ โ€” agent loop, security, cron, SOP, skills, onboarding wizard, observability
  • crates/zeroclaw-memory/ โ€” memory backends (markdown, sqlite, embeddings, vector merge)
  • crates/zeroclaw-infra/ โ€” shared infrastructure (debounce, session, stall watchdog)
  • crates/zeroclaw-gateway/ โ€” webhook/gateway server (separate binary)
  • crates/zeroclaw-hardware/ โ€” USB discovery, peripherals, serial, GPIO
  • crates/zeroclaw-tui/ โ€” TUI onboarding wizard
  • crates/zeroclaw-plugins/ โ€” WASM plugin system
  • crates/zeroclaw-tool-call-parser/ โ€” tool call parsing
  • docs/ โ€” topic-based documentation (setup-guides, reference, ops, security, hardware, contributing, maintainers)
  • .github/ โ€” CI, templates, automation workflows

Risk Tiers

  • Low risk: docs/chore/tests-only changes
  • Medium risk: most crates/*/src/** behavior changes without boundary/security impact
  • High risk: crates/zeroclaw-runtime/src/** (especially src/security/), crates/zeroclaw-gateway/src/**, crates/zeroclaw-tools/src/**, .github/workflows/**, access-control boundaries

When uncertain, classify as higher risk.

Workflow

  1. Read before write โ€” inspect existing module, factory wiring, and adjacent tests before editing.
  2. One concern per PR โ€” avoid mixed feature+refactor+infra patches.
  3. Implement minimal patch โ€” no speculative abstractions, no config keys without a concrete use case.
  4. Validate by risk tier โ€” docs-only: lightweight checks. Code changes: full relevant checks.
  5. Document impact โ€” update PR notes for behavior, risk, side effects, and rollback.
  6. Queue hygiene โ€” stacked PR: declare Depends on #.... Replacing old PR: declare Supersedes #....

Branch/commit/PR rules:

  • Work from a non-master branch. Open a PR to master; do not push directly.
  • Use conventional commit titles. Prefer small PRs (size: XS/S/M).
  • Follow .github/pull_request_template.md fully.
  • Never commit secrets, personal data, or real identity information (see @docs/contributing/pr-discipline.md).

Anti-Patterns

  • Do not add heavy dependencies for minor convenience.
  • Do not silently weaken security policy or access constraints.
  • Do not add speculative config/feature flags "just in case".
  • Do not mix massive formatting-only changes with functional changes.
  • Do not modify unrelated modules "while here".
  • Do not bypass failing checks without explicit explanation.
  • Do not hide behavior-changing side effects in refactor commits.
  • Do not include personal identity or sensitive information in test data, examples, docs, or commits.

Linked References

  • @docs/contributing/change-playbooks.md โ€” adding providers, channels, tools, peripherals; security/gateway changes; architecture boundaries
  • @docs/contributing/pr-discipline.md โ€” privacy rules, superseded-PR attribution/templates, handoff template
  • @docs/contributing/docs-contract.md โ€” docs system contract, i18n rules, locale parity
โšก