From 69ad5073ff9f146f55abb181c380a10e054334d0 Mon Sep 17 00:00:00 2001 From: Merverli Date: Sat, 20 Jun 2026 15:27:39 -0500 Subject: [PATCH 01/21] Add PIA UI quality skill --- .opencode/skills/ui-quality/SKILL.md | 103 +++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 .opencode/skills/ui-quality/SKILL.md diff --git a/.opencode/skills/ui-quality/SKILL.md b/.opencode/skills/ui-quality/SKILL.md new file mode 100644 index 0000000..04614b9 --- /dev/null +++ b/.opencode/skills/ui-quality/SKILL.md @@ -0,0 +1,103 @@ +--- +name: ui-quality +description: Apply PIA-specific UI quality checks to web and mobile redesign work while preserving approved repository contracts, adapter constraints, and dependency gates. +compatibility: opencode +metadata: + audience: frontend-and-mobile-ui-agents + governance: contract-preserving +--- + +## Use this skill when + +A task touches `apps/web/`, `.ui-redesign/`, mobile/PWA surfaces, product-page HTML builders, shared CSS, UI states, visual hierarchy, interaction behavior, or design-contract validation. + +This skill is a local quality layer. It does not authorize implementation by itself. + +## Authority order + +Follow this precedence, highest first: + +1. `AGENTS.md` and the task-execution contract. +2. `.ui-redesign/adapter/REPOSITORY_ADAPTER.md`. +3. `.ui-redesign/decisions/DECISION_LEDGER.md`. +4. Approved `.ui-redesign/contracts/*` artifacts. +5. Existing route, API, data, and dependency boundaries. +6. This UI-quality skill. + +If this skill conflicts with an approved repository artifact, the approved repository artifact wins. + +## Hard boundaries + +Do not: + +- convert the frontend to React, Next.js, Vite, Tailwind, Motion, GSAP, shadcn/ui, or another framework; +- add third-party packages unless an approved dependency decision explicitly authorizes them; +- rewrite working server-rendered HTML builders into a new architecture; +- change routes, API contracts, persistence, schemas, infrastructure, deployment, or data behavior as a side effect of visual work; +- replace real data with mocks to make a screen look complete; +- ignore approval-gated redesign, design-contract, iPhone PWA, accessibility, or real-UI validation skills; +- treat image-generation or visual inspiration as implementation authority when a design contract exists. + +## Required workflow + +1. Scan the affected files and identify the current UI architecture, shared tokens, page builders, scripts, and tests. +2. Anchor every visual or behavioral decision to an approved source: design contract, decision ledger, repository adapter, existing baseline, or explicit user task. +3. Diagnose UI weaknesses before editing: typography, spacing, hierarchy, touch targets, safe areas, focus behavior, loading/error/empty states, status semantics, motion, and PWA constraints. +4. Fix surgically using the existing stack. Prefer tokenized CSS, semantic HTML, native browser behavior, and small page-builder changes. +5. Cross-check output completeness before reporting: no placeholder comments, no omitted states, no unverified claims, no invented tests. +6. Report evidence with changed files, tests/checks run, observed residual risks, and next validation step. Do not self-approve. + +## PIA visual quality checklist + +For every relevant UI change, check: + +- typography uses the approved system stack and readable line height; +- body text does not run too wide on desktop; +- iPhone 16 Pro viewport behavior uses `100dvh` or contract-approved alternatives rather than brittle `100vh` assumptions; +- safe-area insets are preserved for header, sheet, FAB, composer, and bottom navigation surfaces; +- tap targets satisfy the approved touch minimum; +- focus-visible behavior remains visible and keyboard-accessible; +- dialogs, sheets, and modals preserve focus handling; +- network loss, loading, empty, error, disabled, streaming, interrupted, failed, and success states are represented when applicable; +- status colors remain semantic and contract-aligned; +- motion uses approved motion tokens and honors reduced-motion behavior; +- z-index values use the established scale instead of arbitrary escalation; +- visual hierarchy makes the primary task clear without decorative noise; +- copy is specific, calm, and product-accurate; no generic AI phrases, lorem ipsum, fake dashboards, or placeholder names; +- meaningful images/icons have accessible text alternatives or are correctly hidden when decorative; +- no dead links, no buttons to `#`, and no navigation dead ends. + +## Anti-slop rules for PIA + +Avoid these patterns unless an approved contract explicitly requires them: + +- generic admin cards with border + white background + weak shadow everywhere; +- centered empty states with vague motivational copy; +- excessive pill badges or repeated status chips without hierarchy; +- purple/blue AI-gradient decoration unrelated to PIA's approved single-accent system; +- all-caps labels everywhere; +- inconsistent gray families or unapproved accent colors; +- hardcoded pixel layouts that break on iPhone safe areas; +- non-semantic `div` structures where `main`, `nav`, `section`, `article`, `form`, `dialog`, `button`, `table`, `dl`, or `output` would be more accurate; +- decorative motion that competes with reading, retrieval, citations, or approval decisions. + +## Output completeness rules + +Before final response, verify: + +- every requested file/change was completed or explicitly blocked by an approved stop condition; +- no placeholder such as `TODO`, `implementation omitted`, `add more here`, or `left as exercise` was used as a substitute for work; +- every claim about tests, screenshots, device validation, or accessibility is backed by a real command or artifact; +- if output must be split, stop at a clean boundary and state exactly what remains. + +## Stop conditions + +Stop and report instead of editing when: + +- the task would require a new design decision; +- the task would modify protected areas without approval; +- the approved design contract is missing, stale, or contradictory; +- dependency installation is required but not approved; +- real-data or real-device evidence is required but unavailable; +- accessibility, performance, PWA, or security evidence contradicts the intended change; +- the requested aesthetic conflicts with PIA's trust-first, evidence-grounded product posture. From cbbbf01f18ca5d2a2cea80fcc33f94f2b023f943 Mon Sep 17 00:00:00 2001 From: Merverli Date: Sat, 20 Jun 2026 15:27:59 -0500 Subject: [PATCH 02/21] Register PIA UI quality skill --- .opencode/REGISTRY.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.opencode/REGISTRY.md b/.opencode/REGISTRY.md index d48d586..ab7b740 100644 --- a/.opencode/REGISTRY.md +++ b/.opencode/REGISTRY.md @@ -1,7 +1,7 @@ # opencode System Registry **Generated:** 2026-06-20 -**Counts:** 25 agents, 28 commands, 12 skills +**Counts:** 25 agents, 28 commands, 13 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. @@ -79,7 +79,7 @@ | `/task-review` | `reviewer` | Verify one implemented backlog task | | `/task-run` | `delivery` | Execute one backlog task | -## Skills (12) +## Skills (13) | Skill | Description | | ---------------------------- | ----------------------------------------------------------------------------------------------- | @@ -95,6 +95,7 @@ | `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 | ## CI Assertions From ffb36a25c5944dcff6324edc9686f1022c09b881 Mon Sep 17 00:00:00 2001 From: Merverli Date: Sat, 20 Jun 2026 16:11:15 -0500 Subject: [PATCH 03/21] Add visual concept quality skill --- .../skills/visual-concept-quality/SKILL.md | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 .opencode/skills/visual-concept-quality/SKILL.md diff --git a/.opencode/skills/visual-concept-quality/SKILL.md b/.opencode/skills/visual-concept-quality/SKILL.md new file mode 100644 index 0000000..3d9d372 --- /dev/null +++ b/.opencode/skills/visual-concept-quality/SKILL.md @@ -0,0 +1,47 @@ +--- +name: visual-concept-quality +description: Improve PIA mobile visual concepts before they become design decisions or contracts. +compatibility: opencode +metadata: + audience: visual-concept-prototyper + output: concept-critique +--- + +## Use this skill when + +A task creates, reviews, or compares concept artifacts under `.ui-redesign/concepts/`, `.ui-redesign/reports/`, or `.ui-redesign/decisions/`. + +## Rules + +- Concepts are advisory until converted into an approved decision or contract. +- Use real product content and known PIA states. +- Produce at least two materially different directions when concept selection is open. +- Do not create new routes, data behavior, dependencies, or implementation scope through a concept. +- Preserve iPhone 16 Pro portrait, network-required PWA, safe-area, accessibility, and evidence-first product constraints. + +## Concept checklist + +Evaluate each concept for: + +- product read: private intelligence, retrieval, citations, memory, and governed actions; +- primary flow clarity; +- bottom navigation, sheets, composer, citations, feedback, and status surfaces; +- loading, empty, error, disabled, streaming, interrupted, and offline states; +- density and reading comfort on 393 x 852 logical viewport; +- touch target clarity; +- evidence and citation legibility; +- trust-first tone; +- generic AI dashboard risk; +- implementation-contract readiness. + +## Output + +Return: + +1. concept ID and inspected paths; +2. strengths; +3. weaknesses; +4. generic-pattern risks; +5. contract-ready details; +6. rejected details and why; +7. recommendation: ACCEPT, REJECT, HYBRID, or REVISE. From f2fa8986e7f701e194f4b4ebe897d4c8c0e1fceb Mon Sep 17 00:00:00 2001 From: Merverli Date: Sat, 20 Jun 2026 16:11:23 -0500 Subject: [PATCH 04/21] Add output completeness skill --- .opencode/skills/output-completeness/SKILL.md | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 .opencode/skills/output-completeness/SKILL.md diff --git a/.opencode/skills/output-completeness/SKILL.md b/.opencode/skills/output-completeness/SKILL.md new file mode 100644 index 0000000..835bc04 --- /dev/null +++ b/.opencode/skills/output-completeness/SKILL.md @@ -0,0 +1,58 @@ +--- +name: output-completeness +description: Prevent partial agent work by requiring complete implementation, explicit blockers, and evidence-backed reporting. +compatibility: opencode +metadata: + audience: implementation-and-review-agents + output: completion-check +--- + +## Use this skill when + +A task modifies files, reports task completion, produces a run record, writes a review, or summarizes validation. + +## Completion standard + +A response is complete only when each requested item is either: + +- implemented; +- verified as already satisfied; +- explicitly out of scope with source-backed reason; +- blocked by a named stop condition. + +## Forbidden substitutes + +Do not use any of these as implementation: + +- placeholder TODO comments; +- omitted sections; +- fake tests; +- invented screenshots; +- invented device results; +- vague follow-up promises; +- summaries that hide incomplete files. + +## Required final check + +Before reporting, verify: + +- changed files are listed; +- tests or checks are listed exactly as run; +- skipped checks include the reason; +- generated artifacts are named; +- residual risks are explicit; +- next validation step is concrete; +- no claim depends on unobserved evidence. + +## Output + +Return: + +1. requested work; +2. completed work; +3. files changed; +4. checks run; +5. evidence produced; +6. blocked or deferred items; +7. residual risks; +8. next validation step. From 865b4d18782169438f65251a61711e7708c66d5e Mon Sep 17 00:00:00 2001 From: Merverli Date: Sat, 20 Jun 2026 16:11:31 -0500 Subject: [PATCH 05/21] Add image to implementation bridge skill --- .../image-to-implementation-bridge/SKILL.md | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 .opencode/skills/image-to-implementation-bridge/SKILL.md diff --git a/.opencode/skills/image-to-implementation-bridge/SKILL.md b/.opencode/skills/image-to-implementation-bridge/SKILL.md new file mode 100644 index 0000000..6ef192e --- /dev/null +++ b/.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. From daa1db50814a9053c9c0df24fbf8ecf71d5e382e Mon Sep 17 00:00:00 2001 From: Merverli Date: Sat, 20 Jun 2026 16:11:38 -0500 Subject: [PATCH 06/21] Add README landing quality skill --- .../skills/readme-landing-quality/SKILL.md | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 .opencode/skills/readme-landing-quality/SKILL.md diff --git a/.opencode/skills/readme-landing-quality/SKILL.md b/.opencode/skills/readme-landing-quality/SKILL.md new file mode 100644 index 0000000..3b871ed --- /dev/null +++ b/.opencode/skills/readme-landing-quality/SKILL.md @@ -0,0 +1,45 @@ +--- +name: readme-landing-quality +description: Improve public-facing README, documentation landing sections, and project presentation without changing product behavior. +compatibility: opencode +metadata: + audience: repository-docs-agents + output: docs-quality-review +--- + +## Use this skill when + +A task edits `README.md`, top-level docs, screenshots, assets, badges, roadmap summaries, or public project-positioning copy. + +## Scope + +This skill applies to presentation and documentation. It does not authorize product code changes. + +## Quality checklist + +Check that public-facing material has: + +- clear first-screen value proposition; +- specific audience and use case; +- concrete feature evidence; +- readable visual hierarchy; +- consistent roadmap and status language; +- screenshots or image references when they materially help; +- no generic AI marketing phrases; +- no unsupported claims; +- no stale task counts or command counts; +- links that point to real repository paths. + +## PIA tone + +Use direct, trust-first language. Prefer evidence, provenance, approvals, isolation, retrieval quality, and auditability over vague claims about intelligence or automation. + +## Output + +Return: + +1. inspected paths; +2. stale or weak claims; +3. hierarchy issues; +4. proposed copy changes; +5. validation required. From b3b76c5f080924a6a41e2e4e8ece00b9c6d36b4a Mon Sep 17 00:00:00 2001 From: Merverli Date: Sat, 20 Jun 2026 16:11:45 -0500 Subject: [PATCH 07/21] Add brand system quality skill --- .../skills/brand-system-quality/SKILL.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 .opencode/skills/brand-system-quality/SKILL.md diff --git a/.opencode/skills/brand-system-quality/SKILL.md b/.opencode/skills/brand-system-quality/SKILL.md new file mode 100644 index 0000000..1ebb15b --- /dev/null +++ b/.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. From cafd28669c5e7aa421c05249020c5cf70686f1f6 Mon Sep 17 00:00:00 2001 From: Merverli Date: Sat, 20 Jun 2026 16:11:54 -0500 Subject: [PATCH 08/21] Add mobile state design skill --- .opencode/skills/mobile-state-design/SKILL.md | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 .opencode/skills/mobile-state-design/SKILL.md diff --git a/.opencode/skills/mobile-state-design/SKILL.md b/.opencode/skills/mobile-state-design/SKILL.md new file mode 100644 index 0000000..7766fbb --- /dev/null +++ b/.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. From e869ac4fb817f2033dd50a62bd1cca41817b8249 Mon Sep 17 00:00:00 2001 From: Merverli Date: Sat, 20 Jun 2026 16:12:01 -0500 Subject: [PATCH 09/21] Add design contract lint skill --- .../skills/design-contract-lint/SKILL.md | 54 +++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 .opencode/skills/design-contract-lint/SKILL.md diff --git a/.opencode/skills/design-contract-lint/SKILL.md b/.opencode/skills/design-contract-lint/SKILL.md new file mode 100644 index 0000000..6a5d535 --- /dev/null +++ b/.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. From 21457b5f534f1761b7037ac9b2ddd20a76c3e287 Mon Sep 17 00:00:00 2001 From: Merverli Date: Sat, 20 Jun 2026 16:12:06 -0500 Subject: [PATCH 10/21] Add UI quality audit command --- .opencode/commands/ui-quality-audit.md | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 .opencode/commands/ui-quality-audit.md diff --git a/.opencode/commands/ui-quality-audit.md b/.opencode/commands/ui-quality-audit.md new file mode 100644 index 0000000..be02af8 --- /dev/null +++ b/.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. \ No newline at end of file From 2ab2c6b5359e3770ef8682cd98802d16c4ac5c84 Mon Sep 17 00:00:00 2001 From: Merverli Date: Sat, 20 Jun 2026 16:12:12 -0500 Subject: [PATCH 11/21] Add UI quality fix command --- .opencode/commands/ui-quality-fix.md | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 .opencode/commands/ui-quality-fix.md diff --git a/.opencode/commands/ui-quality-fix.md b/.opencode/commands/ui-quality-fix.md new file mode 100644 index 0000000..5f1f1ff --- /dev/null +++ b/.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. \ No newline at end of file From 78b7d4bd33275f2f9e6dd81949df9dbb2f02131c Mon Sep 17 00:00:00 2001 From: Merverli Date: Sat, 20 Jun 2026 16:12:16 -0500 Subject: [PATCH 12/21] Add UI quality audit template --- .../templates/ui-quality-audit-template.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 .opencode/templates/ui-quality-audit-template.md diff --git a/.opencode/templates/ui-quality-audit-template.md b/.opencode/templates/ui-quality-audit-template.md new file mode 100644 index 0000000..6dcc14d --- /dev/null +++ b/.opencode/templates/ui-quality-audit-template.md @@ -0,0 +1,27 @@ +# UI Quality Audit + +## Scope + +## Sources inspected + +## Approved authority + +## Findings + +| Severity | Finding | Evidence path | Affected surface | Required action | +| --- | --- | --- | --- | --- | + +## State coverage + +| Surface | State | Current behavior | Gap | Proposed fix | +| --- | --- | --- | --- | --- | + +## Accessibility and mobile coverage + +## Contract drift + +## Recommended fixes + +## Approval required + +## Validation plan From 12ee59a34757ba60d122b4843509972b6c349ea7 Mon Sep 17 00:00:00 2001 From: Merverli Date: Sat, 20 Jun 2026 16:12:21 -0500 Subject: [PATCH 13/21] Add visual concept critique template --- .../visual-concept-critique-template.md | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 .opencode/templates/visual-concept-critique-template.md diff --git a/.opencode/templates/visual-concept-critique-template.md b/.opencode/templates/visual-concept-critique-template.md new file mode 100644 index 0000000..e36abfe --- /dev/null +++ b/.opencode/templates/visual-concept-critique-template.md @@ -0,0 +1,23 @@ +# Visual Concept Critique + +## Concept ID + +## Product read + +## Strengths + +## Weaknesses + +## Generic-pattern risk + +## Mobile interaction risk + +## Evidence and citation clarity + +## State coverage + +## Contract readiness + +## Recommendation + +Use one: ACCEPT, REJECT, HYBRID, or REVISE. From cbc7422d14f9ac1e080089e86e6de999975126fc Mon Sep 17 00:00:00 2001 From: Merverli Date: Sat, 20 Jun 2026 16:12:26 -0500 Subject: [PATCH 14/21] Add output completeness check template --- .../output-completeness-check-template.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 .opencode/templates/output-completeness-check-template.md diff --git a/.opencode/templates/output-completeness-check-template.md b/.opencode/templates/output-completeness-check-template.md new file mode 100644 index 0000000..ce64fb8 --- /dev/null +++ b/.opencode/templates/output-completeness-check-template.md @@ -0,0 +1,19 @@ +# Output Completeness Check + +## Requested work + +## Completed work + +## Files changed + +## Tests/checks run + +## Evidence produced + +## Not completed + +## Stop conditions hit + +## Residual risks + +## Next validation step From 4898fd76c6efeea3b68296d085b8a0cdccf9f534 Mon Sep 17 00:00:00 2001 From: Merverli Date: Sat, 20 Jun 2026 16:12:52 -0500 Subject: [PATCH 15/21] Register UI quality additions --- .opencode/REGISTRY.md | 49 +++++++++++++++++++++++++------------------ 1 file changed, 29 insertions(+), 20 deletions(-) diff --git a/.opencode/REGISTRY.md b/.opencode/REGISTRY.md index ab7b740..4ce7883 100644 --- a/.opencode/REGISTRY.md +++ b/.opencode/REGISTRY.md @@ -1,7 +1,7 @@ # opencode System Registry **Generated:** 2026-06-20 -**Counts:** 25 agents, 28 commands, 13 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,24 +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 (13) - -| 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` | Apply PIA-specific UI quality checks while preserving approved contracts and existing stack | +| `/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 From 1225dbc9c86c0ff33a1dfb868d459dbfcdfcfcef Mon Sep 17 00:00:00 2001 From: Merverli Date: Sat, 20 Jun 2026 16:14:06 -0500 Subject: [PATCH 16/21] Reference UI quality skills in frontend implementer --- .opencode/agents/frontend-implementer.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.opencode/agents/frontend-implementer.md b/.opencode/agents/frontend-implementer.md index 8489abd..538b648 100644 --- a/.opencode/agents/frontend-implementer.md +++ b/.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; From b9343db44ea478730c79286e1f162c06546be05f Mon Sep 17 00:00:00 2001 From: Merverli Date: Sat, 20 Jun 2026 16:14:16 -0500 Subject: [PATCH 17/21] Reference concept quality skills in visual prototyper --- .opencode/agents/visual-concept-prototyper.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.opencode/agents/visual-concept-prototyper.md b/.opencode/agents/visual-concept-prototyper.md index a13e063..b5cbb35 100644 --- a/.opencode/agents/visual-concept-prototyper.md +++ b/.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//`; From 3e3180afa26bc8e4659543d3c831ddfe5717a645 Mon Sep 17 00:00:00 2001 From: Merverli Date: Sat, 20 Jun 2026 16:14:27 -0500 Subject: [PATCH 18/21] Reference UI quality validation skills --- .opencode/agents/accessibility-performance-validator.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/.opencode/agents/accessibility-performance-validator.md b/.opencode/agents/accessibility-performance-validator.md index 0bf177b..16cfc68 100644 --- a/.opencode/agents/accessibility-performance-validator.md +++ b/.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; From 0db07dca630fbf02867d50cf1ef0243f0d9586d3 Mon Sep 17 00:00:00 2001 From: Merverli Date: Sat, 20 Jun 2026 16:14:42 -0500 Subject: [PATCH 19/21] Reference UI quality workflow improvements --- .opencode/agents/workflow-improvement-reviewer.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.opencode/agents/workflow-improvement-reviewer.md b/.opencode/agents/workflow-improvement-reviewer.md index 3f0511e..7319fdd 100644 --- a/.opencode/agents/workflow-improvement-reviewer.md +++ b/.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: From 7a8d0ede251f075e5118a3523785d7fe5bba7710 Mon Sep 17 00:00:00 2001 From: Merverli Date: Sat, 20 Jun 2026 16:15:20 -0500 Subject: [PATCH 20/21] Wire UI quality additions into orchestrator --- .opencode/agents/mobile-ui-orchestrator.md | 26 +++++++++++++++++----- 1 file changed, 21 insertions(+), 5 deletions(-) diff --git a/.opencode/agents/mobile-ui-orchestrator.md b/.opencode/agents/mobile-ui-orchestrator.md index 9169ac2..1b6352d 100644 --- a/.opencode/agents/mobile-ui-orchestrator.md +++ b/.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. From 1fd57c37e85cf7b424e2d799bb9886da778c2b52 Mon Sep 17 00:00:00 2001 From: Merverli Date: Sat, 20 Jun 2026 16:15:46 -0500 Subject: [PATCH 21/21] Align registry count check with registry source of truth --- scripts/ci/check-registry-counts.sh | 22 +++------------------- 1 file changed, 3 insertions(+), 19 deletions(-) diff --git a/scripts/ci/check-registry-counts.sh b/scripts/ci/check-registry-counts.sh index 28d2691..e948f21 100755 --- a/scripts/ci/check-registry-counts.sh +++ b/scripts/ci/check-registry-counts.sh @@ -1,8 +1,8 @@ #!/usr/bin/env bash # check-registry-counts.sh — Verify agent/command/skill counts match reality. # -# Compares actual file counts against REGISTRY.md and README.md claims. -# Prevents drift between manifests and the filesystem. +# Compares actual file counts against REGISTRY.md claims. +# Prevents drift between the registry and the filesystem. # # Usage: # bash scripts/ci/check-registry-counts.sh @@ -31,7 +31,6 @@ echo -n "Agents: $ACTUAL_AGENTS actual ... " AGENT_TABLE_START=$(grep -n "^## Agents" .opencode/REGISTRY.md | cut -d: -f1) AGENT_TABLE_END=$(grep -n "^### Agent categories" .opencode/REGISTRY.md | cut -d: -f1) REGISTRY_AGENTS=$(sed -n "${AGENT_TABLE_START},${AGENT_TABLE_END}p" .opencode/REGISTRY.md | grep -c "^| \`" || echo 0) -README_AGENTS=$(grep -oE '[0-9]+ agents' README.md 2>/dev/null | head -1 | grep -oE '[0-9]+' || echo 0) if [ "$REGISTRY_AGENTS" -eq "$ACTUAL_AGENTS" ] 2>/dev/null; then echo "REGISTRY.md: $REGISTRY_AGENTS ✓" @@ -40,19 +39,11 @@ else FAILED=1 fi -if [ "$README_AGENTS" -eq "$ACTUAL_AGENTS" ] 2>/dev/null; then - echo " README.md: $README_AGENTS ✓" -else - echo " README.md: $README_AGENTS ✗ (expected $ACTUAL_AGENTS)" - FAILED=1 -fi - # Check command count (count rows in command table only, between "## Commands" and "## Skills") echo -n "Commands: $ACTUAL_COMMANDS actual ... " CMD_TABLE_START=$(grep -n "^## Commands" .opencode/REGISTRY.md | cut -d: -f1) CMD_TABLE_END=$(grep -n "^## Skills" .opencode/REGISTRY.md | cut -d: -f1) REGISTRY_COMMANDS=$(sed -n "${CMD_TABLE_START},${CMD_TABLE_END}p" .opencode/REGISTRY.md | grep -c "^| \`/" || echo 0) -README_COMMANDS=$(grep -oE '[0-9]+ commands' README.md 2>/dev/null | head -1 | grep -oE '[0-9]+' || echo 0) if [ "$REGISTRY_COMMANDS" -eq "$ACTUAL_COMMANDS" ] 2>/dev/null; then echo "REGISTRY.md: $REGISTRY_COMMANDS ✓" @@ -61,13 +52,6 @@ else FAILED=1 fi -if [ "$README_COMMANDS" -eq "$ACTUAL_COMMANDS" ] 2>/dev/null; then - echo " README.md: $README_COMMANDS ✓" -else - echo " README.md: $README_COMMANDS ✗ (expected $ACTUAL_COMMANDS)" - FAILED=1 -fi - # Check skill count (count rows in skill table only, between "## Skills" and "## CI Assertions") echo -n "Skills: $ACTUAL_SKILLS actual ... " SKILL_TABLE_START=$(grep -n "^## Skills" .opencode/REGISTRY.md | cut -d: -f1) @@ -87,7 +71,7 @@ if [ "$FAILED" -eq 0 ]; then echo "All registry counts match actual files." exit 0 else - echo "Registry count drift detected. Update REGISTRY.md or README.md." + echo "Registry count drift detected. Update REGISTRY.md." echo "Run: ls .opencode/agents/*.md | wc -l" echo "Run: ls .opencode/commands/*.md | wc -l" echo "Run: ls -d .opencode/skills/*/ | wc -l"