Skip to content

CLAUDE.md

Latest commit

 

History

History
55 lines (46 loc) · 2.96 KB

CLAUDE.md

File metadata and controls

55 lines (46 loc) · 2.96 KB

AgentKeys

Architecture

Rust monorepo with Cargo workspace. See docs/spec/architecture.md for component inventory. See docs/spec/credential-backend-interface.md for the CredentialBackend trait contract (15 methods). See docs/spec/plans/development-stages.md for the 8-stage build plan. See docs/spec/plans/execution-plan.md for the orchestration runbook (ralph, team, ultraqa). Do not read folder docs/archived

Version Control

Use jj (Jujutsu) for all version control. Never use raw git commands.

Development Workflow (Anthropic Harness Pattern)

On every session start:

  1. jj log --limit 10 && cat harness/progress.json && bash harness/init.sh $(jq -r .current_stage harness/progress.json)
  2. Read the stage contract for your current stage in docs/spec/plans/development-stages.md
  3. Pick the HIGHEST-PRIORITY incomplete deliverable from harness/features.json
  4. Implement ONE deliverable
  5. Run tests: cargo test -p <crate> for the affected crate
  6. Describe: jj describe -m "agentkeys: stage N -- <deliverable name>"
  7. Update harness/features.json (set implemented: true) and harness/progress.json
  8. New change: jj new -m "harness: update progress"

Stage Completion Protocol

  1. Run bash harness/stage-N-done.sh -- must exit 0
  2. jj bookmark create stage-N-done (bookmark marks the completion point)
  3. Update harness/progress.json: set stage status to "complete"
  4. jj describe -m "harness: stage N complete"
  5. jj new (start fresh change for next stage)

Code Conventions

  • Rust: thiserror for library errors, anyhow for binary errors
  • All async: tokio runtime, #[tokio::test] for async tests
  • Crate names: agentkeys-types, agentkeys-core, agentkeys-cli, agentkeys-daemon, agentkeys-mock-server, agentkeys-mcp, agentkeys-provisioner
  • Git commits: agentkeys: stage N -- <deliverable>
  • Never self-grade: run bash harness/stage-N-done.sh to verify

Mock Server Design Principles

The mock server mirrors Heima blockchain extrinsics. Follow these rules:

  • Typed parameters: Every endpoint must accept explicit typed inputs (e.g., identity_type + identity_value), never parse opaque JSON blobs to guess types at runtime. Blockchain extrinsics require typed parameters -- the mock must enforce the same contract.
  • Shared identity resolution: Use a single resolve_identity(db, identity_type, identity_value) -> Result<String> utility in handlers/identity.rs for all identity-to-wallet lookups. Never inline if/else chains per identity variant.
  • Modular handlers: Split request-type-specific logic into separate functions (e.g., mint_pair_session(), mint_recover_session()). The approve_auth_request handler dispatches to these, not inline everything.

Test Commands

cargo test -p agentkeys-types
cargo test -p agentkeys-core
cargo test -p agentkeys-mock-server
cargo test -p agentkeys-cli
cargo test -p agentkeys-daemon -p agentkeys-mcp
cargo test -p agentkeys-provisioner
npm test --prefix provisioner-scripts