oh-my-ag 1.2.0

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

@@ -0,0 +1,362 @@
+# 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 → **workflow-guide**
+- [ ] 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 `.gemini/antigravity/brain/bugs/`:
+
+```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)
+- **Serena MCP**: find_symbol, search_for_pattern, find_referencing_symbols
+- **Antigravity Browser**: Automated testing and reproduction
+- **React Profiler**: Performance analysis
+- **Lighthouse**: Performance audit
+- **Git bisect**: Find when bug was introduced

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

@@ -0,0 +1,94 @@
+# Debug Agent - Error Recovery Playbook
+
+When you encounter a failure during debugging, follow these recovery steps.
+Do NOT stop or ask for help until you have exhausted the playbook.
+
+---
+
+## 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. **3회 시도 후**: result에 `Status: 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. **5턴 진전 없음**: 현재 분석 결과를 progress에 기록, 다른 가설로 전환
+
+---
+
+## 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. **직접 수정하지 말 것** — 다른 에이전트의 코드를 건드리면 충돌 발생
+
+---
+
+## 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
+
+동일: backend-agent 플레이북의 해당 섹션 참조.
+
+---
+
+## 일반 원칙
+
+- **3회 실패**: 같은 접근 3번 실패하면 반드시 다른 방법 시도
+- **막힘**: 5턴 이상 진전 없으면 현재 상태 저장, `Status: blocked`
+- **범위 초과**: 다른 에이전트 영역은 기록만, 직접 수정 금지

package/.agent/skills/debug-agent/resources/examples.md

@@ -0,0 +1,87 @@
+# Debug Agent - Examples
+
+## Example 1: Null Reference Error
+
+**Input**: "TodoList crashes with 'Cannot read property map of undefined'"
+
+**Output**:
+```
+## Bug Analysis
+
+**Root Cause**: TodoList renders before API data loads. `todos` is undefined
+on first render, and `.map()` is called immediately.
+
+**Why**: useEffect fetches async, but component doesn't guard against
+undefined initial state.
+
+## Fix
+- Before: `todos.map(t => <TodoItem ... />)`
+- After: `todos?.map(t => <TodoItem ... />) ?? <EmptyState />`
+- Also added loading spinner while fetching
+
+## Changes Made
+1. Added `if (isLoading) return <Spinner />`
+2. Added optional chaining on `todos?.map()`
+3. Added empty state component
+
+## Files Modified
+- src/components/TodoList.tsx (guard + loading state)
+- src/components/EmptyState.tsx (NEW)
+- tests/TodoList.test.tsx (regression test)
+
+## Prevention
+Use TanStack Query which provides `isLoading`/`data` pattern by default.
+```
+
+## Example 2: N+1 Query Performance Bug
+
+**Input**: "The posts page takes 3 seconds to load with only 50 posts"
+
+**Output**:
+```
+## Bug Analysis
+
+**Root Cause**: N+1 query. For each post, a separate SQL query fetches
+the author. 50 posts = 51 queries.
+
+**Why**: SQLAlchemy lazy-loads relationships by default.
+
+## Fix
+- Before: `db.query(Post).all()`
+- After: `db.query(Post).options(joinedload(Post.author)).all()`
+
+## Changes Made
+1. Added eager loading with joinedload
+2. Load time: 3000ms -> 45ms
+
+## Files Modified
+- app/api/posts.py (eager loading)
+- tests/test_posts.py (performance assertion: < 200ms)
+```
+
+## Example 3: Race Condition
+
+**Input**: "Search results show wrong data when typing fast"
+
+**Output**:
+```
+## Bug Analysis
+
+**Root Cause**: Race condition. Fast typing triggers multiple API calls.
+Slower early requests resolve after faster recent ones, overwriting
+correct results.
+
+**Why**: No request cancellation; last-write-wins causes stale data.
+
+## Fix
+Added AbortController to cancel previous request on new keystroke.
+
+## Changes Made
+1. useEffect cleanup cancels pending request
+2. Added debounce (300ms) to reduce API calls
+3. Added `cancelled` flag to ignore stale responses
+
+## Files Modified
+- src/hooks/useSearch.ts (abort + debounce)
+- tests/useSearch.test.ts (race condition test)
+```

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

@@ -0,0 +1,51 @@
+# Debug Agent - Execution Protocol
+
+## Step 0: Prepare
+1. **Assess difficulty** — see `../_shared/difficulty-guide.md`
+   - **Simple**: Skip to Step 3 | **Medium**: All 4 steps | **Complex**: All steps + checkpoints
+2. **Check lessons** — read your domain section in `../_shared/lessons-learned.md`
+3. **Clarify requirements** — follow `../_shared/clarification-protocol.md`
+   - Check **Uncertainty Triggers**: 보안/인증 관련 버그, 기존 코드 충돌 가능성?
+   - Determine level: LOW → proceed | MEDIUM → present options | HIGH → ask immediately
+4. **Use reasoning templates** — for Complex bugs, use `../_shared/reasoning-templates.md` (hypothesis loop, execution trace)
+5. **Budget context** — follow `../_shared/context-budget.md` (use find_symbol, not read_file)
+
+**⚠️ Intelligent Escalation**: When uncertain, escalate early. Don't blindly proceed.
+
+Follow these steps in order (adjust depth by difficulty).
+
+## Step 1: Understand
+- Gather: What happened? What was expected? Error messages? Steps to reproduce?
+- Read relevant code using Serena:
+  - `find_symbol("functionName")`: Locate the failing function
+  - `find_referencing_symbols("Component")`: Find all callers
+  - `search_for_pattern("error pattern")`: Find similar issues
+- 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
+
+## Step 3: Fix & Test
+- Apply minimal fix that addresses the root cause
+- Write a regression test that:
+  - Fails without the fix
+  - Passes with the fix
+  - Covers the specific edge case
+- Check for similar patterns elsewhere: `search_for_pattern("same_bug_pattern")`
+- If found, fix proactively or report them
+
+## Step 4: Document & Verify
+- Run `resources/checklist.md` items
+- Save bug report to `.gemini/antigravity/brain/bugs/` using `resources/bug-report-template.md`
+- Include: root cause, fix, prevention advice
+- Verify no regressions in related functionality
+
+## On Error
+See `resources/error-playbook.md` for recovery steps.

package/.agent/skills/frontend-agent/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: frontend-agent
+description: Frontend specialist for React, Next.js, TypeScript, and modern UI development
+---
+
+# Frontend Agent - UI/UX Specialist
+
+## When to use
+- Building user interfaces and components
+- Client-side logic and state management
+- Styling and responsive design
+- Form validation and user interactions
+- Integrating with backend APIs
+
+## When NOT to use
+- Backend API implementation -> use Backend Agent
+- Native mobile development -> use Mobile Agent
+
+## Core Rules
+1. TypeScript strict mode; explicit interfaces for all props
+2. Tailwind CSS only (no inline styles, no CSS modules)
+3. Semantic HTML with ARIA labels; keyboard navigation required
+4. Loading, error, and empty states for every async operation
+5. Responsive at 320px, 768px, 1024px, 1440px
+6. shadcn/ui + Radix for component primitives
+
+## How to Execute
+Follow `resources/execution-protocol.md` step by step.
+See `resources/examples.md` for input/output examples.
+Before submitting, run `resources/checklist.md`.
+
+## Serena Memory (CLI Mode)
+See `../_shared/serena-memory-protocol.md`.
+
+## References
+- Execution steps: `resources/execution-protocol.md`
+- Code examples: `resources/examples.md`
+- Code snippets: `resources/snippets.md`
+- Checklist: `resources/checklist.md`
+- Error recovery: `resources/error-playbook.md`
+- Tech stack: `resources/tech-stack.md`
+- Component template: `resources/component-template.tsx`
+- Tailwind rules: `resources/tailwind-rules.md`
+- Context loading: `../_shared/context-loading.md`
+- Reasoning templates: `../_shared/reasoning-templates.md`
+- Clarification: `../_shared/clarification-protocol.md`
+- Context budget: `../_shared/context-budget.md`
+- Lessons learned: `../_shared/lessons-learned.md`

package/.agent/skills/frontend-agent/resources/checklist.md

@@ -0,0 +1,38 @@
+# Frontend Agent - Self-Verification Checklist
+
+Run through every item before submitting your work.
+
+## TypeScript
+- [ ] Strict mode, no `any` types
+- [ ] Explicit interfaces for all component props
+- [ ] No TypeScript errors (`npx tsc --noEmit`)
+
+## Styling
+- [ ] Tailwind CSS only (no inline styles, no CSS modules)
+- [ ] Responsive at 320px, 768px, 1024px, 1440px
+- [ ] Dark mode supported (if project uses it)
+- [ ] No hardcoded colors (use Tailwind theme tokens)
+
+## Accessibility (WCAG 2.1 AA)
+- [ ] Semantic HTML elements (`<nav>`, `<main>`, `<button>`)
+- [ ] All images have alt text
+- [ ] Color contrast >= 4.5:1 (normal text), >= 3:1 (large text)
+- [ ] Keyboard navigation works for all interactive elements
+- [ ] ARIA labels on non-obvious interactive elements
+- [ ] Focus indicators visible
+
+## UX States
+- [ ] Loading state (skeleton or spinner)
+- [ ] Error state (user-friendly message + retry action)
+- [ ] Empty state (helpful message + CTA)
+- [ ] Optimistic updates where appropriate
+
+## Performance
+- [ ] No unnecessary re-renders (check with React DevTools Profiler)
+- [ ] Code splitting for route-level components
+- [ ] Images optimized and lazy-loaded
+
+## Testing
+- [ ] Unit tests for components with logic
+- [ ] User interactions tested (click, type, submit)
+- [ ] Async behavior tested (loading -> data -> display)