[codex] Add Codex plugin source package

.gitignore

@@ -8,3 +8,4 @@ site/dist/
 .playwright-cli/
 .worktrees/
 output/
+packages/codex-plugin/dist/

package.json

@@ -13,6 +13,9 @@
   },
   "scripts": {
     "benchmark": "node evals/benchmark.mjs",
+    "codex-plugin:build": "node scripts/build-codex-plugin.mjs",
+    "codex-plugin:check": "node scripts/verify-codex-plugin.mjs",
+    "codex-plugin:sync:local": "node scripts/sync-codex-plugin.mjs",
     "capture:model-ui": "node scripts/capture-model-ui-matrix.mjs",
     "capture:model-ui:screenshots": "node scripts/capture-model-ui-screenshots.mjs",
     "demo:comparison": "node scripts/demo-comparison.mjs",
@@ -36,7 +39,7 @@
     "site:serve": "node scripts/site-local-server.mjs",
     "smoke:icons": "node scripts/lucide-icon-catalog-smoke.mjs",
     "smoke:openai-ui-workflow": "node scripts/smoke-openai-ui-workflow.mjs",
-    "test": "node tests/lucide-icon-catalog.test.mjs && node tests/lucide-icon-catalog-smoke.test.mjs && node tests/kernel-contract.test.mjs && node tests/analyze-implementation-brief.test.mjs && node tests/activity-model-review.test.mjs && node tests/surface-types.test.mjs && node tests/ui-generation-handoff.test.mjs && node tests/cognitive-dimensions-review.test.mjs && node tests/openai-responses-provider.test.mjs && node tests/cli.test.mjs && node tests/demo-one-shot.test.mjs && node tests/demo-modal-actions.test.mjs && node tests/demo-comparison.test.mjs && node tests/demo-music-comparison.test.mjs && node tests/demo-model-ui-matrix.test.mjs && node tests/ui-generation-evals.test.mjs && node tests/mcp-pilot-evals.test.mjs && node tests/mcp-pilot-llm-judge.test.mjs && node tests/eval-rerun-guardrails.test.mjs && node tests/mcp.test.mjs && node tests/mcp-stdio.test.mjs && node tests/mcp-http.test.mjs && node tests/install-mcp.test.mjs && node tests/ai-native-design-system-release.test.mjs && node tests/er-flow-dashboard.test.mjs && node tests/site.test.mjs && node tests/site-local-server.test.mjs && node tests/skills.test.mjs && node evals/run-evals.mjs"
+    "test": "node tests/lucide-icon-catalog.test.mjs && node tests/lucide-icon-catalog-smoke.test.mjs && node tests/kernel-contract.test.mjs && node tests/analyze-implementation-brief.test.mjs && node tests/activity-model-review.test.mjs && node tests/surface-types.test.mjs && node tests/ui-generation-handoff.test.mjs && node tests/cognitive-dimensions-review.test.mjs && node tests/openai-responses-provider.test.mjs && node tests/cli.test.mjs && node tests/demo-one-shot.test.mjs && node tests/demo-modal-actions.test.mjs && node tests/demo-comparison.test.mjs && node tests/demo-music-comparison.test.mjs && node tests/demo-model-ui-matrix.test.mjs && node tests/ui-generation-evals.test.mjs && node tests/mcp-pilot-evals.test.mjs && node tests/mcp-pilot-llm-judge.test.mjs && node tests/eval-rerun-guardrails.test.mjs && node tests/mcp.test.mjs && node tests/mcp-stdio.test.mjs && node tests/mcp-http.test.mjs && node tests/install-mcp.test.mjs && node tests/codex-plugin.test.mjs && node tests/ai-native-design-system-release.test.mjs && node tests/er-flow-dashboard.test.mjs && node tests/site.test.mjs && node tests/site-local-server.test.mjs && node tests/skills.test.mjs && node evals/run-evals.mjs"
   },
   "dependencies": {
     "@emotion/cache": "^11.14.0",

packages/codex-plugin/.codex-plugin/plugin.json

@@ -0,0 +1,39 @@
+{
+  "name": "judgmentkit",
+  "version": "0.1.0",
+  "description": "AI UI review and handoff guidance that helps Codex preserve design intent, catch workflow mismatches, and enforce hard design-system acceptance gates.",
+  "author": {
+    "name": "JudgmentKit",
+    "url": "https://judgmentkit.ai"
+  },
+  "homepage": "https://judgmentkit.ai",
+  "repository": "https://github.com/mikeylong/judgmentkit",
+  "keywords": [
+    "ai-ui-review",
+    "design-handoff",
+    "design-system",
+    "figma",
+    "workflow-fit",
+    "ui-critique"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "JudgmentKit",
+    "shortDescription": "AI UI review with hard design-system gates",
+    "longDescription": "JudgmentKit helps product designers and design teams review AI-generated UI before screens are planned, built, or accepted. It turns product briefs, Figma or Adobe handoffs, design-system guidance, and generated screens into clear decisions, states, terminology, workflow checks, implementation evidence, and hard design-system acceptance gates. If generated UI does not pass the active design system, it is a failed candidate, not an artifact. The hosted endpoint is for allowed or sanitized work; use a local or self-hosted JudgmentKit path for confidential briefs, unreleased designs, proprietary design-system details, source code, or customer data.",
+    "developerName": "JudgmentKit",
+    "category": "Productivity",
+    "capabilities": [
+      "Interactive",
+      "Read"
+    ],
+    "websiteURL": "https://judgmentkit.ai",
+    "brandColor": "#255C99",
+    "defaultPrompt": [
+      "Turn this product brief into UI decisions and review criteria.",
+      "Review this sanitized Figma or generated screen for workflow fit and disclosure issues.",
+      "Create hard design-system acceptance criteria for this interface."
+    ]
+  },
+  "mcpServers": "./.mcp.json"
+}

packages/codex-plugin/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "judgmentkit": {
+      "type": "http",
+      "url": "https://judgmentkit.ai/mcp"
+    }
+  }
+}

packages/codex-plugin/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0 - 2026-07-04
+
+- Added versioned source package for the JudgmentKit Codex plugin under `packages/codex-plugin`.
+- Bootstrapped plugin manifest, hosted MCP configuration, hosted MCP skill, and OpenAI agent metadata from the local personal plugin source.
+- Normalized the committed plugin version to base semver `0.1.0` with no Codex cachebuster suffix.
+- Documented the package-local version policy and hosted privacy/local boundary.

packages/codex-plugin/README.md

@@ -0,0 +1,33 @@
+# JudgmentKit Codex Plugin Source
+
+This package is the versioned source for the JudgmentKit Codex plugin. It was bootstrapped from the local personal plugin source, not from an installed Codex cache.
+
+## Version Policy
+
+- `package.json` is the committed plugin version source.
+- `.codex-plugin/plugin.json` mirrors the same base semver version for Codex plugin metadata.
+- Do not commit Codex timestamp or cachebuster suffixes in this source package.
+- Cachebuster versions, if needed, belong only in local sync or install output outside this checked-in package.
+
+Current committed plugin version: `0.1.0`.
+
+## Package Contents
+
+- `package.json`: package metadata and authoritative plugin version.
+- `.codex-plugin/plugin.json`: Codex plugin manifest.
+- `.mcp.json`: hosted JudgmentKit MCP endpoint configuration.
+- `skills/judgmentkit-hosted-mcp/SKILL.md`: agent-facing hosted MCP usage policy and workflow.
+- `skills/judgmentkit-hosted-mcp/agents/openai.yaml`: OpenAI agent metadata for the skill.
+- `CHANGELOG.md`: package-local release history.
+
+## Hosted Privacy Boundary
+
+The included MCP configuration points to `https://judgmentkit.ai/mcp`. Hosted requests leave the local environment and are appropriate only for allowed or sanitized work.
+
+Do not send confidential briefs, unreleased designs, proprietary design-system details, source code, customer data, or internal roadmaps to the hosted endpoint unless the active workspace policy allows it. For that work, use a local checkout, local stdio server, or self-hosted JudgmentKit MCP endpoint instead.
+
+## Source Boundary
+
+Keep this package limited to plugin source files. Do not use it for generated install caches, root project scripts, root tests, repository-wide docs, or installed Codex cache contents.
+
+Build output belongs under `dist/` and is ignored by git. Local personal plugin copies are sync targets, not source.

packages/codex-plugin/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@judgmentkit/codex-plugin",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Versioned source package for the JudgmentKit Codex plugin.",
+  "type": "module",
+  "files": [
+    ".codex-plugin/",
+    ".mcp.json",
+    "skills/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "judgmentkit": {
+    "pluginManifest": "./.codex-plugin/plugin.json",
+    "versionSource": "./package.json"
+  }
+}

packages/codex-plugin/skills/judgmentkit-hosted-mcp/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: judgmentkit-hosted-mcp
+description: Use JudgmentKit when the user explicitly asks or the project opts in to clarify what a UI must support, choose the right surface type, review workflow fit, set disclosure boundaries, enforce design-system acceptance gates, or prepare design-system handoff criteria before product UI is planned, generated, reviewed, or accepted.
+---
+
+# JudgmentKit Hosted MCP
+
+## Overview
+
+Use this skill to help product designers working with Codex clarify the job a product UI must do before screens, components, or styling are chosen. Start from a brief, Figma or Adobe handoff, design mockup, generated screen, or local source context and make the design decision set explicit: participants, outcomes, workflow, surface type, domain language, disclosure boundaries, required states, and evidence needed for handoff or acceptance.
+
+MCP and server details belong only in setup, diagnostics, audit, or integration work. Keep them out of product-facing UI and copy.
+
+## Design-System Acceptance Gate
+
+Treat the active design system as an existential gate for generated UI:
+
+- A generated UI that does not pass the active design system is not an artifact. It is a failed candidate.
+- If no complete external design-system adapter is supplied and intended, the active authority is the internal JudgmentKit design system returned by `create_ui_implementation_contract`.
+- Do not accept, render, publish, summarize as successful, or preserve a generated UI candidate until `review_ui_implementation_candidate` passes against the active implementation contract.
+- Do not repair design-system failures in the renderer or downstream glue code. Send the failed candidate back through JudgmentKit MCP review and use the returned hard constraints and repair instructions.
+- Do not treat "mostly uses tokens", wrapper normalization, fallback styling, visual cleanup, or post-hoc token rewriting as design-system compliance.
+- Reject strict JudgmentKit candidates that carry visual authority outside the active design system, including inline `style` attributes, model-defined visual custom properties, local aliases, literal colors, literal shadows, undeclared token names, external fonts, or unsupported component semantics.
+- Legacy, stale, or previously accepted captures must be re-reviewed against the active implementation contract before they can be used as current artifacts.
+- If the active design-system review fails, the next action is repair or regeneration against the MCP-returned constraints, not acceptance with caveats.
+
+## Privacy Boundary
+
+The hosted endpoint processes the MCP request payload and records sanitized usage events such as event type and tool name. It does not intentionally store submitted briefs, design context, generated code, or review packets, but hosted requests still leave the local environment.
+
+Use sanitized inputs for confidential work. For unreleased designs, proprietary design-system details, source code, customer data, or internal roadmaps, prefer a local checkout, local stdio server, or self-hosted JudgmentKit MCP endpoint instead of `https://judgmentkit.ai/mcp`.
+
+## Policy Check
+
+Before calling MCP tools, check the active user, project, and AGENTS instructions.
+
+- Use JudgmentKit only when the user explicitly asks for it or the current project instructions opt into JudgmentKit for the task.
+- Do not send confidential briefs, unreleased designs, proprietary design-system details, source code, customer data, or internal roadmap context to the hosted endpoint unless workspace policy allows it.
+- When allowed, use JudgmentKit for UI generation, UI critique, implementation planning, workflow review, handoff review, and generated UI acceptance.
+- Do not use JudgmentKit for unrelated backend work, factual answers, docs-only edits, or general code review unless the task depends on UI activity fit.
+- If the activity is setup, debugging, auditing, or integration work, implementation details may be visible. Otherwise, keep prompts, schemas, resource ids, MCP servers, tool names, traces, and model configuration out of product UI.
+- When ranking findings, use `High`, `Medium`, and `Low` labels.
+
+## Default Workflow
+
+1. Read the user's brief and available local source context.
+2. Call `create_activity_model_review` with the source brief.
+3. If the packet needs source context, ask only the targeted blocking questions unless local context answers them.
+4. Call `recommend_surface_types({ brief, activity_review })` before workflow or frontend implementation guidance.
+5. When a model or agent proposes an activity model, call `review_activity_model_candidate` before trusting it.
+6. When a UI workflow is proposed, call `recommend_ui_workflow_profiles` for specialized review fit when useful, then call `review_ui_workflow_candidate`.
+7. Call `review_cognitive_dimensions_candidate` when mapping, visibility, hidden dependencies, premature commitment, progressive evaluation, change cost, mental operations, or disclosure risks matter.
+8. Call `create_ui_implementation_contract`. Use the default JudgmentKit design-system source unless a complete external design-system adapter is available and intended.
+9. Call `create_ui_generation_handoff` with the reviewed workflow and implementation contract before generating UI.
+10. Call `create_frontend_generation_context` when implementation needs project runtime, UI library, approved component families, visual requirements, verification commands, or browser checks.
+11. Call `create_frontend_implementation_skill_context` when the implementing agent needs portable frontend guidance.
+12. After implementation, call `review_ui_implementation_candidate` with the generated code or evidence and the active implementation contract before accepting the result.
+13. If design-system authority fails, stop treating the output as generated UI. Use the MCP review result to issue hard constraints and regenerate or repair before any acceptance step.
+
+Use the MCP response `structuredContent` for follow-up tool calls and implementation decisions. Use `content[0].text` as the concise human-facing planning card.
+
+## Activity Contract
+
+Before suggesting screens, components, or styling, establish:
+
+- activity being supported
+- participants
+- objective and outcomes
+- existing tools and artifacts
+- rules and rituals
+- division of labor
+- domain vocabulary
+- implementation concepts that must stay hidden
+- diagnostics that may be revealed only when useful
+
+Then produce or verify the interaction contract:
+
+- what the user is trying to do
+- how they think about the work
+- primary decisions
+- what should be easy or harder
+- terms to use and avoid
+- state changes that matter to the activity
+- what the user should leave knowing or having done
+
+## Surface Types
+
+Treat surface type as activity-purpose guidance, not visual theme guidance:
+
+- `marketing`: persuade, orient, convert, or explain an offer
+- `workbench`: inspect, compare, decide, and act across work items
+- `operator_review`: review AI- or system-produced work, evidence, risk, and handoff
+- `form_flow`: collect or change structured information with validation
+- `dashboard_monitor`: track status, exceptions, trends, or operational health
+- `content_report`: read, understand, cite, or share information
+- `setup_debug_tool`: configure, inspect, test, or troubleshoot machinery
+- `conversation`: support open-ended exchange where the thread is primary
+
+If two surface types are plausible, choose from the user's completion state before choosing components. For example, a monitor stays a monitor when tickets are downstream drill-in, while an operator review surface is appropriate when a human reviews AI- or system-produced work before it advances.
+
+## Disclosure Rules
+
+Product UI should use domain language and hide implementation machinery unless the user is doing setup, debugging, auditing, integration, or explicit source inspection.
+
+Avoid copying these terms into product UI:
+
+- `ready_for_review`
+- `activity_model`
+- `review_status`
+- `Primary user`
+- `Main decision`
+- prompt template
+- resource id
+- schema
+- tool call
+- MCP server
+- trace
+- model configuration
+
+Translate implementation language into activity language:
+
+- Use `refund request`, not `database table`.
+- Use `handoff reason`, not `tool call result`.
+- Use `policy review`, not `prompt template`.
+
+## Implementation Gate
+
+Generate or accept frontend work only after the activity, target participant, primary decision, outcome, domain language, disclosure boundary, workflow candidate, surface type, and implementation contract are explicit enough for review.
+
+Design-system compliance is mandatory:
+
+- The generated UI must pass the active implementation contract's design-system source.
+- If no external adapter is active, generated UI must use the internal JudgmentKit design-system authority exactly as returned by the contract.
+- A failed design-system check blocks acceptance, publishing, screenshots, examples, release evidence, and handoff completion.
+- Renderer-side cleanup may make failed work easier to inspect, but it must not convert failed work into an accepted artifact.
+
+Require evidence appropriate to the surface:
+
+- approved primitives and required states from the implementation contract
+- static checks
+- desktop and mobile browser QA
+- accessibility evidence for semantics, keyboard navigation, focus order, focus-visible, responsive reflow/no-overflow, and automated checks
+- conditional evidence for meaningful non-text visuals, custom widgets, forms, status messages, overlays, motion, dense controls, hover or focus content, and text over generated or rendered visuals
+
+When substantive visuals are required, use image generation, Three.js/WebGL, or D3-style visualization rather than rudimentary CSS/SVG/JS geometry as the final visual asset.
+
+## Fallback
+
+If the hosted MCP server is unavailable, say that JudgmentKit results could not be created and ask whether to continue with the deterministic activity-first checklist. Do not label checklist output as a JudgmentKit packet.

packages/codex-plugin/skills/judgmentkit-hosted-mcp/agents/openai.yaml

@@ -0,0 +1,13 @@
+interface:
+  display_name: "JudgmentKit Hosted MCP"
+  short_description: "UI workflow review and hard design-system gates"
+  default_prompt: "Use $judgmentkit-hosted-mcp to review this UI brief for workflow fit, surface choice, disclosure boundaries, and the hard design-system acceptance gate. If the generated UI does not pass the active design system, treat it as a failed candidate and send it back through JudgmentKit for hard repair constraints."
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "judgmentkit"
+      description: "Hosted JudgmentKit MCP server"
+      transport: "streamable_http"
+      url: "https://judgmentkit.ai/mcp"
+policy:
+  allow_implicit_invocation: false