Add a shared design-lead workflow for Pickforge UI work

[ElbertePlinio]

Summary

Create a shared Pickforge UI workflow that gives one named model the design-lead role for substantial visual work. The design lead owns hierarchy, composition, interaction language, motion, and final screenshot acceptance; implementation and review models work against that locked direction instead of redesigning independently.

This is planning only. No skill or policy change is approved by this issue alone.

Problem

Prompts such as “make it premium” leave every model free to reinterpret the UI. Multiple models then make conflicting aesthetic decisions, producing inconsistent screens and expensive iteration.

The owner should provide product intent and references, not act as the visual designer. The workflow should make one model accountable for taste while keeping architecture, implementation, accessibility, and validation independently reviewable.

Recommended responsibility split

• AGENTS.md / CLAUDE.md: short policy and skill trigger only.
• New shared pickforge-ui skill: design-lead selection, reference audit, UI brief, handoff, screenshot loop, and final acceptance.
• Existing pickforge-design skill: keep brand assets and Claude Design sync responsibilities; do not overload it with app UI implementation workflow.
• GitHub Issue: canonical product scope, chosen design direction, decisions, and acceptance checklist.

Suggested policy language:

For substantial user-facing UI work, use the shared Pickforge UI workflow and name one design lead. Once the direction is locked, implementers and reviewers must not silently redesign it; proposed visual deviations return to the design lead for acceptance.

The design lead is a role, not a permanently hardcoded vendor. Fable is the default for taste-heavy work; Opus or another vision-capable model may own the role when routing or quota makes it the better fit.

Workflow hypothesis

1. Read the repo UI, design system, tokens, and existing components.
2. Inspect attached reference images/videos at fixed target viewports.
3. Produce a take / reject reference audit.
4. Name one design lead and record the model in the issue/brief.
5. Lock one direction: hierarchy, card/component anatomy, states, motion, and explicit anti-goals.
6. Hand the locked brief to the implementation model.
7. Use a vision-capable checker for screenshot comparison during iteration.
8. Return final screenshots to the same design lead for acceptance.
9. Run VRT/goldens, reduced-motion, keyboard, overflow, and contrast validation.

Proposed skill contents

• Lean SKILL.md containing the role protocol and workflow.
• One reusable UI brief template under assets/ or references/.
• Reference intake rules: use actual screenshots/video frames, not URLs alone.
• Required brief sections: outcome, one primary element, take/reject audit, data hierarchy, complete state inventory, resize behavior, motion/static contract, accessibility, proof.
• Handoff contract: implementers preserve the locked aesthetic direction and surface deviations explicitly.
• Acceptance contract: compare screenshots at agreed viewports and inspect the actual VRT images.
• Anti-slop rules: no unrequested gradients, glass, excessive glow, rainbow statuses, decorative dashboards, or meaningless motion.

Planning checklist

• Confirm canonical home and name; recommendation: pickforge-platform/skills/pickforge-ui/ with workspace linking.
• Confirm how Claude Code and Codex discover the same canonical skill without duplicated instructions.
• Define the minimal AGENTS.md and CLAUDE.md trigger text.
• Define design-lead selection and quota fallback rules.
• Define where the locked brief lives during work; recommendation: tracking issue/progress comment by default, committed doc only when durable product documentation is justified.
• Define screenshot/VRT acceptance states and target viewports.
• Forward-test the skill on one real Pickforge UI task before linking it studio-wide.
• Validate the skill package and linking script.

Non-goals

• Hardcode Fable for every UI change.
• Let the design lead change architecture, persistence, auth, security, or scope without owner approval.
• Duplicate the full brand system inside the skill.
• Replace branding-visual/ or the existing pickforge-design DesignSync workflow.
• Require this process for tiny token-aligned UI fixes with no design judgment.

Open decisions

• Should the skill be studio-wide immediately or prove itself in PickForge first?
• Should final design acceptance be mandatory for every substantial UI PR or only taste-heavy/high-visibility work?
• Is an issue comment sufficient as the locked brief, or should the skill emit a small temporary artifact for implementation handoff?

[ElbertePlinio]

Scope refinement: general core + Pickforge overlay

The design-lead workflow should be split into two skills, not one Pickforge-only package.

1. General personal skill: design-director (name provisional)

Use for greenfield projects, unfamiliar repos, existing-product UX/UI improvement, redesigns, marketing sites, desktop/mobile product surfaces, and focused component work.

Owns:

• design-lead selection per task (never permanently hardcode a model);
• the reusable prompt contract;
• greenfield / preserve / overhaul / targeted-improvement modes;
• repo and existing-design audit;
• reference take / reject analysis;
• information architecture, interaction states, visual hierarchy, motion/static contract, accessibility;
• implementation handoff, screenshot comparison, and final design-lead acceptance.

The installed design-taste-frontend skill may be used as a specialist reference for landing pages, portfolios, and marketing redesigns. It cannot be the general core because it explicitly excludes dashboards/product UI and contains React/Tailwind-specific defaults.

2. Pickforge workspace skill: pickforge-ui

Thin overlay that applies the general workflow and preloads Pickforge-specific constraints:

• local branding-visual/ remains the source of truth;
• app-local design docs, tokens, signature components, VRT/goldens, one-ember rule, Geist/Geist Mono;
• existing pickforge-design skill remains responsible for brand assets and Claude Design synchronization;
• on substantial Pickforge visual work, Claude Code may use DesignSync to read/compare only the relevant mirror files;
• non-Claude agents delegate that operation through claude -p "/pickforge-design <task>" when needed;
• if the mirror differs, local repo wins;
• durable design-system changes land in branding-visual/ first, then are pushed repo -> Claude Design after review/commit. Never edit the Claude Design mirror as the canonical copy.

Prompt-contract ownership

Keep the base prompt-contract.md only in design-director. pickforge-ui pre-fills/overrides its brand, component, motion, and validation sections. Do not maintain two copies.

Agent instruction precedence

• Global/personal instructions: use design-director for substantial UI/UX work unless a repo-specific design skill exists.
• Pickforge workspace instructions: use pickforge-ui; the overlay invokes/applies the general design-director workflow.
• AGENTS.md / CLAUDE.md contain short triggers only. Detailed procedure stays in the skills.

Updated planning checklist

• Decide the canonical personal home/repository for design-director before creating it.
• Define composition/invocation between design-director and pickforge-ui without duplicating the contract.
• Keep pickforge-design focused on brand/DesignSync.
• Forward-test the general skill on three cases: greenfield, unfamiliar-repo audit, and existing product UI improvement.
• Forward-test the Pickforge overlay on one real app surface and verify local repo -> Claude Design sync behavior.

General-skill tracking should not be forced into pickforge-platform until its canonical personal home is chosen. This issue remains the tracker for the Pickforge overlay and workspace integration.

[ElbertePlinio]

Agent plan

Goal: add the Pickforge-specific UI overlay on top of the reusable design-director workflow.

Checklist:

• Add the thin pickforge-ui skill without duplicating the prompt contract
• Load canonical brand and app-local design context
• Document the pickforge-design / DesignSync bridge
• Distribute the skill across workspace repos
• Forward-test one real Pickforge surface
• Validate skill metadata and workspace linking

Validation:

• skill quick validation
• workspace link script syntax and discovery
• real-surface dry run

Current status: In progress
Next action: scaffold the overlay in an isolated worktree

[ElbertePlinio]

Progress update:

• Added the thin pickforge-ui overlay
• Routed canonical brand/app-local context
• Kept DesignSync in pickforge-design and out of routine UI work
• Forward-tested the Orchestra usage-card case
• Codex PR review and merge

PR: #31
Blocked: none
Next: automatic review

[ElbertePlinio]

Done:

• pickforge-ui overlay merged
• Canonical brand/app context routing
• External dependencies documented and fail closed
• Codex findings fixed and round 2 clean
• Workspace links applied and implicit selection smoke-tested

PR: #31
Merged: c63edcc