@jhm1909/ag-kit 0.1.0

package/.agent/skills/debugging/references/systematic-debugging.md

@@ -0,0 +1,295 @@
+---
+name: Systematic Debugging
+description: Four-phase debugging framework that ensures root cause investigation before attempting fixes. Never jump to solutions.
+when_to_use: when encountering any bug, test failure, or unexpected behavior, before proposing fixes
+version: 2.1.0
+languages: all
+---
+
+# Systematic Debugging
+
+## Overview
+
+Random fixes waste time and create new bugs. Quick patches mask underlying issues.
+
+**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
+
+**Violating the letter of this process is violating the spirit of debugging.**
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+If you haven't completed Phase 1, you cannot propose fixes.
+
+## When to Use
+
+Use for ANY technical issue:
+- Test failures
+- Bugs in production
+- Unexpected behavior
+- Performance problems
+- Build failures
+- Integration issues
+
+**Use this ESPECIALLY when:**
+- Under time pressure (emergencies make guessing tempting)
+- "Just one quick fix" seems obvious
+- You've already tried multiple fixes
+- Previous fix didn't work
+- You don't fully understand the issue
+
+**Don't skip when:**
+- Issue seems simple (simple bugs have root causes too)
+- You're in a hurry (rushing guarantees rework)
+- Manager wants it fixed NOW (systematic is faster than thrashing)
+
+## The Four Phases
+
+You MUST complete each phase before proceeding to the next.
+
+### Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+1. **Read Error Messages Carefully**
+   - Don't skip past errors or warnings
+   - They often contain the exact solution
+   - Read stack traces completely
+   - Note line numbers, file paths, error codes
+
+2. **Reproduce Consistently**
+   - Can you trigger it reliably?
+   - What are the exact steps?
+   - Does it happen every time?
+   - If not reproducible → gather more data, don't guess
+
+3. **Check Recent Changes**
+   - What changed that could cause this?
+   - Git diff, recent commits
+   - New dependencies, config changes
+   - Environmental differences
+
+4. **Gather Evidence in Multi-Component Systems**
+
+   **WHEN system has multiple components (CI → build → signing, API → service → database):**
+
+   **BEFORE proposing fixes, add diagnostic instrumentation:**
+   ```
+   For EACH component boundary:
+     - Log what data enters component
+     - Log what data exits component
+     - Verify environment/config propagation
+     - Check state at each layer
+
+   Run once to gather evidence showing WHERE it breaks
+   THEN analyze evidence to identify failing component
+   THEN investigate that specific component
+   ```
+
+   **Example (multi-layer system):**
+   ```bash
+   # Layer 1: Workflow
+   echo "=== Secrets available in workflow: ==="
+   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
+
+   # Layer 2: Build script
+   echo "=== Env vars in build script: ==="
+   env | grep IDENTITY || echo "IDENTITY not in environment"
+
+   # Layer 3: Signing script
+   echo "=== Keychain state: ==="
+   security list-keychains
+   security find-identity -v
+
+   # Layer 4: Actual signing
+   codesign --sign "$IDENTITY" --verbose=4 "$APP"
+   ```
+
+   **This reveals:** Which layer fails (secrets → workflow ✓, workflow → build ✗)
+
+5. **Trace Data Flow**
+
+   **WHEN error is deep in call stack:**
+
+   See skills/root-cause-tracing for backward tracing technique
+
+   **Quick version:**
+   - Where does bad value originate?
+   - What called this with bad value?
+   - Keep tracing up until you find the source
+   - Fix at source, not at symptom
+
+### Phase 2: Pattern Analysis
+
+**Find the pattern before fixing:**
+
+1. **Find Working Examples**
+   - Locate similar working code in same codebase
+   - What works that's similar to what's broken?
+
+2. **Compare Against References**
+   - If implementing pattern, read reference implementation COMPLETELY
+   - Don't skim - read every line
+   - Understand the pattern fully before applying
+
+3. **Identify Differences**
+   - What's different between working and broken?
+   - List every difference, however small
+   - Don't assume "that can't matter"
+
+4. **Understand Dependencies**
+   - What other components does this need?
+   - What settings, config, environment?
+   - What assumptions does it make?
+
+### Phase 3: Hypothesis and Testing
+
+**Scientific method:**
+
+1. **Form Single Hypothesis**
+   - State clearly: "I think X is the root cause because Y"
+   - Write it down
+   - Be specific, not vague
+
+2. **Test Minimally**
+   - Make the SMALLEST possible change to test hypothesis
+   - One variable at a time
+   - Don't fix multiple things at once
+
+3. **Verify Before Continuing**
+   - Did it work? Yes → Phase 4
+   - Didn't work? Form NEW hypothesis
+   - DON'T add more fixes on top
+
+4. **When You Don't Know**
+   - Say "I don't understand X"
+   - Don't pretend to know
+   - Ask for help
+   - Research more
+
+### Phase 4: Implementation
+
+**Fix the root cause, not the symptom:**
+
+1. **Create Failing Test Case**
+   - Simplest possible reproduction
+   - Automated test if possible
+   - One-off test script if no framework
+   - MUST have before fixing
+   - See skills/testing/test-driven-development for writing proper failing tests
+
+2. **Implement Single Fix**
+   - Address the root cause identified
+   - ONE change at a time
+   - No "while I'm here" improvements
+   - No bundled refactoring
+
+3. **Verify Fix**
+   - Test passes now?
+   - No other tests broken?
+   - Issue actually resolved?
+
+4. **If Fix Doesn't Work**
+   - STOP
+   - Count: How many fixes have you tried?
+   - If < 3: Return to Phase 1, re-analyze with new information
+   - **If ≥ 3: STOP and question the architecture (step 5 below)**
+   - DON'T attempt Fix #4 without architectural discussion
+
+5. **If 3+ Fixes Failed: Question Architecture**
+
+   **Pattern indicating architectural problem:**
+   - Each fix reveals new shared state/coupling/problem in different place
+   - Fixes require "massive refactoring" to implement
+   - Each fix creates new symptoms elsewhere
+
+   **STOP and question fundamentals:**
+   - Is this pattern fundamentally sound?
+   - Are we "sticking with it through sheer inertia"?
+   - Should we refactor architecture vs. continue fixing symptoms?
+
+   **Discuss with your human partner before attempting more fixes**
+
+   This is NOT a failed hypothesis - this is a wrong architecture.
+
+## Red Flags - STOP and Follow Process
+
+If you catch yourself thinking:
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "Add multiple changes, run tests"
+- "Skip the test, I'll manually verify"
+- "It's probably X, let me fix that"
+- "I don't fully understand but this might work"
+- "Pattern says X but I'll adapt it differently"
+- "Here are the main problems: [lists fixes without investigation]"
+- Proposing solutions before tracing data flow
+- **"One more fix attempt" (when already tried 2+)**
+- **Each fix reveals new problem in different place**
+
+**ALL of these mean: STOP. Return to Phase 1.**
+
+**If 3+ fixes failed:** Question the architecture (see Phase 4.5)
+
+## your human partner's Signals You're Doing It Wrong
+
+**Watch for these redirections:**
+- "Is that not happening?" - You assumed without verifying
+- "Will it show us...?" - You should have added evidence gathering
+- "Stop guessing" - You're proposing fixes without understanding
+- "Ultrathink this" - Question fundamentals, not just symptoms
+- "We're stuck?" (frustrated) - Your approach isn't working
+
+**When you see these:** STOP. Return to Phase 1.
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. |
+| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |
+| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
+| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. |
+| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
+| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. |
+| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
+| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. |
+
+## Quick Reference
+
+| Phase | Key Activities | Success Criteria |
+|-------|---------------|------------------|
+| **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |
+| **2. Pattern** | Find working examples, compare | Identify differences |
+| **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |
+| **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |
+
+## When Process Reveals "No Root Cause"
+
+If systematic investigation reveals issue is truly environmental, timing-dependent, or external:
+
+1. You've completed the process
+2. Document what you investigated
+3. Implement appropriate handling (retry, timeout, error message)
+4. Add monitoring/logging for future investigation
+
+**But:** 95% of "no root cause" cases are incomplete investigation.
+
+## Integration with Other Skills
+
+This skill works with:
+- skills/root-cause-tracing - How to trace back through call stack
+- skills/defense-in-depth - Add validation after finding root cause
+- skills/testing/condition-based-waiting - Replace timeouts identified in Phase 2
+- skills/verification-before-completion - Verify fix worked before claiming success
+
+## Real-World Impact
+
+From debugging sessions:
+- Systematic approach: 15-30 minutes to fix
+- Random fixes approach: 2-3 hours of thrashing
+- First-time fix rate: 95% vs 40%
+- New bugs introduced: Near zero vs common

package/.agent/skills/debugging/references/verification-before-completion.md

@@ -0,0 +1,142 @@
+---
+name: Verification Before Completion
+description: Run verification commands and confirm output before claiming success
+when_to_use: when about to claim work is complete, fixed, or passing, before committing or creating PRs
+version: 1.1.0
+languages: all
+---
+
+# Verification Before Completion
+
+## Overview
+
+Claiming work is complete without verification is dishonesty, not efficiency.
+
+**Core principle:** Evidence before claims, always.
+
+**Violating the letter of this rule is violating the spirit of this rule.**
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this message, you cannot claim it passes.
+
+## The Gate Function
+
+```
+BEFORE claiming any status or expressing satisfaction:
+
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute the FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm the claim?
+   - If NO: State actual status with evidence
+   - If YES: State claim WITH evidence
+5. ONLY THEN: Make the claim
+
+Skip any step = lying, not verifying
+```
+
+## Common Failures
+
+| Claim | Requires | Not Sufficient |
+|-------|----------|----------------|
+| Tests pass | Test command output: 0 failures | Previous run, "should pass" |
+| Linter clean | Linter output: 0 errors | Partial check, extrapolation |
+| Build succeeds | Build command: exit 0 | Linter passing, logs look good |
+| Bug fixed | Test original symptom: passes | Code changed, assumed fixed |
+| Regression test works | Red-green cycle verified | Test passes once |
+| Agent completed | VCS diff shows changes | Agent reports "success" |
+| Requirements met | Line-by-line checklist | Tests passing |
+
+## Red Flags - STOP
+
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!", etc.)
+- About to commit/push/PR without verification
+- Trusting agent success reports
+- Relying on partial verification
+- Thinking "just this once"
+- Tired and wanting work over
+- **ANY wording implying success without having run verification**
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "Should work now" | RUN the verification |
+| "I'm confident" | Confidence ≠ evidence |
+| "Just this once" | No exceptions |
+| "Linter passed" | Linter ≠ compiler |
+| "Agent said success" | Verify independently |
+| "I'm tired" | Exhaustion ≠ excuse |
+| "Partial check is enough" | Partial proves nothing |
+| "Different words so rule doesn't apply" | Spirit over letter |
+
+## Key Patterns
+
+**Tests:**
+```
+✅ [Run test command] [See: 34/34 pass] "All tests pass"
+❌ "Should pass now" / "Looks correct"
+```
+
+**Regression tests (TDD Red-Green):**
+```
+✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
+❌ "I've written a regression test" (without red-green verification)
+```
+
+**Build:**
+```
+✅ [Run build] [See: exit 0] "Build passes"
+❌ "Linter passed" (linter doesn't check compilation)
+```
+
+**Requirements:**
+```
+✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
+❌ "Tests pass, phase complete"
+```
+
+**Agent delegation:**
+```
+✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
+❌ Trust agent report
+```
+
+## Why This Matters
+
+From 24 failure memories:
+- your human partner said "I don't believe you" - trust broken
+- Undefined functions shipped - would crash
+- Missing requirements shipped - incomplete features
+- Time wasted on false completion → redirect → rework
+- Violates: "Honesty is a core value. If you lie, you'll be replaced."
+
+## When To Apply
+
+**ALWAYS before:**
+- ANY variation of success/completion claims
+- ANY expression of satisfaction
+- ANY positive statement about work state
+- Committing, PR creation, task completion
+- Moving to next task
+- Delegating to agents
+
+**Rule applies to:**
+- Exact phrases
+- Paraphrases and synonyms
+- Implications of success
+- ANY communication suggesting completion/correctness
+
+## The Bottom Line
+
+**No shortcuts for verification.**
+
+Run the command. Read the output. THEN claim the result.
+
+This is non-negotiable.

package/.agent/skills/designer/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: designer
+description: >
+  UI/UX design intelligence with searchable database. 50+ styles, 161 color palettes, 57 font pairings,
+  161 product types, 99 UX guidelines. BM25 search engine for data-driven design decisions.
+  Use for creating interfaces, visual identity, design systems, and accessibility.
+license: MIT
+compatibility: Claude Code, Cursor, Gemini CLI, GitHub Copilot
+metadata:
+  author: jhm1909
+  version: "4.0.0"
+  domain: design
+  estimated_tokens: 15000
+---
+
+# Designer — Design Intelligence
+
+Expert design guidance powered by a **searchable design database** with BM25 ranking.
+
+## Knowledge Graph
+
+- **extends**: []
+- **requires**: []
+- **suggests**: [[frontend-developer]], [[research-first]]
+- **conflicts**: []
+- **enhances**: [[frontend-developer]] (implementation of designs)
+- **moc**: [[design-moc]]
+
+---
+
+## Design Intelligence Search (REQUIRED)
+
+Before making ANY design decision, **search the database** for data-driven recommendations.
+
+### Prerequisites
+
+```bash
+python3 --version  # Python 3.x required (zero external dependencies)
+```
+
+### Design System Generation (Start Here)
+
+```bash
+python3 skills/designer/scripts/ui-search/search.py "<product_type> <industry> <keywords>" --design-system [-p "Project Name"]
+```
+
+**Example:**
+```bash
+python3 skills/designer/scripts/ui-search/search.py "fintech SaaS dashboard modern" --design-system -p "PayFlow"
+```
+
+Returns: Complete design system (style, colors, typography, effects, anti-patterns).
+
+### Domain Search (Deep-Dive)
+
+```bash
+python3 skills/designer/scripts/ui-search/search.py "<keyword>" --domain <domain> [-n <max_results>]
+```
+
+| Domain | Use For | Example |
+|--------|---------|---------|
+| `product` | Product type recommendations | `--domain product "SaaS e-commerce"` |
+| `style` | UI styles, effects | `--domain style "glassmorphism dark"` |
+| `color` | Color palettes by product | `--domain color "fintech professional"` |
+| `typography` | Font pairings | `--domain typography "elegant modern"` |
+| `chart` | Chart types + libraries | `--domain chart "trend dashboard"` |
+| `ux` | Best practices, anti-patterns | `--domain ux "animation accessibility"` |
+| `icons` | Icon recommendations | `--domain icons "navigation e-commerce"` |
+| `react` | React/Next.js performance | `--domain react "rerender bundle"` |
+| `web` | App interface guidelines | `--domain web "touch targets safe areas"` |
+| `landing` | Page structure, CTA | `--domain landing "hero social-proof"` |
+
+### Workflow
+
+```
+1. ANALYZE requirements → product type, audience, style keywords
+2. SEARCH --design-system → get full recommendation
+3. DEEP-DIVE --domain → supplement specific needs
+4. IMPLEMENT → using verified, data-driven choices
+```
+
+---
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Key Checks |
+|----------|----------|--------|------------|
+| 1 | Accessibility | CRITICAL | Contrast 4.5:1, alt text, keyboard nav, aria-labels |
+| 2 | Touch & Interaction | CRITICAL | Min 44×44px targets, 8px spacing, loading feedback |
+| 3 | Performance | HIGH | WebP/AVIF, lazy loading, CLS < 0.1 |
+| 4 | Style Selection | HIGH | Match product type, consistency, SVG icons |
+| 5 | Layout & Responsive | HIGH | Mobile-first, viewport meta, no horizontal scroll |
+| 6 | Typography & Color | MEDIUM | Base 16px, line-height 1.5, semantic tokens |
+| 7 | Animation | MEDIUM | 150-300ms, transform/opacity only, reduced-motion |
+| 8 | Forms & Feedback | MEDIUM | Visible labels, error near field, progressive disclosure |
+| 9 | Navigation | HIGH | Bottom nav ≤5, predictable back, deep linking |
+| 10 | Charts & Data | LOW | Legends, tooltips, accessible colors |
+
+---
+
+## Core Principles
+
+### Intentionality Over Trends
+- **Why this color?** — Brand meaning, accessibility, contrast
+- **Why this font?** — Readability, personality, performance
+- **Why this animation?** — User feedback, spatial understanding
+
+### Distinctive Over Generic (Anti-AI-Slop)
+- ❌ Default gradients, Inter everywhere, card templates
+- ✅ Committed aesthetic, unique typography, contextual layouts
+- 📖 Load [Frontend Design Aesthetics](./references/frontend_design_aesthetics.md) for Anthropic's anti-AI-slop guide
+
+### Technical Excellence
+- Semantic HTML first
+- CSS custom properties for theming
+- Performance-minded animations
+- Accessibility as foundation
+
+---
+
+## Pre-Delivery Checklist
+
+### Visual
+- [ ] SVG icons (no emojis as UI elements)
+- [ ] Consistent icon family and style
+- [ ] Semantic theme tokens (no hardcoded hex)
+
+### Interaction
+- [ ] All tappable elements have press feedback
+- [ ] Touch targets ≥44×44pt
+- [ ] Micro-interactions 150-300ms
+- [ ] Disabled states visually clear
+
+### Light/Dark Mode
+- [ ] Primary text contrast ≥4.5:1 in both modes
+- [ ] Dividers/borders visible in both modes
+- [ ] Both themes tested before delivery
+
+### Layout
+- [ ] Safe areas respected
+- [ ] 4/8dp spacing rhythm maintained
+- [ ] Verified on small + large screens
+
+### Accessibility
+- [ ] All images/icons have alt text
+- [ ] Color is never the only indicator
+- [ ] Reduced motion supported
+
+---
+
+## Asset Creation Workflow
+
+1. **Generate** with `generate_image` (follow `.agent/rules/nano-banana.md`)
+2. **Process** with `scripts/remove_background.py`
+3. **Deliver** to [[frontend-developer]] for implementation
+
+---
+
+*Design intelligence v4.0 | Searchable database + Anthropic aesthetics | Source: [Anthropic frontend-design](https://github.com/anthropics/skills)*

package/.agent/skills/designer/concepts/apple-glass.md

@@ -0,0 +1,48 @@
+# Apple Glassmorphism (VisionOS / modern macOS)
+
+**Concept**: A premium, depth-oriented interface that mimics physical glass materials. It relies heavily on background blurring, translucency, and light interaction to create a sense of hierarchy and spatial awareness.
+
+**Key Characteristics**:
+
+- **Translucency**: High-quality `backdrop-filter: blur()`.
+- **Depth**: Multiple layers of glass with varying opacity.
+- **Light**: Subtle white borders and inner shadows to simulate edge lighting and thickness.
+- **Hierarchy**: Content floats on top of the background, creating a sense of Z-axis layering.
+
+**CSS Implementation Guide**:
+
+```css
+.apple-glass {
+  /* Base Material */
+  background: rgba(255, 255, 255, 0.65); /* Light mode base */
+  backdrop-filter: blur(20px) saturate(180%);
+  -webkit-backdrop-filter: blur(20px) saturate(180%);
+
+  /* Border / Edge Light */
+  border: 1px solid rgba(255, 255, 255, 0.4);
+
+  /* Depth & Volume */
+  box-shadow:
+    0 4px 30px rgba(0, 0, 0, 0.1),
+    /* Drop shadow for lift */ inset 0 0 0 1px rgba(255, 255, 255, 0.2); /* Inner lighting */
+
+  border-radius: 20px;
+}
+
+/* Dark Mode Variant */
+@media (prefers-color-scheme: dark) {
+  .apple-glass {
+    background: rgba(30, 30, 30, 0.6);
+    border: 1px solid rgba(255, 255, 255, 0.1);
+    box-shadow:
+      0 4px 30px rgba(0, 0, 0, 0.3),
+      inset 0 0 0 1px rgba(255, 255, 255, 0.05);
+  }
+}
+```
+
+**Usage**:
+
+- Sidebars, modal windows, floating controls.
+- When you want a "native" application feel.
+- Best used with colorful, abstract backgrounds to show off the blur effect.

package/.agent/skills/designer/concepts/aurora-gradients.md

@@ -0,0 +1,26 @@
+# Aurora / Mesh Gradients
+
+**Concept**: Ethereal, flowing, and mood-setting. Focuses on soft, moving gradients that blend multiple colors seamlessly.
+
+**Key Characteristics**:
+
+- **Backgrounds**: Multiple radial gradients blurred together.
+- **Motion**: Slow, liquid movement of color blobs.
+- **Overlay**: Often paired with Glassmorphism.
+
+**CSS Implementation Guide**:
+
+```css
+.aurora-bg {
+  background-color: #ff9a9e;
+  background-image:
+    radial-gradient(at 40% 20%, hsla(28, 100%, 74%, 1) 0px, transparent 50%),
+    radial-gradient(at 80% 0%, hsla(189, 100%, 56%, 1) 0px, transparent 50%),
+    radial-gradient(at 0% 50%, hsla(355, 100%, 93%, 1) 0px, transparent 50%);
+  filter: blur(40px);
+}
+```
+
+**Usage**:
+
+- SaaS landing pages, login screens, emotional branding.

package/.agent/skills/designer/concepts/bento-grids.md

@@ -0,0 +1,14 @@
+# Bento Grids
+
+**Concept**: Inspired by Japanese lunch boxes (Bento). Content is organized into rigid, yet varied rectangular distinct cells.
+
+**Key Characteristics**:
+
+- **Layout**: CSS Grid based.
+- **Content**: Each cell is self-contained (image, text, control).
+- **Spacing**: Consistent, typically large gaps.
+- **Curvature**: Uniform border-radius on all cells (`24px+`).
+
+**Usage**:
+
+- Product showcases, feature lists, shiny marketing sections.