opendevbrowser 0.0.16 → 0.0.18

package/skills/opendevbrowser-continuity-ledger/SKILL.md

@@ -1,13 +1,17 @@
 ---
 name: opendevbrowser-continuity-ledger
 description: This skill should be used when the user asks to "track continuity", "resume a long task", "maintain CONTINUITY.md", or run multi-step work that may span context compaction.
-version: 1.1.0
+version: 1.2.0
 ---
 
 # OpenDevBrowser Continuity Ledger
 
 Use this guide to maintain compaction-safe project state in `CONTINUITY.md`.
 
+Validation helper:
+
+- `scripts/validate-skill-assets.sh`
+
 ## When to Use This Skill
 
 Use this skill when any of these are true:
@@ -68,6 +72,15 @@ Update `CONTINUITY.md` whenever one of these changes:
 
 Keep entries factual and concise. Avoid transcript-style logging.
 
+## Validator Contract
+
+The validator must confirm all of these remain documented:
+
+- `CONTINUITY.md` and `sub_continuity.md` ownership boundaries
+- start-of-turn read and update protocol
+- required ledger headings and `UNCONFIRMED` handling
+- reply pattern with a short ledger snapshot before the main answer
+
 ## Handling Open Questions
 
 When uncertainty exists:

package/skills/opendevbrowser-continuity-ledger/scripts/validate-skill-assets.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+skill_file="$root/SKILL.md"
+
+node - "$skill_file" <<'NODE'
+const fs = require("node:fs");
+
+const [skillFile] = process.argv.slice(2);
+const content = fs.readFileSync(skillFile, "utf8");
+const failures = [];
+
+const requiredMarkers = [
+  "scripts/validate-skill-assets.sh",
+  "CONTINUITY.md",
+  "sub_continuity.md",
+  "Allow only the main orchestrator agent to edit `CONTINUITY.md`.",
+  "Run this sequence at the beginning of each turn:",
+  "Goal (incl. success criteria):",
+  "Constraints/Assumptions:",
+  "Key decisions:",
+  "State:",
+  "Open questions (UNCONFIRMED if needed):",
+  "Working set (files/ids/commands):",
+  "Key learnings: what worked; what didn't work, best approach identified for next time",
+  "UNCONFIRMED",
+  "Start response messages with a short ledger snapshot:"
+];
+
+for (const marker of requiredMarkers) {
+  if (!content.includes(marker)) {
+    failures.push(`SKILL.md missing marker: ${marker}`);
+  }
+}
+
+const turnSteps = [
+  "1. Read `CONTINUITY.md`.",
+  "2. Read `sub_continuity.md`.",
+  "3. Update `CONTINUITY.md` to reflect the current goal, constraints, decisions, and execution state.",
+  "4. Proceed with implementation."
+];
+for (const step of turnSteps) {
+  if (!content.includes(step)) {
+    failures.push(`Start-of-turn protocol missing step: ${step}`);
+  }
+}
+
+if (!/## Validator Contract[\s\S]*reply pattern/i.test(content)) {
+  failures.push("Validator contract section must document the reply pattern guarantee.");
+}
+
+if (failures.length > 0) {
+  for (const failure of failures) {
+    console.error(failure);
+  }
+  process.exit(1);
+}
+
+console.log("Continuity ledger skill assets validated.");
+NODE

package/skills/opendevbrowser-data-extraction/SKILL.md

@@ -28,6 +28,12 @@ Use this skill to extract structured, auditable datasets from dynamic pages with
 ./skills/opendevbrowser-data-extraction/scripts/run-extraction-workflow.sh infinite-scroll
 ```
 
+## Supporting Surfaces
+
+- Use browser replay (`screencast-start` / `screencast-stop`) when lazy loading, infinite scroll, or pagination drift needs time-based proof.
+- Use desktop observation only for read-only evidence around sibling desktop surfaces; most extraction flows should stay browser-only.
+- Use `--challenge-automation-mode off|browser|browser_with_helper` only for bounded browser-scoped computer use when provider challenges appear; stop before any desktop-control interpretation.
+
 ## Core Rules
 
 - Define schema before extraction.

package/skills/opendevbrowser-data-extraction/scripts/validate-skill-assets.sh

@@ -15,6 +15,16 @@ required=(
 )
 
 status=0
+
+require_marker() {
+  local label="$1"
+  local output="$2"
+  local marker="$3"
+  if [[ "$output" != *"$marker"* ]]; then
+    echo "$label missing marker: $marker" >&2
+    status=1
+  fi
+}
 for rel in "${required[@]}"; do
   if [[ ! -f "$root/$rel" ]]; then
     echo "Missing required asset: $rel" >&2
@@ -42,6 +52,108 @@ for rel in assets/templates/extraction-schema.json assets/templates/pagination-s
   fi
 done
 
+list_output="$("$root/scripts/run-extraction-workflow.sh" list-workflows)"
+for workflow_name in \
+  table \
+  pagination \
+  infinite-scroll \
+  load-more \
+  anti-bot-pressure \
+  checkpoint-resume
+do
+  require_marker "workflow list" "$list_output" "$workflow_name"
+done
+
+list_output="$("$root/scripts/run-extraction-workflow.sh" list)"
+require_marker "list extraction workflow" "$list_output" "opendevbrowser_snapshot"
+require_marker "list extraction workflow" "$list_output" "opendevbrowser_get_attr"
+
+table_output="$("$root/scripts/run-extraction-workflow.sh" table)"
+require_marker "table workflow" "$table_output" "opendevbrowser_dom_get_html"
+require_marker "table workflow" "$table_output" "table-ref"
+
+pagination_output="$("$root/scripts/run-extraction-workflow.sh" pagination)"
+require_marker "pagination workflow" "$pagination_output" "opendevbrowser_click"
+require_marker "pagination workflow" "$pagination_output" "networkidle"
+
+infinite_scroll_output="$("$root/scripts/run-extraction-workflow.sh" infinite-scroll)"
+require_marker "infinite-scroll workflow" "$infinite_scroll_output" "opendevbrowser_scroll"
+require_marker "infinite-scroll workflow" "$infinite_scroll_output" "opendevbrowser_wait"
+
+anti_bot_output="$("$root/scripts/run-extraction-workflow.sh" anti-bot-pressure)"
+require_marker "anti-bot-pressure workflow" "$anti_bot_output" "403/429/challenge"
+require_marker "anti-bot-pressure workflow" "$anti_bot_output" "Retry-After"
+
+checkpoint_output="$("$root/scripts/run-extraction-workflow.sh" checkpoint-resume)"
+require_marker "checkpoint-resume workflow" "$checkpoint_output" "pagination checkpoint"
+require_marker "checkpoint-resume workflow" "$checkpoint_output" "opendevbrowser_snapshot"
+
+if ! node - "$root" <<'NODE'
+const fs = require("node:fs");
+const path = require("node:path");
+
+const [root] = process.argv.slice(2);
+const failures = [];
+
+const extractionSchema = JSON.parse(fs.readFileSync(path.join(root, "assets/templates/extraction-schema.json"), "utf8"));
+const paginationState = JSON.parse(fs.readFileSync(path.join(root, "assets/templates/pagination-state.json"), "utf8"));
+const qualityGates = JSON.parse(fs.readFileSync(path.join(root, "assets/templates/quality-gates.json"), "utf8"));
+
+for (const field of ["title", "url"]) {
+  if (!Array.isArray(extractionSchema.required_fields) || !extractionSchema.required_fields.includes(field)) {
+    failures.push(`extraction-schema.json missing required field: ${field}`);
+  }
+}
+if (extractionSchema.field_types?.price !== "number") {
+  failures.push("extraction-schema.json must keep price typed as number.");
+}
+for (const field of ["price", "rating", "availability"]) {
+  if (!Array.isArray(extractionSchema.optional_fields) || !extractionSchema.optional_fields.includes(field)) {
+    failures.push(`extraction-schema.json missing optional field: ${field}`);
+  }
+}
+
+for (const key of ["checkpoint_token", "retry_after_seconds", "challenge_loops", "stopping_reason"]) {
+  if (!(key in paginationState)) {
+    failures.push(`pagination-state.json missing key: ${key}`);
+  }
+}
+if (paginationState.current_page !== 1) {
+  failures.push("pagination-state.json must start with current_page=1.");
+}
+
+for (const key of [
+  "max_required_null_rate",
+  "max_duplicate_rate",
+  "require_positive_page_delta",
+  "max_consecutive_empty_pages",
+  "max_consecutive_challenge_loops",
+  "max_retries_per_page",
+  "respect_retry_after",
+  "stop_on_repeated_anti_bot_signals"
+]) {
+  if (!(key in qualityGates)) {
+    failures.push(`quality-gates.json missing key: ${key}`);
+  }
+}
+if (qualityGates.max_retries_per_page !== 2) {
+  failures.push("quality-gates.json must cap retries per page at 2.");
+}
+if (qualityGates.respect_retry_after !== true || qualityGates.stop_on_repeated_anti_bot_signals !== true) {
+  failures.push("quality-gates.json must enforce Retry-After and repeated anti-bot stops.");
+}
+
+if (failures.length > 0) {
+  for (const failure of failures) {
+    console.error(failure);
+  }
+  process.exit(1);
+}
+NODE
+then
+  status=1
+fi
+
 if [[ $status -ne 0 ]]; then
   exit $status
 fi

package/skills/opendevbrowser-design-agent/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: opendevbrowser-design-agent
+description: This skill should be used when the user asks to design, redesign, audit, or implement frontend/UI work with OpenDevBrowser, screenshots, or the /canvas surface. It turns briefs and existing interfaces into contract-first, real-browser-validated design execution.
+version: 1.1.0
+---
+
+# Design Agent Skill
+
+Use this skill for frontend work that must be visually strong, contract-first, and verified in a real browser instead of judged only from code.
+
+## Pack Contents
+
+- `artifacts/design-workflows.md`
+- `artifacts/design-contract-playbook.md`
+- `artifacts/frontend-evaluation-rubric.md`
+- `artifacts/external-pattern-synthesis.md`
+- `artifacts/component-pattern-index.md`
+- `artifacts/existing-surface-adaptation.md`
+- `artifacts/app-shell-and-state-wiring.md`
+- `artifacts/state-ownership-matrix.md`
+- `artifacts/async-search-state-ownership.md`
+- `artifacts/loading-and-feedback-surfaces.md`
+- `artifacts/theming-and-token-ownership.md`
+- `artifacts/isolated-preview-validation.md`
+- `artifacts/performance-audit-playbook.md`
+- `artifacts/scroll-reveal-surface-planning.md`
+- `artifacts/research-harvest-workflow.md`
+- `artifacts/design-release-gate.md`
+- `artifacts/opendevbrowser-ui-example-map.md`
+- `artifacts/implementation-anti-patterns.md`
+- `assets/templates/design-brief.v1.md`
+- `assets/templates/design-audit-report.v1.md`
+- `assets/templates/design-contract.v1.json`
+- `assets/templates/canvas-generation-plan.design.v1.json`
+- `assets/templates/design-review-checklist.json`
+- `assets/templates/real-surface-design-matrix.json`
+- `assets/templates/reference-pattern-board.v1.json`
+- `assets/templates/design-release-gate.v1.json`
+- `scripts/design-workflow.sh`
+- `scripts/extract-canvas-plan.sh`
+- `scripts/validate-skill-assets.sh`
+- Shared robustness matrix: `../opendevbrowser-best-practices/artifacts/browser-agent-known-issues-matrix.md`
+- Shared canvas workflow baseline: `../opendevbrowser-best-practices/SKILL.md`
+
+## Fast Start
+
+1. Validate pack integrity.
+
+```bash
+./skills/opendevbrowser-design-agent/scripts/validate-skill-assets.sh
+```
+
+2. Print a workflow.
+
+```bash
+./skills/opendevbrowser-design-agent/scripts/design-workflow.sh contract-first
+./skills/opendevbrowser-design-agent/scripts/design-workflow.sh canvas-contract
+./skills/opendevbrowser-design-agent/scripts/design-workflow.sh real-surface-validation
+./skills/opendevbrowser-design-agent/scripts/design-workflow.sh research-harvest
+./skills/opendevbrowser-design-agent/scripts/design-workflow.sh release-gate
+./skills/opendevbrowser-design-agent/scripts/design-workflow.sh performance-audit
+```
+
+3. Convert a full design contract into a `/canvas`-ready generation plan.
+
+```bash
+./skills/opendevbrowser-design-agent/scripts/extract-canvas-plan.sh \
+  skills/opendevbrowser-design-agent/assets/templates/design-contract.v1.json
+```
+
+## Supporting Surfaces
+
+- Use browser replay (`screencast-start` / `screencast-stop`) during real-surface validation when motion, sequencing, or transition timing matters.
+- Desktop observation stays read-only and is only for external window or OS-level evidence around the workflow; it is not a design-surface control lane.
+- Browser-scoped computer use remains a challenge posture knob via `--challenge-automation-mode`, not a desktop-agent capability.
+
+## Core Rules
+
+- Start with a design contract, not ad-hoc implementation.
+- Build a reference pattern board before locking a new direction when external inspiration matters.
+- Choose a component family from `artifacts/component-pattern-index.md` before inventing a new screen structure.
+- Start from the closest shipped OpenDevBrowser example in `artifacts/opendevbrowser-ui-example-map.md` when the repo already has a related surface.
+- Route repo-first redesigns through `artifacts/existing-surface-adaptation.md` before changing shells or component anatomy.
+- Decide state ownership before writing component APIs, prompts, or `/canvas` patches.
+- Declare app-shell, route, and overlay ownership with `artifacts/app-shell-and-state-wiring.md` before expanding navigation chrome or shared panels.
+- Declare navigation and deep-link ownership in the contract before buttons, tabs, or search params start pushing route changes ad hoc.
+- Declare async and search ownership with `artifacts/async-search-state-ownership.md` before wiring input-driven fetches, scopes, or background refresh.
+- Keep one semantic token source with `artifacts/theming-and-token-ownership.md`; do not let leaf components invent raw colors, spacing, or type rules ad hoc.
+- Define layout-preserving loading, empty/error recovery, and transient feedback surfaces with `artifacts/loading-and-feedback-surfaces.md` before polishing the happy path.
+- For scan-heavy screens, declare list identity, lazy-loading, and progressive-reveal posture before polishing individual cards or rows.
+- Keep one visual direction per task. Do not mix unrelated design languages.
+- Prefer real content, realistic states, and explicit user journeys over placeholder copy.
+- Preserve the repo's existing design system when one already exists. Only introduce a new direction when the brief or product gap justifies it.
+- Treat `/canvas` governance as the strongest contract in the repo: read the handshake, respect `generationPlanRequirements`, and do not mutate before the plan is accepted.
+- For non-canvas frontend work, still fill the same design-contract fields before coding so decisions stay consistent across code, preview, and docs.
+- Use one owner for overlays, drawers, sheets, and detail panels; prefer item-backed state over boolean sprawl.
+- If motion depends on scroll or viewport progress, define the driver and reduced-motion fallback before implementation.
+- Use `artifacts/scroll-reveal-surface-planning.md` whenever the design depends on pinned sections, reveal stages, or viewport-driven sequencing.
+- Validate new patterns in isolation or `/canvas` preview with `artifacts/isolated-preview-validation.md`, including deterministic fixtures and installed dependencies, before declaring the integrated screen finished.
+- Verify default, hover, focus, empty, loading, success, and error states when they are relevant.
+- Validate responsive behavior intentionally; do not assume desktop layouts scale down cleanly.
+- If the UI feels slow or unstable, switch to `artifacts/performance-audit-playbook.md` and capture a baseline before changing structure.
+- Use OpenDevBrowser CLI for real-browser validation, not just static reasoning.
+- Record the final ship decision in `assets/templates/design-release-gate.v1.json`; if evidence is missing, the task is not done.
+- Finish by updating docs, AGENTS guidance, and any skill-pack references affected by the new UI behavior.
+
+## Design Contract
+
+The mandatory design contract lives in `assets/templates/design-contract.v1.json`.
+
+Every design task should answer these blocks before implementation:
+
+- `intent`
+- `designLanguage`
+- `contentModel`
+- `navigationModel`
+- `asyncModel`
+- `layoutSystem`
+- `typographySystem`
+- `motionSystem`
+- `performanceModel`
+- `responsiveSystem`
+- `accessibilityPolicy`
+- `generationPlan`
+
+### `/canvas` Required Generation Plan Fields
+
+The `generationPlan` block must include:
+
+- `targetOutcome`
+- `visualDirection`
+- `layoutStrategy`
+- `contentStrategy`
+- `componentStrategy`
+- `motionPosture`
+- `responsivePosture`
+- `accessibilityPosture`
+- `validationTargets`
+
+Use `scripts/extract-canvas-plan.sh` when the full contract already exists and only the `/canvas` payload is needed.
+
+## Recommended Workflow Modes
+
+### `contract-first`
+
+Use when starting from a brief or existing product requirement.
+
+- Fill `assets/templates/design-brief.v1.md`.
+- Translate it into `assets/templates/design-contract.v1.json`.
+- Check `artifacts/opendevbrowser-ui-example-map.md` and `artifacts/app-shell-and-state-wiring.md` before deciding the shell structure.
+- If a nearby shipped surface exists, review `artifacts/existing-surface-adaptation.md` before changing shell or component structure.
+- Review `artifacts/design-contract-playbook.md`.
+- Implement only after the contract is coherent.
+
+### `research-harvest`
+
+Use when a redesign needs external references or when the brief explicitly asks for competitive learning.
+
+- Start with `artifacts/research-harvest-workflow.md`.
+- Capture `3` to `5` live references with OpenDevBrowser.
+- Record them in `assets/templates/reference-pattern-board.v1.json`.
+- Turn the synthesis into contract deltas before implementation.
+
+### `screenshot-audit`
+
+Use when starting from screenshots, mocks, or an existing page.
+
+- Decompose the design into layout, type, spacing, state, motion, and accessibility decisions.
+- Rewrite those observations into the same contract fields used for `/canvas`.
+- Record issues and fixes in `assets/templates/design-audit-report.v1.md`.
+- Use `artifacts/frontend-evaluation-rubric.md` before editing code.
+- If the screen uses scroll-driven sequencing, add `artifacts/scroll-reveal-surface-planning.md` to the audit inputs.
+
+### `canvas-contract`
+
+Use when the task should run through the design canvas.
+
+- Start with `canvas.session.open` or `canvas.capabilities.get`.
+- Read the handshake and confirm mutation is allowed.
+- Fill the full design contract and extract the `generationPlan`.
+- Submit `canvas.plan.set`, then mutate with `canvas.document.patch`.
+- Validate extension-stage history controls against public `canvas.history.undo` and `canvas.history.redo`; design-tab clicks emit the internal `canvas_history_requested` event, but acceptance is still on the public command outcomes.
+- When token work is in scope, validate collection or mode authoring, token value or alias edits, selected-node binding, and token usage inspection in the extension stage.
+- If annotation send is part of the workflow, record whether the design tab returned `Delivered to agent` or `Stored only; fetch with annotate --stored`.
+- Use `canvas.feedback.poll`, `canvas.preview.render`, `canvas.preview.refresh`, and `canvas.document.save` as the validation loop.
+
+### `real-surface-validation`
+
+Use when design work must be proven on live surfaces.
+
+- Validate the design on the actual browser surface with `snapshot`, `screenshot`, `debug-trace-snapshot`, and relevant `/canvas` preview commands.
+- Run `artifacts/isolated-preview-validation.md` first when the component family or state matrix is still unstable.
+- Run the same real task across supported modes when parity is part of the acceptance criteria.
+- Record blockers explicitly instead of hand-waving them away.
+
+### `performance-audit`
+
+Use when the design feels heavy, re-renders too often, or becomes unstable with realistic content.
+
+- Capture the slow interaction and baseline with `artifacts/performance-audit-playbook.md`.
+- Use `assets/templates/design-audit-report.v1.md` to record `issue / evidence / fix / validation`.
+- Prefer ownership and structure fixes before memoization or micro-optimizations.
+- If scroll-driven motion is part of the problem, validate the progress owner with `artifacts/scroll-reveal-surface-planning.md` before tuning timing.
+
+### `release-gate`
+
+Use when the implementation looks done and the remaining work is proof and cleanup.
+
+- Start with `artifacts/design-release-gate.md`.
+- Fill `assets/templates/design-release-gate.v1.json`.
+- Re-run the real-surface matrix and the design review checklist.
+- Follow the canonical direct-run release evidence policy from `../opendevbrowser-best-practices/SKILL.md`; this pack does not redefine release-proof ownership.
+- Fix remaining gaps before ship-audit.
+
+## Research-Backed Patterns
+
+These patterns are summarized in `artifacts/external-pattern-synthesis.md` and should shape how the skill is applied:
+
+- Specialized agents work best when scope, tooling, and examples are explicit.
+- Frontend generation quality improves when prompts specify stack, layout intent, interaction states, and visual references instead of generic adjectives.
+- Competitive harvest works best when each reference captures borrow and reject decisions instead of a mood board only.
+- Large UI tasks should be broken into deliberate passes: contract, structure, implementation, then live validation.
+- Real content and real workflows outperform placeholder-heavy prompts.
+- Frontend design agents should own both aesthetics and verification, not just code output.
+- Component libraries and screen families should be referenced intentionally instead of rediscovered from scratch on every task.
+- Existing shipped surfaces should be treated as first-class adaptation inputs, not obstacles to work around.
+- State ownership, overlay ownership, async ownership, and preview discipline need to be explicit or the implementation will drift even when the design language is strong.
+- Route ownership should be explicit and typed: one owner translates deep links, tabs, URL params, and external entry points into screen state.
+- Scroll-reveal work needs one declared progress owner and an explicit reduced-motion contract or it will regress across breakpoints.
+- Debounced async search, layout-preserving placeholders, semantic token ownership, and non-reflow feedback surfaces should be decided in the contract instead of improvised during polish.
+- Scan-heavy screens need stable item identity, lazy containers or progressive reveal where justified, and a declared scan unit before per-item polish or motion work.
+
+## Parallel Multitab Alignment
+
+- Apply shared concurrency policy from `../opendevbrowser-best-practices/SKILL.md` ("Parallel Operations").
+- Treat design validation as `session-per-worker`; do not alternate unrelated target streams inside one session.
+- Re-check extension readiness before `/canvas` or relay-backed annotation steps after idle windows.
+
+## Robustness Coverage (Known-Issue Matrix)
+
+Matrix source: `../opendevbrowser-best-practices/artifacts/browser-agent-known-issues-matrix.md`
+
+- `ISSUE-01`: stale refs and DOM churn during iterative UI validation
+- `ISSUE-07`: MV3 extension state loss during `/canvas` and popup-driven design loops
+- `ISSUE-08`: restricted origins and unsupported extension pages during design validation
+- `ISSUE-12`: stale evidence or unsupported design claims in final deliverables
+
+Reload discipline for unpacked-extension design work:
+
+- After `npm run extension:build`, do not trust a live Chrome result until the unpacked extension is actually reloaded in Chrome.
+- Stale MV3 runtime state can preserve old popup or `/canvas` design-tab behavior even when the repo bundle is already fixed.
+- If design-tab commands still throw `restricted_url` on `chrome-extension://.../canvas.html`, treat that as an unpacked-extension reload problem first, then reconnect the extension and rerun the design workflow.
+
+## Commands
+
+```bash
+./skills/opendevbrowser-design-agent/scripts/design-workflow.sh contract-first
+./skills/opendevbrowser-design-agent/scripts/design-workflow.sh canvas-contract
+./skills/opendevbrowser-design-agent/scripts/design-workflow.sh screenshot-audit
+./skills/opendevbrowser-design-agent/scripts/design-workflow.sh real-surface-validation
+./skills/opendevbrowser-design-agent/scripts/design-workflow.sh research-harvest
+./skills/opendevbrowser-design-agent/scripts/design-workflow.sh performance-audit
+./skills/opendevbrowser-design-agent/scripts/design-workflow.sh release-gate
+./skills/opendevbrowser-design-agent/scripts/design-workflow.sh ship-audit
+./skills/opendevbrowser-design-agent/scripts/extract-canvas-plan.sh ./tmp/design-contract.json
+```
+
+## References
+
+- Anthropic Claude Code subagents best practices: https://docs.anthropic.com/en/docs/claude-code/sub-agents
+- Anthropic Claude Code settings and agent ownership patterns: https://docs.anthropic.com/en/docs/claude-code/settings
+- Vercel v0 prompting guide: https://v0.dev/docs/prompting/text
+- Lovable prompting guide: https://docs.lovable.dev/prompting/prompting-best-practices
+- Public frontend-designer subagent example: https://github.com/iannuttall/claude-agents
+- Dimillian SwiftUI UI patterns: https://github.com/Dimillian/Skills/blob/main/swiftui-ui-patterns/SKILL.md

package/skills/opendevbrowser-design-agent/artifacts/app-shell-and-state-wiring.md

@@ -0,0 +1,84 @@
+# App Shell And State Wiring
+
+Use this guide when the design task affects navigation shells, route depth, search params, inspectors, drawers, or shared workspace state.
+
+## 1. Shell First
+
+Before styling, decide which layer owns each responsibility:
+
+- app shell: global navigation, workspace switchers, auth-scoped chrome, top-level keyboard shortcuts
+- feature shell: feature tabs, inspector visibility, page-local actions, route-local loading states
+- component: presentational toggles, disclosure state, hover or pressed affordances
+
+If the same concern appears in two shells, pick one owner and document it in the design contract.
+
+## 2. Route Ownership
+
+Use the URL for state that should survive refresh, deep links, or handoff:
+
+- active tab that matters outside one component
+- search query, sort, filters, pagination, selected record id
+- editor sub-mode when the user expects shareable or recoverable state
+
+Keep purely presentational toggles out of the URL:
+
+- card expansion that does not change the task
+- hover or preview affordances
+- temporary compare or reveal states
+
+Treat deep links as a translation contract, not a side effect:
+
+- one route owner maps params into tabs, filters, selected records, or editor sub-modes
+- one invalid-route fallback returns the user to a safe baseline when params are stale or incomplete
+- row actions, tabs, and shortcut handlers should call the same route translator instead of assembling strings independently
+- external entry points should resolve to the same canonical route model as in-app navigation
+
+## 3. Overlay Ownership
+
+All overlays need one owner:
+
+- route-owned when the overlay changes page meaning or selected entity
+- feature-owned when the overlay is local to a workflow
+- component-owned only for low-risk ephemeral UI
+
+Prefer item-backed overlay state:
+
+- `activeDrawerItemId`
+- `commandPaletteMode`
+- `confirmDeleteTarget`
+
+Avoid parallel booleans for one overlay family.
+
+## 4. Shared Dependencies
+
+Keep dependency boundaries explicit:
+
+- data caches and async records belong in the data layer
+- auth/session context belongs at the app or workspace shell
+- feature controllers own only feature-local orchestration
+- heavy editors or canvases should expose narrow mutation surfaces instead of leaking internal state across the tree
+
+## 5. Async And Error Boundaries
+
+State which shell owns:
+
+- initial loading
+- incremental refresh
+- empty results
+- recoverable errors
+- destructive retry actions
+
+Do not split one async story across unrelated branches unless the user can act on them independently.
+
+## 6. Review Prompts
+
+Before implementation, answer:
+
+1. Which state belongs in the URL?
+2. Which state belongs in a shared workspace store?
+3. Which overlay has the final authority to open or close?
+4. Which shell owns the primary action row?
+5. Which route owner resolves deep links, invalid params, and tab switching?
+6. Which branch is allowed to show the loading or error affordance?
+
+If any answer is unclear, the shell wiring is not ready.

package/skills/opendevbrowser-design-agent/artifacts/async-search-state-ownership.md

@@ -0,0 +1,58 @@
+# Async And Search State Ownership
+
+Use this when a screen loads remote data, reacts to changing input, or exposes search, scope, filter, or sort controls that can restart work.
+
+## 1. Choose The Trigger Model First
+
+Name the async trigger before writing component structure:
+
+- `load-on-enter`: initial screen load or detail fetch tied to first render
+- `restart-on-input`: query, selection, scope, filter, or sort changes
+- `long-lived-workflow`: work that must survive navigation, dismissal, or cross-screen reuse
+
+If the trigger model is unclear, the UI will usually duplicate state or fire stale requests.
+
+## 2. One Owner Per Search Story
+
+Decide where query and result ownership lives:
+
+- local component or route state when search is specific to one surface
+- URL or search params when the search should survive refresh, deep links, or handoff
+- shared store or service only when multiple surfaces truly need the same search session
+
+Keep result arrays, status, and restart logic close to the canonical owner or in the data layer. Do not mirror them into sibling components.
+
+## 3. Execution Rules
+
+- Debounce user-driven restarts before they hit the network or expensive local filtering.
+- Treat cancellation as normal for stale requests. Do not surface cancellation as a user-facing error.
+- Clear back to a baseline or empty state when the query is empty unless the product explicitly needs default results.
+- Apply the same restart policy to scope, filter, and sort changes when they mutate the same result set.
+- Keep retry, caching, offline, and dedupe policy in a service once the rules exceed simple view ownership.
+
+## 4. Move Work Out Of The View When
+
+- the work must survive dismissal or route changes
+- multiple screens depend on the same in-flight state
+- cache, retry, or optimistic rules become product-level policy
+- the view is mostly coordinating app-shell or account lifecycle instead of rendering a local task
+
+The view should still own presentation-state transitions even when execution moves into a service.
+
+## 5. Review Prompts
+
+Before implementation, answer:
+
+1. What restarts the async work?
+2. Where do query, scope, and sort live?
+3. What should happen on an empty query?
+4. How are stale responses ignored or cancelled?
+5. At what point does the work move out of the view into a service or shared controller?
+
+## Failure Signals
+
+- searches run for empty input with no product reason
+- typeahead or scoped search has no debounce or cancellation story
+- the same query state exists in the URL, local state, and a shared store
+- result ownership is split across sibling components
+- retry and cache rules leak into presentation components