GECX Chat Agent Prompt Library

Copy these prompts into Claude Code, Codex, Antigravity, Cursor, Copilot, or another coding agent. Each prompt is written to push the agent toward mock-first, typed, app-owned chat experiences with gecx-chat.

Weekend Hacker Prompts

1. Build Me A Chat UI

Build a working chat UI with `gecx-chat`.
Start mock-first with `createMockTransport` and `scenarioCatalog.list()`.
Use `gecx-chat/react`, render `message.parts` with `<MessagePart key={part.id} part={part} />`, and include send/stop controls.
Do not use the legacy web widget or browser secrets.
Add a smoke test with `createMockChatClient`.
Run `pnpm typecheck` and the relevant test.

Expected outcome: a runnable support-style chat surface.

Key files: docs/agent/llms.txt, docs/agent/llms-full.txt section 1, packages/gecx-chat/src/react/.

2. Add Tool Calling

Add a schema-backed client tool to this GECX Chat app.
Use `defineClientTool`, typed inputs, JSON Schema, permissions, `timeoutMs`, and `ctx.signal`.
Require approval for state-changing behavior.
Add tests for success, invalid input, denial, and abort.

Expected outcome: a safe tool plus tests.

Key files: docs/agent/llms-full.txt section 3, packages/gecx-chat/src/tools/.

3. Make It Stream Nicely

Improve the streaming UX for this `gecx-chat` experience.
Use `chat.isStreaming`, `chat.stop`, a slow mock scenario, and accessible status text.
Install or adapt the `streaming-indicators` recipe if useful.
Verify with `scenarioCatalog.get('slow-streaming')`.

Expected outcome: polished streaming/stop affordances.

Key files: recipes/streaming-indicators/, docs/agent/llms-full.txt section 2.

4. Add Product Cards

Add product card rich content to this GECX Chat app.
Use a typed `product-carousel` renderer or `gecx add product-carousel`.
Keep payloads inert and validated; do not render assistant-provided HTML.
Add a mock scenario or test that renders at least one product card.

Expected outcome: copy-owned product carousel.

Key files: recipes/product-carousel/, docs/agent/llms-full.txt sections 4-5.

5. Deploy It

Prepare this GECX Chat app for production build.
Keep mock mode available, move live auth to `/api/gecx-chat-token`, avoid browser secrets, add server origin checks, and document required environment variables.
Run typecheck, tests, build, and any route smoke checks.

Expected outcome: production-safe build checklist and fixes.

Key files: docs/agent/llms-full.txt sections 6 and 17.

6. Use A Different Backend

Connect this GECX Chat UI to a non-GECX backend.
Implement a `ChatTransport` adapter or use a transport recipe.
Keep secrets server-side and preserve SDK `TransportEvent` ordering.
Add a contract test for the transport.

Expected outcome: backend-agnostic adapter.

Key files: docs/agent/llms-full.txt sections 7-8, recipes/transport-*/.

Product Engineer Prompts

7. Add A Custom Renderer

Add a typed custom message-part renderer to this `gecx-chat` app.
Register it through `createRendererRegistry`, keep unknown payloads inert, and add a focused renderer test.

Expected outcome: registry-backed renderer.

Key files: packages/gecx-chat/src/react/RendererRegistry.ts, docs/agent/llms-full.txt section 5.

8. Implement Approval Flow

Implement approval UI for state-changing GECX Chat tools.
Show approve, deny, pending, running, success, and failure states.
Use tool call IDs correctly and fail closed when denied or unknown.

Expected outcome: safe approval flow.

Key files: packages/gecx-chat/src/tools/approval.ts, recipes/tool-call-cards/.

9. Add File Uploads

Add file upload to this chat.
Use `chat.attachFile(file)`, validation, upload progress, cancellation, and safe error states.
Test accepted files, rejected MIME types, oversized files, and aborts.

Expected outcome: validated upload path.

Key files: packages/gecx-chat/src/upload/, docs/agent/llms-full.txt section 9.

10. Custom Transport Adapter

Implement a custom `ChatTransport` for this backend.
Map backend responses to ordered GECX `TransportEvent`s, support cancellation where possible, and add contract tests.

Expected outcome: reusable transport implementation.

Key files: packages/gecx-chat/src/transport/, docs/agent/llms-full.txt section 7.

11. Add Handoff To Live Agent

Add live-agent handoff UI to this GECX Chat experience.
Represent requested, queued, connected, failed, and ended states.
Use mock handoff scenarios for local proof.

Expected outcome: complete handoff lifecycle.

Key files: packages/gecx-chat/src/handoff/, docs/agent/llms-full.txt section 10.

12. Extend The State Machine

Extend the chat state machine for the requested session behavior.
Keep transitions explicit, add tests for invalid transitions, and preserve existing public API names.

Expected outcome: tested state behavior.

Key files: packages/gecx-chat/src/core/stateMachine.ts, packages/gecx-chat/test/stateMachine.test.ts.

13. Add Telemetry

Add telemetry hooks for this GECX Chat flow.
Record high-level state, tool, transport, and error events while redacting tokens and sensitive message content.
Add redaction tests.

Expected outcome: safe trace/debug events.

Key files: packages/gecx-chat/src/telemetry/, docs/agent/llms-full.txt sections 12-13.

14. Production Hardening

Harden this GECX Chat app for production.
Check server token route, proxy route, browser secret exposure, retry/error behavior, upload limits, renderer safety, accessibility, tests, and build.
Report exact commands run.

Expected outcome: production readiness pass.

Key files: docs/agent/llms-full.txt section 17, docs/concepts/auth-and-security.md.

Debugging Prompts

15. Why Is Auth Failing?

Diagnose this GECX Chat auth failure.
Inspect `/api/gecx-chat-token`, `tokenEndpointAuth`, allowed origins, token TTL, response shape, and redacted debug bundle timestamps.
Do not log token values.

Expected outcome: specific auth fix.

Key files: docs/reference/error-codes.md, docs/agent/llms-full.txt section 6.

16. Stream Keeps Dropping

Diagnose an interrupted GECX Chat stream.
Check proxy buffering, event ordering, abort signals, retry behavior, and browser/server logs with secrets redacted.
Use the slow-streaming mock scenario to reproduce UI behavior.

Expected outcome: stream reliability fix.

Key files: docs/reference/transport-events.md, docs/agent/llms-full.txt section 8.

17. Tool Not Executing

Diagnose why a GECX Chat tool is not executing.
Verify tool registration, name match, JSON Schema, approval handler, unknown-tool failure, and `ctx.signal` propagation.
Add a regression test.

Expected outcome: registered and tested tool path.

Key files: packages/gecx-chat/src/tools/, packages/gecx-chat/test/toolRegistry.test.ts.

18. Session Expired Unexpectedly

Diagnose unexpected session expiry in a GECX Chat app.
Inspect storage namespace, token TTL, reconnect behavior, state machine transitions, and debug bundle timing.
Add a recovery or error-state test.

Expected outcome: clear expiry handling.

Key files: packages/gecx-chat/src/core/ChatSession.ts, packages/gecx-chat/src/storage/.

19. Generate A Debug Bundle

Generate and inspect a GECX Chat debug bundle.
Confirm tokens, credentials, private keys, and sensitive content are redacted.
Capture trace events and error codes needed to reproduce the issue.

Expected outcome: safe support artifact.

Key files: packages/gecx-chat/src/telemetry/debugBundle.ts.

20. Run The Chat Doctor

Run GECX Chat diagnostics on this integration.
Use `gecx doctor` and, if MCP is available, `gecx_validate` and `gecx_diagnose`.
Fix browser secrets, legacy widget usage, unsafe HTML, index keys, missing tool schemas, and missing `ctx.signal`.

Expected outcome: actionable diagnostic report.

Key files: packages/gecx-chat-mcp-server/src/tools.ts, docs/agent/llms.txt.

21. Add A2UI Generative UI

Add an A2UI v0.9 generative UI flow to this GECX Chat app.
Use `rich.payload` with `payloadType: 'a2ui.frame'`.
Normalize frames into `a2ui-surface` parts; do not execute custom payloads as code.
Render through `gecx-chat/a2ui/react` with explicit catalogs from `@a2ui/react/v0_9`.
Keep action routing host-defined and policy-gated.
Redact A2UI frames, actions, and data model snapshots in debug output.
Add tests for frame normalization, renderer catalog rejection, and the demo action path.
Run `pnpm typecheck`, `pnpm test`, and the relevant Playwright route.

Expected outcome: typed generated UI with safe action routing.

Key files: packages/gecx-chat/src/a2ui/, packages/gecx-chat/src/react/a2ui/, docs/guides/generative-ui.md.

22. Install An A2UI Catalog Component

Install an A2UI catalog component into this app to handle a common moment.
Look at the 20 available components in `a2ui-catalog/` first; pick one that fits, or report none if no entry matches.
Run `gecx add ui:<name> --out ./src/a2ui/components/<name>`.
Wire `catalogManifestLookup` and `onCatalogTelemetry` into `createA2UIRenderer`.
Run `gecx ui:doctor` to confirm integrity (`ok` for every component).
Add a Playwright spec under `tests/<name>.spec.ts` tagged `@a2ui-catalog` that exercises one action envelope and captures a screenshot baseline.

Expected outcome: a vetted A2UI moment with integrity guarantees and analytics events.

Key files: a2ui-catalog/<name>/manifest.json, packages/gecx-chat/src/a2ui/catalog/, docs/concepts/a2ui-catalog.md, docs/guides/contributing-ui-catalog.md.

23. Add Long-Term Memory

Add long-term memory to this app so the assistant remembers user facts across sessions.
Configure `ChatClientConfig.memory` with `createLocalMemoryAdapter` (prototype) or `createHybridMemoryAdapter` (production).
Default the read mode to `inject` for low latency and the write path to tool-call.
In the React surface, mount `<MemoryList />` so the user can audit and edit what is remembered.
Do not break sends on memory errors — the interceptor must catch silently.
Add tests for inject mode, tool-call write, and the consent kill switch.

Expected outcome: opt-in long-term memory with a visible audit surface.

Key files: packages/gecx-chat/src/memory/, packages/gecx-chat/src/react/memory/, docs/guides/memory.md, docs/reference/memory.md.

24. Enable Voice

Enable voice on this `ChatClient`. Use the one-line config.
Set `voice: 'auto'` in `ChatClientConfig`. In React, render `<VoiceToggle voice={chat.voice} />`.
`chat.voice` is a lazy getter — do not eagerly read it; the toggle's mount triggers provider construction.
For production, configure an explicit `VoiceConfig` with `createGeminiLiveProvider({ tokenEndpoint: '/api/chat/voice-token' })` and wire the proxy `voice-token` route.
Show `firstAudioMs` in the UI to verify <400 ms target.
Add tests for the lazy-getter invariant (provider is not constructed until session.voice is read) and the permission-denied UX.

Expected outcome: working voice without microphone access until the user clicks.

Key files: packages/gecx-chat/src/voice/, packages/gecx-chat/src/react/voice/, apps/proxy-reference/src/server.ts (handleVoiceToken), docs/guides/voice-integration.md.

25. Wire Sentiment + Intent Escalation

Wire sentiment-driven escalation to a human agent.
Configure `signals: { adapters: [ruleAdapter({ patterns: defaultRulePatterns })], escalation: [{ id, signal: 'sentiment', match: { category: 'frustration' }, operator: '>', threshold: 0.7, windowTurns: 2, cooldownMs: 60000 }] }`.
Verify the rule calls into the existing `HandoffController.requestTransfer()` — do not introduce a new handoff path.
In React, render `useSentiment(messages)` as a sentiment meter and `useIntent(messages)` as an intent badge.
Override the `sentiment-signal` renderer to be visible (default is `sr-only`).
Add tests for the rule firing past threshold, the cooldown preventing double-fires, and the escalation surfacing an `AgentTransferPart`.

Expected outcome: a proactive, observable escalation path with sentiment-aware UI.

Key files: packages/gecx-chat/src/signals/, packages/gecx-chat/src/react/useSignals.ts, docs/guides/sentiment-and-intent.md.

26. Scaffold An Agent Graph

Split this app's monolithic system prompt into routed specialists using `agentGraph`.
For each specialist domain (e.g. returns, billing, order), call `defineSpecialist({ id, description, client: createA2AAgentClient({ agentCardUrl }) })`.
Define a `defineRouter({ id, intent, routes })` over the specialists. Use `createHeuristicIntentClassifier` with regex rules for v1; swap to `createLLMIntentClassifier` later if accuracy demands it.
Wrap the host transport with `createAgentGraphTransport({ graph, fallback: <existing transport> })`. ChatSession must remain unchanged.
For testing, use `createMockA2AClient` so specialists do not need to be live.
Add an inspector view that subscribes to the analytics stream and highlights the active node.
Add tests for routing accuracy, max-depth enforcement, and the `bot_to_human` fallback to `HandoffController`.

Expected outcome: a typed, observable specialist routing layer with no ChatSession changes.

Key files: packages/gecx-chat/src/agents/, docs/guides/agent-graph.md, docs/concepts/agents.md.

27. Add A Computer-Use Moment

Add a bounded computer-use moment to this app.
Confirm with the user that the moment is bounded (one or two hostnames, clear success criterion) and that they have read the threat model in `docs/reference/computer-use-threat-model.md`.
On the SDK side, set `governance.computerUse = { enabled: true, allowlist: ['exact.hostname.example.com'], maxDurationMs: 5*60_000, maxActionsPerSession: 30, highRiskActions: ['submit_form', 'download', 'navigate_external'], killSwitch: false }` and add `computerUseTool({ endpoint: '/chat/tool-call', policy: { ... } })` to the tools list.
On the proxy side, mount `createComputerUseHandler({ provider, policy, audit })`. Use `MockProvider` for local dev and `BrowserbaseProvider` for prod.
Render `<ComputerUseSurface>` in the React tree.
Add tests for the consent → stream → high-risk approval → completion happy path, allowlist violation, and user abort.
Never re-enable computer-use silently or widen the SDK-side allowlist to bypass the proxy.

Expected outcome: a default-off computer-use flow with three independent enforcement layers.

Key files: packages/gecx-chat/src/tools/computerUse.ts, packages/gecx-chat/src/server/computerUse/, apps/proxy-reference/src/computerUse/, docs/guides/computer-use.md.

28. Write An Eval Scenario

Write an eval scenario that gates a quality property in CI.
Pick the format that fits the team: `.scenario.ts` for type-safety, `.scenario.yaml` for non-engineer review.
Express the property as scorers — `tool-called`, `tool-call-accuracy`, `message-contains`, `latency-p95-under`, `no-handoff`, `error-code`, or one of the LLM-judge scorers (hallucination, helpfulness, tone).
Add the scenario to the directory listed in `pnpm eval:showcase` (or your equivalent).
Update the baseline file by running `pnpm gecx eval <dir>` once and committing the resulting `*.eval.json`.
In CI, run `pnpm gecx eval <dir> --baseline <baseline> --fail-on-regress`.

Expected outcome: a committed scenario plus baseline that blocks PRs on regression.

Key files: apps/showcase/scenarios/, apps/showcase/baseline.eval.json, docs/guides/evaluation.md, docs/reference/eval-cli.md.

29. Embed Pre-Built Dashboards

Embed the SDK's pre-built dashboards in this app.
Install recharts as a peer dependency.
Render `<MetricsDashboard events={events} />` from `gecx-chat/dashboards`, or compose individual widgets — `<DeflectionTrend>`, `<CsatDistribution>`, `<AhtHistogram>`, `<AgentAssistRate>`, `<GmvBreakdown>`.
Source events from the local `ProductAnalyticsCollector` for a live dashboard, or from a server-side fetch for a historical dashboard.
For a backend, use `apps/dashboard-reference` (self-hostable) or pipe `httpSink` at your existing warehouse.
Add `chat.trackPurchase({ orderId, revenue, currency })` at the order-confirmation point so `<GmvBreakdown>` has data.

Expected outcome: the five canonical metrics rendered without writing chart code.

Key files: packages/gecx-chat/src/analytics/, apps/dashboard-reference/, docs/guides/analytics.md, docs/guides/hosted-dashboard.md.

30. Configure Cross-Platform Permissions

Configure cross-platform device permissions for this app.
For web, the default `createBrowserPermissionProvider()` is fine — `client.permissions` is always present.
For React Native / Expo, plug in the Expo provider following the skeleton in `docs/reference/permission-providers.md`.
For Capacitor, plug in the Capacitor provider following the same skeleton.
In the UI, render `<PermissionPrompt capability="microphone" onGranted={...} />` and rely on `usePermission('microphone').status` for fine-grained UX.
Insecure context returns `{ status: 'unsupported', reason: 'insecure_context' }` — render setup guidance, not a re-prompt.
Add tests against `createMockPermissionProvider` for granted, denied, dismissed, and insecure-context paths.

Expected outcome: a single permissions surface that works on web today and ports to native runtimes.

Key files: packages/gecx-chat/src/permissions/, packages/gecx-chat/src/react/permissions/, docs/concepts/permissions.md, docs/reference/permission-providers.md.