Eve forge

eve-forge — turn a business into a deployed eve agent

The orchestrator/forge (a Claude Agent SDK program) produces a deployed, tenant-scoped eve agent from a business's absorption inputs. This skill encodes the real eve workflow + every trap learned dogfooding it, and gates the consequential steps so the forge cannot repeat the benchmark's mistakes.

Latent vs deterministic split:

• Latent (agent judgment, this SKILL.md): absorb (Word template + transcript
  • examples → tenant-spec.json) and author (write the eve agent/ files in the business's voice from the templates).
• Deterministic (scripts/, tested): preflight (Node ≥ 24), deploy-safety (never ship unlocked auth), validate (eve info clean), smoke (output vs ground truth). Precision work lives in code; the latent space invokes it.

The 8-stage pipeline

#	Stage	How	Gate
1	Absorb	read the template + 1–2 transcripts + 2–3 filled examples → write tenant-spec.json (see references/templates/tenant-spec.example.json) + a ground-truth truth.json (required substrings + case-scoped forbidden). Stage these OUTSIDE the tenant dir — eve init refuses a non-empty target ("has no package.json")	latent
2	Scaffold	python3 scripts/eve_forge.py preflight then nvm use 24 && npx eve@latest init <slug>, then move tenant-spec.json/truth.json in	preflight blocks if Node < 24 (the npx trap)
3	Author	fill from tenant-spec.json: copy references/templates/{fill_document,send_document}.ts → agent/tools/; write agent/instructions.md (business voice + "strip HTML comments from the output"); EDIT the scaffolded agent/channels/eve.ts — remove placeholderAuth() → auth: [vercelOidc(), localDev()] (never none()). Do NOT hand-write defineChannel; the scaffold already ships eveChannel	latent
4	Validate	npx eve info --json | python3 scripts/validate.py --expect-tools fill_document,send_document (validate.py strips eve's banner + reads the real dict-diagnostics/status schema) + npm run typecheck	0 diagnostic errors + tools registered, or iterate
5	Deploy	python3 scripts/eve_forge.py gate agent/ (point at the agent/ dir, not the project root) before vercel deploy --scope <team>; use the production alias (the raw URL 302s to SSO)	deploy-safety denies if auth not locked
6	Smoke	drive the deployed agent (see §Smoke against a locked channel) → python3 scripts/smoke.py --output <filled.txt> --truth truth.json	assert vs ground truth (evidence-gated)
7	Register	commit freelance/<slug>/ (agent dir + tenant-spec.json + truth.json + smoke-receipt.json: {url, verdict, coverage, at}); report URL + evidence	tenant = versioned data
8	Evolve	owner draft→approve corrections → forge proposes a diff to instructions.md/skills	propose → test vs fixtures → owner-approve → commit

The deploy-safety gate (the incident-derived check)

A benchmark run shipped a public, auth: none(), Gateway-billed eve endpoint — anyone could spend credits. This skill makes that structurally unreachable. In the Claude-Code orchestrator, wire it as a PreToolUse hook that runs scripts/deploy_safety.py <agent_dir> before any vercel deploy and denies the tool call on a non-zero exit. Rule (prod): the channel auth: array must contain a real authenticator (vercelOidc) and must NOT contain none()/placeholderAuth(); a lone localDev() is dev-only. Fail-closed if no auth: array is found.

Smoke against a locked channel

A correctly-locked channel returns 401 to anonymous callers — so the smoke driver must authenticate (the only reason a naive smoke "worked" in the benchmark was the auth: none() incident). On the Vercel deploy:

vercel env pull /tmp/<slug>.env --environment=production --scope <team>   # mints VERCEL_OIDC_TOKEN
TOKEN=$(grep VERCEL_OIDC_TOKEN /tmp/<slug>.env | cut -d= -f2- | tr -d '"')
# POST a turn — payload field is `message` (NOT `input`); returns 202 + sessionId:
curl -s -XPOST "https://<slug>.vercel.app/eve/v1/session" -H "Authorization: Bearer $TOKEN" \
     -H 'content-type: application/json' -d '{"message":"<transcript>"}'
# GET the stream (it long-polls at session.waiting → cap it), extract the fill_document output:
curl -s --max-time 60 "https://<slug>.vercel.app/eve/v1/session/<sessionId>/stream?startIndex=0" \
     -H "Authorization: Bearer $TOKEN" > /tmp/<slug>.stream

Delete /tmp/<slug>.env after (it holds a live token).

Deterministic scripts

• scripts/eve_forge.py preflight — Node ≥ 24 or fail (the npx eve init trap).
• scripts/eve_forge.py gate <agent_dir> [--info info.json --expect-tools a,b] — runs deploy-safety (+ validate) as one pre-deploy gate.
• scripts/deploy_safety.py <agent_dir> [--env prod|dev] / --stdin — the auth-lock check.
• scripts/validate.py --expect-tools a,b (reads eve info --json on stdin) — diagnostics + tools.
• scripts/smoke.py --output <file> --truth <json> — deployed-output vs ground-truth (strips HTML comments; truth.json forbidden encodes case-scoped negatives, e.g. no "bloodwork" for a non-senior patient).

Gotchas (see references/gotchas.md)

Node-24 hard requirement (npx silently uses the wrong Node) · non-TTY eve dev errors (scaffold succeeds, the auto-dev-launch fails) · fail-closed default auth + Vercel Deployment-Protection SSO (use the production alias, keep auth locked) · eve not auto-detected as a Vercel framework ("No framework detected" → its native Agent-Runs observability may not activate) · AI-Gateway auth works via project OIDC at runtime (zero keys). Pin the eve + claude CLI versions (eve is beta).

Anti-rationalization

Excuse	Reality
"Deploy it, I'll lock auth later."	The deploy-safety gate is binary and PreToolUse-wired. auth: none() never reaches prod.
"eve info was clean when I wrote it."	Re-run validate after every author edit; typecheck drift is silent.
"It looks right, ship it."	Smoke-test against the business's own ground-truth example, or it's prose, not evidence.
"npx eve init failed weirdly."	Run preflight — it's the Node-24 trap 9 times out of 10.

References

• references/gotchas.md — the full benchmark gotcha list.
• references/templates/ — the 4 eve agent file templates the author stage fills.
• research/entities/concept/eve-agent-orchestrator.md — the orchestrator design + provenance.
• docs/reports/2026-07-04-life-vs-eve-benchmark.html — the driven benchmark this distills.