flyee 0.1.0

package/core/skills/geo-fundamentals/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: geo-fundamentals
+description: Generative Engine Optimization for AI search engines (ChatGPT, Claude, Perplexity).
+allowed-tools: Read, Glob, Grep
+---
+
+# GEO Fundamentals
+
+> Optimization for AI-powered search engines.
+
+---
+
+## 1. What is GEO?
+
+**GEO** = Generative Engine Optimization
+
+| Goal | Platform |
+|------|----------|
+| Be cited in AI responses | ChatGPT, Claude, Perplexity, Gemini |
+
+### SEO vs GEO
+
+| Aspect | SEO | GEO |
+|--------|-----|-----|
+| Goal | #1 ranking | AI citations |
+| Platform | Google | AI engines |
+| Metrics | Rankings, CTR | Citation rate |
+| Focus | Keywords | Entities, data |
+
+---
+
+## 2. AI Engine Landscape
+
+| Engine | Citation Style | Opportunity |
+|--------|----------------|-------------|
+| **Perplexity** | Numbered [1][2] | Highest citation rate |
+| **ChatGPT** | Inline/footnotes | Custom GPTs |
+| **Claude** | Contextual | Long-form content |
+| **Gemini** | Sources section | SEO crossover |
+
+---
+
+## 3. RAG Retrieval Factors
+
+How AI engines select content to cite:
+
+| Factor | Weight |
+|--------|--------|
+| Semantic relevance | ~40% |
+| Keyword match | ~20% |
+| Authority signals | ~15% |
+| Freshness | ~10% |
+| Source diversity | ~15% |
+
+---
+
+## 4. Content That Gets Cited
+
+| Element | Why It Works |
+|---------|--------------|
+| **Original statistics** | Unique, citable data |
+| **Expert quotes** | Authority transfer |
+| **Clear definitions** | Easy to extract |
+| **Step-by-step guides** | Actionable value |
+| **Comparison tables** | Structured info |
+| **FAQ sections** | Direct answers |
+
+---
+
+## 5. GEO Content Checklist
+
+### Content Elements
+
+- [ ] Question-based titles
+- [ ] Summary/TL;DR at top
+- [ ] Original data with sources
+- [ ] Expert quotes (name, title)
+- [ ] FAQ section (3-5 Q&A)
+- [ ] Clear definitions
+- [ ] "Last updated" timestamp
+- [ ] Author with credentials
+
+### Technical Elements
+
+- [ ] Article schema with dates
+- [ ] Person schema for author
+- [ ] FAQPage schema
+- [ ] Fast loading (< 2.5s)
+- [ ] Clean HTML structure
+
+---
+
+## 6. Entity Building
+
+| Action | Purpose |
+|--------|---------|
+| Google Knowledge Panel | Entity recognition |
+| Wikipedia (if notable) | Authority source |
+| Consistent info across web | Entity consolidation |
+| Industry mentions | Authority signals |
+
+---
+
+## 7. AI Crawler Access
+
+### Key AI User-Agents
+
+| Crawler | Engine |
+|---------|--------|
+| GPTBot | ChatGPT/OpenAI |
+| Claude-Web | Claude |
+| PerplexityBot | Perplexity |
+| Googlebot | Gemini (shared) |
+
+### Access Decision
+
+| Strategy | When |
+|----------|------|
+| Allow all | Want AI citations |
+| Block GPTBot | Don't want OpenAI training |
+| Selective | Allow some, block others |
+
+---
+
+## 8. Measurement
+
+| Metric | How to Track |
+|--------|--------------|
+| AI citations | Manual monitoring |
+| "According to [Brand]" mentions | Search in AI |
+| Competitor citations | Compare share |
+| AI-referred traffic | UTM parameters |
+
+---
+
+## 9. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Publish without dates | Add timestamps |
+| Vague attributions | Name sources |
+| Skip author info | Show credentials |
+| Thin content | Comprehensive coverage |
+
+---
+
+> **Remember:** AI cites content that's clear, authoritative, and easy to extract. Be the best answer.
+
+---
+
+## Script
+
+| Script | Purpose | Command |
+|--------|---------|---------|
+| `scripts/geo_checker.py` | GEO audit (AI citation readiness) | `python scripts/geo_checker.py <project_path>` |
+

package/core/skills/geo-fundamentals/scripts/geo_checker.py

@@ -0,0 +1,289 @@
+#!/usr/bin/env python3
+"""
+GEO Checker - Generative Engine Optimization Audit
+Checks PUBLIC WEB CONTENT for AI citation readiness.
+
+PURPOSE:
+    - Analyze pages that will be INDEXED by AI engines (ChatGPT, Perplexity, etc.)
+    - Check for structured data, author info, dates, FAQ sections
+    - Help content rank in AI-generated answers
+
+WHAT IT CHECKS:
+    - HTML files (actual web pages)
+    - JSX/TSX files (React page components)
+    - NOT markdown files (those are developer docs, not public content)
+
+Usage:
+    python geo_checker.py <project_path>
+"""
+import sys
+import re
+import json
+from pathlib import Path
+
+# Fix Windows console encoding
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+    sys.stderr.reconfigure(encoding='utf-8', errors='replace')
+except AttributeError:
+    pass
+
+
+# Directories to skip (not public content)
+SKIP_DIRS = {
+    'node_modules', '.next', 'dist', 'build', '.git', '.github',
+    '__pycache__', '.vscode', '.idea', 'coverage', 'test', 'tests',
+    '__tests__', 'spec', 'docs', 'documentation'
+}
+
+# Files to skip (not public pages)
+SKIP_FILES = {
+    'jest.config', 'webpack.config', 'vite.config', 'tsconfig',
+    'package.json', 'package-lock', 'yarn.lock', '.eslintrc',
+    'tailwind.config', 'postcss.config', 'next.config'
+}
+
+
+def is_page_file(file_path: Path) -> bool:
+    """Check if this file is likely a public-facing page."""
+    name = file_path.stem.lower()
+    
+    # Skip config/utility files
+    if any(skip in name for skip in SKIP_FILES):
+        return False
+    
+    # Skip test files
+    if name.endswith('.test') or name.endswith('.spec'):
+        return False
+    if name.startswith('test_') or name.startswith('spec_'):
+        return False
+    
+    # Likely page indicators
+    page_indicators = ['page', 'index', 'home', 'about', 'contact', 'blog', 
+                       'post', 'article', 'product', 'service', 'landing']
+    
+    # Check if it's in a pages/app directory (Next.js, etc.)
+    parts = [p.lower() for p in file_path.parts]
+    if 'pages' in parts or 'app' in parts or 'routes' in parts:
+        return True
+    
+    # Check filename indicators
+    if any(ind in name for ind in page_indicators):
+        return True
+    
+    # HTML files are usually pages
+    if file_path.suffix.lower() == '.html':
+        return True
+    
+    return False
+
+
+def find_web_pages(project_path: Path) -> list:
+    """Find public-facing web pages only."""
+    patterns = ['**/*.html', '**/*.htm', '**/*.jsx', '**/*.tsx']
+    
+    files = []
+    for pattern in patterns:
+        for f in project_path.glob(pattern):
+            # Skip excluded directories
+            if any(skip in f.parts for skip in SKIP_DIRS):
+                continue
+            
+            # Check if it's likely a page
+            if is_page_file(f):
+                files.append(f)
+    
+    return files[:30]  # Limit to 30 pages
+
+
+def check_page(file_path: Path) -> dict:
+    """Check a single web page for GEO elements."""
+    try:
+        content = file_path.read_text(encoding='utf-8', errors='ignore')
+    except Exception as e:
+        return {'file': str(file_path.name), 'passed': [], 'issues': [f"Error: {e}"], 'score': 0}
+    
+    issues = []
+    passed = []
+    
+    # 1. JSON-LD Structured Data (Critical for AI)
+    if 'application/ld+json' in content:
+        passed.append("JSON-LD structured data found")
+        if '"@type"' in content:
+            if 'Article' in content:
+                passed.append("Article schema present")
+            if 'FAQPage' in content:
+                passed.append("FAQ schema present")
+            if 'Organization' in content or 'Person' in content:
+                passed.append("Entity schema present")
+    else:
+        issues.append("No JSON-LD structured data (AI engines prefer structured content)")
+    
+    # 2. Heading Structure
+    h1_count = len(re.findall(r'<h1[^>]*>', content, re.I))
+    h2_count = len(re.findall(r'<h2[^>]*>', content, re.I))
+    
+    if h1_count == 1:
+        passed.append("Single H1 heading (clear topic)")
+    elif h1_count == 0:
+        issues.append("No H1 heading - page topic unclear")
+    else:
+        issues.append(f"Multiple H1 headings ({h1_count}) - confusing for AI")
+    
+    if h2_count >= 2:
+        passed.append(f"{h2_count} H2 subheadings (good structure)")
+    else:
+        issues.append("Add more H2 subheadings for scannable content")
+    
+    # 3. Author Attribution (E-E-A-T signal)
+    author_patterns = ['author', 'byline', 'written-by', 'contributor', 'rel="author"']
+    has_author = any(p in content.lower() for p in author_patterns)
+    if has_author:
+        passed.append("Author attribution found")
+    else:
+        issues.append("No author info (AI prefers attributed content)")
+    
+    # 4. Publication Date (Freshness signal)
+    date_patterns = ['datePublished', 'dateModified', 'datetime=', 'pubdate', 'article:published']
+    has_date = any(re.search(p, content, re.I) for p in date_patterns)
+    if has_date:
+        passed.append("Publication date found")
+    else:
+        issues.append("No publication date (freshness matters for AI)")
+    
+    # 5. FAQ Section (Highly citable)
+    faq_patterns = [r'<details', r'faq', r'frequently.?asked', r'"FAQPage"']
+    has_faq = any(re.search(p, content, re.I) for p in faq_patterns)
+    if has_faq:
+        passed.append("FAQ section detected (highly citable)")
+    
+    # 6. Lists (Structured content)
+    list_count = len(re.findall(r'<(ul|ol)[^>]*>', content, re.I))
+    if list_count >= 2:
+        passed.append(f"{list_count} lists (structured content)")
+    
+    # 7. Tables (Comparison data)
+    table_count = len(re.findall(r'<table[^>]*>', content, re.I))
+    if table_count >= 1:
+        passed.append(f"{table_count} table(s) (comparison data)")
+    
+    # 8. Entity Recognition (E-E-A-T signal) - NEW 2025
+    entity_patterns = [
+        r'"@type"\s*:\s*"Organization"',
+        r'"@type"\s*:\s*"LocalBusiness"', 
+        r'"@type"\s*:\s*"Brand"',
+        r'itemtype.*schema\.org/(Organization|Person|Brand)',
+        r'rel="author"'
+    ]
+    has_entity = any(re.search(p, content, re.I) for p in entity_patterns)
+    if has_entity:
+        passed.append("Entity/Brand recognition (E-E-A-T)")
+    
+    # 9. Original Statistics/Data (AI citation magnet) - NEW 2025
+    stat_patterns = [
+        r'\d+%',                    # Percentages
+        r'\$[\d,]+',                # Dollar amounts
+        r'study\s+(shows|found)',   # Research citations
+        r'according to',            # Source attribution
+        r'data\s+(shows|reveals)',  # Data-backed claims
+        r'\d+x\s+(faster|better|more)', # Comparison stats
+        r'(million|billion|trillion)', # Large numbers
+    ]
+    stat_matches = sum(1 for p in stat_patterns if re.search(p, content, re.I))
+    if stat_matches >= 2:
+        passed.append("Original statistics/data (citation magnet)")
+    
+    # 10. Conversational/Direct answers - NEW 2025
+    direct_answer_patterns = [
+        r'is defined as',
+        r'refers to',
+        r'means that',
+        r'the answer is',
+        r'in short,',
+        r'simply put,',
+        r'<dfn'
+    ]
+    has_direct = any(re.search(p, content, re.I) for p in direct_answer_patterns)
+    if has_direct:
+        passed.append("Direct answer patterns (LLM-friendly)")
+    
+    # Calculate score
+    total = len(passed) + len(issues)
+    score = (len(passed) / total * 100) if total > 0 else 0
+    
+    return {
+        'file': str(file_path.name),
+        'passed': passed,
+        'issues': issues,
+        'score': round(score)
+    }
+
+
+def main():
+    target = sys.argv[1] if len(sys.argv) > 1 else "."
+    target_path = Path(target).resolve()
+    
+    print("\n" + "=" * 60)
+    print("  GEO CHECKER - AI Citation Readiness Audit")
+    print("=" * 60)
+    print(f"Project: {target_path}")
+    print("-" * 60)
+    
+    # Find web pages only
+    pages = find_web_pages(target_path)
+    
+    if not pages:
+        print("\n[!] No public web pages found.")
+        print("    Looking for: HTML, JSX, TSX files in pages/app directories")
+        print("    Skipping: docs, tests, config files, node_modules")
+        output = {"script": "geo_checker", "pages_found": 0, "passed": True}
+        print("\n" + json.dumps(output, indent=2))
+        sys.exit(0)
+    
+    print(f"Found {len(pages)} public pages to analyze\n")
+    
+    # Check each page
+    results = []
+    for page in pages:
+        result = check_page(page)
+        results.append(result)
+    
+    # Print results
+    for result in results:
+        status = "[OK]" if result['score'] >= 60 else "[!]"
+        print(f"{status} {result['file']}: {result['score']}%")
+        if result['issues'] and result['score'] < 60:
+            for issue in result['issues'][:2]:  # Show max 2 issues
+                print(f"    - {issue}")
+    
+    # Average score
+    avg_score = sum(r['score'] for r in results) / len(results) if results else 0
+    
+    print("\n" + "=" * 60)
+    print(f"AVERAGE GEO SCORE: {avg_score:.0f}%")
+    print("=" * 60)
+    
+    if avg_score >= 80:
+        print("[OK] Excellent - Content well-optimized for AI citations")
+    elif avg_score >= 60:
+        print("[OK] Good - Some improvements recommended")
+    elif avg_score >= 40:
+        print("[!] Needs work - Add structured elements")
+    else:
+        print("[X] Poor - Content needs GEO optimization")
+    
+    # JSON output
+    output = {
+        "script": "geo_checker",
+        "project": str(target_path),
+        "pages_checked": len(results),
+        "average_score": round(avg_score),
+        "passed": avg_score >= 60
+    }
+    print("\n" + json.dumps(output, indent=2))
+    
+    sys.exit(0 if avg_score >= 60 else 1)
+
+
+if __name__ == "__main__":
+    main()

package/core/skills/git-workflow/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: git-workflow
+description: Git branch strategy, commit patterns, and merge guidance. Branch-per-phase, configurable auto/manual commits, boundary maps between phases. Absorbed from GSD-2 auto-worktree.ts and native-git-bridge.ts patterns.
+---
+
+# Git Workflow
+
+> **Absorbed from:** GSD-2 `auto-worktree.ts`, `native-git-bridge.ts`
+> **Purpose:** Structured git workflow that keeps changes organized and reversible.
+
+---
+
+## 🎯 PURPOSE
+
+Without a git strategy, AI agents create giant "implement everything" commits.
+This skill provides:
+- Branch-per-phase for clean isolation
+- Structured commit messages
+- Easy rollback if a phase goes wrong
+- Configurable: auto or manual commits
+
+---
+
+## ⚙️ CONFIGURATION
+
+### User preference (in `.flyee/config.json`)
+
+```json
+{
+  "git": {
+    "auto_commit": false,
+    "auto_branch": true,
+    "commit_style": "conventional",
+    "branch_prefix": "flyee"
+  }
+}
+```
+
+### Options
+
+| Setting | Values | Default | Description |
+|---------|--------|---------|-------------|
+| `auto_commit` | `true`/`false` | `false` | Commit after each task completion |
+| `auto_branch` | `true`/`false` | `true` | Create branch per phase automatically |
+| `commit_style` | `conventional`/`descriptive` | `conventional` | Commit message format |
+| `branch_prefix` | string | `flyee` | Branch name prefix |
+
+### First-Time Setup
+
+On first run, ask the user:
+
+```
+🔧 Git Workflow Configuration
+
+How do you want commits handled?
+  1. 🤖 Auto-commit after each task (I trust the agent)
+  2. ✋ Manual commits (suggest message, I decide when)
+
+> Choice: _
+```
+
+Store preference in `.flyee/config.json`.
+
+---
+
+## 🌿 BRANCH STRATEGY
+
+### Pattern: `{prefix}/{sprint}/{phase-name}`
+
+```
+main
+├── flyee/S09/backend-api          ← P01
+├── flyee/S09/frontend-components  ← P02
+├── flyee/S09/cms-admin            ← P03
+└── flyee/S09/seo-meta             ← P04
+```
+
+### Branch Lifecycle
+
+```
+1. Phase starts → Create branch from main (or previous phase branch)
+2. Tasks execute → Commits on this branch
+3. Phase completes → Verification gate passes
+4. Phase merges → Squash merge to main (manual approval)
+5. Next phase branches from updated main
+```
+
+### Branch Commands
+
+```bash
+# Create branch for phase
+git checkout -b flyee/S09/frontend-components main
+
+# After phase completion
+git checkout main
+git merge --squash flyee/S09/frontend-components
+git commit -m "feat(S09): P02 frontend components"
+```
+
+---
+
+## 📝 COMMIT MESSAGES
+
+### Conventional Style (default)
+
+```
+{type}({scope}): {description}
+
+Types: feat, fix, refactor, test, docs, style, chore
+Scope: sprint/phase/task identifier
+```
+
+**Examples:**
+
+```
+feat(S09/P02): implement BlogCard component
+fix(S09/P02/T03): fix image aspect ratio in BlogCard
+test(S09/P02): add BlogCard unit tests
+refactor(S09/P01): extract post validation to helper
+docs(S09): update README with blog setup instructions
+```
+
+### Descriptive Style (alternative)
+
+```
+[S09/P02/T03] Implement BlogCard with responsive images
+
+- Created BlogCard.tsx with Post prop interface
+- Added CSS Modules with design tokens
+- Connected to usePosts hook for data
+- Added hover scale animation
+```
+
+---
+
+## 🤖 AUTO-COMMIT PROTOCOL
+
+When `auto_commit: true`:
+
+```
+After task completion:
+  1. Run verification gate → PASS required
+  2. Stage changed files: git add <modified files>
+  3. Generate commit message from task summary
+  4. Commit: git commit -m "<generated message>"
+  5. Log commit hash to cost-log
+
+  IF verification gate FAILS:
+  → Do NOT commit
+  → Fix issues first
+```
+
+### Safety Guards
+
+- Never auto-commit if tests fail
+- Never auto-commit if typecheck fails
+- Never auto-push (push is always manual)
+- User can always `git reset HEAD~1` to undo
+
+---
+
+## ✋ MANUAL COMMIT PROTOCOL
+
+When `auto_commit: false` (default):
+
+```
+After task completion:
+  1. Run verification gate → PASS
+  2. Suggest commit to user:
+
+  📝 Suggested commit:
+  git add src/components/BlogCard.tsx src/components/BlogCard.module.css
+  git commit -m "feat(S09/P02): implement BlogCard component"
+
+  Files changed:
+  - src/components/BlogCard.tsx (new, 87 lines)
+  - src/components/BlogCard.module.css (new, 42 lines)
+
+  3. User decides when/how to commit
+```
+
+---
+
+## 🗺️ BOUNDARY MAPS
+
+When branching phases, define what each produces:
+
+```markdown
+## Boundary Map: P01 → P02
+
+### P01 produces (available on main after merge):
+- `src/types/post.ts` → Post, Author interfaces
+- `src/app/api/posts/route.ts` → GET, POST handlers
+- `src/lib/posts.ts` → createPost, getPosts functions
+
+### P02 consumes:
+- `Post` type from `src/types/post.ts`
+- `GET /api/posts` endpoint for data fetching
+
+### P02 MUST NOT change:
+- Any file in `src/app/api/`
+- Any file in `src/lib/posts.ts`
+- The Post interface (if breaking change needed → new task)
+```
+
+---
+
+## 🔄 MERGE CHECKLIST
+
+Before merging a phase branch:
+
+```
+Pre-merge checklist for flyee/S09/frontend-components:
+  [ ] All tasks in phase complete (T01–T04)
+  [ ] Verification gate passed on ALL tasks
+  [ ] No conflicts with main
+  [ ] Branch is up to date with main
+  [ ] Phase SUMMARY.md written
+  [ ] Commit history clean (squash if messy)
+```
+
+---
+
+## 📡 FLYEE SAAS EVENTS
+
+```python
+# When branch created
+bridge.emit_event("git.branch_created", {
+    "sprint": "S09", "phase": "P02",
+    "branch": "flyee/S09/frontend-components"
+})
+
+# When phase merged
+bridge.emit_event("git.phase_merged", {
+    "sprint": "S09", "phase": "P02",
+    "branch": "flyee/S09/frontend-components",
+    "commits": 4, "files_changed": 12
+})
+
+# When commit made (auto-commit mode)
+bridge.emit_event("git.commit", {
+    "sprint": "S09", "phase": "P02", "task": "T03",
+    "hash": "abc1234", "message": "feat(S09/P02): implement BlogCard"
+})
+```
+
+---
+
+## ⚡ QUICK REFERENCE
+
+```bash
+# Check git preferences
+cat .flyee/config.json | python3 -m json.tool
+
+# Create phase branch
+git checkout -b flyee/S09/P02-frontend main
+
+# Squash merge after phase
+git checkout main && git merge --squash flyee/S09/P02-frontend
+
+# View branch structure
+git branch --list "flyee/*"
+```