Skip to content

CLAUDE.md

Latest commit

 

History

History
71 lines (51 loc) · 4.18 KB

CLAUDE.md

File metadata and controls

71 lines (51 loc) · 4.18 KB

CLAUDE.md

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

Project Overview

Opal agent implementation for the Whitney Museum of American Art. Three agent types demonstrate Optimizely's Opal platform capabilities: a standalone A/B test analyzer, a two-step content workflow (writer -> reviewer), and a Cloudflare Workers tool service that wraps the Whitney public API and content analysis checks.

Commands

# Everything runs from tools/
cd tools && npm install
cp .env.example .env  # fill in ANTHROPIC_API_KEY (and optionally Cloudflare creds)

# Tool service (Cloudflare Workers + Hono)
npm run dev          # local dev server via wrangler (http://localhost:8787)
npm run typecheck    # tsc --noEmit
npm run deploy       # deploy to Cloudflare Workers (requires CLOUDFLARE_API_TOKEN)
npm run tail         # stream live logs from deployed worker

# Local agent test harness (runs agents via Claude API)
npm run harness -- list --agents-dir ../agents
npm run harness -- discover
npm run harness -- run ../agents/<agent>.json -p key=value [-v]

# Endpoints (tool service)
# GET  /              health check
# GET  /discovery     Opal tool discovery (SDK pattern)
# GET  /registry      Opal tool discovery (raw HTTP pattern)
# POST /tools/:name   execute a tool (body = parameters JSON)

No test suite or linter exists yet.

Architecture

Agents (agents/) — JSON configs for the Opal platform, testable locally via the harness:

  • whitney-exhibition-ab-test-analyzer.json — standalone specialized agent, no tools, creativity 0.2
  • whitney-content-writer.json — workflow step 1, uses get_exhibitions + search_collection, creativity 0.7
  • whitney-content-reviewer.json — workflow step 2, uses check_brand_voice + check_accessibility, creativity 0.2
  • whitney-exhibition-content-workflow.json — workflow orchestrator linking writer -> reviewer

Tool service (tools/src/index.ts) — single-file Hono app deployed as a Cloudflare Worker:

  • get_exhibitions / search_collection — proxy the Whitney public API (whitney.org/api), no auth needed
  • check_brand_voice — regex-based checks against 5 rules (WBV-001 through WBV-005), score starts at 100 with deductions
  • check_accessibility — Flesch-Kincaid grade level + 4 structural checks (ACC-001 through ACC-005), default target grade 8

Tools are defined in the TOOLS array with metadata and handler functions. The /discovery endpoint is generated from this array (replaces the Opal SDK's @tool decorator auto-generation).

Test harness (tools/src/cli.ts) — local CLI that replaces Opal's runtime for testing. Reads agent JSON configs, sends prompts to the Claude API, routes tool calls to the local Worker. Supports single agents and multi-step workflows. Run via npm run harness.

Instructions (instructions/) — CLEAR framework templates (Context, Layout, Example, Action, Review) used as instruction references alongside agent prompt_templates.

CI/CD (.github/workflows/deploy.yml) — deploys tool service to Cloudflare Workers on push to main when tools/** changes. Requires two GitHub Actions secrets: CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID.

Secrets

No secrets in plain files. All credentials go through:

  • GitHub Actions secrets: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID
  • Cloudflare Workers secrets: wrangler secret put SECRET_NAME (accessed via c.env.SECRET_NAME in Hono)
  • Local dev/harness: tools/.env file (gitignored) — holds ANTHROPIC_API_KEY and optionally Cloudflare creds
  • Worker runtime secrets: tools/.dev.vars file (gitignored)

Key Conventions

  • Agent JSON schema: schema_version: "1.0", fields include creativity, inference_type, enabled_tools, prompt_template, parameters
  • Whitney API uses Ransack query syntax: q[field_matcher]=value (e.g., q[title_cont]=hopper, q[start_time_gt]=...)
  • Brand voice rules use "exhibition" not "exhibit", "artwork"/"work" not "art piece", avoid exclusionary terms (see WBV-003)
  • Tool execution accepts both { parameters: {...} } and flat parameter objects
  • TypeScript strict mode; wrangler handles bundling (no separate build step)