@su-record/vibe 2.7.6 → 2.7.9

package/skills/seo-checklist/SKILL.md

@@ -1,244 +1,57 @@
 ---
 name: seo-checklist
-description: "SEO/GEO checklist for web development - meta tags, structured data, Core Web Vitals"
+description: "SEO gotchas for web development - easy-to-miss items that hurt search ranking"
 triggers: [seo, search, meta, sitemap, schema, structured data, og, opengraph, google, naver]
 priority: 65
 ---
-# SEO Checklist Skill
 
-Development output SEO quality checklist for web projects.
+# SEO Checklist
 
-## When to Use
+## Pre-check (K1)
 
-- Web application development with `/vibe.run`
-- Landing pages and marketing sites
-- E-commerce product pages
-- Content-heavy applications
+> Is this a public-facing web page that needs search visibility? Internal tools, admin panels, and authenticated-only pages don't need SEO optimization.
 
-## Essential SEO Elements
+## Easy-to-Miss Gotchas
 
-### 1. Meta Tags (Required)
+### Meta & Social
 
-```html
-<!-- Basic -->
-<title>Page Title - Brand (50-60 chars)</title>
-<meta name="description" content="Compelling description (150-160 chars)">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<link rel="canonical" href="https://example.com/page">
+| Gotcha | Why It Hurts | Fix |
+|--------|-------------|-----|
+| Missing `<link rel="canonical">` | Duplicate content penalty from URL variants | Set canonical on every page, including paginated |
+| OG image wrong size | Cropped/pixelated on social share | Must be exactly **1200x630px** |
+| Same title/description on all pages | Google treats as duplicate content | Unique title (50-60 chars) + description (150-160 chars) per page |
+| Missing `og:type` | Defaults to "website" for articles | Set `article` for posts, `product` for products |
 
-<!-- Open Graph -->
-<meta property="og:title" content="Title">
-<meta property="og:description" content="Description">
-<meta property="og:image" content="https://example.com/og-image.png">
-<meta property="og:url" content="https://example.com/page">
-<meta property="og:type" content="website">
+### Technical
 
-<!-- Twitter -->
-<meta name="twitter:card" content="summary_large_image">
-<meta name="twitter:title" content="Title">
-<meta name="twitter:description" content="Description">
-<meta name="twitter:image" content="https://example.com/twitter-image.png">
-```
+| Gotcha | Why It Hurts | Fix |
+|--------|-------------|-----|
+| `robots.txt` blocks important pages | Pages not indexed | `Allow: /` for public, only block `/api/`, `/admin/` |
+| No sitemap or stale sitemap | Crawler misses new pages | Auto-generate, include `<lastmod>` with real dates |
+| `noindex` left in production | Entire site invisible | Verify `<meta name="robots">` in production build |
+| Images without `width`/`height` | CLS layout shift penalty | Always set dimensions + `loading="lazy"` for below-fold |
 
-### 2. Structured Data (Schema.org)
+### Core Web Vitals
 
-```html
-<script type="application/ld+json">
-{
-  "@context": "https://schema.org",
-  "@type": "WebPage",
-  "name": "Page Title",
-  "description": "Page description",
-  "url": "https://example.com/page"
-}
-</script>
-```
+| Metric | Target | Common Miss |
+|--------|--------|-------------|
+| LCP | ≤2.5s | Hero image not preloaded — add `<link rel="preload">` |
+| INP | ≤200ms | Heavy JS on interaction — defer non-critical scripts |
+| CLS | ≤0.1 | Dynamic content without reserved space — set `min-height` |
 
-#### Common Schema Types
+### Structured Data
 
-| Type | Use Case |
-|------|----------|
-| `Organization` | Company/brand pages |
-| `Product` | E-commerce product pages |
-| `Article` | Blog posts, news |
-| `FAQPage` | FAQ sections |
-| `BreadcrumbList` | Navigation breadcrumbs |
-| `LocalBusiness` | Local/physical stores |
+| Gotcha | Fix |
+|--------|-----|
+| JSON-LD not validated | Test with Google Rich Results Test before deploy |
+| Wrong `@type` | `Product` for products, `Article` for posts, `FAQPage` for FAQs |
+| Missing `BreadcrumbList` | Add breadcrumb schema for all non-root pages |
 
-### 3. Technical SEO Files
+## Done Criteria (K4)
 
-#### robots.txt
-```
-User-agent: *
-Allow: /
-Disallow: /api/
-Disallow: /admin/
-
-Sitemap: https://example.com/sitemap.xml
-```
-
-#### sitemap.xml
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
-  <url>
-    <loc>https://example.com/</loc>
-    <lastmod>2024-01-01</lastmod>
-    <changefreq>weekly</changefreq>
-    <priority>1.0</priority>
-  </url>
-</urlset>
-```
-
-### 4. Performance (Core Web Vitals)
-
-| Metric | Good | Needs Work | Poor |
-|--------|------|------------|------|
-| LCP (Largest Contentful Paint) | ≤2.5s | ≤4.0s | >4.0s |
-| INP (Interaction to Next Paint) | ≤200ms | ≤500ms | >500ms |
-| CLS (Cumulative Layout Shift) | ≤0.1 | ≤0.25 | >0.25 |
-
-### 5. Image Optimization
-
-```html
-<!-- Responsive images -->
-<img
-  src="image.webp"
-  alt="Descriptive alt text"
-  width="800"
-  height="600"
-  loading="lazy"
-  decoding="async"
->
-
-<!-- Next.js Image -->
-<Image
-  src="/image.webp"
-  alt="Descriptive alt text"
-  width={800}
-  height={600}
-  priority={false}
-/>
-```
-
-## Framework-Specific Implementation
-
-### Next.js (App Router)
-
-```typescript
-// app/layout.tsx
-import { Metadata } from 'next';
-
-export const metadata: Metadata = {
-  title: {
-    default: 'Site Name',
-    template: '%s | Site Name',
-  },
-  description: 'Site description',
-  openGraph: {
-    title: 'Site Name',
-    description: 'Site description',
-    url: 'https://example.com',
-    siteName: 'Site Name',
-    images: [{ url: '/og-image.png', width: 1200, height: 630 }],
-    locale: 'ko_KR',
-    type: 'website',
-  },
-  robots: {
-    index: true,
-    follow: true,
-  },
-};
-```
-
-### React (Vite + react-helmet-async)
-
-```typescript
-import { Helmet } from 'react-helmet-async';
-
-function SEO({ title, description, image }) {
-  return (
-    <Helmet>
-      <title>{title}</title>
-      <meta name="description" content={description} />
-      <meta property="og:title" content={title} />
-      <meta property="og:description" content={description} />
-      <meta property="og:image" content={image} />
-    </Helmet>
-  );
-}
-```
-
-## Quality Checklist
-
-### Pre-Launch
-
-- [ ] All pages have unique title and description
-- [ ] Open Graph tags on all shareable pages
-- [ ] Structured data validates (Google Rich Results Test)
-- [ ] robots.txt allows important pages
-- [ ] sitemap.xml includes all public pages
-- [ ] canonical URLs set correctly
-- [ ] Images have alt text
-- [ ] No broken links (404s)
-
-### Performance
-
-- [ ] LCP < 2.5s on mobile
-- [ ] Images optimized (WebP, lazy loading)
-- [ ] CSS/JS minified and compressed
-- [ ] Server response time < 200ms
-
-### Accessibility (SEO Impact)
-
-- [ ] Semantic HTML (h1-h6 hierarchy)
-- [ ] ARIA labels where needed
-- [ ] Keyboard navigation works
-- [ ] Color contrast meets WCAG AA
-
-## Validation Tools
-
-| Tool | Purpose |
-|------|---------|
-| [Google Search Console](https://search.google.com/search-console) | Index status, errors |
-| [Google Rich Results Test](https://search.google.com/test/rich-results) | Schema validation |
-| [PageSpeed Insights](https://pagespeed.web.dev/) | Core Web Vitals |
-| [Lighthouse](https://developer.chrome.com/docs/lighthouse) | SEO audit |
-| [Ahrefs/Screaming Frog](https://www.screamingfrog.co.uk/) | Site crawl |
-
-## Integration with /vibe.run
-
-During implementation phase, check:
-
-1. **Phase 1 (Setup)**: Create robots.txt, sitemap structure
-2. **Phase 2-3 (Core)**: Add meta tags to layout/pages
-3. **Phase 4 (Polish)**: Validate structured data, test OG images
-4. **Phase 5 (QA)**: Run Lighthouse SEO audit, fix issues
-
-## Generative Engine Optimization (AI 검색)
-
-For AI search engines (ChatGPT, Perplexity, Google AI Overviews):
-
-### Content Structure for LLM Citation
-
-- Add summary paragraph at page top
-- Use clear Q&A format for FAQs
-- Include data/statistics with sources
-- Add author, publish date, last updated
-- Structure content with clear headings
-
-### Machine-Readable Formats
-
-```json
-// /api/public/faq.json (optional)
-{
-  "faqs": [
-    {
-      "question": "What is X?",
-      "answer": "X is...",
-      "source": "https://example.com/docs",
-      "lastUpdated": "2024-01-01"
-    }
-  ]
-}
-```
+- [ ] Every page has unique title, description, canonical URL
+- [ ] OG images are 1200x630px on all shareable pages
+- [ ] `robots.txt` and `sitemap.xml` present and correct
+- [ ] Structured data validates in Rich Results Test
+- [ ] Core Web Vitals green (LCP ≤2.5s, INP ≤200ms, CLS ≤0.1)
+- [ ] No `noindex` tags in production

package/skills/tool-fallback/SKILL.md

@@ -4,16 +4,16 @@ description: "Tool failure fallback strategies with circuit breaker. Auto-activa
 triggers: [API error, search failure, timeout, 429, 5xx, overloaded, fallback, circuit breaker]
 priority: 80
 ---
+
 # Tool Fallback Strategies
 
-Guide for finding alternatives when tools fail to continue work.
+## Pre-check (K1)
 
-## Circuit Breaker Pattern
+> Did a tool just fail? If the error is a simple typo or wrong path, fix the input first. This skill is for persistent failures (429, 5xx, timeouts).
 
-Track tool failures and temporarily disable unreliable tools:
+## Circuit Breaker State Machine
 
 ```
-Tool State Machine:
 ┌─────────┐   3 failures   ┌─────────┐   30s cooldown   ┌─────────────┐
 │ CLOSED  │ ─────────────→ │  OPEN   │ ───────────────→ │ HALF-OPEN   │
 │ (normal)│                │ (block) │                  │ (test 1 req)│
@@ -25,169 +25,79 @@ Tool State Machine:
 
 | State | Behavior |
 |-------|----------|
-| **CLOSED** | Normal operation, count failures |
-| **OPEN** | Block all requests, use alternative immediately |
-| **HALF-OPEN** | Allow 1 test request after cooldown |
+| CLOSED | Normal operation, count failures |
+| OPEN | Skip tool immediately, use alternative |
+| HALF-OPEN | Allow 1 test request after cooldown |
 
-**Per-tool tracking:**
-```
-GPT hook: failures=2, state=CLOSED
-Gemini hook: failures=0, state=CLOSED
-WebSearch: failures=3, state=OPEN (blocked until 14:32:00)
-context7: failures=1, state=CLOSED
-```
+## Decision Trees
 
-## When Web Search Fails
-
-| Alternative | Method |
-|-------------|--------|
-| context7 plugin | `resolve-library-id` → `get-library-docs` |
-| VibeOrchestrator | `smartWebSearch()` - auto fallback chain |
-| Cached knowledge | Use Claude's built-in knowledge |
+### Web Search Fails
 
 ```
 Web Search fails (429, 529, timeout)
-    ↓
-Check circuit breaker state
-    ↓
-If OPEN → Skip to alternative immediately
-    ↓
-If CLOSED → Try context7 for library docs
-    ↓
-If still fails: VibeOrchestrator.smartWebSearch()
-    ↓
-Last resort: Claude's built-in knowledge
-```
-
-## API Error Responses
-
-| Error | Cause | Response | Circuit Breaker |
-|-------|-------|----------|-----------------|
-| 429 | Rate Limit | Exponential backoff | +1 failure count |
-| 5xx | Server Error | Switch to alternative | +1 failure count |
-| 529 | Overloaded | Wait and retry | +1 failure count |
-| Timeout | Network | Split request or retry | +1 failure count |
-| 401/403 | Auth Error | Re-auth or alternative | Don't count (auth issue) |
-
-## When File/Code Not Found
-
-```
-Glob fails
-    ↓
-Expand pattern: *.ts → **/*.ts → **/*
-    ↓
-Use Grep for content-based search
-    ↓
-Check git log for history
+  → Check circuit state
+  → OPEN? → Skip to alternative immediately
+  → CLOSED? → Try context7 for library docs
+  → Still fails? → Claude's built-in knowledge (last resort)
 ```
 
-## When External LLM Fails
-
-**Production (VibeOrchestrator):**
+### External LLM Fails
 
 ```
 VibeOrchestrator.smartRoute({ type, prompt })
-    ↓
-LLM priority based on task type:
-  - architecture/debugging: GPT → Gemini → Claude
-  - uiux/code-analysis: Gemini → GPT → Claude
-  - code-gen: Claude only
-    ↓
-Auto fallback on primary LLM failure
-    ↓
-Claude handles directly when all fail
-```
-
-**Test/Debug Hooks (development only):**
-
-```
-gpt- or gpt. [question] fails
-    ↓
-Check circuit: If OPEN, skip to next
-    ↓
-Try gemini- or gemini. [question] (similar capability)
-    ↓
-Try context7 (for docs)
-    ↓
-Claude solves alone
+  → Primary LLM fails (429, 401, 5xx)
+  → Skip to secondary LLM (no retry on rate limit)
+  → Secondary fails → Claude handles directly
 ```
 
-> **Note:** `test-gpt`, `test-gemini` prefixes are for hook connectivity testing only.
-> For actual work, use VIBE commands (`/vibe.run`, `/vibe.spec`, etc.) and
-> VibeOrchestrator will automatically select the appropriate LLM.
-
-## Retry Strategy with Circuit Breaker
+### File/Code Not Found
 
 ```
-Request to tool
-    ↓
-Check circuit state
-    ↓
-┌─ OPEN? ──→ Use alternative immediately (no retry)
-│
-└─ CLOSED/HALF-OPEN? ──→ Try request
-                              ↓
-                         Success? ──→ Reset failure count
-                              ↓ No
-                         Retry with backoff:
-                           retry(1): wait 2s
-                           retry(2): wait 4s
-                           retry(3): wait 8s
-                              ↓
-                         All failed? ──→ +1 failure, check threshold
-                              ↓
-                         failures >= 3? ──→ OPEN circuit for 30s
-                              ↓
-                         Use alternative
+Glob fails → Expand pattern: *.ts → **/*.ts → **/*
+  → Use Grep for content-based search
+  → Check git log for file history
 ```
 
-## VibeOrchestrator Smart Routing
-
-VIBE commands (`/vibe.spec`, `/vibe.run`, etc.) use VibeOrchestrator internally.
-
-### LLM Priority by Task Type
+## Error Response Actions
 
-| Task Type       | Primary | Secondary | Fallback |
-|-----------------|---------|-----------|----------|
-| `architecture`  | GPT     | Gemini    | Claude   |
-| `debugging`     | GPT     | Gemini    | Claude   |
-| `uiux`          | Gemini  | GPT       | Claude   |
-| `code-analysis` | Gemini  | GPT       | Claude   |
-| `web-search`    | GPT     | Gemini    | Claude   |
-| `code-gen`      | Claude  | -         | -        |
-| `general`       | Claude  | -         | -        |
+| Error | Action | Circuit Impact |
+|-------|--------|---------------|
+| 429 Rate Limit | Skip to next alternative (don't retry) | +1 failure |
+| 5xx Server Error | Retry with backoff, then switch | +1 failure |
+| 529 Overloaded | Wait and retry once | +1 failure |
+| Timeout | Split request or retry | +1 failure |
+| 401/403 Auth | Re-auth or switch alternative | Don't count |
 
-### Auto Fallback Logic
+## Retry Strategy
 
 ```
-smartRoute({ type: 'architecture', prompt })
-    ↓
-1. Try GPT (max 2 retries)
-    ↓ fails (429, 401, 5xx)
-2. Try Gemini (max 2 retries)
-    ↓ fails
-3. Claude handles directly (fallback message)
+Request → Check circuit
+  ├─ OPEN → Use alternative immediately
+  └─ CLOSED/HALF-OPEN → Try request
+       ├─ Success → Reset failure count
+       └─ Fail → Backoff (2s → 4s → 8s)
+            └─ All retries failed → +1 failure
+                 └─ failures ≥ 3 → OPEN circuit (30s)
+                      └─ Use alternative
 ```
 
-### Retry vs Immediate Switch
+## LLM Priority by Task Type
 
-| Error            | Action                 |
-|------------------|------------------------|
-| 429 Rate Limit   | Skip to next LLM       |
-| 401/403 Auth     | Skip to next LLM       |
-| Network Error    | Retry with backoff     |
-| 5xx Server Error | Retry then switch      |
+| Task Type | Primary → Secondary → Fallback |
+|-----------|-------------------------------|
+| architecture, debugging | GPT → Gemini → Claude |
+| uiux, code-analysis | Gemini → GPT → Claude |
+| code-gen, general | Claude only |
 
-### Availability Cache
+## Principles
 
-- 5-minute TTL for LLM status cache
-- Auto-disable after 3 consecutive failures
-- Failed LLMs are skipped in subsequent requests
+1. **Never stop** — always find an alternative
+2. **Try before asking** — exhaust alternatives before asking user
+3. **Fail fast** — skip OPEN-circuit tools immediately
+4. **Auto-recover** — test after 30s cooldown
 
-## Principles
+## Done Criteria (K4)
 
-1. **Never stop** - Always find an alternative
-2. **Before asking user** - Try alternatives first
-3. **Track failures** - Open circuit after 3 consecutive failures
-4. **Auto-recover** - Test after 30s cooldown
-5. **Fail fast** - Skip blocked tools immediately
+- [ ] Work continued despite tool failure
+- [ ] Alternative tool/method used successfully
+- [ ] No unnecessary retries on rate-limited tools