@jairodri/huckleberry-cli 1.0.2 → 1.1.0

package/skills/schema-markup/references/schema-examples.md

@@ -0,0 +1,398 @@
+# Schema Markup Examples
+
+Complete JSON-LD examples for common schema types.
+
+## Contents
+- Organization
+- WebSite (with SearchAction)
+- Article / BlogPosting
+- Product
+- SoftwareApplication
+- FAQPage
+- HowTo
+- BreadcrumbList
+- LocalBusiness
+- Event
+- Multiple Schema Types
+- Implementation Example (Next.js)
+
+## Organization
+
+For company/brand homepage or about page.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Organization",
+  "name": "Example Company",
+  "url": "https://example.com",
+  "logo": "https://example.com/logo.png",
+  "sameAs": [
+    "https://twitter.com/example",
+    "https://linkedin.com/company/example",
+    "https://facebook.com/example"
+  ],
+  "contactPoint": {
+    "@type": "ContactPoint",
+    "telephone": "+1-555-555-5555",
+    "contactType": "customer service"
+  }
+}
+```
+
+---
+
+## WebSite (with SearchAction)
+
+For homepage, enables sitelinks search box.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "WebSite",
+  "name": "Example",
+  "url": "https://example.com",
+  "potentialAction": {
+    "@type": "SearchAction",
+    "target": {
+      "@type": "EntryPoint",
+      "urlTemplate": "https://example.com/search?q={search_term_string}"
+    },
+    "query-input": "required name=search_term_string"
+  }
+}
+```
+
+---
+
+## Article / BlogPosting
+
+For blog posts and news articles.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Article",
+  "headline": "How to Implement Schema Markup",
+  "image": "https://example.com/image.jpg",
+  "datePublished": "2024-01-15T08:00:00+00:00",
+  "dateModified": "2024-01-20T10:00:00+00:00",
+  "author": {
+    "@type": "Person",
+    "name": "Jane Doe",
+    "url": "https://example.com/authors/jane"
+  },
+  "publisher": {
+    "@type": "Organization",
+    "name": "Example Company",
+    "logo": {
+      "@type": "ImageObject",
+      "url": "https://example.com/logo.png"
+    }
+  },
+  "description": "A complete guide to implementing schema markup...",
+  "mainEntityOfPage": {
+    "@type": "WebPage",
+    "@id": "https://example.com/schema-guide"
+  }
+}
+```
+
+---
+
+## Product
+
+For product pages (e-commerce or SaaS).
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Product",
+  "name": "Premium Widget",
+  "image": "https://example.com/widget.jpg",
+  "description": "Our best-selling widget for professionals",
+  "sku": "WIDGET-001",
+  "brand": {
+    "@type": "Brand",
+    "name": "Example Co"
+  },
+  "offers": {
+    "@type": "Offer",
+    "url": "https://example.com/products/widget",
+    "priceCurrency": "USD",
+    "price": "99.99",
+    "availability": "https://schema.org/InStock",
+    "priceValidUntil": "2024-12-31"
+  },
+  "aggregateRating": {
+    "@type": "AggregateRating",
+    "ratingValue": "4.8",
+    "reviewCount": "127"
+  }
+}
+```
+
+---
+
+## SoftwareApplication
+
+For SaaS product pages and app landing pages.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "SoftwareApplication",
+  "name": "Example App",
+  "applicationCategory": "BusinessApplication",
+  "operatingSystem": "Web, iOS, Android",
+  "offers": {
+    "@type": "Offer",
+    "price": "0",
+    "priceCurrency": "USD"
+  },
+  "aggregateRating": {
+    "@type": "AggregateRating",
+    "ratingValue": "4.6",
+    "ratingCount": "1250"
+  }
+}
+```
+
+---
+
+## FAQPage
+
+For pages with frequently asked questions.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "FAQPage",
+  "mainEntity": [
+    {
+      "@type": "Question",
+      "name": "What is schema markup?",
+      "acceptedAnswer": {
+        "@type": "Answer",
+        "text": "Schema markup is a structured data vocabulary that helps search engines understand your content..."
+      }
+    },
+    {
+      "@type": "Question",
+      "name": "How do I implement schema?",
+      "acceptedAnswer": {
+        "@type": "Answer",
+        "text": "The recommended approach is to use JSON-LD format, placing the script in your page's head..."
+      }
+    }
+  ]
+}
+```
+
+---
+
+## HowTo
+
+For instructional content and tutorials.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "HowTo",
+  "name": "How to Add Schema Markup to Your Website",
+  "description": "A step-by-step guide to implementing JSON-LD schema",
+  "totalTime": "PT15M",
+  "step": [
+    {
+      "@type": "HowToStep",
+      "name": "Choose your schema type",
+      "text": "Identify the appropriate schema type for your page content...",
+      "url": "https://example.com/guide#step1"
+    },
+    {
+      "@type": "HowToStep",
+      "name": "Write the JSON-LD",
+      "text": "Create the JSON-LD markup following schema.org specifications...",
+      "url": "https://example.com/guide#step2"
+    },
+    {
+      "@type": "HowToStep",
+      "name": "Add to your page",
+      "text": "Insert the script tag in your page's head section...",
+      "url": "https://example.com/guide#step3"
+    }
+  ]
+}
+```
+
+---
+
+## BreadcrumbList
+
+For any page with breadcrumb navigation.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "BreadcrumbList",
+  "itemListElement": [
+    {
+      "@type": "ListItem",
+      "position": 1,
+      "name": "Home",
+      "item": "https://example.com"
+    },
+    {
+      "@type": "ListItem",
+      "position": 2,
+      "name": "Blog",
+      "item": "https://example.com/blog"
+    },
+    {
+      "@type": "ListItem",
+      "position": 3,
+      "name": "SEO Guide",
+      "item": "https://example.com/blog/seo-guide"
+    }
+  ]
+}
+```
+
+---
+
+## LocalBusiness
+
+For local business location pages.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "LocalBusiness",
+  "name": "Example Coffee Shop",
+  "image": "https://example.com/shop.jpg",
+  "address": {
+    "@type": "PostalAddress",
+    "streetAddress": "123 Main Street",
+    "addressLocality": "San Francisco",
+    "addressRegion": "CA",
+    "postalCode": "94102",
+    "addressCountry": "US"
+  },
+  "geo": {
+    "@type": "GeoCoordinates",
+    "latitude": "37.7749",
+    "longitude": "-122.4194"
+  },
+  "telephone": "+1-555-555-5555",
+  "openingHoursSpecification": [
+    {
+      "@type": "OpeningHoursSpecification",
+      "dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
+      "opens": "08:00",
+      "closes": "18:00"
+    }
+  ],
+  "priceRange": "$$"
+}
+```
+
+---
+
+## Event
+
+For event pages, webinars, conferences.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Event",
+  "name": "Annual Marketing Conference",
+  "startDate": "2024-06-15T09:00:00-07:00",
+  "endDate": "2024-06-15T17:00:00-07:00",
+  "eventAttendanceMode": "https://schema.org/OnlineEventAttendanceMode",
+  "eventStatus": "https://schema.org/EventScheduled",
+  "location": {
+    "@type": "VirtualLocation",
+    "url": "https://example.com/conference"
+  },
+  "image": "https://example.com/conference.jpg",
+  "description": "Join us for our annual marketing conference...",
+  "offers": {
+    "@type": "Offer",
+    "url": "https://example.com/conference/tickets",
+    "price": "199",
+    "priceCurrency": "USD",
+    "availability": "https://schema.org/InStock",
+    "validFrom": "2024-01-01"
+  },
+  "performer": {
+    "@type": "Organization",
+    "name": "Example Company"
+  },
+  "organizer": {
+    "@type": "Organization",
+    "name": "Example Company",
+    "url": "https://example.com"
+  }
+}
+```
+
+---
+
+## Multiple Schema Types
+
+Combine multiple schema types using @graph.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@graph": [
+    {
+      "@type": "Organization",
+      "@id": "https://example.com/#organization",
+      "name": "Example Company",
+      "url": "https://example.com"
+    },
+    {
+      "@type": "WebSite",
+      "@id": "https://example.com/#website",
+      "url": "https://example.com",
+      "name": "Example",
+      "publisher": {
+        "@id": "https://example.com/#organization"
+      }
+    },
+    {
+      "@type": "BreadcrumbList",
+      "itemListElement": [...]
+    }
+  ]
+}
+```
+
+---
+
+## Implementation Example (Next.js)
+
+```jsx
+export default function ProductPage({ product }) {
+  const schema = {
+    "@context": "https://schema.org",
+    "@type": "Product",
+    name: product.name,
+    // ... other properties
+  };
+
+  return (
+    <>
+      <Head>
+        <script
+          type="application/ld+json"
+          dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}
+        />
+      </Head>
+      {/* Page content */}
+    </>
+  );
+}
+```

package/skills/self-improve/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: self-improve
+description: "Self-improvement system for agent behavior. Three layers: outcome journaling, behavior evals, and weekly review."
+---
+
+# Self-Improvement System
+
+Three layers that close the loop: observe → evaluate → improve → repeat.
+
+---
+
+## Pre-Task Check (MANDATORY)
+
+**Before starting any task for Jairo**, scan active corrections to avoid repeating mistakes:
+
+```bash
+node scripts/self-improve/behavior-eval/behavior-eval.mjs stats
+```
+
+Or read `memory/corrections.md` directly — focus on the **Active Corrections** section.
+
+**Why:** Corrections are useless if you never read them. This is the closed loop — read before acting, log after acting, review weekly.
+
+---
+
+## Layer 1: Outcome Journal
+
+**After every task**, log the outcome:
+
+```bash
+node scripts/self-improve/outcome-journal/log-outcome.mjs log "<task description>" <success|corrected|failed|partial> "<correction if any>" <agent-name>
+```
+
+**When to log:**
+- After completing any task Jairo asked for
+- After a task fails or gets corrected
+- After sub-agent work completes (log the sub-agent's outcome)
+
+**Examples:**
+```bash
+# Success
+node scripts/self-improve/outcome-journal/log-outcome.mjs log "fixed auth timeout bug" success "" kestrel
+
+# Corrected — Jairo said to use WhatsApp format, not Discord format
+node scripts/self-improve/outcome-journal/log-outcome.mjs log "send update to Jairo" corrected "used Discord formatting instead of WhatsApp format → check platform before formatting" kestrel
+
+# Failed
+node scripts/self-improve/outcome-journal/log-outcome.mjs log "deploy to production" failed "Vercel API key expired → always check key validity before deploy attempts" kestrel
+```
+
+**View stats:**
+```bash
+node scripts/self-improve/outcome-journal/log-outcome.mjs summary
+```
+
+**Key files:**
+- `memory/outcome-journal.md` — raw outcome log
+- `memory/corrections.md` — extracted correction patterns
+
+---
+
+## Layer 2: Behavior Evals
+
+16 binary evals that define "good agent behavior." Scored weekly.
+
+**Defined in:** `memory/behavior-evals.md`
+
+**Eval categories:**
+- Core Behavior (10 evals) — acknowledgment, conciseness, execution style
+- Content Quality (3 evals) — scroll-stopping, authentic voice, actionable
+- Technical (3 evals) — lint, conventions, dependency checking
+
+**How evals connect to corrections:**
+When a correction is logged, it's pattern-matched against eval categories. If the same category keeps getting corrections, that eval starts failing.
+
+**Check evals:**
+```bash
+node scripts/self-improve/behavior-eval/behavior-eval.mjs list   # show all evals
+node scripts/self-improve/behavior-eval/behavior-eval.mjs stats  # recent stats
+node scripts/self-improve/behavior-eval/behavior-eval.mjs prompt # generate review prompt
+```
+
+**Scoring threshold:**
+- 90%+: Healthy, no action needed
+- 75-89%: Improvement zone, targeted mutations
+- <75%: Autoresearch recommended on failing evals
+
+---
+
+## Layer 3: Weekly Self-Review
+
+**Cron:** Mondays at 09:00 UTC
+
+**What it does:**
+1. Reads the past 7 days of outcomes and corrections
+2. Scores all behavior evals
+3. Identifies failing evals and suggests AGENTS.md mutations
+4. Writes score to `memory/eval-scores.md`
+5. If score < 75%, recommends running autoresearch
+
+**Run manually:**
+```bash
+node scripts/self-improve/weekly-review/weekly-review.mjs run    # full review
+node scripts/self-improve/weekly-review/weekly-review.mjs score  # JSON score only
+```
+
+**Review output includes:**
+- Outcome stats for the week
+- Pass/fail for each eval
+- Suggested AGENTS.md mutations for failing evals
+- Corrections to distill into MEMORY.md
+
+---
+
+## How the Loop Works
+
+```
+Task completes
+  → log outcome (Layer 1)
+  → if corrected/failed, log correction with pattern
+
+Weekly cron fires
+  → scores all evals against week's outcomes (Layer 2)
+  → identifies failing patterns (Layer 3)
+  → proposes AGENTS.md / SOUL.md mutations
+  → if score < 75%, flag for autoresearch
+
+Jairo approves mutations (or autoresearch runs them)
+  → agent behavior improves
+  → outcomes get better
+  → repeat
+```
+
+---
+
+## Integration with Existing Systems
+
+**MEMORY.md:** Weekly review extracts correction patterns and writes them as lessons
+**AGENTS.md:** Mutations from eval failures get proposed as specific rule additions
+**autoresearch skill:** If eval score < 75%, the review recommends running autoresearch on the agent's behavior prompts
+**memory_dream:** Corrections older than 30 days get archived during dream cycle
+
+---
+
+## Adding New Evals
+
+When a new pattern of mistake is identified:
+1. Write it as a binary yes/no question
+2. Add to `memory/behavior-evals.md` in the appropriate category
+3. Add a scoring case to `scripts/self-improve/weekly-review/weekly-review.mjs` in the `scoreEvals()` function
+4. The weekly review will start scoring it automatically
+
+---
+
+## Maintenance (Auto-Pruned)
+
+Nothing grows forever. Every file has hard limits:
+
+| File | Max Age | Max Size | Pruned By |
+|------|---------|----------|-----------|
+| `corrections.md` | 7 days | 10 entries | Weekly review + log-outcome |
+| `outcome-journal.md` | 30 days | N/A | Weekly review (prune command) |
+| `eval-scores.md` | Indefinite | Table rows only | Manual (trend data, small) |
+| `behavior-evals.md` | Indefinite | ~16 evals | Quarterly review, remove ones that always pass |
+
+**The principle:** corrections are RAM, not disk. They exist to be distilled into behavior, not stored. If a correction keeps recurring, it becomes a rule in AGENTS.md. Once learned, the correction disappears.