### Core Impeccable Workflow

Source: https://github.com/pbakaus/impeccable/blob/main/site/content/tutorials/getting-started.md

The essential sequence to get started: install, initialize context, and polish a page.

```bash
npx impeccable install
/impeccable init
/impeccable polish the page you care about
```

--------------------------------

### Empty State Example

Source: https://github.com/pbakaus/impeccable/blob/main/plugin/skills/impeccable/reference/onboard.md

Illustrates how to use empty states to guide users towards creating their first item. Provides context and a clear call to action.

```markdown
No projects yet
Projects help you organize your work and collaborate with your team.
[Create your first project] or [Start from template]
```

--------------------------------

### Start Local Bun Server

Source: https://github.com/pbakaus/impeccable/blob/main/AGENTS.md

Starts the local development server using Bun. Use this for active development.

```bash
bun run dev
```

--------------------------------

### Install Impeccable CLI

Source: https://github.com/pbakaus/impeccable/blob/main/README.md

Run this command from your project root to install the Impeccable CLI. After installation, run `/impeccable init` within your AI coding tool.

```bash
npx impeccable install
```

--------------------------------

### Start Impeccable Browser Overlay Server

Source: https://github.com/pbakaus/impeccable/blob/main/CLAUDE.md

Starts the browser overlay server for live detection. Ensure you have the necessary browser extensions or configurations.

```bash
npx impeccable live                              # start browser overlay server
```

--------------------------------

### Run Live Helper Commands with Codex

Source: https://github.com/pbakaus/impeccable/blob/main/skill/reference/live.md

When using Codex, run live helper commands, the app dev server, and any dependency-installing setup with `sandbox_permissions: "require_escalated"` from the start. Live mode requires localhost and package-manager network access, which the sandbox normally blocks.

```yaml
<codex>
Codex: run live helper commands, the app dev server, and any dependency-installing setup with `sandbox_permissions: "require_escalated"` from the start; live mode depends on localhost and package-manager network access that the sandbox blocks.
</codex>
```

--------------------------------

### Project Foundation: Framework Detection

Source: https://github.com/pbakaus/impeccable/blob/main/plugin/skills/impeccable/reference/craft.md

When starting a new project (greenfield), determine the appropriate framework by checking for existing configuration files. If a framework is detected, use it instead of introducing a new one. This snippet shows example checks for common frameworks.

```bash
ls
# Check for:
# - astro.config.mjs/ts
# - next.config.js/ts
# - nuxt.config.ts
# - svelte.config.js
# - vite.config.js/ts
# - package.json with framework deps
# - Cargo.toml + Leptos/Yew
# - Gemfile + Rails
```

--------------------------------

### Skip Hook Setup During Install/Update

Source: https://github.com/pbakaus/impeccable/blob/main/site/content/reference/hooks.md

When running installer or updater commands, use these flags to temporarily skip the hook setup process for a single run.

```bash
npx impeccable install --no-hooks
```

```bash
npx impeccable update --no-hooks
```

--------------------------------

### Install and Update Impeccable

Source: https://github.com/pbakaus/impeccable/blob/main/README.md

Standard commands to install or update the Impeccable tool. These commands also handle the setup of provider-native hook manifests.

```bash
npx impeccable install
npx impeccable update
```

--------------------------------

### Example Impeccable Optimize Output

Source: https://github.com/pbakaus/impeccable/blob/main/site/content/skills/optimize.md

This example shows the expected output format after running an optimization. It details improvements in LCP, INP, CLS, and bundle size, along with specific changes made.

```text
LCP: 3.2s → 1.4s
  - Hero image preloaded (-800ms)
  - Removed render-blocking font stylesheet (-240ms)
  - Deferred analytics script (-180ms)

INP: 240ms → 90ms
  - Debounced scroll handler
  - Memoized expensive list render
  - Removed synchronous layout read in event loop

CLS: 0.18 → 0.02
  - Set dimensions on hero image and logo
  - Reserved space for async header badge

Bundle: 340KB → 180KB
  - Removed unused lodash import (52KB)
  - Code-split the playground route (78KB)
  - Dropped deprecated icon set (30KB)
```

--------------------------------

### Run Local Preview

Source: https://github.com/pbakaus/impeccable/blob/main/CLAUDE.md

Builds the project and starts a local preview using Cloudflare Pages.

```bash
bun run preview    # Build + Cloudflare Pages local preview
```

--------------------------------

### Start Impeccable Live Mode

Source: https://github.com/pbakaus/impeccable/blob/main/plugin/skills/impeccable/reference/live.md

Execute this script to start Impeccable's live mode. It outputs a JSON object containing status, server details, and file information. The server port and token are for the Impeccable live helper server, not the main dev server.

```bash
node .claude/skills/impeccable/scripts/live.mjs
```

--------------------------------

### Configuration Drift Example

Source: https://github.com/pbakaus/impeccable/blob/main/plugin/skills/impeccable/reference/live.md

An example of the JSON output when configuration drift is detected, indicating HTML files exist that are not included in the project's configuration.

```json
{
  "ok": true,
  "serverPort": 8400,
  "pageFiles": [ "..." ],
  "configDrift": {
    "orphans": ["public/new-section/index.html", "public/docs/new-command.html"],
    "orphanCount": 2,
    "hint": "2 HTML file(s) exist but aren't in config.files. Consider adding them, or use a glob pattern like \"public/**/*.html\""
  }
}
```

--------------------------------

### Live Server Configuration Drift Example

Source: https://github.com/pbakaus/impeccable/blob/main/skill/reference/live.md

An example of the JSON output when the live server detects HTML files in the project that are not included in the configuration's `files` list.

```json
{
  "ok": true,
  "serverPort": 8400,
  "pageFiles": [ "..." ],
  "configDrift": {
    "orphans": ["public/new-section/index.html", "public/docs/new-command.html"],
    "orphanCount": 2,
    "hint": "2 HTML file(s) exist but aren't in config.files. Consider adding them, or use a glob pattern like \"public/**/*.html\"."
  }
}
```

--------------------------------

### Install Impeccable Skills

Source: https://github.com/pbakaus/impeccable/blob/main/README.npm.md

Installs the AI harness skills for various providers. Use -y for non-interactive installation.

```bash
npx impeccable skills install
```

```bash
npx impeccable skills install -y --providers=claude,codex --scope=project
```

--------------------------------

### Install Impeccable via General Skills Add

Source: https://github.com/pbakaus/impeccable/blob/main/site/content/tutorials/getting-started.md

A general-purpose command to add Impeccable, installing a shared build for all harnesses.

```bash
npx skills add pbakaus/impeccable
```

--------------------------------

### Install Impeccable Skills

Source: https://github.com/pbakaus/impeccable/blob/main/CLAUDE.md

Installs available skills for the Impeccable CLI. This command fetches and sets up new or updated skill definitions.

```bash
npx impeccable skills install                    # install skills
```

--------------------------------

### Build Project Commands

Source: https://github.com/pbakaus/impeccable/blob/main/docs/DEVELOP.md

Commands to build, clean, or rebuild the project. Ensure Bun is installed as a prerequisite.

```bash
# Build all provider formats
bun run build

# Clean dist folder
bun run clean

# Rebuild from scratch
bun run rebuild
```

--------------------------------

### Install Impeccable Plugin for Claude Code

Source: https://github.com/pbakaus/impeccable/blob/main/site/content/tutorials/getting-started.md

Alternative installation method for Claude Code users via the plugin marketplace.

```bash
/plugin marketplace add pbakaus/impeccable
```

--------------------------------

### Run Development Server

Source: https://github.com/pbakaus/impeccable/blob/main/CLAUDE.md

Starts the Bun development server for local development. Requires a server restart for changes in specific directories.

```bash
bun run dev        # Bun dev server at http://localhost:4321
```

--------------------------------

### Start Impeccable Live Mode

Source: https://github.com/pbakaus/impeccable/blob/main/site/content/skills/live.md

Initiates live mode for iterative design. Use this command in your terminal to begin.

```bash
/impeccable live
```

--------------------------------

### Encouraging Empty State Copy Examples

Source: https://github.com/pbakaus/impeccable/blob/main/plugin/skills/impeccable/reference/delight.md

Offers examples of encouraging copy for empty states, aiming to motivate users and align with a positive brand tone.

```text
"No projects"
"Your canvas awaits. Create something amazing."

"No messages"
"Inbox zero! You're crushing it today."
```

--------------------------------

### Optional Runtime Steer Configuration

Source: https://github.com/pbakaus/impeccable/blob/main/tests/framework-fixtures/README.md

Provides an example of the optional `runtime.steer` configuration block for fine-tuning steer smoke tests.

```json
{
  "steer": {
    "message": "steer-e2e mark hero",
    "sourceFile": "src/routes/About.jsx",
    "expectSelector": "h1.hero-title[data-impeccable-steer=\"e2e\"]",
    "expectSourceContains": "data-impeccable-steer=\"e2e\"",
    "preActions": [{ "type": "click", "selector": "[data-testid='nav-about']" }]
  }
}

```

--------------------------------

### Browser Visualization Setup

Source: https://github.com/pbakaus/impeccable/blob/main/skill/reference/critique.md

Steps for setting up browser visualization, including preflight checks, live server startup, and script injection. Avoid 'file://' URLs; use localhost for local files.

```bash
node {{scripts_path}}/live-server.mjs --background
```

--------------------------------

### Install Playwright Browsers

Source: https://github.com/pbakaus/impeccable/blob/main/CLAUDE.md

Installs the necessary Chromium browser for Playwright, which is required for the live-mode E2E tests. This is a one-time setup step.

```bash
npx playwright install chromium
```

--------------------------------

### Execute Live Mode Steps in Order

Source: https://github.com/pbakaus/impeccable/blob/main/skill/reference/live.md

Follow these steps sequentially for live mode execution. This includes booting the live script, opening the app URL, and entering a polling loop for events.

```bash
1. `live.mjs`: boot. If the request names or implies a file, route, or app inside a monorepo, infer the concrete path and run `node {{scripts_path}}/live.mjs --target <path>` instead; then run the rest of this live session from the returned `projectRoot`.
2. Open the app URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). Never use `serverPort`; it's the helper, not the app. **Cursor:** `browser_navigate` to that URL before polling; do not skip. **Other harnesses:** use the available browser tool; if the URL is uncertain, ask the user once.
3. Poll loop with the default long timeout (600000 ms). After every event or `--reply`, run `live-poll.mjs` again immediately. Never pass a short `--timeout=`.
```

--------------------------------

### Install Skills Without Hooks

Source: https://github.com/pbakaus/impeccable/blob/main/README.npm.md

Installs or updates skills without using hook manifests.

```bash
npx impeccable skills install --no-hooks
```

--------------------------------

### Start Live Server for Browser Visualization

Source: https://github.com/pbakaus/impeccable/blob/main/plugin/skills/impeccable/reference/critique.md

Initiates a background live server for browser-based evidence collection. This is used when browser automation is available and local files need to be served via localhost.

```bash
node .claude/skills/impeccable/scripts/live-server.mjs --background
```

--------------------------------

### Prepare for Shipping with Polish Command

Source: https://github.com/pbakaus/impeccable/blob/main/README.md

Use the `polish` command for a final pass on your design, ensuring alignment with the design system and readiness for shipping. This example targets the settings section.

```bash
/impeccable polish settings
```

--------------------------------

### Build System Commands

Source: https://github.com/pbakaus/impeccable/blob/main/CLAUDE.md

Commands for building the project's site output. Use `build:release` or `rebuild:release` to sync root harness directories.

```bash
bun run build            # Build dist/site output without syncing root harness dirs
```

```bash
bun run build:release    # Build dist/site output and sync root harness dirs + plugin/
```

```bash
bun run rebuild          # Clean and rebuild without root harness sync
```

```bash
bun run rebuild:release  # Clean and rebuild with root harness sync
```

--------------------------------

### Copy Impeccable for Codex CLI

Source: https://github.com/pbakaus/impeccable/blob/main/README.md

Manually copy Impeccable skills for Codex CLI. Supports project-local installation and user-wide skill installation.

```bash
# Project-local
cp -r dist/agents/.agents your-project/
mkdir -p your-project/.codex
cp dist/codex/.codex/hooks.json your-project/.codex/hooks.json

# Or install the skill user-wide. Copy .codex/hooks.json into each project
# where you want the design hook to run.
mkdir -p ~/.agents/skills
cp -r dist/agents/.agents/skills/* ~/.agents/skills/
```

--------------------------------

### Generate Design Context Files

Source: https://github.com/pbakaus/impeccable/blob/main/site/content/reference/context.md

After initialization, run this command to generate the DESIGN.md file and a helper JSON file. Review and edit these markdown files to match your product's design.

```text
/impeccable document
```

--------------------------------

### Playful Error Message Examples

Source: https://github.com/pbakaus/impeccable/blob/main/plugin/skills/impeccable/reference/delight.md

Provides examples of playful copy for error messages, designed to soften frustration and align with a whimsical brand personality.

```text
"Error 404"
"This page is playing hide and seek. (And winning)"

"Connection failed"
"Looks like the internet took a coffee break. Want to retry?"
```

--------------------------------

### Playful Label and Tooltip Examples

Source: https://github.com/pbakaus/impeccable/blob/main/plugin/skills/impeccable/reference/delight.md

Demonstrates how to inject personality into labels and tooltips, using examples like 'Send to void' for delete actions and 'Rescue me' for help.

```text
"Delete"
"Send to void" (for playful brand)

"Help"
"Rescue me" (tooltip)
```

--------------------------------

### Run /impeccable onboard command

Source: https://github.com/pbakaus/impeccable/blob/main/site/content/skills/onboard.md

Use this command to initiate the onboarding design process for a specific feature or area, such as 'the editor'.

```bash
/impeccable onboard the editor
```

--------------------------------

### Example CSP Patch for append-string

Source: https://github.com/pbakaus/impeccable/blob/main/plugin/skills/impeccable/reference/live.md

Illustrates how to interpolate the dev-only allowance string into an existing CSP value string for 'script-src' and 'connect-src' directives. This example assumes the CSP is already a template literal.

```typescript
// script-src 'self' 'unsafe-inline' → `` `script-src 'self' 'unsafe-inline'${__impeccableLiveDev}` ``
// connect-src 'self' → `` `connect-src 'self'${__impeccableLiveDev}` ``
```

--------------------------------

### Initialize Impeccable

Source: https://github.com/pbakaus/impeccable/blob/main/README.npm.md

Runs the first command within your AI harness to initialize Impeccable.

```bash
/impeccable init
```

--------------------------------

### Add New Provider Placeholder Configuration

Source: https://github.com/pbakaus/impeccable/blob/main/docs/DEVELOP.md

Example of adding a new provider's placeholder configuration to `scripts/lib/utils.js`. This defines model, config file, and command prefix for the new provider.

```javascript
'my-provider': {
  model: 'MyModel',
  config_file: 'CONFIG.md',
  ask_instruction: 'ask the user directly to clarify.',
  command_prefix: '/'
}
```

--------------------------------

### Project Foundation: Greenfield Framework Prompt

Source: https://github.com/pbakaus/impeccable/blob/main/plugin/skills/impeccable/reference/craft.md

For greenfield projects without an existing framework, prompt the user to select a framework. This example provides sensible defaults based on the brief.

```text
What should this be built on?
  - Astro (default for content-led brand sites, landing pages, marketing surfaces)
  - SvelteKit / Next.js / Nuxt (when the brief implies an app surface or significant interactivity)
  - Single index.html (one-shot demo, prototype, or a deliberately framework-free experiment)
```

--------------------------------

### Update Impeccable Skills

Source: https://github.com/pbakaus/impeccable/blob/main/README.npm.md

Updates installed skills to the latest version.

```bash
npx impeccable skills update
```

--------------------------------

### Update Impeccable CLI

Source: https://github.com/pbakaus/impeccable/blob/main/README.md

Refresh an existing Impeccable installation using the update command.

```bash
npx impeccable update
```

--------------------------------

### Start Impeccable Live Script

Source: https://github.com/pbakaus/impeccable/blob/main/skill/reference/live.md

Execute the live script to initiate the live development server. This script injects live-reload functionality into specified HTML entries.

```bash
node {{scripts_path}}/live.mjs
```