Skip to content

CLAUDE.md

Latest commit

 

History

History
118 lines (79 loc) · 5.82 KB

CLAUDE.md

File metadata and controls

118 lines (79 loc) · 5.82 KB

CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

Commands

bun setup                    # Initial setup (deps, packages, .env)
bun dev                      # Start all services via PM2
bun dev:stop                 # Stop all services
bun format && bun lint       # Format and lint workspace
bun run test                 # Run all tests (CRITICAL: not `bun test`)
bun build                    # Build everything (respects dependency order)

bun test vs bun run test: bun test uses bun's built-in runner (ignores vitest config). bun run test runs the package.json script (vitest with proper environment). Always use bun run test.

Per-package: bun run test, bun build, bun lint (check each package.json for available scripts).

Contracts (never use raw forge commands): bun build (adaptive changed-target compile), bun build:changed (changed Solidity only), bun build:target -- src/... (single-target compile), bun build:full (CI/deploy only), bun run test:fork (needs RPC URLs).

Architecture

Green Goods is an offline-first, single-chain platform for documenting regenerative work on-chain. Bun monorepo.

Key Principles

  1. Offline-First: Client PWA works without internet, syncs when connected
  2. Single Environment: All packages share root .env (never create package-specific .env)
  3. Single Chain: Target chain set by VITE_CHAIN_ID at build time
  4. Shared Logic: ALL React hooks MUST live in @green-goods/shared

Build Order

  1. contracts -> ABIs for other packages
  2. shared -> hooks/modules for frontends
  3. indexer -> needs contract ABIs
  4. client/admin/agent -> need shared package

Documentation

The docs/ directory contains a Docusaurus site with product documentation, user guides, and developer references. When investigating domain questions, architecture decisions, or user-facing behavior, consult:

  • System architecture (diagrams): docs/docs/developers/architecture.mdx
  • Domain glossary: docs/docs/glossary.md
  • Impact model (CIDS): docs/docs/concepts/impact-model.mdx
  • Strategy and goals: docs/docs/concepts/strategy-and-goals.mdx
  • Entity matrix: docs/docs/developers/reference/entity-matrix.mdx

Package-specific context files (.claude/context/*.md) include additional documentation references relevant to each package.

Key Patterns

Hook Boundary: ALL hooks in @green-goods/shared. Client/admin only have components and views.

import { useAuth, useGardens } from '@green-goods/shared'; // correct

Contract Integration: Import deployment artifacts, never hardcode addresses.

import deployment from '../../../contracts/deployments/11155111-latest.json';

Barrel Imports: Always import { x } from "@green-goods/shared", never deep paths.

Type System: Domain types (Garden, Work, Action, Address) live in @green-goods/shared. Use Address type (not string) for Ethereum addresses.

Error Handling: Never swallow errors. Use parseContractError() + USER_FRIENDLY_ERRORS for contract errors. Use createMutationErrorHandler() in shared mutation hooks. Use logger from shared (not console.log).

Query Keys: Use queryKeys.* helpers from shared. Serialize objects in query keys.

Indexer Boundary: Envio indexes only Green Goods core state (actions, gardens, hats role membership, vault history, yield split history, minimal hypercert linkage/claims). Do not re-index EAS attestations, Gardens V2 community/pools, marketplace, ENS lifecycle, cookie jars, or Hypercert display metadata.

Investigate Before Answering: Never speculate about code you have not opened. If referencing a specific file, you MUST read it before answering. Give grounded, hallucination-free answers based on actual file contents, not assumptions about what code might look like.

Subagent Discipline: Spawn teammates when tasks can run in parallel, require isolated context, or involve independent workstreams. Work directly (no subagent) for single-file edits, sequential operations, tasks sharing state across steps, or any task needing fewer than 10 tool calls. Prefer the simplest approach that completes the task.

Contract Deployment

bun script/deploy.ts core --network sepolia              # Dry run
bun script/deploy.ts core --network sepolia --broadcast   # Deploy
bun script/deploy.ts core --network sepolia --broadcast --update-schemas  # Deploy + schemas

Deployment artifacts: deployments/{chainId}-latest.json is the source of truth for all addresses. Zero addresses mean the module hasn't been deployed yet (not a blocker for optional modules).

Environment

Single .env at root (never create package-specific .env). VITE_CHAIN_ID sets target chain at build time. See .env.example.

Git Workflow

Branches: type/description (e.g., feature/hats-v2, bug/admin-fix)

Commits: Conventional Commits with scope: type(scope): description

  • Types: feat, fix, refactor, chore, docs, test, perf, ci
  • Scopes: contracts, indexer, shared, client, admin, agent, claude

Validation before committing: bun format && bun lint && bun run test && bun build

Session Continuity

Before context compaction or ending a long session, write a session-state.md in the working directory:

## Session State
- **Current task**: [what you're working on]
- **Progress**: [what's done, what's in progress]
- **Files modified**: [list of changed files]
- **Tests**: [passing/failing/not yet written]
- **Next steps**: [immediate next actions]
- **Blocked by**: [blockers, if any]

This is distinct from agent-memory (which stores learnings). Session state captures execution context for the next context window.

Cleanup

If you create temporary files, scripts, or helpers during iteration, remove them before reporting task completion.