artifact-refiner

Artifact Refiner

A PMPO-driven, iterative artifact refinement engine for logos, UI components, content, images, code, meta-prompts, and A2UI specifications. Built as a Claude Code plugin and Agent Skills compliant skill with cross-session state management and multi-agent deployment support.

Quick Start

Use domain-specific slash commands:

/refine-logo     — Logo and brand system refinement
/refine-ui       — React/HTML UI component refinement
/refine-content  — Content/Markdown refinement
/refine-image    — Image artifact refinement
/refine-a2ui     — A2UI specification refinement
/refine-status   — Check current refinement progress
/refine-validate — Run validation checks on current state

Or invoke the general skill with a free-form request describing what you want to refine.

Installation

Via cowork (Recommended)

Install across all supported agents in one command:

cowork install GQAdonis/artifact-refiner-skill

This deploys to up to 15 agents (Claude Code, Cursor, OpenCode, Gemini CLI, Windsurf, Roo Code, etc.).

As a Claude Plugin

claude plugin install artifact-refiner

Per-Agent Installers

Individual installer scripts are available for each supported agent:

# Examples
bash scripts/installers/claude-code/install.sh
bash scripts/installers/cursor/install.sh
bash scripts/installers/opencode/install.sh
bash scripts/installers/gemini-cli/install.sh

See scripts/installers/README.md for the full list of 12 supported agents.

Manual

Clone the repository into your Claude Code plugins directory:

git clone https://github.com/GQAdonis/artifact-refiner-skill.git ~/.claude/plugins/artifact-refiner

e2b Sandbox (Optional)

For sandboxed code execution, set your e2b API key:

export E2B_API_KEY="your-key-here"

The skill works without e2b by falling back to the built-in code_interpreter.

Browser Preview Tooling (Optional, for UI/A2UI)

Install local preview tooling for TSX compilation and browser screenshots:

npm install

This enables:

• node scripts/compile-tsx-preview.mjs (TSX → browser preview bundle)
• node scripts/render-preview.mjs (preview render + screenshot + diagnostics)

Submodules and vendored binaries

This repo consumes two external Rust projects as git submodules:

Submodule	Path	Source	Purpose
rust-mcp-filesystem	tools/rust-mcp-filesystem/	upstream rust-mcp-stack/rust-mcp-filesystem (pinned v0.4.2)	Filesystem MCP server (24 tools) for harnesses without native file access
sycophancy-correction	shared/sycophancy-correction/	Know-Me-Tools/sycophancy-correction-skill (pinned 01150389)	Sycophancy detection/correction skill consumed by the PMPO loop; shared with prometheus-skill-pack

Clone with submodules:

git clone --recurse-submodules https://github.com/GQAdonis/artifact-refiner-skill.git
cd artifact-refiner-skill
bash scripts/setup-submodules.sh

scripts/setup-submodules.sh:

1. Runs git submodule update --init --recursive.
2. Invokes scripts/build-vendored-binaries.sh to install rust-mcp-filesystem (probes PATH → Homebrew tap → cargo-binstall → cargo install from submodule).
3. Prints status for rust-mcp-filesystem, template-forge, and template-forge-mcp binaries.

For the template-forge workspace (deterministic branded-artifact renderer), see tools/template-forge-rs/ and scripts/install-template-forge.sh.

External prerequisites (optional)

Prerequisite	Required?	Purpose	Setup
openai-proxy	optional	Subscription-priced inference for cost-aware routing of mechanical PMPO phases	docs/integrations/openai-proxy.md

When openai-proxy is running and reachable, the refiner can route mechanical phases (refiner-iterate, refiner-finalize) through a ChatGPT Plus/Pro subscription via the proxy's OpenAI-compatible HTTP surface. When it is not running, the refiner falls back to host-harness inference transparently — no hard failure, just a warning in the routing log. Cost routing is a nice-to-have; functional inference is the requirement.

To enable: install + run the proxy per its README, then keep the prefer_endpoint: openai_proxy entries in .kbd-orchestrator/project.json → model_policy. To disable: stop the proxy (the refiner will fall back automatically) or remove the prefer_endpoint overrides.

Pipeline Capabilities

Eleven phases have shipped under the KBD lifecycle. The capabilities below are what those phases delivered. Each cites the file path so you can verify the claim.

Conversion skills

These transform an artifact in one shape into another. All produce phase-2-scaffolder-ready output where applicable.