JudgmentKit

Docs

Quickstart

Install JudgmentKit for your MCP client, then connect to the hosted Streamable HTTP endpoint.

curl -fsSL https://judgmentkit.ai/install | bash
curl -fsSL https://judgmentkit.ai/install | bash -s -- --client claude
curl -fsSL https://judgmentkit.ai/install | bash -s -- --client cursor

Codex is the default client. Use --client codex, --client claude, or --client cursor when scripting.

Planning Mode Examples

Use these examples to review whether an agent is using JudgmentKit well. A good planning response should make the activity, decision, outcome, and disclosure boundary clearer before it proposes UI structure.

Ready brief

Plan a UI for a support lead reviewing refund requests during daily triage. They decide whether each case is approved, sent to policy review, or returned for missing evidence. The outcome is a clear handoff with the next action and reason.

Good response: proceed to concept planning because the activity, participant, decision, and outcome are clear. Keep the plan centered on evidence review, decision options, and handoff.

Accept: approval, policy review, return for evidence, and handoff reasons are easy to compare and complete.

Reject: charts, widgets, or visual polish appear before the refund review work is named.

Vague brief

Plan a dashboard for the system.

Good response: pause instead of inventing a dashboard. Ask only targeted questions about the activity, primary decision or next action, and outcome.

Accept: the agent asks what work the dashboard supports, what decision it should make easier, and what the user should leave knowing or having done.

Reject: a full dashboard plan with metrics, cards, charts, and navigation invented from no source context.

Implementation-heavy brief

Plan an admin UI from our JSON schema, database tables, tool call traces, prompt template, and API endpoints.

Good response: treat schemas, tables, traces, prompts, and endpoints as diagnostic details unless the task is explicitly setup, debugging, auditing, or integration work. Translate toward the user's activity before proposing a primary surface.

Accept: implementation terms move into diagnostics and the agent asks for the domain activity or decision behind the admin surface.

Reject: tables, schemas, prompt templates, tool calls, or API endpoints become the main product UI.

MCP

JudgmentKit supports MCP through the hosted Streamable HTTP endpoint at https://judgmentkit.ai/mcp. The installer registers that endpoint as judgmentkit in Codex, Claude Code, or Cursor. A browser GET to /mcp returns endpoint metadata; MCP clients should connect to the same URL with Streamable HTTP.

MCP tool responses include structuredContent as the stable machine-readable contract and content[0].text as a concise Markdown planning card for Codex-style planning chat. Use the card to explain status, next step, blocking questions, and compact diagnostics; use structured content for implementation decisions and follow-up tool calls.

System Map

Use JudgmentKit before generation and across iterations. It is the contract and review layer around the LLM or agent, not the final UI renderer.

Scroll the page normally. Drag to pan the map; use controls or pinch/ctrl-wheel to zoom.

JudgmentKit system design map A static fallback node and edge diagram showing source context, the MCP boundary, JudgmentKit kernel, optional LLM provider seam, UI rendering outside JudgmentKit, Material UI adapter, blocked path, and iteration with updated context returning to source and activity review. MCP boundary Agent / Client / MCP Codex or agent client Calls tools; owns the turn. Source brief + product context Brief, product facts, current draft findings. MCP server Access and transport only. MCP is not the LLM. tools/list + tools/call JudgmentKit kernel Deterministic review, guardrails, handoff analyze_implementation_brief Extract activity evidence, source gaps, implementation terms, disclosure risks. create_activity_model_review Name activity, participant, objective, decision, outcome, vocabulary. review_activity_model_candidate Review model or agent candidates before trusting them. review_ui_workflow_candidate Check grounding, action support, handoff clarity, leakage containment. recommend_ui_workflow_profiles Optional guidance such as operator-review-ui; not styling. create_ui_generation_handoff Gate: only ready workflow reviews become generation handoffs. Blocked path Resolve targeted questions or leakage before UI generation. LLM / provider seam Optional model assistance Provider adapter OpenAI, local model, or injected caller. Candidate proposal Activity/workflow JSON. Reviewed before use. Outside JudgmentKit UI rendering from reviewed handoff LLM / agent UI pass Generate from reviewed handoff, not raw brief. Renderer choice after reviewed handoff JudgmentKit does not enforce Material UI or any design system. Material UI adapter @mui/material components applied after judgment. without design system Still use the handoff; choose simple UI primitives. UI draft Reviewed by human or agent for next iteration. Iteration loop Draft findings become updated context Review findings updated context MCP tool call needs source context request candidate proposed JSON returns for review reviewed handoff with design system without design system review draft updated context returns to source/activity review

MCP boundary: agents call JudgmentKit tools through MCP; MCP is access and transport, not the LLM.

JudgmentKit kernel: deterministic review, candidate review, disclosure rules, targeted questions, and the handoff gate decide whether UI generation is ready.

LLM / provider seam: a model may propose activity or workflow candidates, but JudgmentKit reviews those candidates before trusting them.

Surface type: recommend_surface_types classifies activity purpose as marketing, workbench, operator review, form flow, dashboard monitor, content/report, setup/debug tool, or conversation before frontend implementation guidance.

UI generation: the LLM or agent generates the interface outside JudgmentKit from the reviewed handoff.

Implementation contract: create_ui_implementation_contract supplies approved primitives, required states, static checks, and browser QA expectations before final handoff. review_ui_implementation_candidate checks generated UI against that contract.

Frontend adapter: create_frontend_generation_context combines a ready handoff, selected surface type, project frontend context, and verification expectations. create_frontend_implementation_skill_context turns that ready context into portable implementation instructions without exposing raw skill files. Design-system compliance is not a substitute for activity fit.

Iteration: draft review produces updated context that re-enters source/activity review rather than becoming only a longer prompt.

Blocked path: if activity, workflow, or handoff is not ready, resolve targeted questions or leakage details before generating UI.

Activity Review

Call create_activity_model_review before generating UI from a brief. Use the returned candidate only when the activity, participant, decision, outcome, and disclosure boundary are clear enough.

Workflow Review

Call review_ui_workflow_candidate before accepting an agent-proposed workflow. It checks source grounding, action support, completion or handoff clarity, and leakage containment.

Surface Type

Call recommend_surface_types after activity review and before workflow or frontend implementation guidance. Surface type is activity-purpose guidance, not a visual theme.

Handoff

Call create_ui_generation_handoff only on a ready workflow review. If the gate blocks, resolve the targeted questions or leakage details first.

Implementation Contract

Call create_ui_implementation_contract before final handoff so generated UI has approved primitives, state coverage, static checks, and browser QA expectations. Call review_ui_implementation_candidate before accepting generated UI code or evidence.

Frontend Context

Call create_frontend_generation_context after the handoff gate when an agent needs frontend implementation guidance with selected surface type, project context, and verification expectations. Call create_frontend_implementation_skill_context when an MCP client needs compiled implementation skill guidance instead of repo-local skill access.

Guidance Profiles

Call recommend_ui_workflow_profiles when a brief sounds like specialized review work. Pass profile_id: "operator-review-ui" only when the recommendation evidence supports it.