CLAUDE.md

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

What this is

Guidewire MCP for Claude — a Claude Code plugin (/plugin install jeremylongshore/guidewire-mcp-for-claude) + carrier-native MCP server for the Guidewire InsuranceSuite (PolicyCenter, ClaimCenter, BillingCenter). v0.1.0 ships read-only PolicyCenter with 5 carrier-vocabulary tools. Live architecture diagram: guidewire-mcp.intentsolutions.io.

The thesis: tool names are operator questions (find-submissions-waiting-on-me), never API verbs (search_policies). A governance harness gates all writes via plan → policy → approval → execute → audit → rollback. The audit hash-chain + the carrier vocabulary are the durable moats. Harness library + CLI shipped; full pipeline proven end-to-end against testcontainers Postgres in packages/harness/tests/e2e.pg.test.ts. Remaining E3 work: npm publish (bundled with E11+ marketplace push).

Build / test / run

pnpm workspace, Node 22 LTS, TypeScript 5.5+, Vitest, Biome (single linter+formatter, no ESLint+Prettier). Cloud API contract tests live in tests/contract/ on Karate (JDK 11 + Gradle) per D-022 — TS covers orchestration / unit / integration; Karate covers the Cloud API wire contract.

pnpm install                                    # prepare hook builds all workspaces
pnpm -r build                                   # rebuild all 8 workspaces (7 packages + 1 server)
pnpm -r test                                    # 135 tests across all workspaces
pnpm --filter @intentsolutions/guidewire-audit test                            # single workspace
pnpm --filter @intentsolutions/guidewire-audit test -- audit-store.test.ts     # single test file
pnpm typecheck                                  # tsc --noEmit across all workspaces
pnpm lint                                       # biome check .
pnpm format                                     # biome format --write .
pnpm smoke-reach                                # ping librarian-cataloged Cloud endpoints with dev-tier creds
node servers/policycenter-mcp/dist/cli.js                              # boot with in-memory default profile
node servers/policycenter-mcp/dist/cli.js --profile profiles/oss-demo  # boot with on-disk profile

# Cloud API contract tests (Karate — JVM-side; runs when GUIDEWIRE_OAUTH_CLIENT_ID is set, skips cleanly when not):
cd tests/contract && ./gradlew test

The prepare script (pnpm -r build in root package.json) fires on every pnpm install so plugin-install end-users get a built dist/ automatically. dist/ is gitignored; CI rebuilds in workflows. Fail-loud by design — if the build breaks on a user's machine, pnpm install errors out with the underlying message instead of silently completing. Don't reintroduce || true (PR #96).

pnpm.overrides in root package.json pins vite >=6.4.2 and ip-address >=10.1.1 to clear transitive moderate CVEs that the direct devDeps don't bump on their own pace. pnpm audit is clean — keep it that way; new vulns surface here first.

Architecture big-picture

5 layers, top to bottom (the live diagram visualizes this):

1. Agent host — Claude Code, Claude Desktop, Anthropic API
2. MCP servers — servers/<suite>-mcp/ (only policycenter-mcp built; claimcenter / billingcenter / producer / events planned)
3. Harness — packages/harness/ (library + CLI built; end-to-end pipeline proven via testcontainers in tests/e2e.pg.test.ts; npm publish pending). Gates writes via plan → policy → approval → execute → audit → rollback. NOT an MCP server (recursion + tool-selection problem). Production-wiring detail: when wiring against real Postgres, the harness needs both pools — audit_writer for audit.append() (INSERT-only) and audit_reader for evidence.build() (SELECT-only). Surfaced by the e2e test; in-memory tests can't catch it because the memory store has no role separation. The e2e test is the canonical wiring template for any server that boots the harness in approved_execute mode.
4. E1 foundation packages (all built; packages/):
   • @intentsolutions/guidewire-schemas — Zod schemas + TS contracts
   • @intentsolutions/guidewire-observability — OTel + pino + Sentry factory
   • @intentsolutions/guidewire-auth — Hub OAuth + JWT propagation
   • @intentsolutions/guidewire-audit — Postgres + hash-chain audit store
   • @intentsolutions/guidewire-client — undici Cloud API client with two-key idempotency (harness gwh1: cache key + Guidewire GW-DBTransaction-ID wire header — never reuse the same value)
   • @intentsolutions/guidewire-mcp-runtime — MCP SDK wrapper
5. External — Guidewire Cloud API, Hub OAuth, Postgres (audit chain), OTLP collector + Sentry

Profile system (loader + scaffold landed; full per-tenant story is E4):

• Plug-and-play default: createDefaultProfile() in servers/policycenter-mcp/src/profile.ts returns an in-memory profile covering all 5 v0.1.0 read-only tools. Zero YAML editing required for the 80% case. This is what the Claude Code plugin install uses.
• Per-tenant override: loadProfile(path) reads 9 YAMLs from profiles/<tenant>/ (auth, roles, lob, typelists, custom-entities, field-aliases, approval-matrix, pii-policy, events; per PRD § 6.1-6.9), validates each via Zod schemas in packages/schemas/src/profile/. Customers copy profiles/_template/ → profiles/<their-tenant>/, edit, run with --profile <path>.
• profiles/oss-demo/ is a fully-populated reference. Read-only — never the production path.

Three execution modes per tool (selected per-tool via profile): read_only (E2 ships these), draft_only (E5), approved_execute (E3 + harness). The harness is the only path to writes — depcruise

• AST rules in CI prevent server code from importing packages/client-sdk (npm @intentsolutions/guidewire-client) write methods except inside an execute() callback.

Hard rules

These travel with the code; CI workflows in .github/workflows/ enforce what's enforceable.

1. Carrier-vocabulary tool names. Tool names are the question an operator would actually ask. Reject API-shaped names (search_*, list_*, get_*) at PR review.
2. NO MOCKS. Real Guidewire Cloud endpoints from day one. No hand-written fixtures/. tests/recordings/ holds HTTP recordings captured from real dev-tier sandbox calls with provenance metadata. Per D-008 + D-021.
3. No write without audit, policy, idempotency. Hash-chained audit per tenant; tamper-resistant via three Postgres roles (writer / reader / verifier) per D-019. E1 ships a testcontainers test asserting audit_writer cannot UPDATE / DELETE (per audit-response triage AR-7 in audits/00-AUDIT-RESPONSES.md).
4. Observability from line 1. Every public function in servers/* and packages/harness/ opens a span. Every throw uses a typed AppError in packages/observability/. CI fails on raw console.log in production code paths.
5. Source-doc citation discipline. Every claim about Cloud API endpoints, typelist values, LOB codes, custom-entity shape, App Events, or any Guidewire technical surface must cite an authoritative public reference (typically a release-versioned URL from 000-docs/005-DR-REF-guidewire-public-resources.md) OR explicitly mark the claim (unverified — practitioner knowledge from public docs; first integration engagement validates). Never invent endpoint shapes or syntax.
6. Beads for ALL task tracking. Never TodoWrite, TaskCreate, or markdown TODO. Each bead carries a Blueprint: reference to the relevant 000-docs/blueprint/ section.

Workflow

bd ready                                   # find available work
bd update <id> --status=in_progress
git checkout -b <type>/<short-description>
# work
bd close <id> -r "evidence" && git add ... && git commit ... && git push -u origin <branch>
gh pr create --title "..." --body "..."
gh pr merge <N> --squash --auto --delete-branch     # auto-merges after Gemini review + checks

Branch protection on main is enforced by the repository ruleset main: required checks + 1 review (active 2026-05-06). It binds:

• 6 required status checks — all must pass before merge: Lint (Biome), Typecheck (tsc --noEmit), Test (Vitest), Build (tsup), audit-harness gates, gitleaks.
• 1 required PR approval — author cannot self-approve.
• No force-push, no deletion of main.

Bypass: the ruleset's bypass_actors list explicitly grants the RepositoryRole=Admin (id 5) bypass_mode: always. Without that explicit entry, even repo OWNER cannot bypass — verified empirically 2026-05-06 (an unconfigured ruleset blocked the OWNER's own admin-merge attempt). With it, gh pr merge --admin succeeds for owner-authored PRs (the common case where Claude opens the PR on Jeremy's behalf — GitHub blocks the PR author from approving their own PR, so admin-merge is the only CLI path; web-UI workflows are not used).

If a separate bot account is ever set up for Claude's commits, the PR-author / approver split would be natural: bot opens PR, owner approves via gh pr review --approve, normal merge works without the bypass. Until then, every Claude-opened PR ends with gh pr merge --admin --squash --delete-branch.

Rebase gotcha: .beads/issues.jsonl conflicts on every rebase because both branches accrete bead activity (the file is a sqlite export that bd auto-rewrites on every command). Resolution is mechanical — take main's version, the underlying state is identical: git checkout --theirs .beads/issues.jsonl && git add .beads/issues.jsonl && git rebase --continue.

Release version-bump discipline: do NOT use jq '.version = "..."' across multiple package.json files — jq's default formatting expands short string arrays ("files": [...]) into multi-line which biome wants compact, leaving the release commit CI-red. Either bump via Edit (exact-string replace per file) or follow with npx biome check --write . before commit. Lesson learned 2026-05-07 on the v0.1.1 release; see commit history for the cleanup PR.

Gemini Code Assist is the convention for external review on every PR but is NOT enforced as a required reviewer (Gemini posts as a bot, marking it required would break the OSS contributor flow). By convention: wait for Gemini's review before approving — it catches drift the human reviewer often misses (per session log 2026-05-06: Gemini caught 3 real defects on PRs #84-#88, including a security-medium GRANT issue and an env-var name bug that would have silently broken smoke-reach).

5 specialist agents in .claude/agents/ (project-scoped) auto-review designs: mcp-safety-reviewer, carrier-vocabulary-curator, guidewire-api-archaeologist, harness-runtime-architect, guidewire-reference-librarian. Spawn the librarian before drafting any tool / profile / recording that asserts a Cloud API shape — it consults the public-docs KB and flags unverified gaps.

Where to look (canonical sources of truth)

Plugin / installation surface

The repo ships as a Claude Code plugin via .claude-plugin/plugin.json + .mcp.json. End-users run /plugin install ..., set 4 env vars (GUIDEWIRE_OAUTH_CLIENT_ID, GUIDEWIRE_OAUTH_CLIENT_SECRET, GUIDEWIRE_TOKEN_ENDPOINT, GUIDEWIRE_PC_BASE_URL), and ask Claude carrier questions in their session. The plugin path is the primary product surface; the pnpm install && pnpm -r build flow is the developer / contributor path.

Author

Jeremy Longshore, Intent Solutions IO · intentsolutions.io · jeremy@intentsolutions.io