Skip to content

Latest commit

 

History

History
102 lines (84 loc) · 6.09 KB

AGENTS.md

File metadata and controls

102 lines (84 loc) · 6.09 KB

AGENTS.md

1) Project Overview

Clawdentity is a mixed TypeScript + Rust monorepo that provides cryptographic identity and trusted relay infrastructure for agent-to-agent communication. The deployable surface is in apps/ (registry, proxy, CLI packaging, OpenClaw skill), shared contracts/runtime libraries are in packages/, and Rust runtime + CLI implementation is in crates/. Design and delivery must assume operators may run Clawdentity in local or constrained/offline environments, with OpenClaw integration as a first-class workflow.

2) Build Commands

TypeScript (apps + packages)

Run from repository root:

  • pnpm install
  • pnpm build
  • pnpm test

DID Format Guidance

  • Keep all DID construction/parsing inside packages/protocol/src/did.ts so the switch to did:cdi stays centralized and tests update automatically.
  • Trust slices (AIT, CRL, registry ownership, proxy pairings, connectors) should call shared helpers (e.g., parseDid, validateAgentDid) instead of copying brittle string-prefix checks; this keeps role expectations tied to context when DID semantics depend on parsed entity and authority fields.
  • When new DID authorities appear (registry-owned vs self-hosted), track their identifiers in configuration and rely on parsed authority metadata for routing/trust checks rather than scattering hardcoded strings.

Execution Governance

  • GitHub issues are the source of truth for sequencing, blockers, and rollout updates.
  • Primary execution tracker: #74.
  • Do not use local execution-order files as governance source.

Common quality checks:

  • pnpm lint
  • pnpm -r typecheck
  • pnpm check:file-size

Rust (crates workspace)

Run from crates/:

  • cargo check
  • cargo clippy --all-targets
  • cargo test
  • cargo build

3) Module Map

Apps (deployable services)

  • apps/registry - Cloudflare Worker HTTP API for humans, agents, invites, API keys, and revocation data.
  • apps/proxy - Cloudflare Worker relay/proxy that verifies Clawdentity auth headers and enforces trust policy.
  • apps/cli - TypeScript CLI compatibility package (clawdentity); Rust CLI is the canonical operator surface.
  • apps/openclaw-skill - OpenClaw skill package and relay transform artifacts used by CLI install flow.

Packages (shared libraries)

  • packages/protocol - Canonical protocol models and signing/verification wire-contract definitions.
  • packages/common - Shared utility layer (errors, helpers, validation glue, shared types).
  • packages/connector - TypeScript connector client/runtime primitives for relay connectivity.
  • packages/sdk - Developer SDK for identity operations, verification, auth flows, and integration helpers.

Rust workspace crates

  • crates/clawdentity-core - Core Rust library for identity, registry clients, connector/runtime, providers, pairing, and persistence.
  • crates/clawdentity-cli - Rust CLI binary and command surface for current operator workflows.

Rust local test services

  • crates/tests/local/mock-registry - Local mock registry used for integration and harness-style flows.
  • crates/tests/local/mock-proxy - Local mock relay/proxy used for integration and connector testing.

4) CLI Commands

TypeScript CLI (apps/cli)

  • Build/package: pnpm -F clawdentity build
  • Treat command docs here as compatibility guidance, not canonical runtime surface.

Rust CLI (crates/clawdentity-cli)

  • Help: cargo run -p clawdentity-cli -- --help
  • Common ops: cargo run -p clawdentity-cli -- init, register, whoami, agent create <name>, agent auth revoke <name>, provider setup --for <platform> --agent-name <name>, provider doctor --for <platform>, connector start <agent>

5) Deeper Docs

Use docs/ as system of record:

  • docs/ARCHITECTURE.md - end-to-end architecture across apps, packages, crates, and trust flows.
  • docs/MONOREPO.md - workspace structure, dependency/build ordering, and cross-ecosystem testing strategy.
  • docs/DESIGN_DECISIONS.md - architectural choices and tradeoffs.
  • docs/GOLDEN_PRINCIPLES.md - non-negotiable quality constraints.
  • docs/HARNESS_ACTION_PLAN.md - staged execution and quality-enforcement plan.

6) Quality Rules

  • Follow docs/GOLDEN_PRINCIPLES.md for code and documentation changes.
  • Keep modules small, testable, and dependency direction explicit.
  • Favor actionable errors and stable machine-readable outputs.
  • Run relevant TypeScript and Rust checks before commit (pnpm build and cargo check are baseline gates).
  • Keep docs synchronized with implementation changes, especially when changing CLI flows or skill behavior.
  • Keep user onboarding docs prompt-first (/skill.md canonical); treat command-by-command and Rust toolchain flows as advanced fallback guidance only.

7) Release Automation

  • Keep Rust release automation in .github/workflows/publish-rust.yml as the single canonical path for version bump + crates.io publish + tag creation + binary release.
  • Rust crate publish flow must derive the next version from crates metadata via cargo info, avoid direct crates.io API endpoint calls, verify the new rust/vX.Y.Z tag does not yet exist, and keep clawdentity-core / clawdentity-cli versions aligned.
  • Rust crate publish order is strict: publish clawdentity-core before clawdentity-cli.
  • Rust binary builds must use the same rust/vX.Y.Z tag created by the crate publish flow.
  • Rust binary releases must publish cross-platform assets for Windows x64, Linux x64/aarch64, and macOS x64/aarch64.
  • Keep release asset names stable:
    • clawdentity-<version>-linux-x86_64.tar.gz
    • clawdentity-<version>-linux-aarch64.tar.gz
    • clawdentity-<version>-macos-x86_64.tar.gz
    • clawdentity-<version>-macos-aarch64.tar.gz
    • clawdentity-<version>-windows-x86_64.zip
    • clawdentity-<version>-windows-aarch64.zip
    • clawdentity-<version>-checksums.txt
  • Binary naming contract for release artifacts:
    • Unix binary is clawdentity
    • Windows binary is clawdentity.exe
  • irm/PowerShell is a download/install path only; do not treat it as a runtime binary format.
  • Every release run must publish SHA256 checksums for all archives.