cfsa-antigravity 6.0.0 → 6.2.0

package/README.md

@@ -37,6 +37,8 @@ Runtimes are auto-detected from the template. Currently shipped:
 - **Antigravity** (`.agents/`) -- Antigravity, Cursor, Gemini CLI
 - **Codex** (`.codex/`) -- Standalone Codex runtime
 - **Claude Code** (`.claude/`) -- Standalone Claude Code runtime
+- **Copilot** (`.github/`) -- GitHub Copilot (VS Code / Insiders)
+- **Pi** (`.pi/`) -- Standalone Pi Coding Agent runtime
 - **Factory Droid** (`.factory/`) -- Standalone Factory Droid runtime
 
 Each runtime is fully standalone with no cross-references. Install any combination side-by-side.
@@ -111,8 +113,9 @@ Examples:
 1. Antigravity install → keep `.agents/` out of `.gitignore`
 2. Codex install → keep `.codex/` out of `.gitignore`
 3. Claude install → keep `.claude/` out of `.gitignore`
-4. Factory install → keep `.factory/` out of `.gitignore`
-5. Use `.git/info/exclude` for local exclusions instead of changing shared ignore rules
+4. Pi install → keep `.pi/` out of `.gitignore`
+5. Factory install → keep `.factory/` out of `.gitignore`
+6. Use `.git/info/exclude` for local exclusions instead of changing shared ignore rules
    
 ## Get Started
 

package/bin/cli.mjs

@@ -38,6 +38,8 @@ const RUNTIME_DISPLAY = {
     ".agent":   { name: "Antigravity",   desc: "Antigravity, Cursor, Gemini CLI" },
     ".codex":   { name: "Codex",         desc: "Standalone Codex runtime" },
     ".claude":  { name: "Claude Code",   desc: "Standalone Claude Code runtime" },
+    ".pi":      { name: "Pi",            desc: "Standalone Pi Coding Agent runtime" },
+    ".github":  { name: "Copilot",       desc: "GitHub Copilot (VS Code / Insiders)" },
     ".factory": { name: "Factory Droid", desc: "Standalone Factory Droid runtime" },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cfsa-antigravity",
-  "version": "6.0.0",
+  "version": "6.2.0",
   "description": "CFSA Pipeline — Constraint-First Specification Architecture for AI agents. Production-grade from line one.",
   "scripts": {
     "changeset": "changeset",

package/template/.agents/mcp_config.json

@@ -0,0 +1,7 @@
+{
+  "mcpServers": {
+    "context-mode": {
+      "command": "context-mode"
+    }
+  }
+}

package/template/.agents/skills/brand-guidelines/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: brand-guidelines
-description: "Apply the confirmed design direction to all visual surfaces. If `{{DESIGN_DIRECTION}}` still appears as a literal placeholder, the design direction has not been confirmed — run `/create-prd` first."
+description: "Apply the confirmed design direction to all visual surfaces. This skill now bridges the pipeline's placeholder system with the `impeccable` skill's PRODUCT.md and DESIGN.md files. If `{{DESIGN_DIRECTION}}` still appears as a literal placeholder, run `/impeccable teach` to establish design context."
 ---
 
 # {{PROJECT_NAME}} Brand Guidelines
 
-> **Status**: {{#if DESIGN_DIRECTION}}Active{{else}}⚠️ UNFILLED — Run /create-prd to confirm design direction before using this skill{{/if}}
+> **Status**: {{#if DESIGN_DIRECTION}}Active{{else}}⚠️ UNFILLED — Run `/impeccable teach` to establish design direction before using this skill{{/if}}
+>
+> **Bridge mode**: This file now reads from the `impeccable` skill's context files. When `PRODUCT.md` and `DESIGN.md` exist at the project root (written by `/impeccable teach` and `/impeccable document`), values from those files take precedence over the placeholder slots below. Run `node .agents/skills/impeccable/scripts/load-context.mjs` to load the current design context.
 
 ## Design Direction
 
@@ -13,6 +15,8 @@ description: "Apply the confirmed design direction to all visual surfaces. If `{
 - **Rationale**: {{DESIGN_DIRECTION_RATIONALE}}
 - **Primary audience**: {{DESIGN_AUDIENCE}}
 
+> When `PRODUCT.md` exists, extract direction/audience from its Users and Product Purpose sections.
+
 ## Color Palette
 
 | Role | Value | Usage |
@@ -23,6 +27,8 @@ description: "Apply the confirmed design direction to all visual surfaces. If `{
 | Background | {{BACKGROUND_COLOR}} | Page/app background |
 | Text | {{TEXT_COLOR}} | Primary text color |
 
+> When `DESIGN.md` exists, extract colors from its Colors section (OKLCH or hex).
+
 ## Typography
 
 | Role | Font | Usage |
@@ -31,10 +37,14 @@ description: "Apply the confirmed design direction to all visual surfaces. If `{
 | Body | {{BODY_FONT}} | Paragraphs, descriptions, UI labels |
 | Mono | {{MONO_FONT}} | Code blocks, terminal output, technical values |
 
+> When `DESIGN.md` exists, extract fonts from its Typography section.
+
 ## Motion Philosophy
 
 {{MOTION_PHILOSOPHY}}
 
+> When `DESIGN.md` exists, extract motion philosophy from its Motion section.
+
 ## Existing Brand Assets
 
 {{EXISTING_BRAND_ASSETS}}
@@ -42,3 +52,5 @@ description: "Apply the confirmed design direction to all visual surfaces. If `{
 ## What to Avoid
 
 {{DESIGN_AVOID}}
+
+> The `impeccable` skill's anti-pattern rules (27 deterministic + 12 LLM critique) automatically apply. No need to duplicate them here.

package/template/.agents/skills/create-prd/SKILL.md

@@ -5,7 +5,7 @@ pipeline:
   stage: architecture
   predecessors: [ideate]
   successors: [audit-ambiguity, decompose-architecture] # audit-ambiguity recommended before decompose
-  skills: [api-design-principles, brainstorming, brand-guidelines, clean-code, database-schema-design, design-anti-cliche, design-direction, error-handling-patterns, find-skills, logging-best-practices, performance-budgeting, pipeline-rubrics, prd-templates, resolve-ambiguity, security-scanning-security-hardening, tdd-workflow, tech-stack-catalog, technical-writer]
+  skills: [api-design-principles, brainstorming, brand-guidelines, clean-code, database-schema-design, design-anti-cliche, design-direction, error-handling-patterns, find-skills, impeccable, logging-best-practices, performance-budgeting, pipeline-rubrics, prd-templates, resolve-ambiguity, security-scanning-security-hardening, tdd-workflow, tech-stack-catalog, technical-writer]
   calls-bootstrap: true # tech stack decisions trigger skill provisioning
 shards: [create-prd-stack, create-prd-design-system, create-prd-architecture, create-prd-security, create-prd-compile]
 ---

package/template/.agents/skills/create-prd-design-system/SKILL.md

@@ -9,7 +9,7 @@ pipeline:
   stage: architecture
   predecessors: [create-prd-stack]
   successors: [create-prd-architecture]
-  skills: [brand-guidelines, design-anti-cliche, design-direction, prd-templates, technical-writer]
+  skills: [impeccable, brand-guidelines, prd-templates, technical-writer]
   calls-bootstrap: false
 ---
 
@@ -19,15 +19,25 @@ pipeline:
 
 Establish the structural UI architecture — navigation paradigm, layout grid, page archetypes, global component inventory, motion language, data density philosophy, and global state design language. Produces `.memory/wiki/specs/design-system.md` which all FE specs must consume.
 
-**Prerequisite**: Tech stack decisions must be locked (`/create-prd-stack` completed). Design direction must be confirmed in `.agents/skills/brand-guidelines/SKILL.md`.
+**Prerequisite**: Tech stack decisions must be locked (`/create-prd-stack` completed). Design context must exist — run `/impeccable teach` first to establish PRODUCT.md and DESIGN.md, then verify `.agents/skills/brand-guidelines/SKILL.md` has no `{{PLACEHOLDER}}` values.
 
 ---
 
 ## 0. Prerequisite check
 
-1. Read `.agents/skills/brand-guidelines/SKILL.md`.
-2. Scan for any `{{PLACEHOLDER}}` values that are still unfilled. If any exist → **stop** and tell the user: _"Design direction hasn't been confirmed yet. Run `/create-prd-stack` first to establish the design direction before designing the system."_
-3. If all placeholders are filled → extract and store for this session: the confirmed `DESIGN_DIRECTION`, color palette, typography choices, motion philosophy, and anti-patterns.
+### 0.1 Load impeccable context
+
+1. Run `node .agents/skills/impeccable/scripts/load-context.mjs` to load PRODUCT.md and DESIGN.md.
+2. If PRODUCT.md is missing, empty, or placeholder → **stop** and tell the user: _"Design context hasn't been established yet. Run `/impeccable teach` first to define the product's users, brand, tone, and design principles."_
+3. Extract from the context: brand register (brand vs product), design direction, color palette (OKLCH or hex), typography, motion philosophy, spatial principles.
+
+### 0.2 Verify pipeline placeholders
+
+4. Read `.agents/skills/brand-guidelines/SKILL.md`.
+5. Scan for any `{{PLACEHOLDER}}` values that are still unfilled. If any exist → **stop** and tell the user: _"Design direction hasn't been confirmed yet. Run `/create-prd-stack` first to establish the design direction before designing the system."_
+6. If all placeholders are filled → extract and store for this session: the confirmed `DESIGN_DIRECTION`, color palette, typography choices, motion philosophy, and anti-patterns.
+
+### 0.3 Source material
 
 Read `## Engagement Tier` from `.memory/wiki/specs/ideation/ideation-index.md`.
 
@@ -35,7 +45,7 @@ Read the engagement tier protocol (`.agents/skills/prd-templates/references/enga
 
 1. Read `.memory/wiki/specs/ideation/meta/constraints.md` — extract the **Project Surfaces** section. Read `.memory/wiki/specs/ideation/ideation-index.md` — extract the feature inventory from the MoSCoW Summary.
 2. Read `.agents/skills/brand-guidelines/SKILL.md` — extract the confirmed `DESIGN_DIRECTION`.
-3. Read `.agents/skills/design-direction/SKILL.md` — for direction characteristics and anti-patterns.
+Read `.agents/skills/impeccable/SKILL.md` — for the shared design laws (color, typography, motion, spatial) and the full command reference.
 4. Read `.agents/skills/technical-writer/SKILL.md` — for document writing conventions.
 5. Read `.agents/skills/prd-templates/references/design-system-decisions.md` — all decision option menus and the output template for `.memory/wiki/specs/design-system.md`.
 6. Note which surfaces are in scope from `## Project Surfaces`.

package/template/.agents/skills/create-prd-stack/SKILL.md

@@ -9,7 +9,7 @@ pipeline:
   stage: architecture
   predecessors: [ideate]
   successors: [create-prd-design-system]
-  skills: [database-schema-design, design-direction, session-continuity, tech-stack-catalog]
+  skills: [database-schema-design, impeccable, design-direction, session-continuity, tech-stack-catalog]
   calls-bootstrap: true
 ---
 
@@ -116,7 +116,15 @@ Read .agents/skills/database-schema-design/SKILL.md and follow its Persistence M
 
 ### Design Direction
 
-Read `.agents/skills/design-direction/SKILL.md` and follow its interview methodology to determine the project's visual direction. After confirmation, fire bootstrap with `DESIGN_DIRECTION=[confirmed direction]`. **HARD GATE**: Follow the bootstrap verification protocol (`.agents/skills/prd-templates/references/bootstrap-verification-protocol.md`).
+Run `/impeccable teach` to establish the project's design context. This produces `PRODUCT.md` (users, brand, tone, strategic principles) and `DESIGN.md` (colors, typography, components) at the project root.
+
+After `/impeccable teach` completes:
+1. Read the resulting `PRODUCT.md` and `DESIGN.md` files
+2. Extract the confirmed design direction, color palette, typography, and motion philosophy
+3. Fire bootstrap with `DESIGN_DIRECTION=[confirmed direction]`, `PRIMARY_COLOR=[extracted]`, `HEADING_FONT=[extracted]`, etc.
+4. **HARD GATE**: Follow the bootstrap verification protocol (`.agents/skills/prd-templates/references/bootstrap-verification-protocol.md`).
+
+> The legacy `design-direction` SKILL.md now delegates to this flow. The `brand-guidelines` SKILL.md bridges the pipeline's `{{PLACEHOLDER}}` system with `impeccable`'s PRODUCT.md/DESIGN.md — both are kept in sync.
 
 ### Development tooling
 

package/template/.agents/skills/design-anti-cliche/SKILL.md

@@ -1,13 +1,29 @@
 ---
 name: design-anti-cliche
-description: "Universal AI design correction rules. Always active. Prevents the agent from falling into common AI-generated design patterns that produce generic, indistinguishable output. Project-specific brand-guidelines can override any rule here."
+description: "Universal AI design correction rules — SUPERSEDED. The `impeccable` skill now provides 27 deterministic anti-pattern rules plus a 12-rule LLM critique pass, which are more comprehensive and runtime-enforced via the `impeccable` CLI. This file is kept for backward compatibility — the `impeccable` skill's design laws and anti-patterns take precedence."
 ---
 
-# Design Anti-Cliché Rules
+# Design Anti-Cliché Rules — SUPERSEDED by `impeccable`
+
+> **⚠️ This skill is superseded.** The `impeccable` skill's shared design laws, anti-pattern rules, and deterministic checks (CLI + browser extension) provide more comprehensive, runtime-enforced design quality. The `impeccable` anti-patterns are tied to specific design guidance the skill teaches against, include OKLCH color rules, and are actively maintained (25k+ stars).
+>
+> All design work should use `impeccable`'s rules. Use `/impeccable audit` for scored quality checks.
+>
+> The original rules below are preserved for reference. When `impeccable` is active, its rules take precedence over everything below.
+
+## Delegation
+
+When this skill is active and `impeccable` is installed:
+1. `impeccable`'s shared design laws (color, typography, motion, spatial) take precedence
+2. Run `/impeccable audit` for deterministic anti-pattern detection
+3. The CLI `npx impeccable` runs 27 deterministic checks with no LLM or API key
+
+<details>
+<summary>Original anti-cliché rules (superseded — reference only)</summary>
 
 > **Scope**: These rules apply to ALL design work — ideation, spec writing, design system creation, and implementation. They correct universal AI tendencies, not project-specific preferences.
 
-> **Override**: The `brand-guidelines` skill can override ANY rule below. If the user's confirmed brand direction contradicts a rule here (e.g., purple IS the brand color), `brand-guidelines` takes precedence.
+> **Override**: The `impeccable` skill can override ANY rule below. If the user's confirmed brand direction contradicts a rule here, `impeccable`'s DESIGN.md takes precedence.
 
 ---
 
@@ -150,10 +166,12 @@ These rules are **universal defaults**. They can be overridden by:
 2. **Explicit user request** — If the user says "I want a bento grid layout," use it
 3. **Design reference data** — If the searchable design database returns a style that uses a forbidden element and the user confirms it, use it
 
-**Override hierarchy:** User request > brand-guidelines > design-anti-cliche defaults
+**Override hierarchy:** User request > impeccable DESIGN.md > brand-guidelines > design-anti-cliche defaults
 
 When overriding, acknowledge the override:
 ```
 Using glassmorphism per confirmed "Glass" design direction — 
 anti-cliché default overridden by brand-guidelines.
 ```
+
+</details>

package/template/.agents/skills/design-direction/SKILL.md

@@ -1,45 +1,54 @@
 ---
 name: design-direction
 description: >
-  Design direction interview methodology — constraint-first discovery of visual
-  direction for web, desktop, and mobile surfaces. Covers 5 constraint questions,
-  6 direction options, and CLI-surface variant.
+  Design direction interview methodology — SUPERSEDED. The `impeccable` skill's
+  `/impeccable teach` command now handles design direction discovery with a more
+  comprehensive, multi-round interview that writes PRODUCT.md and DESIGN.md.
+  This file is kept for pipeline backward compatibility — all new design work
+  should use `/impeccable teach` instead.
 triggers:
-  - /create-prd-stack (Design Direction axis)
+  - /create-prd-stack (Design Direction axis — delegates to impeccable)
 ---
 
-# Design Direction
+# Design Direction — SUPERSEDED by `/impeccable teach`
 
-Constraint-first discovery of visual direction for all visual surfaces (web, desktop, mobile). For CLI-only projects, use the CLI variant at the end.
+> **⚠️ This skill is superseded.** The pipeline now uses the `impeccable` skill for all frontend design work. The `/impeccable teach` command provides a more comprehensive design discovery process: it runs a multi-round interview covering users, brand, tone, strategic principles, and visual identity, then writes PRODUCT.md and DESIGN.md files that all other `impeccable` commands consume.
+>
+> This file is retained for pipeline backward compatibility. When the pipeline triggers design direction discovery, delegate to `/impeccable teach`.
 
-## Constraint Questions
+## Delegation Protocol
 
-Ask these five questions first:
+When this skill is invoked (e.g., during `/create-prd-stack`):
+
+1. Run `/impeccable teach` to gather design context
+2. Extract the confirmed design direction, color palette, typography, and motion philosophy from the resulting PRODUCT.md and DESIGN.md
+3. Fire bootstrap with the extracted `DESIGN_DIRECTION`, `PRIMARY_COLOR`, `HEADING_FONT`, etc.
+4. Do NOT run the legacy constraint questions or option table below
+
+## Legacy Content (Reference Only)
+
+The original design direction interview methodology is preserved below for reference. Do not use it — use `/impeccable teach` instead.
+
+<details>
+<summary>Original design-direction methodology (superseded)</summary>
+
+### Constraint Questions
 
 1. What is the emotional tone of the product? (professional/trustworthy, playful/approachable, premium/luxury, raw/technical, editorial/content-first)
 2. Who is the primary audience? (developers, consumers, enterprise, creatives, general public)
-3. Are there existing brand assets? (logo, colors, fonts — if yes, the direction must work within them)
+3. Are there existing brand assets? (logo, colors, fonts)
 4. What are the top 2–3 competitors' visual styles?
 5. Are there hard constraints? (WCAG AA required, white-label needs, dark mode required, existing brand guidelines)
 
-## Option Table
-
-Present 5 options + Hybrid:
+### Option Table
 
 | Direction | What It Is | Pros | Cons | Best For |
 |---|---|---|---|---|
 | Minimal/Functional | Clean, whitespace-heavy, typography-led | Timeless, fast, accessible | Can feel cold or generic | SaaS tools, developer products |
-| Editorial/Magazine | Strong typographic hierarchy, content-first | Distinctive, great for content-heavy products | Complex to maintain | Media, blogs, knowledge platforms |
-| Luxury/Refined | Restrained palette, premium materials feel, subtle motion | High perceived value | Can feel inaccessible | Premium SaaS, fintech, professional services |
-| Playful/Expressive | Bold color, personality, illustration, animation | Memorable, high engagement | Can age quickly | Consumer apps, gaming, social |
-| Technical/Brutalist | Raw, grid-exposed, monospace, data-dense | Authentic for technical audiences | Polarizing | Dev tools, dashboards, data products |
-| Hybrid | Combine elements from two directions | Best of both | Requires design discipline | When constraints pull in two directions |
-
-## Per-Axis Flow
-
-1. Ask constraint questions
-2. Present filtered option table with recommendation based on constraints
-3. Wait for user confirmation
-4. Fire bootstrap with `DESIGN_DIRECTION=[confirmed direction]`
+| Editorial/Magazine | Strong typographic hierarchy, content-first | Distinctive | Complex to maintain | Media, blogs, knowledge platforms |
+| Luxury/Refined | Restrained palette, premium materials feel | High perceived value | Can feel inaccessible | Premium SaaS, fintech |
+| Playful/Expressive | Bold color, personality, illustration | Memorable | Can age quickly | Consumer apps, gaming, social |
+| Technical/Brutalist | Raw, grid-exposed, monospace, data-dense | Authentic for technical audiences | Polarizing | Dev tools, dashboards |
+| Hybrid | Combine elements from two directions | Best of both | Requires design discipline | When constraints pull two ways |
 
-> **CLI surfaces**: For CLI-only projects, replace the visual direction options with CLI-appropriate ones: output verbosity philosophy (terse vs. informative), color usage (minimal/semantic vs. rich), information density (compact vs. spacious), personality (friendly vs. utilitarian).
+</details>

package/template/.agents/skills/impeccable/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: impeccable
+description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.
+---
+
+Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft.
+
+## Setup (non-optional)
+
+Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project.
+
+| Gate | Required check | If fail |
+|---|---|---|
+| Context | The PRODUCT.md / DESIGN.md loader result is known from `node .agents/skills/impeccable/scripts/load-context.mjs`. | Run the loader before continuing. |
+| Product | PRODUCT.md exists and is not empty or placeholder (`[TODO]` markers, <200 chars). | Run `$impeccable teach`, refresh context, then resume. Never synthesize PRODUCT.md from the user's original prompt alone. |
+| Command | The matching command reference is loaded when a sub-command is used. | Load the reference before continuing. |
+| Craft | `$impeccable craft` has a user-confirmed shape brief for this task. `teach` / PRODUCT.md never counts as shape. | Run `$impeccable shape` and wait for explicit brief confirmation. |
+| Image | Required visual probes / mocks are generated or skipped with a reason. | Resolve the image-generation gate in `shape.md` or `craft.md` before code. |
+| Mutation | All active gates above pass. | Do not edit project files yet. |
+
+Codex-style agents must state this before editing files:
+
+```text
+IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped:<reason> mutation=open
+```
+
+For `$impeccable craft`, `shape=pass` is only valid after a separate user response approving the shape design brief, or when the user provided an already-confirmed brief in the request. Do not mark `shape=pass` after writing PRODUCT.md, summarizing assumptions, or drafting an unconfirmed brief yourself.
+
+Other harnesses should follow the same checklist when they can expose this state.
+
+### 1. Context gathering
+
+Two files, case-insensitive. The loader looks at the project root by default and falls back to `.agents/context/` and `docs/` if the root is clean. Override with `IMPECCABLE_CONTEXT_DIR=path/to/dir` (absolute or relative to cwd).
+
+- **PRODUCT.md**: required. Users, brand, tone, anti-references, strategic principles.
+- **DESIGN.md**: optional, strongly recommended. Colors, typography, elevation, components.
+
+Load both in one call:
+
+```bash
+node .agents/skills/impeccable/scripts/load-context.mjs
+```
+
+Consume the full JSON output. Never pipe through `head`, `tail`, `grep`, or `jq`. The output's `contextDir` field tells you where the files were resolved from.
+
+If the output is already in this session's conversation history, don't re-run. Exceptions requiring a fresh load: you just ran `$impeccable teach` or `$impeccable document` (they rewrite the files), or the user manually edited one.
+
+`$impeccable live` already warms context via `live.mjs`. If you've run `live.mjs`, don't also run `load-context.mjs` this session.
+
+If PRODUCT.md is missing, empty, or placeholder (`[TODO]` markers, <200 chars): run `$impeccable teach`, then resume the user's original task with the fresh context. If the original task was `$impeccable craft`, resume into `$impeccable shape` before any implementation work.
+
+If DESIGN.md is missing: nudge once per session (*"Run `$impeccable document` for more on-brand output"*), then proceed.
+
+### 2. Register
+
+Every design task is **brand** (marketing, landing, campaign, long-form content, portfolio: design IS the product) or **product** (app UI, admin, dashboard, tool: design SERVES the product).
+
+Identify before designing. Priority: (1) cue in the task itself ("landing page" vs "dashboard"); (2) the surface in focus (the page, file, or route being worked on); (3) `register` field in PRODUCT.md. First match wins.
+
+If PRODUCT.md lacks the `register` field (legacy), infer it once from its "Users" and "Product Purpose" sections, then cache the inferred value for the session. Suggest the user run `$impeccable teach` to add the field explicitly.
+
+Load the matching reference: [reference/brand.md](reference/brand.md) or [reference/product.md](reference/product.md). The shared design laws below apply to both.
+
+## Shared design laws
+
+Apply to every design, both registers. Match implementation complexity to the aesthetic vision: maximalism needs elaborate code, minimalism needs precision. Interpret creatively. Vary across projects; never converge on the same choices. GPT is capable of extraordinary work. Don't hold back.
+
+### Color
+
+- Use OKLCH. Reduce chroma as lightness approaches 0 or 100; high chroma at extremes looks garish.
+- Never use `#000` or `#fff`. Tint every neutral toward the brand hue (chroma 0.005–0.01 is enough).
+- Pick a **color strategy** before picking colors. Four steps on the commitment axis:
+  - **Restrained**: tinted neutrals + one accent ≤10%. Product default; brand minimalism.
+  - **Committed**: one saturated color carries 30–60% of the surface. Brand default for identity-driven pages.
+  - **Full palette**: 3–4 named roles, each used deliberately. Brand campaigns; product data viz.
+  - **Drenched**: the surface IS the color. Brand heroes, campaign pages.
+- The "one accent ≤10%" rule is Restrained only. Committed / Full palette / Drenched exceed it on purpose. Don't collapse every design to Restrained by reflex.
+
+### Theme
+
+Dark vs. light is never a default. Not dark "because tools look cool dark." Not light "to be safe."
+
+Before choosing, write one sentence of physical scene: who uses this, where, under what ambient light, in what mood. If the sentence doesn't force the answer, it's not concrete enough. Add detail until it does.
+
+"Observability dashboard" does not force an answer. "SRE glancing at incident severity on a 27-inch monitor at 2am in a dim room" does. Run the sentence, not the category.
+
+### Typography
+
+- Cap body line length at 65–75ch.
+- Hierarchy through scale + weight contrast (≥1.25 ratio between steps). Avoid flat scales.
+
+### Layout
+
+- Vary spacing for rhythm. Same padding everywhere is monotony.
+- Cards are the lazy answer. Use them only when they're truly the best affordance. Nested cards are always wrong.
+- Don't wrap everything in a container. Most things don't need one.
+
+### Motion
+
+- Don't animate CSS layout properties.
+- Ease out with exponential curves (ease-out-quart / quint / expo). No bounce, no elastic.
+
+### Absolute bans
+
+Match-and-refuse. If you're about to write any of these, rewrite the element with different structure.
+
+- **Side-stripe borders.** `border-left` or `border-right` greater than 1px as a colored accent on cards, list items, callouts, or alerts. Never intentional. Rewrite with full borders, background tints, leading numbers/icons, or nothing.
+- **Gradient text.** `background-clip: text` combined with a gradient background. Decorative, never meaningful. Use a single solid color. Emphasis via weight or size.
+- **Glassmorphism as default.** Blurs and glass cards used decoratively. Rare and purposeful, or nothing.
+- **The hero-metric template.** Big number, small label, supporting stats, gradient accent. SaaS cliché.
+- **Identical card grids.** Same-sized cards with icon + heading + text, repeated endlessly.
+- **Modal as first thought.** Modals are usually laziness. Exhaust inline / progressive alternatives first.
+
+### Copy
+
+- Every word earns its place. No restated headings, no intros that repeat the title.
+- **No em dashes.** Use commas, colons, semicolons, periods, or parentheses. Also not `--`.
+
+### The AI slop test
+
+If someone could look at this interface and say "AI made that" without doubt, it's failed. Cross-register failures are the absolute bans above. Register-specific failures live in each reference.
+
+**Category-reflex check.** Run at two altitudes; the second one catches what the first one misses.
+
+- **First-order:** if someone could guess the theme + palette from the category alone ("observability → dark blue", "healthcare → white + teal", "finance → navy + gold", "crypto → neon on black"), it's the first training-data reflex. Rework the scene sentence and color strategy until the answer isn't obvious from the domain.
+- **Second-order:** if someone could guess the aesthetic family from category-plus-anti-references ("AI workflow tool that's not SaaS-cream → editorial-typographic", "fintech that's not navy-and-gold → terminal-native dark mode"), it's the trap one tier deeper. The first reflex was avoided; the second wasn't. Rework until both answers are not obvious. The brand register's [reflex-reject aesthetic lanes](reference/brand.md) list catches the currently-saturated families.
+
+## Commands
+
+| Command | Category | Description | Reference |
+|---|---|---|---|
+| `craft [feature]` | Build | Shape, then build a feature end-to-end | [reference/craft.md](reference/craft.md) |
+| `shape [feature]` | Build | Plan UX/UI before writing code | [reference/shape.md](reference/shape.md) |
+| `teach` | Build | Set up PRODUCT.md and DESIGN.md context | [reference/teach.md](reference/teach.md) |
+| `document` | Build | Generate DESIGN.md from existing project code | [reference/document.md](reference/document.md) |
+| `extract [target]` | Build | Pull reusable tokens and components into design system | [reference/extract.md](reference/extract.md) |
+| `critique [target]` | Evaluate | UX design review with heuristic scoring | [reference/critique.md](reference/critique.md) |
+| `audit [target]` | Evaluate | Technical quality checks (a11y, perf, responsive) | [reference/audit.md](reference/audit.md) |
+| `polish [target]` | Refine | Final quality pass before shipping | [reference/polish.md](reference/polish.md) |
+| `bolder [target]` | Refine | Amplify safe or bland designs | [reference/bolder.md](reference/bolder.md) |
+| `quieter [target]` | Refine | Tone down aggressive or overstimulating designs | [reference/quieter.md](reference/quieter.md) |
+| `distill [target]` | Refine | Strip to essence, remove complexity | [reference/distill.md](reference/distill.md) |
+| `harden [target]` | Refine | Production-ready: errors, i18n, edge cases | [reference/harden.md](reference/harden.md) |
+| `onboard [target]` | Refine | Design first-run flows, empty states, activation | [reference/onboard.md](reference/onboard.md) |
+| `animate [target]` | Enhance | Add purposeful animations and motion | [reference/animate.md](reference/animate.md) |
+| `colorize [target]` | Enhance | Add strategic color to monochromatic UIs | [reference/colorize.md](reference/colorize.md) |
+| `typeset [target]` | Enhance | Improve typography hierarchy and fonts | [reference/typeset.md](reference/typeset.md) |
+| `layout [target]` | Enhance | Fix spacing, rhythm, and visual hierarchy | [reference/layout.md](reference/layout.md) |
+| `delight [target]` | Enhance | Add personality and memorable touches | [reference/delight.md](reference/delight.md) |
+| `overdrive [target]` | Enhance | Push past conventional limits | [reference/overdrive.md](reference/overdrive.md) |
+| `clarify [target]` | Fix | Improve UX copy, labels, and error messages | [reference/clarify.md](reference/clarify.md) |
+| `adapt [target]` | Fix | Adapt for different devices and screen sizes | [reference/adapt.md](reference/adapt.md) |
+| `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) |
+| `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) |
+
+Plus two management commands: `pin <command>` and `unpin <command>`, detailed below.
+
+### Routing rules
+
+1. **No argument**: render the table above as the user-facing command menu, grouped by category. Ask what they'd like to do.
+2. **First word matches a command**: load its reference file and follow its instructions. Everything after the command name is the target.
+3. **First word doesn't match**: general design invocation. Apply the setup steps, shared design laws, and the loaded register reference, using the full argument as context.
+
+Setup (context gathering, register) is already loaded by then; sub-commands don't re-invoke `$impeccable`.
+
+If the first word is `craft`, setup still runs first, but [reference/craft.md](reference/craft.md) owns the rest of the flow. If setup invokes `teach` as a blocker, finish teach, refresh context, then resume the original command and target.
+
+## Pin / Unpin
+
+**Pin** creates a standalone shortcut so `$<command>` invokes `$impeccable <command>` directly. **Unpin** removes it. The script writes to every harness directory present in the project.
+
+```bash
+node .agents/skills/impeccable/scripts/pin.mjs <pin|unpin> <command>
+```
+
+Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.

package/template/.agents/skills/impeccable/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: Impeccable
+  short_description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify,...
+  default_prompt: Use Impeccable to redesign, critique, audit, or polish this frontend.