Add PIA UI quality OpenCode skill

.opencode/REGISTRY.md

@@ -1,7 +1,7 @@
 # opencode System Registry
 
 **Generated:** 2026-06-20
-**Counts:** 25 agents, 28 commands, 12 skills
+**Counts:** 25 agents, 30 commands, 20 skills
 
 > This registry enumerates every agent, command, and skill in the opencode system layer. Maintained alongside the source files; CI verifies counts match actual file counts.
 
@@ -46,7 +46,7 @@
 | Mobile UI orchestration (13 specialists + orchestrator) | `mobile-ui-orchestrator`, `accessibility-performance-validator`, `design-system-architect`, `evidence-regression-controller`, `frontend-implementer`, `iphone-interaction-specialist`, `product-ux-analyst`, `real-ui-product-tester`, `repository-discovery`, `visual-concept-prototyper`, `workflow-improvement-reviewer`, `feature-advocate`, `feature-critic`, `feature-judge` |
 | Security/architecture (read-only)                       | `architect`, `data-modeler`, `security`                                                                                                                                                                                                                                                                                                                                            |
 
-## Commands (28)
+## Commands (30)
 
 | Command                       | Agent                    | Description                                        |
 | ----------------------------- | ------------------------ | -------------------------------------------------- |
@@ -78,23 +78,33 @@
 | `/security-review`            | `security`               | Focused security and privacy review                |
 | `/task-review`                | `reviewer`               | Verify one implemented backlog task                |
 | `/task-run`                   | `delivery`               | Execute one backlog task                           |
-
-## Skills (12)
-
-| Skill                        | Description                                                                                     |
-| ---------------------------- | ----------------------------------------------------------------------------------------------- |
-| `approval-gated-redesign`    | Enforce decision packets, explicit approvals, contract boundaries, decision-ledger traceability |
-| `database-migration`         | Design and verify PostgreSQL migrations with tenant isolation and forward compatibility         |
-| `design-contract`            | Convert approved concepts into human-readable and machine-readable design system                |
-| `evidence-bundle`            | Build redacted, traceable evidence package from baseline through delivery                       |
-| `iphone-16-pro-pwa`          | iPhone 16 Pro portrait-first, network-required PWA design and validation                        |
-| `real-ui-validation`         | Validate real running application without mock-only evidence                                    |
-| `repository-adapter`         | Detect and document repository architecture, commands, runtime, and protected areas             |
-| `repository-docs-analysis`   | Map repository evidence, detect stale documentation, identify contradictions                    |
-| `repository-docs-update`     | Apply evidence-backed documentation edits with approval gates                                   |
-| `repository-docs-validation` | Validate documentation structure, links, commands, factual claims, and secrets                  |
-| `retrieval-quality`          | Implement hybrid retrieval, ACL filtering, version-aware citations, and ranking                 |
-| `task-execution`             | Execute one machine-readable backlog task with dependency and validation controls               |
+| `/ui-quality-audit`           | `mobile-ui-orchestrator` | Read-only UI quality audit                         |
+| `/ui-quality-fix`             | `mobile-ui-orchestrator` | Apply bounded approved UI quality fixes            |
+
+## Skills (20)
+
+| Skill                            | Description                                                                                     |
+| -------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `approval-gated-redesign`        | Enforce decision packets, explicit approvals, contract boundaries, decision-ledger traceability |
+| `brand-system-quality`           | Keep PIA identity, screenshots, icons, and visual language consistent                           |
+| `database-migration`             | Design and verify PostgreSQL migrations with tenant isolation and forward compatibility         |
+| `design-contract`                | Convert approved concepts into human-readable and machine-readable design system                |
+| `design-contract-lint`           | Review design contracts for completeness and implementation readiness                           |
+| `evidence-bundle`                | Build redacted, traceable evidence package from baseline through delivery                       |
+| `image-to-implementation-bridge` | Translate visual references into contract-compatible implementation guidance                    |
+| `iphone-16-pro-pwa`              | iPhone 16 Pro portrait-first, network-required PWA design and validation                        |
+| `mobile-state-design`            | Ensure mobile and PWA screens represent real application states clearly                         |
+| `output-completeness`            | Require complete implementation, explicit blockers, and evidence-backed reporting               |
+| `readme-landing-quality`         | Improve public-facing README, documentation landing sections, and project presentation          |
+| `real-ui-validation`             | Validate real running application without mock-only evidence                                    |
+| `repository-adapter`             | Detect and document repository architecture, commands, runtime, and protected areas             |
+| `repository-docs-analysis`       | Map repository evidence, detect stale documentation, identify contradictions                    |
+| `repository-docs-update`         | Apply evidence-backed documentation edits with approval gates                                   |
+| `repository-docs-validation`     | Validate documentation structure, links, commands, factual claims, and secrets                  |
+| `retrieval-quality`              | Implement hybrid retrieval, ACL filtering, version-aware citations, and ranking                 |
+| `task-execution`                 | Execute one machine-readable backlog task with dependency and validation controls               |
+| `ui-quality`                     | Apply PIA-specific UI quality checks while preserving approved contracts and existing stack     |
+| `visual-concept-quality`         | Improve mobile visual concepts before they become design decisions or contracts                 |
 
 ## CI Assertions
 

.opencode/agents/accessibility-performance-validator.md

@@ -35,6 +35,13 @@ permission:
 
 Independently validate the implemented product.
 
+Use these skills as checklists, not as substitutes for measured results:
+
+- `ui-quality` for visual hierarchy, state completeness, safe-area behavior, and interaction polish;
+- `mobile-state-design` for loading, empty, error, offline, streaming, interrupted, and approval-required states;
+- `design-contract-lint` when contract completeness or contract drift is part of validation;
+- `output-completeness` before issuing the final validation report.
+
 Accessibility target:
 
 - WCAG 2.2 AA minimum;

.opencode/agents/frontend-implementer.md

@@ -49,6 +49,9 @@ Before changing files, verify:
 During implementation:
 
 - follow the approved design contract;
+- use `ui-quality` for `apps/web`, shared CSS, page builders, and mobile/PWA UI polish;
+- use `mobile-state-design` when a change touches loading, empty, error, disabled, streaming, offline, or approval-required states;
+- use `output-completeness` before reporting completion;
 - preserve real data and integrations;
 - do not add mocks as a substitute;
 - keep commits atomic and decision-linked;

.opencode/agents/mobile-ui-orchestrator.md

@@ -78,6 +78,20 @@ Transform the current repository into a highly interactive, powerful, iPhone 16
 9. Keep commits small and traceable to decisions and contracts.
 10. On failure, preserve evidence, perform root-cause analysis, update contracts, and require approval before retry.
 
+## UI quality skill routing
+
+Use the local UI-quality skill set as bounded checklists inside the approved workflow:
+
+- `visual-concept-quality` during concept production and concept critique;
+- `brand-system-quality` for app identity, screenshots, icons, and public visual language;
+- `image-to-implementation-bridge` when screenshots, image references, or generated frames might influence implementation;
+- `design-contract-lint` before declaring a contract implementation-ready;
+- `ui-quality` for approved `apps/web` and `.ui-redesign` UI work;
+- `mobile-state-design` for state coverage on mobile/PWA flows;
+- `output-completeness` before final reporting.
+
+These skills do not authorize implementation. Approved repository artifacts remain authoritative.
+
 ## Initial execution
 
 When no approved repository adapter exists:
@@ -200,6 +214,11 @@ When to use the panel:
 - When a specialist raises a concern that warrants multi-perspective evaluation
 - When two specialists disagree and the conflict needs structured resolution
 
+## UI quality commands
+
+- Use `/ui-quality-audit` for read-only review of current UI surfaces, state coverage, contract drift, and fix recommendations.
+- Use `/ui-quality-fix` only after a bounded fix scope or decision ID is approved.
+
 ## Delegation
 
 Use specialists for bounded work. Provide them with the exact phase, evidence, repository paths, contracts, and expected output. Do not ask a specialist to make product decisions outside its role.
@@ -210,6 +229,7 @@ When delegating, always include in your message:
 2. Reference to the context cache ("Read `.ui-redesign/state/CONTEXT_CACHE.md` first")
 3. The expected output format
 4. Any protected areas relevant to the task
+5. Which UI-quality skill, if any, applies as a checklist
 
 ## Final acceptance
 
@@ -218,8 +238,4 @@ Do not declare completion until:
 - all required automated checks pass;
 - physical device checks pass;
 - automated and device results agree;
-- feature parity is resolved;
-- evidence is redacted and indexed;
-- rollback instructions exist;
-- the pull request is complete;
-- the user explicitly accepts the evidence bundle.
+- output completeness has been checked for omitted work, placeholder implementation, and unsupported claims.

.opencode/agents/visual-concept-prototyper.md

@@ -36,6 +36,9 @@ Create materially distinct concepts only after the orchestrator supplies an appr
 
 Requirements:
 
+- use `visual-concept-quality` to generate and critique materially different mobile concept directions;
+- use `brand-system-quality` when concepts affect identity, app icon, screenshots, or public visual language;
+- use `image-to-implementation-bridge` when visual references might influence implementation scope;
 - use real product content and real repository data;
 - do not invent labels, entities, metrics, or workflows;
 - store all work under `.ui-redesign/concepts/<concept-id>/`;

.opencode/agents/workflow-improvement-reviewer.md

@@ -44,7 +44,8 @@ Identify:
 - missing validation;
 - agent overlap;
 - commands that failed or were ambiguous;
-- instructions that produced inconsistent behavior.
+- instructions that produced inconsistent behavior;
+- opportunities to apply `ui-quality`, `visual-concept-quality`, `mobile-state-design`, `design-contract-lint`, or `output-completeness` more precisely.
 
 Propose:
 

.opencode/commands/ui-quality-audit.md

@@ -0,0 +1,10 @@
+---
+description: Run a read-only UI quality audit against approved PIA contracts and current app surfaces.
+agent: mobile-ui-orchestrator
+---
+
+Requested scope:
+
+$ARGUMENTS
+
+Run a read-only audit using `ui-quality`, `mobile-state-design`, and `design-contract-lint` when applicable. Inspect only the requested surfaces or the current approved mobile UI scope. Use approved repository artifacts as authority. Produce findings with severity, source paths, affected states, approval requirements, and a validation plan. Do not modify product code.

.opencode/commands/ui-quality-fix.md

@@ -0,0 +1,10 @@
+---
+description: Apply a bounded approved UI quality fix while preserving PIA contracts, stack, and validation requirements.
+agent: mobile-ui-orchestrator
+---
+
+Approved scope or decision ID:
+
+$ARGUMENTS
+
+Before editing, verify the approved scope, affected files, contract authority, dependency status, tests, and rollback path. Use `ui-quality` and `output-completeness`. Apply only the approved fix. Stop if a new design decision, route/API change, dependency change, data behavior change, or protected-area change appears. Report changed files, checks run, residual risks, and next validation step.

.opencode/skills/brand-system-quality/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: brand-system-quality
+description: Keep PIA public identity, app chrome, icons, screenshots, and visual language consistent with the trust-first product posture.
+compatibility: opencode
+metadata:
+  audience: docs-and-ui-agents
+  output: brand-quality-review
+---
+
+## Use this skill when
+
+A task touches `README.md`, `assets/`, `.ui-redesign/concepts/`, `.ui-redesign/contracts/`, `apps/web/public/`, icons, screenshots, or visual identity language.
+
+## Brand posture
+
+PIA should feel private, reliable, evidence-grounded, and controlled. Avoid decorative choices that imply uncontrolled autonomy or generic AI hype.
+
+## Checklist
+
+Verify:
+
+- the single approved accent remains dominant;
+- screenshots and icons feel consistent;
+- app identity supports retrieval, citations, memory, and approved actions;
+- no generic purple AI-gradient motif is introduced;
+- color, type, and surfaces align with approved contracts;
+- public copy is specific and calm;
+- PWA icons and app labels match the product name and current manifest intent;
+- visual assets have clear source paths and update rationale.
+
+## Output
+
+Return:
+
+1. inspected brand surfaces;
+2. inconsistencies;
+3. proposed corrections;
+4. contract or asset updates required;
+5. validation plan.

.opencode/skills/design-contract-lint/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: design-contract-lint
+description: Review PIA design contracts for completeness, internal consistency, and implementation readiness before product changes begin.
+compatibility: opencode
+metadata:
+  audience: design-system-and-validation-agents
+  output: contract-lint-report
+---
+
+## Use this skill when
+
+A task writes, reviews, or updates `.ui-redesign/contracts/*` artifacts.
+
+## Lint checklist
+
+Validate that the contract includes:
+
+- target devices and environments;
+- semantic tokens;
+- typography, spacing, shape, elevation, and motion rules;
+- reduced-motion behavior;
+- safe-area and dynamic-viewport behavior;
+- component anatomy;
+- loading, empty, error, disabled, offline, and success states;
+- accessibility requirements;
+- PWA behavior;
+- data policy;
+- decision references;
+- validation plan;
+- rollback notes.
+
+## Consistency checks
+
+Flag:
+
+- Markdown and JSON contract disagreement;
+- unresolved choices hidden as prose;
+- token names used without definitions;
+- components without states;
+- states without validation;
+- references to unavailable files;
+- visual decisions not tied to approved decisions;
+- dependency or route implications without approval path.
+
+## Output
+
+Return:
+
+1. contract paths inspected;
+2. pass/fail summary;
+3. blocking issues;
+4. non-blocking issues;
+5. required decision packets;
+6. implementation readiness verdict.

.opencode/skills/image-to-implementation-bridge/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: image-to-implementation-bridge
+description: Translate visual references into contract-compatible PIA implementation guidance without treating images as direct authority.
+compatibility: opencode
+metadata:
+  audience: concept-and-frontend-agents
+  output: implementation-bridge
+---
+
+## Use this skill when
+
+A task uses screenshots, generated images, prototype frames, or visual references to influence PIA code or contracts.
+
+## Principle
+
+Images are evidence or inspiration. They are not implementation authority. Only approved decisions and contracts authorize product changes.
+
+## Procedure
+
+1. Describe the image objectively.
+2. Extract concrete UI details: layout, hierarchy, state, motion, density, color, and interaction cues.
+3. Compare extracted details against the approved adapter, decision ledger, and design contract.
+4. Classify each detail as:
+   - already approved;
+   - needs decision;
+   - rejected due to conflict;
+   - presentation-only.
+5. Convert eligible details into a decision packet or contract amendment.
+6. Do not implement until the resulting scope is approved.
+
+## Reject details that
+
+- require new routes or APIs;
+- invent data or product behavior;
+- violate approved tokens or safe-area rules;
+- weaken accessibility;
+- add unapproved dependencies;
+- change offline or PWA assumptions;
+- conflict with real PIA content or evidence.
+
+## Output
+
+Return a mapping table with: visual detail, source image/path, classification, required approval, and implementation note.

.opencode/skills/mobile-state-design/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: mobile-state-design
+description: Ensure PIA mobile and PWA screens represent real application states clearly and accessibly.
+compatibility: opencode
+metadata:
+  audience: mobile-ui-and-frontend-agents
+  output: state-coverage-review
+---
+
+## Use this skill when
+
+A task changes mobile or PWA UI for documents, search, conversations, citations, feedback, memory, approvals, uploads, or network behavior.
+
+## Required states
+
+For each relevant surface, account for:
+
+- initial loading;
+- empty data;
+- successful data;
+- validation error;
+- server or network error;
+- disabled or pending action;
+- retryable failure;
+- offline or reconnecting state;
+- streaming or in-progress output;
+- interrupted or cancelled output;
+- permission or approval-required state;
+- completed state.
+
+## State design rules
+
+- Use real product terms and state names.
+- Keep copy calm and specific.
+- Preserve touch targets and focus behavior.
+- Do not hide failed, quarantined, interrupted, or approval-required states behind generic error copy.
+- Keep citation and evidence states legible.
+- Represent disabled actions visibly and programmatically.
+- Avoid state colors that conflict with approved semantic tokens.
+
+## Output
+
+Return a state coverage matrix with surface, state, current behavior, gap, proposed fix, and validation method.