Imported from wakeuplabs-io/alpen-multisig (AGENTS.md). Install upstream with npx skills add wakeuplabs-io/alpen-multisig. Copyright stays with the author.

Strata Multisig

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Documentation Structure

docs/
├── 0-prd/              # Product Requirements from the client (Alpen) — do not modify
├── 1-proposal/         # WakeUp Labs technical proposal and scope — do not modify
├── 2-discovery/        # Phase 1 research (+ crate-inventory.md)
├── 3-stories/          # Story map and non-functional items
├── architecture/       # System architecture overview
│   └── adrs/           # Architecture Decision Records
├── specs/              # Feature specs (functional contracts)
├── assessment/         # Backlog SSOT, audits/, archive/ (wave history)
├── operations/         # Runbook, threat model, delivery plan
├── archive/            # Historical: features/, evolution/, poc-specs/ — not SSOT
├── external/           # Client-facing deliverables (canonical for delivery)
└── README.md           # Internal SSOT map — start here for navigation

See docs/README.md for conflict resolution and topic index.

Commands

Rust Workspace

cargo build                                # Build entire workspace
cargo test                                 # Run all tests
cargo test -p orchestrator-be               # Test backend only
cargo test -p alpen-multisig-e2e-tests     # Run e2e tests only
cargo test -p orchestrator-be -- test_name  # Run a single test
cargo clippy                               # Lint
cargo fmt --check                          # Format check

Desktop App

cd desktop-app && npm install     # Install dependencies
cd desktop-app && npm run dev     # Vite dev server (frontend only, no Tauri IPC)
cd desktop-app && npm run build   # TypeScript + Vite build
cd desktop-app && npm run tauri dev   # Full desktop app (Rust + React)

WebDriver smoke (real Tauri binary, real services): see desktop-app/e2e-webdriver/README.md — requires tauri-driver, WebKitWebDriver (Linux), and the usual local stack. In desktop-app/e2e-webdriver, npm run test:e2e runs only the wallet smoke spec; use npm run test:e2e:all or the test:e2e:* scripts in that package to run other flows one at a time.

Running the System

1. Backend: cargo run -p orchestrator-be (starts Axum server on port 3000)
2. Desktop: cd desktop-app && npm run tauri dev

Architecture

Cargo workspace with 3 members: orchestrator-be, desktop-app/src-tauri, e2e-tests

• orchestrator-be — Offchain coordination backend (Axum HTTP). Domain-driven layout: domain/, application/, infrastructure/, handlers/, state.rs, config.rs, error.rs. Entry: src/main.rs. Postgres when DATABASE_URL is set; in-memory repo for local dev without it.
• desktop-app/src-tauri — Tauri 2 desktop shell. Rust backend process communicates with React frontend via IPC (invoke()). Entry: src/main.rs
• e2e-tests — Workspace member. Integration tests against Alpen/Strata protocol crates. See docs/architecture/adrs/001-alpen-crate-dependencies.md for dependency strategy.

Frontend (desktop-app/src/): React 18 + TypeScript + Vite + react-router-dom. Current layout: components/, contexts/, hooks/, screens/, wallet/, api/tauri-bridge.ts, api/signing.ts, types/, App.tsx, main.tsx

Full architecture: docs/architecture/overview.md

Dependencies

Alpen/Strata crates are not on crates.io — consumed as git dependencies. Shared pins are centralized in root Cargo.toml under [workspace.dependencies]. See docs/architecture/adrs/001-alpen-crate-dependencies.md for full strategy, risks, and update procedure.

Key Conventions

• Protocol alignment: SPS-50, SPS-51, SPS-65 are source of truth
• Backend is coordination only: proposal creation, signature collection, lifecycle tracking — never re-implement protocol validity rules
• Signer safety: Explicit confirmation steps, authority context, high-signal errors
• Manual fallback: Users can aggregate signatures and broadcast if backend unavailable
• Error handling: anyhow::Result for binaries, thiserror for libraries
• Frontend: Use tabs, single quotes, ~120 char lines, strict equality
• Naming: Use kebab-case for directories and file names
• Patterns: Match existing project patterns before introducing new abstractions
• CI: All generated code must pass CI checks — verify locally before considering work done
• Git / develop: Never push directly to develop. Use a branch and PR for all changes (code and docs); merge only after review and green CI

Pre-Commit CI Checklist

Run all of the following locally and confirm they pass before every commit. Do not push until all are green.

# Rust (from repo root) — use exact CI flags
cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

# Frontend (from desktop-app/)
cd desktop-app
npm run format:check
npm run lint
npm run build

Rule Files

SSOT: .cursor/rules/ for Cursor; .claude/rules/ is a maintained mirror — update both when changing agent conventions.

Rules in .claude/rules/ auto-load based on paths frontmatter — only the rules relevant to the files being edited are loaded into context:

• typescript-standards.md — Loaded for desktop-app/src/**/*.{ts,tsx}
• react-frontend-patterns.md — Loaded for desktop-app/src/**/*.{ts,tsx}
• rust-backend-standards.md — Loaded for orchestrator-be/**/*.rs, desktop-app/src-tauri/**/*.rs
• backend-api-conventions.md — Loaded for orchestrator-be/**/*.rs