diff --git a/.opencode/REGISTRY.md b/.opencode/REGISTRY.md index d48d586..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, 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 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; 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; 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. 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//`; 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: 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 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 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. 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. 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. 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. 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. 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. 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. 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. 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 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 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. 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"