oh-my-agent-commandcode 0.0.0-stage → 20.38.4

package/skills/oma-debug/resources/debugging-checklist.md

@@ -0,0 +1,364 @@
+# Debugging Checklist
+
+Use this checklist when investigating bugs to ensure thorough analysis.
+
+## Initial Information Gathering
+
+- [ ] **Bug description** - What is the expected vs actual behavior?
+- [ ] **Error messages** - Exact error text, stack trace, error codes
+- [ ] **Reproduction steps** - Clear, numbered steps to trigger the bug
+- [ ] **Frequency** - Every time, intermittent, specific conditions?
+- [ ] **Environment** - Browser/OS/version, mobile device, server environment
+- [ ] **User impact** - How many users affected? Severity?
+- [ ] **Recent changes** - New deploy? Code changes? Configuration updates?
+- [ ] **Screenshots/videos** - Visual evidence of the bug
+
+## Frontend Debugging
+
+### JavaScript/TypeScript Errors
+
+- [ ] Check browser console (F12) for errors
+- [ ] Review stack trace - which file and line?
+- [ ] Identify error type (TypeError, ReferenceError, etc.)
+- [ ] Check for null/undefined values
+- [ ] Verify variable types (especially after API calls)
+- [ ] Look for typos in property names
+
+### React Component Issues
+
+- [ ] **State problems**
+  - [ ] State not updating? (need setState/useState)
+  - [ ] Stale state in closures? (use refs or functional updates)
+  - [ ] State out of sync with props?
+
+- [ ] **Effect problems**
+  - [ ] Missing dependencies in useEffect?
+  - [ ] Effect running too many times?
+  - [ ] Cleanup function needed?
+  - [ ] Memory leak from uncancelled requests?
+
+- [ ] **Rendering issues**
+  - [ ] Conditional rendering logic correct?
+  - [ ] Keys on list items unique and stable?
+  - [ ] Unnecessary re-renders? (use React DevTools Profiler)
+
+### UI/UX Issues
+
+- [ ] CSS not applying? (check specificity, typos)
+- [ ] Layout broken? (check responsive breakpoints)
+- [ ] Accessibility issues? (keyboard nav, screen reader)
+- [ ] Dark mode broken?
+- [ ] Mobile-specific issues?
+
+### API Integration
+
+- [ ] **Network tab investigation**
+  - [ ] Request sent? (check Headers tab)
+  - [ ] Correct endpoint URL?
+  - [ ] Proper HTTP method (GET, POST, etc.)?
+  - [ ] Headers included (Authorization, Content-Type)?
+  - [ ] Request body formatted correctly?
+  - [ ] Response status code (200, 401, 404, 500)?
+  - [ ] Response data structure matches expected?
+
+- [ ] **Error handling**
+  - [ ] Try/catch around API calls?
+  - [ ] Error state displayed to user?
+  - [ ] Timeout handling?
+  - [ ] Network failure handling?
+
+- [ ] **Loading states**
+  - [ ] Loading spinner shown?
+  - [ ] Disabled buttons during load?
+  - [ ] Optimistic updates causing issues?
+
+## Backend Debugging
+
+### Python/FastAPI Errors
+
+- [ ] **Stack trace analysis**
+  - [ ] Read error message carefully
+  - [ ] Identify the failing file and line
+  - [ ] Understand the error type (ValueError, KeyError, etc.)
+  - [ ] Check for None values
+  - [ ] Verify data types
+
+- [ ] **Database issues**
+  - [ ] Query syntax correct?
+  - [ ] N+1 query problem?
+  - [ ] Missing JOIN?
+  - [ ] Indexes present on filtered columns?
+  - [ ] Connection pool exhausted?
+  - [ ] Transaction isolation issues?
+
+- [ ] **Authentication/Authorization**
+  - [ ] Token validation working?
+  - [ ] Token expired?
+  - [ ] Permissions checked correctly?
+  - [ ] User session valid?
+  - [ ] CORS configured properly?
+
+### API Endpoint Issues
+
+- [ ] **Request validation**
+  - [ ] Pydantic schema matches request?
+  - [ ] Required fields present?
+  - [ ] Field types correct?
+  - [ ] Value ranges validated?
+
+- [ ] **Response formatting**
+  - [ ] Correct status code?
+  - [ ] Response schema matches contract?
+  - [ ] Error responses formatted properly?
+  - [ ] Pagination working?
+
+- [ ] **Performance**
+  - [ ] Response time acceptable (<200ms)?
+  - [ ] Query optimization needed?
+  - [ ] Caching implemented?
+  - [ ] Rate limiting working?
+
+### Server Issues
+
+- [ ] **Logs examination**
+  - [ ] Check application logs
+  - [ ] Check error logs
+  - [ ] Check access logs
+  - [ ] Timestamps correlate with bug reports?
+
+- [ ] **Environment**
+  - [ ] Environment variables set?
+  - [ ] Configuration correct for environment (dev/prod)?
+  - [ ] External services reachable?
+  - [ ] Database migrations applied?
+
+## Mobile Debugging
+
+### Platform-Specific Issues
+
+- [ ] **iOS vs Android differences**
+  - [ ] Test on both platforms
+  - [ ] Check platform-specific code (Platform.OS)
+  - [ ] Review native module integration
+  - [ ] Verify permissions (camera, location, etc.)
+
+- [ ] **Device-specific**
+  - [ ] Test on actual device (not just emulator)
+  - [ ] Check different screen sizes
+  - [ ] Test different OS versions
+  - [ ] Memory constraints on older devices?
+
+### Flutter-Specific
+
+- [ ] **Widget tree issues**
+  - [ ] State management correct? (Riverpod/Bloc)
+  - [ ] Build method pure?
+  - [ ] Keys used properly?
+  - [ ] Dispose called for controllers?
+
+- [ ] **Platform channels**
+  - [ ] Native code errors?
+  - [ ] Method channel names correct?
+  - [ ] Data serialization working?
+
+### Mobile Performance
+
+- [ ] Memory leaks? (listeners not disposed)
+- [ ] Excessive rebuilds?
+- [ ] Large images not optimized?
+- [ ] Too many simultaneous network requests?
+
+## Security Bugs
+
+- [ ] **Authentication bypassed?**
+  - [ ] Token validation on all protected routes?
+  - [ ] Token expiry checked?
+  - [ ] Refresh token flow secure?
+
+- [ ] **Authorization broken?**
+  - [ ] User can access others' data?
+  - [ ] Admin functions accessible to regular users?
+  - [ ] Horizontal privilege escalation possible?
+
+- [ ] **Injection vulnerabilities**
+  - [ ] SQL injection? (use parameterized queries)
+  - [ ] XSS? (sanitize user input)
+  - [ ] Command injection?
+  - [ ] Path traversal?
+
+- [ ] **Data exposure**
+  - [ ] Sensitive data in logs?
+  - [ ] Passwords in plain text?
+  - [ ] API keys exposed?
+  - [ ] Error messages leaking info?
+
+## Performance Bugs
+
+### Frontend Performance
+
+- [ ] **Lighthouse audit**
+  - [ ] Performance score >90?
+  - [ ] First Contentful Paint <1.5s?
+  - [ ] Largest Contentful Paint <2.5s?
+  - [ ] Cumulative Layout Shift <0.1?
+
+- [ ] **Bundle analysis**
+  - [ ] Main bundle <500KB?
+  - [ ] Code splitting implemented?
+  - [ ] Large dependencies tree-shaken?
+  - [ ] Lazy loading used?
+
+- [ ] **React performance**
+  - [ ] Unnecessary re-renders? (React DevTools Profiler)
+  - [ ] Memo/useMemo/useCallback used appropriately?
+  - [ ] Virtual scrolling for long lists?
+
+### Backend Performance
+
+- [ ] **API latency**
+  - [ ] p95 response time <200ms?
+  - [ ] Slow queries identified?
+  - [ ] Indexes added?
+  - [ ] Caching implemented?
+
+- [ ] **Database**
+  - [ ] Connection pooling configured?
+  - [ ] Query plan optimized? (EXPLAIN)
+  - [ ] N+1 queries eliminated?
+
+## Root Cause Analysis
+
+- [ ] **Reproduce the bug**
+  - [ ] Follow exact reproduction steps
+  - [ ] Confirm bug exists
+  - [ ] Note any variations
+
+- [ ] **Isolate the problem**
+  - [ ] Which component/function fails?
+  - [ ] What input triggers it?
+  - [ ] What conditions must be met?
+
+- [ ] **Trace the data flow**
+  - [ ] Where does the bad data come from?
+  - [ ] How is it transformed?
+  - [ ] Where does it cause the failure?
+
+- [ ] **Identify the root cause**
+  - [ ] Not just the symptom
+  - [ ] Why does this happen?
+  - [ ] What assumption was wrong?
+
+## Fix Verification
+
+- [ ] **Fix applied**
+  - [ ] Code changed in correct file(s)
+  - [ ] Logic correct
+  - [ ] Edge cases handled
+  - [ ] No new bugs introduced
+
+- [ ] **Testing**
+  - [ ] Regression test written
+  - [ ] Test passes
+  - [ ] Manual verification done
+  - [ ] Edge cases tested
+
+- [ ] **Related areas checked**
+  - [ ] Similar patterns elsewhere?
+  - [ ] Other code depending on this?
+  - [ ] Breaking changes avoided?
+
+- [ ] **Documentation**
+  - [ ] Bug documented in Knowledge Base
+  - [ ] Fix explained
+  - [ ] Prevention notes added
+
+## When to Escalate
+
+Escalate to other agents if:
+
+- [ ] Bug spans multiple domains → **oma-coordination**
+- [ ] Requires architectural change → **PM Agent**
+- [ ] Need comprehensive security audit → **QA Agent**
+- [ ] Complex frontend refactoring needed → **Frontend Agent**
+- [ ] Database schema changes needed → **Backend Agent**
+- [ ] Platform-specific mobile issue → **Mobile Agent**
+
+## Priority Assessment
+
+**CRITICAL** - Fix immediately:
+- [ ] App crashes on launch
+- [ ] Data loss or corruption
+- [ ] Security vulnerability
+- [ ] Payment/auth completely broken
+- [ ] Affects all users
+
+**HIGH** - Fix within 24 hours:
+- [ ] Major feature broken
+- [ ] Affects >50% of users
+- [ ] No workaround available
+- [ ] Significant revenue impact
+
+**MEDIUM** - Fix within sprint:
+- [ ] Minor feature broken
+- [ ] Affects <50% of users
+- [ ] Workaround exists
+- [ ] Moderate inconvenience
+
+**LOW** - Schedule for future:
+- [ ] Edge case
+- [ ] Cosmetic issue
+- [ ] Rarely encountered
+- [ ] No user impact
+
+## Documentation Template
+
+After fixing, document in `.agents/results/bugs/`. For Complex or CRITICAL/HIGH
+severity bugs, use the full `bug-report-template.md`; for Simple/Medium bugs,
+this condensed form is sufficient:
+
+```markdown
+# Bug: [Title]
+**Date**: YYYY-MM-DD
+**Severity**: CRITICAL/HIGH/MEDIUM/LOW
+**Status**: FIXED
+
+## Problem
+[What was broken]
+
+## Root Cause
+[Why it was broken]
+
+## Fix
+[What was changed]
+
+## Files Modified
+- path/to/file
+
+## Testing
+- [x] Regression test added
+- [x] Manual verification
+- [x] Related areas checked
+
+## Prevention
+[How to avoid in future]
+```
+
+---
+
+## Pro Tips
+
+1. **Read the error message** - It usually tells you exactly what's wrong
+2. **Reproduce first** - Don't waste time fixing unconfirmed bugs
+3. **One change at a time** - Don't fix multiple things simultaneously
+4. **Test thoroughly** - Verify the fix and check for regressions
+5. **Document everything** - Future you will be grateful
+6. **Look for patterns** - One bug often reveals more
+
+## Tools Reference
+
+- **Browser DevTools**: F12 (Console, Network, React DevTools)
+- **Code intelligence**: configured symbol, pattern, and reference tools; native search of paths outside this project or ignored paths as fallback
+- **Browser automation**: Browser verification uses the installed MCPs selected in `mcp.devtools_browsers`: Aside (`aside`, default), Chrome DevTools MCP (`chrome`), and Firefox DevTools MCP (`firefox`). Multiple selections are supported; use `oma update mcp` to change them. Discover the selected server’s actual tools before use; tool names and capabilities differ between servers. An empty selection disables browser MCP verification; report any unverified UI checks.
+- **React Profiler**: Performance analysis
+- **Lighthouse**: Performance audit
+- **Git bisect**: Find when bug was introduced

package/skills/oma-debug/resources/error-playbook.md

@@ -0,0 +1,94 @@
+# Debug Agent - Error Recovery Playbook
+
+When you encounter a failure during debugging, follow these recovery steps.
+Use the relevant recovery steps. If required information or authority is missing, pause the dependent action and continue independent work.
+
+---
+
+## Cannot Reproduce the Bug
+
+**Symptoms**: Bug described by user but you can't trigger it
+
+1. Re-read user's reproduction steps; are you following them exactly?
+2. Check environment differences: browser, OS, node/python version
+3. Check data-dependent: does it need specific DB state or test data?
+4. Check timing: is it a race condition? Try adding delays or rapid repetition
+5. **After 3 attempts**: Record `Status: cannot_reproduce` in result with condition list
+   - NEVER give up immediately saying "cannot reproduce"
+
+---
+
+## Fix Introduces New Failure
+
+**Symptoms**: Original bug fixed but other tests break
+
+1. Read the failing tests; are they testing the old (buggy) behavior?
+2. If yes: update tests to reflect correct behavior
+3. If no: your fix has side effects. Revert and try a more targeted approach
+4. `find_referencing_symbols("fixedFunction")` to check all callers
+5. Consider: is the function contract changing? If so, update all callers
+
+---
+
+## Root Cause Unclear
+
+**Symptoms**: You see the failure but can't trace why
+
+1. Add logging at each step of the execution path
+2. Binary search: is the bug before or after the midpoint?
+3. `search_for_pattern("suspicious_pattern")` to find related code
+4. Check git history: `git log --oneline -20 -- path/to/file`. When was it last changed?
+5. Check: is it a dependency issue? Library version mismatch?
+6. **No progress after 5 turns**: Record current analysis in progress, switch to different hypothesis
+
+---
+
+## Bug Is in Another Agent's Domain
+
+**Symptoms**: Frontend bug caused by backend API, or vice versa
+
+1. Confirm: is the root cause really in the other domain?
+2. Document the cross-domain issue clearly:
+   - Which endpoint/component is wrong
+   - What the correct behavior should be
+   - Evidence (request/response logs, stack trace)
+3. Record in result: `cross_domain_issue: {agent: "backend", description: "..."}`
+4. **Do NOT modify directly**; touching another agent's code causes conflicts
+
+---
+
+## Performance Bug Hard to Measure
+
+**Symptoms**: "It's slow" but no clear metric
+
+1. Establish baseline: measure current response time / render time
+2. Backend: enable SQL query logging, count queries, check `EXPLAIN ANALYZE`
+3. Frontend: run Lighthouse, check React DevTools Profiler
+4. Mobile: use Flutter DevTools performance tab
+5. Profile before fixing; never optimize without data
+
+---
+
+## Test Cannot Be Written
+
+**Symptoms**: Bug is real but hard to test (race condition, environment-specific)
+
+1. Try: mock the timing / environment condition
+2. Try: integration test instead of unit test
+3. If truly untestable: document the manual reproduction steps
+4. Add a comment in code explaining why the fix is correct
+5. Note in result: `test_limitation: "reason why automated test is not feasible"`
+
+---
+
+## Rate Limit / Quota / Memory Fallback
+
+Same as the backend playbook: see `../../oma-backend/resources/error-playbook.md` §"Rate Limit / Quota Error (LLM runtime)" and §"Workflow State Unavailable".
+
+---
+
+## General Principles
+
+- **After 3 failures**: If same approach fails 3 times, must try a different method
+- **Blocked**: If no progress after 5 turns, save current state, `Status: blocked`
+- **Out of scope**: Other agent's domain. Only record, do not modify directly

package/skills/oma-debug/resources/execution-protocol.md

@@ -0,0 +1,40 @@
+# Debug Agent - Execution Protocol
+
+## Preparation
+Use the task's scope, existing project conventions, and acceptance criteria. Follow `../../_shared/core/execution-policy.md` when it has not already been supplied. Read only references needed by the selected operation; consult lessons or recovery guides for an observed issue. Expand planning depth only when the change requires it.
+
+## Step 1: Understand
+- Gather: What happened? What was expected? Error messages? Steps to reproduce?
+- Read relevant code following `../../_shared/core/code-intelligence.md`: locate the failing function, find callers, and search similar issues with configured tools or native fallback
+- Classify: logic bug, runtime error, performance issue, security flaw, or integration failure
+
+## Step 2: Reproduce & Diagnose
+- Trace execution flow from entry point to failure
+- Identify the exact line and condition that causes the bug
+- Determine root cause (not just symptom):
+  - Null/undefined access?
+  - Race condition?
+  - Missing validation?
+  - Wrong assumption about data shape?
+- Check `resources/common-patterns.md` for known patterns
+
+Before fixing a confirmed cause in an active OMA debug workflow, record `debug.root-cause` with the actual causal mechanism, selected remedy, bug/reproduction revision as `instanceId`, and reproduction/trace evidence. Verify the same instance using the command pair in `.agents/workflows/debug.md`; a matching subject from an older diagnosis is insufficient.
+
+## Step 3: Fix & Test
+- Write a regression test that:
+  - Fails without the fix
+  - Passes with the fix
+  - Covers the specific edge case
+- **Run the regression test before applying the fix where feasible**: record the failing output (RED), apply the minimal fix, record the pass (GREEN) — include both in the bug report / result file (see `../../_shared/core/test-approach.md` §Debug parity)
+- Apply minimal fix that addresses the root cause
+- Check for similar patterns elsewhere: `search_for_pattern("same_bug_pattern")`
+- If found, fix proactively or report them
+
+## Step 4: Document & Verify
+- Check applicable items in `resources/checklist.md`
+- Save bug report to `.agents/results/bugs/` using `resources/bug-report-template.md` (full template for Complex/CRITICAL/HIGH; condensed form in `resources/debugging-checklist.md` §Documentation Template for Simple/Medium)
+- Include: root cause, fix, prevention advice
+- Verify no regressions in related functionality
+
+## On Error
+See `resources/error-playbook.md` for recovery steps.

package/skills/oma-design/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: oma-design
+description: Define or review a visual system, DESIGN.md, or redesign direction.
+  Use for typography, layout, color, motion, and interaction design decisions.
+---
+
+# oma-design
+
+## Scheduling
+
+### Goal
+Resolve project design intent, select the applicable external design skill, and
+retain the project's visual contract and verification evidence. `DESIGN.md`
+records the design system when the task creates or materially changes it.
+
+### Intent signature
+- Design system, `DESIGN.md`, visual direction, redesign, or UI design review.
+- Typography, color, layout, motion, accessibility, or component decisions before implementation.
+
+### When to use
+- Define or revise a visual system or substantial design direction.
+- Review an existing UI or refine a chosen visual direction.
+- Extract design decisions from existing UI, screenshots, or supplied references.
+
+### When NOT to use
+- Implement application UI or export framework-specific tokens -> `oma-frontend` or `oma-mobile`.
+- Plan product scope -> `oma-pm`; generate an image -> `oma-image`.
+- Review general correctness or security -> `oma-qa` or `oma-security`.
+
+### Expected inputs
+- Requested surface and outcome, existing brand and project facts, and change scope.
+- Available `DESIGN.md`, `.design-context.md`, UI, screenshots, and references.
+- Platform, incumbent stack, content languages, accessibility, and responsive constraints.
+
+### Expected outputs
+- Requested design decision, findings, or implementation handoff with observed evidence.
+- Selected supplier, operation, resolved source, and capability or verification limits.
+
+```yaml
+outputs:
+  - name: design-doc
+    description: Updated visual contract when the design system materially changes
+    artifact: "DESIGN.md"
+    required: false
+  - name: design-context
+    description: Existing context refreshed after substantive discovery
+    artifact: ".design-context.md"
+    required: false
+```
+
+### Dependencies
+- Interface Design, Taste, or Impeccable, selected through `resources/external-design-skills.md`.
+- Project design artifacts and relevant local resources; Stitch and getdesign are optional inputs.
+- The implementation specialist's existing stack and validation tools.
+
+## Structural Flow
+
+### Transitions
+- A scoped correction reuses the affected UI and tokens; a discovery document is unnecessary.
+- For existing products, establish Preserve or Overhaul from the brief and current system.
+- For a post-implementation hierarchy, density, consistency, or craft review of an admin console, dashboard, SaaS product UI, or internal tool, select Interface Design `design-review` through `resources/product-interface-review.md`. The frontend recommendation is advisory unless the task explicitly requires design approval.
+- For other existing-UI critique, accessibility or technical audit, polish, or system extraction, select the matching Impeccable operation.
+- For dashboards, admin panels, SaaS product UI, or internal tools needing visual direction, select Interface Design.
+- When the surface is built around a data table or grid, pass `resources/data-grid.md` to the selected supplier with the brief.
+- For other new web art direction or an authorized visual overhaul, select Taste.
+- A documentation-only or token-contract task can remain local when no new visual judgment is needed.
+- Load one supplier for the current operation. A later operation may select another using the same project context.
+- A chosen GPU effect, cinematic video-scroll scene, or GSAP behavior adds the matching frontend implementation extension; it does not select another visual-direction supplier.
+
+### Failure and recovery
+| Failure | Recovery |
+|---|---|
+| Missing or incomplete external bundle | Resolve the catalog entry or use the bounded upstream loading path; retain its complete support directory. |
+| Supplier changes the stack, brand, or task scope | Restore the project constraints and choose the applicable operation; implementation remains with the owning specialist. |
+| A supplier gate needs an unavailable runtime or unauthorized build | Report the gate as unrun; do not replace it with a claimed pass. |
+| Explicitly requested supplier is unavailable | Report the failed route and missing capability; do not silently substitute a different supplier. |
+| Missing context changes the design decision | Reuse existing artifacts and the brief; ask only about the material unresolved choice. |
+
+### Exit
+The requested decision or artifact is ready for the next action, with the selected
+route, project constraints, observed checks, and unresolved limits recorded.
+
+## Logical Operations
+
+### Canonical workflow path
+1. Inspect the relevant UI, design artifacts, and brief. Establish scope, platform,
+   incumbent stack, languages, brand preservation, and applicable verification.
+2. Use `resources/external-design-skills.md` to select and load the supplier for
+   this operation. Follow its relevant instructions and support files.
+3. Apply the result to the requested decision or artifact. Update `DESIGN.md`
+   only when the visual system changes; use its local specification and semantic
+   token contract. Optional Stitch/getdesign inputs remain project references.
+4. Check the affected result using `resources/checklist.md`. Hand implementation
+   to the owning frontend/mobile specialist with the route and project constraints.
+   Include a specialized frontend route when the brief calls for that capability.
+
+### Resource scope and effects
+Reads project UI and design references; may write requested design artifacts and
+load external skill bundles. Supplier installers, hooks, engine downloads,
+background processes, and paid services are separate effects, not skill loading.
+
+### Guardrails
+1. Keep existing brand, content, URLs, navigation, form contracts, analytics, and
+   legal text within the authorized scope; use the redesign preservation contract.
+2. Keep incumbent fonts when suitable. For ko/ja/zh, verify glyph coverage,
+   fallback, line breaking, and readable metrics; Latin-only references do not establish CJK support.
+3. Carry accessibility, responsive, reduced-motion, and platform requirements into
+   the selected supplier. Keep WCAG AA as the default accessibility target, or
+   the project's stricter target. Its house style does not override that contract.
+4. Use actual project assets and claims. Preserve attribution and label concepts
+   and placeholders through the asset strategy.
+5. Keep the existing implementation stack. The implementation specialist owns
+   CSS/Tailwind/component-library syntax and dependencies.
+6. Keep review-only operations read-only. Existing task authorization and the
+   shared execution policy govern builds, clarification, scope, and side effects.
+7. Keep supplier visual cookbooks upstream. OMA's shared interaction-quality
+   guidance owns its adopted motion and interaction acceptance rules; do not
+   copy an entire external method catalog into these definitions.
+
+## References
+- `resources/product-interface-review.md`: recommended post-implementation product-interface review and frontend handoff.
+- `resources/external-design-skills.md`: supplier selection and complete-bundle loading.
+- `../oma-frontend/resources/specialized-visual-implementation.md`: chosen GPU, video-scroll, or GSAP implementation capability.
+- `../_shared/ui-interaction-quality.md`: motion intent, feedback, and interaction-quality decisions.
+- `resources/execution-protocol.md`: operation scope, artifacts, and handoff.
+- `resources/redesign-protocol.md`: preserving an existing product.
+- `resources/design-md-spec.md`: creating or materially revising DESIGN.md.
+- `resources/design-tokens.md`: semantic token handoff to implementation.
+- `resources/checklist.md`: affected-result verification and evidence.
+- `resources/data-grid.md`: alignment, filter toolbar, and row rules for data tables and grids.
+- `resources/asset-strategy.md`: actual assets, claims, provenance, and placeholders.
+- `resources/getdesign-fetcher.md`: explicitly relevant vendor inspiration.
+- `resources/stitch-integration.md`: requested Stitch operation.
+- `resources/error-playbook.md`: an observed supplier or design-tool failure.
+- `../_shared/core/execution-policy.md`: authorization, budgets, builds, and completion.

package/skills/oma-design/resources/asset-strategy.md

@@ -0,0 +1,34 @@
+# Design Asset Provenance
+
+Load this resource when the affected design uses imagery, brand marks, product
+previews, or placeholders. The selected design supplier owns placement and
+visual treatment; OMA retains the source and what the asset can truthfully show.
+
+## Choose relevant material
+
+1. Reuse suitable user or project assets: approved brand marks, real product
+   screenshots, photography, and existing component previews.
+2. Use `oma-image` for an original raster asset when generation fits the brief
+   and authorized scope. State when it is a concept rather than a real product.
+3. Use stock or placeholders only when permitted. Verify the actual source,
+   availability, applicable attribution, and intended placement.
+4. If required material is missing, label the slot and report what is needed.
+   Text-only content does not need decorative images to satisfy a quota.
+
+## Keep claims tied to evidence
+
+- Never invent a customer relationship or endorsement from a familiar logo.
+- Do not present a generated concept, stock image, or styled mockup as a
+  screenshot of the user's real product. Use an actual screenshot or component
+  preview when the page makes a claim about existing functionality.
+- Preserve approved logo geometry and brand identity within the requested scope.
+- Retain source, license/credit requirements, and generated-asset provenance with
+  the deliverable. A supplier's code license does not license every stock asset.
+- Do not emit guessed asset URLs. Record unavailable or unverified material.
+
+## Verify the affected use
+
+Inspect the rendered placement when an implementation exists. Check that
+essential content remains available if the asset fails, alternative text matches
+its role, and the target viewport/theme does not conceal required information.
+State when only the asset plan or file was inspected.