@harness-engineering/cli 2.6.1 → 2.7.0

package/dist/agents/skills/claude-code/harness-design-craft/SKILL.md

@@ -0,0 +1,212 @@
+# Harness Design Craft
+
+> LLM-judgment-based design ceiling-raiser. Three branchable phases — CRITIQUE finds what's mediocre, POLISH applies high-craft moves, BENCHMARK scores against curated exemplars. The ceiling counterpart to harness-design (declared-intent enforcement, rule-based) and the design-pipeline floor audits.
+
+## When to Use
+
+- Reviewing UI for craft elevation opportunities the rule-based skills can't surface ("hierarchy is muddy here," "loading spinner where a content-matched skeleton would fit")
+- After harness-design has captured intent and basic checks pass — go from "consistent" to "stunning"
+- Before launching customer-facing surfaces — visual judgment beyond consistency
+- During design-engineering work — POLISH phase suggests concrete craft moves with before/after sketches
+- For competitive benchmarking — BENCHMARK scores how close you are to Linear / Stripe / Raycast tier
+- When `on_new_feature` fires AND the feature touches design surface
+- NOT for declared-anti-pattern enforcement (use harness-design)
+- NOT for component anatomy completeness (use audit-component-anatomy)
+- NOT for token validation (use harness-design-system)
+- NOT for accessibility (use harness-accessibility)
+- NOT for code generation from scratch (use v0 / bolt.new / Lovable — different tool class)
+
+## Process
+
+### Argument Resolution
+
+- `mode`: `"fast"` (code-only LLM, cheap, default) or `"deep"` (rendered + vision-LLM, ceiling-raising, requires playwright + vision-capable model)
+- `phases`: subset of `critique`, `polish`, `benchmark`. Default: all three, sequenced.
+- `autoCapture`: B' upgrade behavior. `"prompt"` (default — offer to chain to harness-design if preconditions missing), `"auto"` (chain without prompting), `"skip"` (run with generic-craft rubrics, no offer).
+- `files`: optional scoping. Default: all components/pages discovered.
+
+### B' Precondition Check (every invocation)
+
+Before any phase runs, check four preconditions and offer to fulfill missing ones:
+
+| Precondition                 | Source                                          | If missing                                                           |
+| ---------------------------- | ----------------------------------------------- | -------------------------------------------------------------------- |
+| `designMdExists`             | `design-system/DESIGN.md` present               | Offer to chain to harness-design (INTENT + DIRECTION)                |
+| `aestheticIntentDeclared`    | DESIGN.md Aesthetic Direction section populated | Offer to chain to harness-design (INTENT)                            |
+| `tokensExist`                | `design-system/tokens.json` present             | Note in summary; do not auto-chain (harness-design-system territory) |
+| `componentRegistryPopulated` | DESIGN.md Component Registry section            | Note in summary; falls back to export-name resolution                |
+
+`autoCapture` controls behavior:
+
+- `prompt`: emit `upgradeOffer` interaction; pause for user choice
+- `auto`: chain to harness-design transition automatically (for autopilot)
+- `skip`: run with generic-craft rubrics (degrades quality but unblocks first-run)
+
+### Phase: CRITIQUE — Find what is craft-mediocre
+
+1. **Identify targets.** Discover components (or pages, when scoped to pages) to critique. Apply `files` scoping if provided.
+
+2. **Load critique rubrics.** Read from catalog (`catalog/rubrics/`). 10 rubrics in v1 covering: hierarchy clarity, typography craft, motion quality, color confidence, density rhythm, restraint, polish details, copy voice, interaction craft, brand coherence. Filter by `catalog.rubrics` config if set.
+
+3. **For each target × each rubric, run an LLM critique pass:**
+   - **Fast mode:** pass source code + rubric prompt + AestheticIntent (if present) to text LLM
+   - **Deep mode:** render via playwright at three viewports (1440/768/375), pass screenshots + source + rubric prompt + AestheticIntent to vision-capable LLM
+   - Parse response into 3-axis finding: `tier` (foundational/polish/aspirational), `impact` (small/medium/large), `confidence` (high/medium/low — essential for honest LLM output)
+
+4. **Apply harness-design overlap deferral.** Per `design.craft.enabled = true`, when a CRITIQUE finding matches a declared anti-pattern in DESIGN.md, defer to harness-design (suppress this finding) and increment `meta.deferralsToHarnessDesign`.
+
+5. **Compute derived `priority` field** for each finding (tier × impact × confidence-weighted score) for single-axis sorting when needed.
+
+### Phase: POLISH — Apply craft pattern library
+
+1. **Load polish patterns.** Read from catalog (`catalog/patterns/`). 15 patterns in v1 across 5 categories: motion (3), skeleton (3), typography (3), interaction (3), layout (3). Filter by `catalog.patterns` config if set.
+
+2. **For each target × each applicable pattern, evaluate fit:**
+   - Match pattern's `applicableTo` criteria (jsx-attribute, css-property, component-type, etc.)
+   - LLM judgment: would applying this pattern improve craft here?
+   - If yes: produce 3-axis finding with `before` and `after` content (codemod-TODO sketch, not actual edit)
+
+3. **No source modification.** POLISH only emits suggestions with before/after sketches. The user applies via codemod tools or by hand.
+
+### Phase: BENCHMARK — Score against curated exemplars
+
+1. **Load exemplar corpus.** Read from catalog (`catalog/exemplars/`). 50 exemplars in v1 across 5 component types (EmptyState, LoadingState, ErrorState, Modal, Button — 10 each). Filter by `catalog.exemplars` config if set.
+
+2. **For each target component, identify matching exemplars** by component-type tag (e.g., target is an EmptyState → load all 10 EmptyState exemplars).
+
+3. **For each target × matching exemplars, run an LLM benchmark pass:**
+   - **Fast mode:** structural comparison (code/markup/declared anatomy vs exemplar's reference markup) — limited but useful as a first signal
+   - **Deep mode:** visual comparison via vision-LLM (target screenshot vs exemplar screenshot/URL)
+   - Parse response into 5-dim radar: `philosophicalCoherence`, `hierarchy`, `craftExecution`, `function`, `innovation` — each with score (0-100), confidence, notes
+   - Compute weighted `overall` score
+   - Emit narrative `gaps` (where the target falls short of the best exemplars and why)
+
+4. **Cite exemplars used.** Each `BenchmarkScore` lists `exemplars` (ids) consulted. Increment per-exemplar `citationCount` for measurement.
+
+### Phase: REPORT — Format and persist outputs
+
+1. **Write to graph:** CRITIQUE/POLISH findings → `VIOLATES_CRAFT` edges via extended `DesignConstraintAdapter`. BENCHMARK scores → `CRAFT_SCORE` nodes attached to component nodes. All carry `runId` for sub-project #4 fixpoint detection. Idempotent.
+
+2. **Format markdown report.** Grouped by component, with `CRAFT-*` codes linked to `finding-codes.md` and rubric/pattern/exemplar names linked to their catalog entries. Low-confidence findings visually distinguished (italic or `(low confidence:)` prefix).
+
+3. **Emit summary.** Total findings, breakdown by phase, mode (`fast`/`deep`), LLM cost (`llmCalls.{count, costUsd}`), catalog applied, deferrals to harness-design, precondition state.
+
+4. **Signal feedback.** Append to running aggregate: when the same finding-shape recurs N≥5 times across audits (config: `design.craft.signal.proposalThreshold`), emit a candidate pattern proposal to `.harness/design-craft/proposals/`.
+
+## Harness Integration
+
+- **`harness validate`** — Fast-mode CRITIQUE hook (subset of rubrics; opt-in). Findings respect `design.strictness`.
+- **`mcp__harness__design_craft`** — Programmatic API. Consumed by harness check-design verifier (#4) and design-pipeline orchestrator (#5). Phase selector exposed.
+- **`harness-design`** — Soft dependency. B' progressive upgrade chains to it when AestheticIntent missing. Defers declared-anti-pattern findings to it.
+- **`harness-design-system`** — Soft dependency. Token-related polish patterns enriched when tokens exist.
+- **`DesignConstraintAdapter`** — Extended for `CRAFT-*` codes (CRAFT-C* critique, CRAFT-P* polish, CRAFT-B\* benchmark identifiers) + `CRAFT_SCORE` node type.
+- **`packages/intelligence/`** — Wrapped by `llm/provider.ts` for vision-capable LLM calls. May need extension if no vision support today.
+
+## Success Criteria
+
+See `docs/changes/design-pipeline/design-craft-elevator/proposal.md` for the full 38 success criteria. Highlights:
+
+- Three phases independently invocable via `phases` arg
+- 3-axis output for CRITIQUE/POLISH; 5-dim radar for BENCHMARK
+- Confidence is honest (low-confidence findings emitted, not silently dropped)
+- B' detect-and-offer works (preconditions detected, offer payload emitted, chain to harness-design honored)
+- Seed catalog complete (10 rubrics + 15 patterns + 50 exemplars)
+- Growth infrastructure operational (contribution validation, signal loop, usage measurement)
+- Fast-mode ≤ 30s / 50 files; deep-mode ≤ 3min / 10 components
+- LLM cost tracked per audit
+
+## Examples
+
+### Example: CRITIQUE finds hierarchy muddiness
+
+**Input:** A Dashboard.tsx page rendering three CTA buttons, all using the same `variant="primary"`.
+
+**Output (3-axis finding):**
+
+```
+CRAFT-C001 [foundational | medium | high] Hierarchy muddy: three buttons compete for primary
+  File:        src/pages/Dashboard.tsx:88
+  Rubric:      hierarchy-clarity (rubric-hierarchy-clarity)
+  Tier:        foundational  (this is "fix to be not-broken," not polish)
+  Impact:      medium        (users can still complete tasks, but decision fatigue is real)
+  Confidence:  high          (rule is unambiguous; LLM saw the three buttons + their identical styling)
+  Priority:    derived → 0.78
+  Message:     Three primary-variant buttons in the same view: "Save", "Export", "Share".
+               No visual signal indicates which is the recommended action. Reduce to one
+               primary; demote the others to secondary or ghost variant.
+  Cite:        rubric "hierarchy-clarity" / source: huashu-design#hierarchy
+```
+
+### Example: POLISH suggests spring physics
+
+**Input:** A Modal.tsx using `transition: transform 0.2s cubic-bezier(0.4, 0, 0.2, 1)`.
+
+**Output (3-axis finding with before/after):**
+
+```
+CRAFT-P001 [polish | medium | high] Spring physics would feel more confident here
+  File:        src/components/Modal.tsx:42
+  Pattern:     spring-physics-microinteraction
+  Tier:        polish        (Modal already works; this elevates the feel)
+  Impact:      medium        (users notice modal motion every time)
+  Before:      transition: transform 0.2s cubic-bezier(0.4, 0, 0.2, 1);
+  After:       transition: transform { duration: spring.medium };
+               // stiffness:200 damping:25 for modal entries per emil-design-eng#spring-physics
+  Fix kind:    codemod-todo (POLISH does not modify source; suggestion only)
+```
+
+### Example: BENCHMARK against Linear
+
+**Input:** A custom EmptyState component for the project's task list.
+
+**Output (5-dim radar):**
+
+```
+CRAFT-B001 EmptyState component scored against Linear empty list exemplar
+
+  philosophicalCoherence: 80 [high]   "Restraint aligns with declared minimal aesthetic."
+  hierarchy:              65 [medium] "Heading and body OK; action button competes
+                                       with secondary 'Learn more' link."
+  craftExecution:         55 [medium] "Generic illustration; Linear uses subtle line art
+                                       matching their monochromatic palette. Missing the
+                                       'breathing room' Linear gets via 64px vertical padding."
+  function:               85 [high]   "Action is clear and verb-led."
+  innovation:             50 [low]    "Standard 4-part anatomy; not differentiated."
+
+  Overall: 67  [medium confidence]
+  Gaps:
+    - "Reduce the empty-state to one CTA — the secondary link adds noise"
+    - "Replace stock illustration with a custom line art aligned to brand"
+    - "Increase top padding from 32px to 56px+ to match the breathing-room pattern"
+  Exemplars cited: exemplar-linear-empty-list
+```
+
+## Gates
+
+- **No assertion of "stunning" without LLM judgment.** This skill is LLM-judgment-based; if no LLM provider is configured, halt with explanatory error — do not degrade to rule-based output.
+- **Deep mode requires playwright + vision-capable LLM.** If either is missing, surface to user with the documented fallback path (code-only mode); do not silently degrade.
+- **No autofix.** POLISH emits suggestions only; source files are never modified.
+- **Confidence is honest.** Low-confidence outputs MUST be emitted (with the low-confidence flag) — never silently upgraded.
+- **B' deferral honored.** When `design.craft.enabled = true` and DESIGN.md declares an anti-pattern matching a CRITIQUE finding, defer to harness-design; never double-count.
+
+## Escalation
+
+- **When deep mode renders fail (component not reachable via URL).** Emit a "render-unreachable" finding for the affected component, fall back to fast mode for that component, continue the audit. Do not abort.
+- **When the vision-LLM rejects the screenshot (size, content, format).** Log the rejection; downgrade that component's run to fast mode; do not abort.
+- **When LLM cost exceeds the configured per-audit budget.** Halt the audit, emit findings collected so far, report the cost overrun. Do not retry. Config: `design.craft.llm.maxCostUsd` (default unset = no cap).
+- **When the catalog is empty or unloadable.** Halt with explanatory error pointing to `agents/skills/shared/design-knowledge/craft-{rubrics,patterns,exemplars}/`. Do not synthesize findings without the catalog.
+- **When B' detect-and-offer produces an offer the user declines.** Run in generic-craft mode (no AestheticIntent context); note the degraded quality in summary. User can re-invoke with `autoCapture: skip` to suppress future offers.
+- **When the same finding-shape recurs across many audits (signal feedback loop).** Auto-export a candidate pattern proposal to `.harness/design-craft/proposals/` after N≥`design.craft.signal.proposalThreshold` recurrences; require human review before promotion to the catalog.
+- **When a graph operation fails.** Skip graph integration for that run; emit findings to the report only. Log a warning that `VIOLATES_CRAFT` edges + `CRAFT_SCORE` nodes were not persisted.
+
+## Status
+
+**v1 — in implementation.** See:
+
+- Spec: `docs/changes/design-pipeline/design-craft-elevator/proposal.md`
+- Plan: `docs/changes/design-pipeline/design-craft-elevator/plans/2026-05-23-design-craft-elevator-plan.md`
+- Finding codes: `docs/changes/design-pipeline/design-craft-elevator/finding-codes.md`
+- Contribution guide: `docs/changes/design-pipeline/design-craft-elevator/contribution.md`
+- Growth trajectory: `docs/changes/design-pipeline/design-craft-elevator/growth-trajectory.md`
+- Roadmap entry: `design-pipeline sub-project #6` in `docs/roadmap.md`
+- Prior-art references: `docs/changes/design-pipeline/REFERENCES.md` tier-1 entries #2, #3, #4 (impeccable, emil-design-eng, huashu-design)

package/dist/agents/skills/claude-code/harness-design-craft/skill.yaml

@@ -0,0 +1,57 @@
+name: harness-design-craft
+version: "0.1.0"
+description: LLM-judgment-based design ceiling-raiser. CRITIQUE finds what's mediocre, POLISH applies high-craft moves, BENCHMARK scores against curated exemplars. The ceiling counterpart to rule-based audit skills.
+stability: draft
+cognitive_mode: constructive-architect
+triggers:
+  - manual
+  - on_new_feature
+platforms:
+  - claude-code
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-design-craft
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: mode
+      description: "fast (code-only LLM critique) or deep (rendered + vision-LLM)"
+      required: false
+    - name: phases
+      description: "Subset of critique,polish,benchmark (comma-separated). Default: all three."
+      required: false
+    - name: files
+      description: Optional glob/path scoping
+      required: false
+    - name: autoCapture
+      description: "B' upgrade behavior: prompt | auto | skip. Default: prompt."
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-design-craft
+    path: string
+type: flexible
+tier: 2
+phases:
+  - name: critique
+    description: LLM-judgment finding what is craft-mediocre (3-axis tier/impact/confidence output)
+    required: false
+  - name: polish
+    description: Apply polish patterns with before/after sketches (3-axis output)
+    required: false
+  - name: benchmark
+    description: Score against curated exemplars (5-dim radar output)
+    required: false
+state:
+  persistent: false
+depends_on:
+  - harness-design
+  - harness-design-system

package/dist/agents/skills/claude-code/harness-design-pipeline/SKILL.md

@@ -0,0 +1,266 @@
+# Harness Design Pipeline
+
+> Orchestrator composing all 6 design-pipeline sub-projects into a single sequential pipeline with convergence-based remediation: FRESHEN → DETECT → FIX → AUDIT → FILL → REPORT. Produces a unified `pass` / `warn` / `fail` verdict and a per-phase report. Mirrors harness-docs-pipeline in shape; consumes the formal verifier interface generically so a 5th rule-based verifier composes for free.
+
+## When to Use
+
+- When you want a single-command design health check across drift, anatomy, brand, and craft
+- After major UI refactoring that may have caused widespread drift
+- As a periodic hygiene check (per-PR or per-sprint)
+- When onboarding a new project that has no DESIGN.md (bootstrap mode via FILL phase)
+- When `on_pr` triggers fire on a UI-touching change
+- NOT for fixing a single known drift issue (use align-design-system directly)
+- NOT for single-pass verification (use `harness check-design` directly)
+- NOT for authoring DESIGN.md or tokens.json (use `harness-design` skill — orchestrator only stubs absent inputs)
+
+## Relationship to Sub-Skills
+
+| Skill                   | Pipeline Phase | Role                                                        |
+| ----------------------- | -------------- | ----------------------------------------------------------- |
+| detect-design-drift     | DETECT         | Find token bypass + primitive-adoption drift                |
+| align-design-system     | FIX            | Apply codemods + emit suggestions for drift findings        |
+| audit-component-anatomy | AUDIT          | Find missing required anatomy parts in components           |
+| audit-brand-compliance  | AUDIT          | Find token misuse + forbidden phrases (brand semantics)     |
+| harness-design-craft    | FILL           | Critique copy/hierarchy/polish (LLM-judgment ceiling skill) |
+
+This orchestrator delegates to sub-skills — it never reimplements their logic. Each sub-skill retains full standalone functionality.
+
+## Iron Law
+
+**The pipeline delegates, never reimplements.** If you find yourself writing drift detection logic, fix application logic, or audit logic inside the orchestrator, STOP. Delegate to the dedicated sub-skill.
+
+**Safe fixes are silent, unsafe fixes surface.** v1 follows align-design-system's pre-flight classifier verdict: `applied` outcomes are silent successes; `suggestion` / `skipped-unsafe` / `failed` outcomes surface in the report. Never override the classifier from inside the orchestrator.
+
+## Flags
+
+| Flag                      | Effect                                                            |
+| ------------------------- | ----------------------------------------------------------------- |
+| `--fix`                   | Enable convergence-based auto-fix (default: detect + report only) |
+| `--no-freshen`            | Skip the FRESHEN phase                                            |
+| `--no-fill`               | Skip the FILL phase (input bootstrap + craft polish)              |
+| `--ci`                    | Non-interactive: safe fixes only, no prompts                      |
+| `--mode <m>`              | Verifier mode (`fast` or `full`); default `fast`                  |
+| `--files <...>`           | Optional file/glob scope passed to each verifier                  |
+| `--design-strictness <s>` | Override `design.strictness`                                      |
+| `--json`                  | Machine-readable output                                           |
+
+## Shared Context Object
+
+All phases read from and write to a shared `DesignPipelineContext`:
+
+```typescript
+interface DesignPipelineContext {
+  graphAvailable: boolean;
+  inputs: {
+    designMdExists: boolean;
+    tokensJsonExists: boolean;
+    componentRegistryExists: boolean;
+    brandRulesExist: boolean;
+  };
+  bootstrapped: { designMd; tokensJson; componentRegistry; brandRules: boolean };
+  driftFindings: DriftFinding[];
+  fixesApplied: FixOutcome[];
+  auditFindings: { anatomy: AnatomyFinding[]; brand: BrandFinding[] };
+  craftFindings: CraftFinding[];
+  craftSuggestions: number;
+  exclusions: Set<string>;
+  verifiersRun: string[];
+  verifiersFailed: Array<{ name: string; error: string }>;
+  verdict: 'pass' | 'warn' | 'fail';
+  summary: { totalFindings; bySeverity; byCode; fixesApplied; iterationsRun; durationMs };
+}
+```
+
+The context is passed to sub-skills via `.harness/handoff.json` with a `pipeline` field. align-design-system v1 already supports reading `pipeline.driftFindings` and writing `pipeline.fixesApplied`; other sub-skills run in standalone mode when invoked from the orchestrator.
+
+## Process
+
+### Phase 1: FRESHEN — Input Freshness Check
+
+**Skip this phase if `--no-freshen` flag is set.**
+
+1. **Check graph existence.** Look for `.harness/graph/` directory; set `context.graphAvailable`.
+2. **Check input file presence:**
+   - `design-system/DESIGN.md` exists?
+   - `design-system/tokens.json` exists?
+   - `## Component Registry` section present in DESIGN.md?
+   - `## Brand Rules` section present in DESIGN.md?
+3. **Set `context.inputs.*` flags.** Bootstrap action is DEFERRED to FILL phase (clean phase responsibilities).
+
+### Phase 2: DETECT — Find Design Drift
+
+1. Invoke `runDetectDrift({ path, mode, files? })`.
+2. Populate `context.driftFindings` with all `DRIFT-T*` and `DRIFT-P*` findings.
+3. Record `'detect-drift'` in `context.verifiersRun`.
+4. On failure: push to `context.verifiersFailed` and continue (graceful degradation).
+5. If `design.audit.driftDetection.enabled === false` in config: SKIP this phase entirely.
+
+### Phase 3: FIX — Convergence-Based Drift Remediation
+
+**This phase runs only when `--fix` flag is set.**
+
+#### Convergence Loop
+
+```
+previousCount = context.driftFindings.length
+maxIterations = 5
+
+while iteration < maxIterations:
+  1. Write pipeline.driftFindings to handoff.json
+  2. Invoke align-design-system in pipeline mode
+  3. Append outcomes to context.fixesApplied
+  4. If applied === 0: STOP (converged)
+  5. Re-run detect-design-drift
+  6. newCount = remaining findings
+  7. if newCount >= previousCount: STOP (no progress)
+  8. previousCount = newCount
+  9. iteration++
+```
+
+Each align run mutates source files via its safe codemods (T001/T002/T003 only). Probably-safe / unsafe / failed outcomes are recorded but never auto-applied (align's pre-flight classifier is the gate).
+
+### Phase 4: AUDIT — Rule-Based Verifier Loop
+
+1. Iterate the orchestrator's `VerifierRegistry` generically:
+   - `audit-anatomy` runner → populate `context.auditFindings.anatomy`
+   - `audit-brand` runner → populate `context.auditFindings.brand`
+2. Each verifier's failure is captured in `context.verifiersFailed` without aborting the loop.
+3. **Iron Law:** the orchestrator does NOT branch on verifier name inside the audit logic. Adding a 5th verifier means registering it; the loop body stays unchanged.
+
+### Phase 5: FILL — Bootstrap + Ceiling Polish
+
+**Skip this phase if `--no-fill` flag is set.**
+
+**5a. Bootstrap missing inputs.** For each absent input declared in Phase 1:
+
+- DESIGN.md missing → write a minimal stub with `## Aesthetic Direction`, `## Component Registry`, `## Anti-Patterns`, `## Brand Rules` sections, each containing `<!-- TODO: ... -->` placeholders.
+- tokens.json missing → write a minimal `{ "$description": "TODO: declare design tokens" }` stub.
+- `## Component Registry` missing (DESIGN.md exists but section absent) → append a stub table.
+- `## Brand Rules` missing → append a stub voice subsection.
+
+Set `context.bootstrapped.{designMd,tokensJson,componentRegistry,brandRules}` per-input.
+
+**5b. Invoke design-craft-elevator POLISH (critique phase).**
+
+1. Call `runDesignCraft({ phases: ['critique'] })`.
+2. Populate `context.craftFindings` and `context.craftSuggestions`.
+3. Record `'design-craft-critique'` in `context.verifiersRun`.
+
+design-craft suggestions are surfaced in REPORT but do NOT contribute to the `error`/`warn` severity counts — they're ceiling-layer suggestions, not violations.
+
+### Phase 6: REPORT — Verdict + Summary
+
+Compute verdict:
+
+| Condition                                                               | Verdict |
+| ----------------------------------------------------------------------- | ------- |
+| Any error-severity finding remains after FIX                            | `fail`  |
+| Any warn-severity finding OR craft suggestion OR bootstrapped any input | `warn`  |
+| Zero findings, zero suggestions, zero bootstrapped                      | `pass`  |
+
+Aggregate `summary.bySeverity` and `summary.byCode` across drift + anatomy + brand findings. (Craft findings use tier, not severity — they're tracked separately.)
+
+Render human-readable or JSON output.
+
+## Harness Integration
+
+- **`harness design-pipeline`** — CLI entry point. Recommended for CI usage with `--ci --fix`.
+- **`mcp__harness__run_design_pipeline`** — MCP tool. Same input/output. Consumed by agents needing the full design health check.
+- **`harness check-design`** — Single-pass verifier. The orchestrator INVOKES check-design's underlying verifiers (anatomy, drift, brand) but expands them into a convergence-loop pipeline. Choose check-design for one-shot verification; choose this orchestrator for the full pipeline with fixes.
+- **`harness validate`** — Stays single-pass (and fast). The orchestrator is opt-in and heavier — different contract.
+- **`.harness/handoff.json`** — Carries the `pipeline` field between orchestrator and align-design-system. Other sub-skills run standalone-mode from the orchestrator's perspective.
+
+## Success Criteria
+
+See `docs/changes/design-pipeline/orchestrator/proposal.md` for the full 34 success criteria. Highlights:
+
+- Generic Verifier registry: adding a 5th verifier requires only a `register()` call
+- Iron Law compliance: orchestrator imports NO drift/fix/audit logic, only sub-skill entry points
+- Convergence loop bounded at 5 iterations + plateau detection
+- Verdict: `pass`/`warn`/`fail` per documented rules
+- 4-platform skill markdown shipped
+- MCP tool `run_design_pipeline` registered (count 73 → 74)
+
+## Examples
+
+### Example: Clean project, default flags
+
+```
+$ harness design-pipeline
+
+Verdict: ✓ pass
+
+Phases:
+  FRESHEN  inputs: DESIGN.md=yes tokens.json=yes registry=yes brand=yes
+  DETECT   drift findings: 0
+  FIX      iterations: 0, fixes applied: 0
+  AUDIT    anatomy: 0, brand: 0
+  FILL     bootstrapped: none, craft suggestions: 0
+
+Summary: 0 total findings (0 error, 0 warn, 0 info) in 142ms
+Verifiers run: detect-drift, audit-anatomy, audit-brand, design-craft-critique
+```
+
+### Example: Project with drift, `--fix` enabled
+
+```
+$ harness design-pipeline --fix
+
+Verdict: ⚠ warn
+
+Phases:
+  FRESHEN  inputs: DESIGN.md=yes tokens.json=yes registry=yes brand=yes
+  DETECT   drift findings: 14
+  FIX      iterations: 3, fixes applied: 9
+  AUDIT    anatomy: 1, brand: 0
+  FILL     bootstrapped: none, craft suggestions: 4
+
+Summary: 5 total findings (0 error, 5 warn, 0 info) in 1842ms
+Verifiers run: detect-drift, align-design-system, audit-anatomy, audit-brand, design-craft-critique
+```
+
+(9 drift fixes auto-applied in convergence loop; 5 remaining warnings + 4 craft suggestions for human review)
+
+### Example: Empty project, FILL bootstraps inputs
+
+```
+$ harness design-pipeline
+
+Verdict: ⚠ warn
+
+Phases:
+  FRESHEN  inputs: DESIGN.md=no tokens.json=no registry=no brand=no
+  DETECT   drift findings: 0
+  FIX      iterations: 0, fixes applied: 0
+  AUDIT    anatomy: 0, brand: 0
+  FILL     bootstrapped: designMd, tokensJson, componentRegistry, brandRules, craft suggestions: 0
+
+Summary: 0 total findings (0 error, 0 warn, 0 info) in 89ms
+```
+
+(All inputs absent; FILL wrote minimal stubs; verdict `warn` because bootstrap occurred — author the TODO sections to clear it.)
+
+## Gates
+
+- **No new verifier logic.** Iron Law. Delegate to sub-skills exclusively.
+- **No graph schema changes.** Findings persist through the existing `DesignConstraintAdapter.recordFindings()` path.
+- **No interactive prompts in v1.** `--fix` applies safe codemods silently; probably-safe / unsafe surface as suggestions only. `--ci` is the default behavior in v1; v1.x adds `--interactive` for terminal sessions.
+- **No standalone `harness validate` invocation.** validate stays single-pass; the orchestrator is opt-in.
+- **No DESIGN.md content generation.** Bootstrap writes stubs with TODO comments — sample content rots faster than skeletons.
+
+## Escalation
+
+- **When the convergence loop hits maxIterations without converging:** check `context.summary.iterationsRun === 5`. Real fix oscillation almost always indicates a conflict between drift findings (e.g., two tokens with the same value). Inspect `fixesApplied` outcomes; the failing pattern is usually visible.
+- **When a verifier consistently fails:** `context.verifiersFailed[].error` carries the message. Run the verifier standalone (e.g. `harness skill run audit-brand-compliance`) to reproduce — orchestrator just propagates the failure.
+- **When FILL bootstraps a file you didn't want bootstrapped:** delete the stub; the orchestrator only writes when the file is absent. Or run with `--no-fill` to suppress the entire phase.
+- **When verdict is `fail` but you want to merge anyway:** the orchestrator exits with code 1; bypass via CI config (treating design-pipeline as advisory not blocking). Not recommended — error-severity findings represent declared violations.
+- **When `--ci` mode is too conservative:** v1's `--ci` only applies align's `safe-codemod`-classified fixes. Use v1.x's `--interactive` (or the standalone `harness align-design-system --dry-run`) to review and apply probably-safe fixes manually.
+
+## Status
+
+**v1 — in implementation.** See:
+
+- Spec: `docs/changes/design-pipeline/orchestrator/proposal.md`
+- Roadmap entry: `design-pipeline sub-project #5` (the orchestrator)
+- Sibling: `harness-docs-pipeline` (the pattern this mirrors)
+- Floor + ceiling sub-skills: `detect-design-drift` (#1), `align-design-system` (#1), `audit-component-anatomy` (#2), `audit-brand-compliance` (#3), `check-design` (#4), `harness-design-craft` (#6)

package/dist/agents/skills/claude-code/harness-design-pipeline/skill.yaml

@@ -0,0 +1,70 @@
+name: harness-design-pipeline
+version: "0.1.0"
+description: Orchestrator composing detect-design-drift, align-design-system, audit-component-anatomy, audit-brand-compliance, and design-craft-elevator into a sequential pipeline with convergence-based remediation. Mirrors harness-docs-pipeline. Consumes the formal verifier interface generically.
+stability: draft
+cognitive_mode: constructive-architect
+triggers:
+  - manual
+  - on_pr
+  - on_new_feature
+platforms:
+  - claude-code
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+cli:
+  command: harness design-pipeline
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: fix
+      description: Enable convergence-based remediation
+      required: false
+    - name: no-freshen
+      description: Skip the FRESHEN phase
+      required: false
+    - name: no-fill
+      description: Skip the FILL phase
+      required: false
+    - name: ci
+      description: Non-interactive (safe fixes only)
+      required: false
+mcp:
+  tool: run_design_pipeline
+  input:
+    path: string
+    fix: boolean
+type: rigid
+tier: 2
+phases:
+  - name: freshen
+    description: Check input freshness (DESIGN.md, tokens.json, graph staleness)
+    required: false
+  - name: detect
+    description: Invoke detect-design-drift; collect DRIFT-* findings
+    required: true
+  - name: fix
+    description: Convergence loop with align-design-system (only when --fix is set)
+    required: false
+  - name: audit
+    description: Generic Verifier<F> registry loop (audit-anatomy + audit-brand)
+    required: true
+  - name: fill
+    description: Bootstrap missing inputs + invoke design-craft POLISH
+    required: false
+  - name: report
+    description: Compute verdict + summary
+    required: true
+state:
+  persistent: false
+depends_on:
+  - detect-design-drift
+  - align-design-system
+  - audit-component-anatomy
+  - audit-brand-compliance
+  - harness-design-craft