@jaguilar87/gaia 5.0.0-rc.2

package/dist/gaia-ops/skills/agentic-loop/reference.md

@@ -0,0 +1,378 @@
+# Agentic Loop -- Reference
+
+Exact commands, schemas, templates, and a walkthrough. Read on-demand when executing the loop.
+
+## Setup Phase Commands
+
+```bash
+# 1. Read files_in_scope (use Read tool, not cat)
+
+# 2. Create branch
+git checkout -b {branch}
+
+# 3. Run eval and capture baseline
+{eval_command}
+# Look for line matching: METRIC {name}={number}
+
+# 4. Write state.json (use Write tool)
+# 5. Write worklog.md (use Write tool)
+
+# 6. Commit baseline
+git add state.json worklog.md
+git commit -m "baseline: {metric} {value}"
+```
+
+## Eval Phase: Parsing the Metric
+
+The eval_command must print a line matching this pattern to stdout:
+
+```
+METRIC accuracy=89.0
+METRIC pass_rate=72
+METRIC error_count=15
+```
+
+Format: `METRIC {name}={number}` -- one space after METRIC, no spaces around `=`.
+
+Parse the number as a float. If the line is missing, the eval failed -- treat as a discard and log the error.
+
+## Keep Phase Commands
+
+```bash
+git add -A
+git commit -m "$(cat <<'EOF'
+improve: {metric} {old}->{new}
+
+{one-line description of what changed}
+EOF
+)"
+```
+
+## Discard Phase Commands
+
+```bash
+git checkout -- .
+git clean -fd
+```
+
+Use `-fd`, never `-fdx`. The `-x` flag removes files matching `.gitignore` patterns, which can destroy config files, build caches, or virtual environments needed by the eval command.
+
+## state.json Schema
+
+```json
+{
+  "goal": "Improve test accuracy to 98%",
+  "eval_command": "python run_tests.py --report",
+  "metric": "accuracy",
+  "direction": "higher",
+  "threshold": 98,
+  "baseline": 89.0,
+  "current": 94.5,
+  "best": 94.5,
+  "iteration": 5,
+  "max_iterations": 20,
+  "consecutive_discards": 0,
+  "pivot_count": 0,
+  "status": "iterating",
+  "branch": "improve/accuracy-apr13",
+  "history": [
+    {
+      "iteration": 1,
+      "metric_value": 89.0,
+      "decision": "baseline",
+      "description": "Initial measurement"
+    },
+    {
+      "iteration": 2,
+      "metric_value": 91.2,
+      "decision": "keep",
+      "description": "Normalize input features"
+    },
+    {
+      "iteration": 3,
+      "metric_value": 90.1,
+      "decision": "discard",
+      "description": "Add dropout layer -- hurt accuracy"
+    }
+  ],
+  "timestamp": "2026-04-13T20:30:00Z"
+}
+```
+
+### Field descriptions
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `goal` | string | Human-readable objective from orchestrator |
+| `eval_command` | string | Exact command to run for evaluation |
+| `metric` | string | Name of the metric to parse from eval output |
+| `direction` | string | `"higher"` or `"lower"` -- which direction is better |
+| `threshold` | number | Target value -- loop stops when reached |
+| `baseline` | number | First measurement, never changes |
+| `current` | number | Most recent measurement |
+| `best` | number | Best value seen across all iterations |
+| `iteration` | integer | Current iteration count |
+| `max_iterations` | integer | Hard stop limit |
+| `consecutive_discards` | integer | Reset to 0 on every keep |
+| `pivot_count` | integer | Number of strategy pivots so far |
+| `status` | string | One of: `iterating`, `threshold_reached`, `max_iterations`, `stopped` |
+| `branch` | string | Git branch name |
+| `history` | array | Record of every iteration |
+| `timestamp` | string | ISO 8601 timestamp of last update |
+
+### Metric comparison logic
+
+```
+if direction == "higher":
+    improved = (new_value > current)
+    threshold_reached = (new_value >= threshold)
+elif direction == "lower":
+    improved = (new_value < current)
+    threshold_reached = (new_value <= threshold)
+
+# Special case: equal metric with fewer lines of code = improved
+if new_value == current and lines_removed > 0:
+    improved = true
+```
+
+## worklog.md Template
+
+```markdown
+# Worklog: {goal}
+
+Branch: {branch}
+Metric: {metric} ({direction} is better)
+Threshold: {threshold}
+Baseline: {baseline}
+
+## What's Been Tried
+
+(Updated every 10 iterations -- summary of strategies attempted)
+
+---
+
+### Run 1 (baseline): Initial measurement
+- **Metric:** {metric}={value}
+- **Decision:** BASELINE
+
+### Run 2: Normalize input features
+- **Metric:** accuracy=91.2 (was 89.0)
+- **Decision:** KEEP
+- **Insight:** Feature scaling was the low-hanging fruit
+- **Next:** Try feature selection to reduce noise
+
+### Run 3: Add dropout layer (rate=0.3)
+- **Metric:** accuracy=90.1 (was 91.2)
+- **Decision:** DISCARD
+- **Insight:** Dropout hurts on this small dataset -- underfitting
+- **Next:** Try regularization via weight decay instead
+
+---
+
+## Summary
+(Written at termination)
+
+Final: {metric} {baseline} -> {final} in {N} iterations
+Keeps: X | Discards: Y | Pivots: Z
+Key insight: ...
+```
+
+## continue.md Template
+
+Written when the loop is paused or interrupted, so the next session can resume.
+
+```markdown
+# Continue: {goal}
+
+## State
+- Branch: {branch}
+- Iteration: {N} of {max_iterations}
+- Current: {metric}={value} (baseline={baseline}, best={best})
+- Status: {status}
+
+## Last Action
+{what was done in the last iteration and its result}
+
+## Next Hypothesis
+{what to try next, based on worklog insights}
+
+## Resume Steps
+1. Read state.json to restore loop state
+2. Read worklog.md for context on what's been tried
+3. Continue from iteration {N+1}
+```
+
+## Contract Integration
+
+Every response during the loop must include `loop_status` inside `agent_status`:
+
+```json
+{
+  "agent_status": {
+    "plan_status": "IN_PROGRESS",
+    "agent_id": "a1b2c3",
+    "pending_steps": ["continue iterating"],
+    "next_action": "iteration 6",
+    "loop_status": {
+      "iteration": 5,
+      "metric": 94.5,
+      "best": 94.5,
+      "baseline": 89.0,
+      "threshold": 98,
+      "status": "iterating"
+    }
+  },
+  "evidence_report": {
+    "patterns_checked": [],
+    "files_checked": ["state.json"],
+    "commands_run": ["{eval_command}"],
+    "key_outputs": ["accuracy improved 93.2->94.5 (KEEP)"],
+    "verbatim_outputs": ["METRIC accuracy=94.5"],
+    "cross_layer_impacts": [],
+    "open_gaps": [],
+    "verification": null
+  },
+  "consolidation_report": null,
+  "approval_request": null
+}
+```
+
+On loop completion, set `plan_status: "COMPLETE"` with verification:
+
+```json
+{
+  "agent_status": {
+    "plan_status": "COMPLETE",
+    "loop_status": {
+      "iteration": 12,
+      "metric": 98.1,
+      "best": 98.1,
+      "baseline": 89.0,
+      "threshold": 98,
+      "status": "threshold_reached"
+    }
+  },
+  "evidence_report": {
+    "verification": {
+      "method": "metric",
+      "checks": ["accuracy >= 98 threshold"],
+      "result": "pass",
+      "details": "accuracy=98.1 (baseline=89.0) achieved in 12 iterations"
+    }
+  }
+}
+```
+
+## Escalation Logic
+
+```
+consecutive_discards >= 3 -> REFINE
+    Log: "REFINE: 3 consecutive discards. Adjusting within current strategy."
+    Action: Same general approach, different parameters or targets
+
+consecutive_discards >= 5 -> PIVOT
+    Log: "PIVOT #{N}: 5 consecutive discards. Changing strategy entirely."
+    Action: Structurally different approach. Reset consecutive_discards to 0.
+    Increment pivot_count.
+
+pivot_count >= 3 (without any keep since last reset) -> STOP
+    Log: "STOP: 3 pivots without improvement. Reporting blockers."
+    Action: Set status="stopped". Write summary. Return COMPLETE with
+    verification.result="fail" and details explaining what was tried.
+```
+
+## Resume Logic
+
+When starting an agentic-loop, check for existing state before beginning fresh:
+
+### Decision Tree
+
+1. **`continue.md` exists** → Read it, delete it, resume from the checkpoint described. The continue.md was written during context compaction or interruption.
+
+2. **`state.json` exists AND timestamp < 24h** → Resume from saved state. Read iteration count, best metric, worklog. Continue the loop from where it left off.
+
+3. **`state.json` exists AND timestamp > 24h** → Stale session. Archive: rename `state.json` → `state.json.prev`, `worklog.md` → `worklog.md.prev`. Start fresh.
+
+4. **Neither exists** → Fresh start. Run setup phase from scratch.
+
+### Resume Checklist
+
+When resuming (cases 1 or 2):
+- Read `state.json` for: iteration, current metric, best metric, threshold, consecutive_discards, pivot_count
+- Read `worklog.md` for: what was tried, insights, what to try next
+- Read `continue.md` (if exists) for: exact next action, decisions made, remaining steps
+- Verify branch exists: `git branch --list {branch}`
+- Run eval_command to confirm current metric matches state
+- If metric diverged from state → update state, log discrepancy, continue
+
+### Supporting Hooks
+
+These hooks assist with resume:
+- **UserPromptSubmit**: Detects active loop (state.json present, not stale) and injects "you are in agentic-loop mode" context on every turn
+- **PreCompact**: Before context compaction, injects "write continue.md and update state.json NOW"
+- **Protocol Fingerprint Check**: Every 10 iterations, verify you remember the loop rules
+
+## Example Session Walkthrough
+
+**Scenario:** Orchestrator asks to improve test pass rate from ~70% to 95%.
+
+**Parameters received:**
+- goal: "Improve test pass rate to 95%"
+- eval_command: "pytest tests/ --tb=short 2>&1 | python parse_results.py"
+- metric: "pass_rate"
+- direction: "higher"
+- threshold: 95
+- max_iterations: 30
+- files_in_scope: ["src/parser.py", "src/validator.py", "tests/"]
+- branch: "improve/pass-rate-apr13"
+
+**Setup:**
+1. Read `src/parser.py`, `src/validator.py`, all test files
+2. `git checkout -b improve/pass-rate-apr13`
+3. Run eval: `pytest tests/ --tb=short 2>&1 | python parse_results.py`
+   Output includes: `METRIC pass_rate=68.5`
+4. Write state.json (baseline=68.5), write worklog.md
+5. `git commit -m "baseline: pass_rate 68.5"`
+
+**Iteration 1:**
+- HYPOTHESIZE: Failing tests show TypeError on None input -- add null guard
+- EDIT: Add `if value is None: return default` in `parser.py`
+- EVALUATE: `METRIC pass_rate=74.2`
+- DECIDE: 74.2 > 68.5 -> KEEP
+- LOG: "Run 1: Add null guard in parser.py -- pass_rate=74.2 (KEEP)"
+- Commit: `"improve: pass_rate 68.5->74.2"`
+
+**Iteration 2:**
+- HYPOTHESIZE: Remaining failures are in validator edge cases
+- EDIT: Fix off-by-one in range check
+- EVALUATE: `METRIC pass_rate=71.0`
+- DECIDE: 71.0 < 74.2 -> DISCARD
+- LOG: "Run 2: Fix off-by-one in validator range check -- pass_rate=71.0 (DISCARD)"
+- `git checkout -- . && git clean -fd`
+
+**Iteration 3:**
+- HYPOTHESIZE: The range check fix broke other paths. Try fixing just the boundary condition.
+- EDIT: Change `<` to `<=` in validator boundary
+- EVALUATE: `METRIC pass_rate=79.8`
+- DECIDE: 79.8 > 74.2 -> KEEP
+- Commit: `"improve: pass_rate 74.2->79.8"`
+
+... (continues until pass_rate >= 95 or 30 iterations)
+
+**Termination (threshold reached at iteration 18):**
+- `git commit -m "final: pass_rate 68.5->95.3 in 18 iterations"`
+- Write final state.json (status: "threshold_reached")
+- Write summary in worklog.md
+- Return `plan_status: "COMPLETE"` with verification passing
+
+## Protocol Fingerprint Check (every 10 iterations)
+
+At iterations 10, 20, 30, etc., pause and:
+
+1. Re-read all `files_in_scope` -- the code has changed since setup
+2. Review the "What's Been Tried" section in worklog.md
+3. Update "What's Been Tried" with a summary of strategies so far
+4. Check: are you repeating approaches? Are there untried angles?
+5. Log the check in worklog.md as a separate entry
+
+This prevents tunnel vision. After 10 iterations of micro-optimizations, re-reading the source fresh often reveals a structural improvement that the incremental mindset missed.

package/dist/gaia-ops/skills/blog-writing/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: blog-writing
+description: Use when writing, drafting, or publishing a blog article for metraton.github.io
+metadata:
+  user-invocable: true
+  type: technique
+---
+
+# Blog Writing
+
+Jorge's blog (metraton.github.io) is where he thinks out loud about agentic systems, context engineering, and the intersection of architecture and AI. The articles are bilingual (English and Spanish), grounded in real experience, and written in first person. They are not corporate content -- they are reflections from someone building these systems daily.
+
+## The Writing Process
+
+### 1. Find the story first
+
+Every article starts with something that actually happened -- a deployment that went sideways, a late-night refactor, a conversation that shifted your thinking. The story is the anchor. Without it, you are writing a tutorial, not an article.
+
+Ask Jorge: "What happened recently that surprised you or changed how you think about something?" The best topics come from moments where the outcome was different from the expectation.
+
+### 2. Build the brief
+
+Before writing a single paragraph, define: title, audience, core thesis (one sentence), and format. Jorge's natural format is **Strategic Insight** -- personal experience analyzed through a technical lens, ending with a transferable lesson.
+
+The audience is engineers, solution architects, AI practitioners, and tech leaders. They do not need hand-holding but they appreciate honesty about what did not work.
+
+### 3. Draft in Markdown, iterate with Jorge
+
+Write the first draft in Markdown at `/home/jorge/ws/me/<slug>.md`. Work section by section -- do not dump an entire draft and ask "what do you think?" Each section should be reviewed before moving to the next.
+
+**Article structure** (not rigid, but this is Jorge's natural flow):
+- Opening story -- what happened, told personally
+- The problem -- what was broken or surprising
+- Investigation -- what you looked into and found
+- The shift -- the insight or reframe
+- In practice -- what changed, concretely
+- Results -- evidence it worked
+- Closing thought -- punchy, memorable, one line
+
+### 4. Principles that matter
+
+**Examples must be real.** Not "imagine a team that..." but "I was deploying to Cloud Run when..." If you cannot point to something that actually happened, the example does not belong.
+
+**Each section adds something new.** Do not repeat the same example or insight across sections. If the investigation section already showed the problem, the "in practice" section should show the solution -- not restate the problem.
+
+**Quotes add weight when grounded.** Citing Anthropic, Hinton, or other thought leaders works when the quote connects directly to the experience. A quote floating without context is decoration.
+
+**Technical terms stay in English in both languages.** LLM, skills, agent, Cloud Run, Terraform -- these do not get translated.
+
+**Closing lines are signatures.** "Built with context.", "Built with reasoning." -- short, confident, tied to the article's thesis.
+
+### 5. Convert to bilingual HTML
+
+Once the Markdown draft is approved, convert to the bilingual HTML format. The Spanish version is not a mechanical translation -- it is natural Latin American Spanish, with the same voice and directness. Read `reference.md` for the HTML template and front matter structure.
+
+Final HTML goes in: `/home/jorge/ws/me/metraton.github.io/_posts/YYYY-MM-DD-slug.html`
+
+### 6. Editorial review
+
+Before publishing, pass through both language versions checking:
+- Spelling, grammar, flow, and consistency
+- HTML entities are correct (`&mdash;` `&rsquo;` `&eacute;` etc.)
+- Technical terms stay in English in the Spanish version
+- Gender consistency for borrowed terms ("los skills" not "las skills")
+- No broken anglicisms ("marcar" not "flagear")
+- Citations link to real, accessible URLs
+
+### 7. Visual verification
+
+Ensure Jekyll is running locally (see `reference.md` for environment details). Preview at localhost:4000. Use Playwright to take screenshots at desktop (1280x900) and mobile (375x812). Check that all visual components render, no horizontal overflow, responsive breakpoints work.
+
+### 8. Publish
+
+Commit and push to `master` in the blog repo. GitHub Pages deploys automatically.
+
+### 9. Live verification
+
+Wait ~45s after push for GitHub Pages to build. Use Playwright to screenshot the live URL and compare against the localhost preview.
+
+### 10. LinkedIn post
+
+Draft a sharing post: 1-3 sentence personal hook connecting to the article's insight, the link, and a bilingual P.D. See `reference.md` for the template. Conversational but technical tone, no aggressive hashtags -- the article preview image does the heavy lifting.
+
+## Jorge's Voice
+
+- First person, always. "I was deploying..." not "The team deployed..."
+- Honest about failures and iterations -- does not pretend things worked the first time
+- Confident but not preachy. States what he found, not what everyone should do
+- Direct. Short sentences when making a point. Longer when telling a story
+- Latin American perspective -- references to the region's tech community are natural, not forced
+
+## Anti-Patterns
+
+- Writing generic content that could appear on any corporate blog
+- Translating English to Spanish mechanically instead of rewriting naturally
+- Dumping an entire draft without iterating section by section
+- Using hypothetical examples when real ones exist
+- Repeating the same insight across multiple sections

package/dist/gaia-ops/skills/blog-writing/reference.md

@@ -0,0 +1,130 @@
+# Blog Writing Reference
+
+## Blog Repository
+
+- **Repo path:** `/home/jorge/ws/me/metraton.github.io/`
+- **Site:** https://metraton.github.io/
+- **Engine:** Jekyll static site, GitHub Pages hosted
+- **Posts directory:** `_posts/`
+- **Draft workspace:** `/home/jorge/ws/me/<slug>.md`
+
+## Front Matter Template
+
+Every post requires this YAML front matter. All fields are mandatory for the bilingual layout to work correctly.
+
+```yaml
+---
+layout: bilingual
+title: "English Title Here"
+title_en: "English Title Here"
+title_es: "Spanish Title Here"
+post_title_es: "Spanish Title Here"
+date: YYYY-MM-DD
+terminal_title: "jaguilar@github:~/posts$ cat slug-name"
+terminal_title_es: "jaguilar@github:~/posts$ cat slug-name"
+excerpt: "English excerpt -- one compelling sentence."
+excerpt_es: "Spanish excerpt -- one compelling sentence."
+---
+```
+
+**Notes:**
+- `title` and `title_en` are always identical
+- `title_es` and `post_title_es` are always identical
+- `terminal_title` and `terminal_title_es` are usually the same (the cat command)
+- `date` is the publication date in `YYYY-MM-DD` format
+- Excerpts use HTML entities for special characters (e.g., `&eacute;` for accented characters in Spanish)
+- Some older posts include `permalink:` -- newer posts rely on the filename for the URL
+
+## HTML Structure
+
+The file is named `YYYY-MM-DD-slug.html` and placed in `_posts/`.
+
+```html
+---
+(front matter as above)
+---
+
+      <div class="bilingual-content" lang="en" data-lang-section="en">
+        <!-- English content here -->
+        <!-- Use proper HTML entities: &mdash; &rsquo; &ldquo; &rdquo; etc. -->
+
+        <p class="closing-line"><em>Built with [theme]. Jorge Aguilar, 2025&ndash;2026.</em></p>
+      </div>
+      <div class="bilingual-content" lang="es" data-lang-section="es" hidden>
+        <!-- Spanish content here -->
+        <!-- Same structure as English, naturally rewritten -->
+
+        <p class="closing-line"><em>Construido con [tema]. Jorge Aguilar, 2025&ndash;2026.</em></p>
+      </div>
+```
+
+**HTML conventions observed in existing posts:**
+- Content is indented with 8 spaces (two levels inside the layout)
+- Use `&mdash;` for em dashes, `&rsquo;` for apostrophes, `&ldquo;`/`&rdquo;` for quotes
+- Use `&eacute;`, `&aacute;`, `&iacute;`, `&oacute;`, `&uacute;`, `&ntilde;` for Spanish accented characters
+- Section headings are `<h2>`, subsection headings are `<h3>`
+- Horizontal rules (`<hr />`) separate major sections
+- Blockquotes (`<blockquote>`) are used for key insights and external quotes
+- Code inline uses `<code>`, code blocks use `<pre><code>`
+- The Spanish section has `hidden` attribute (JavaScript toggles it)
+- The closing line uses `class="closing-line"` with `<em>` wrapper
+
+## Article Catalog
+
+| Date | Slug | Status |
+|------|------|--------|
+| 2025-09-29 | context-design-agentic-deployment | PUBLISHED |
+| 2025-11-01 | beyond-delegation-agentic-systems | PUBLISHED |
+| 2026-04-02 | faster-development-orchestration | PUBLISHED |
+| 2026-04-10 | writing-skills-that-actually-work | PUBLISHED |
+| TBD | how-to-build-an-agent-identity | PENDING |
+
+## Environment & Tooling
+
+| Resource | Location |
+|----------|----------|
+| Blog repo | `/home/jorge/ws/me/metraton.github.io/` |
+| Jekyll server | `cd /home/jorge/ws/me/metraton.github.io && bash jekyll-loop.sh` (port 4000) |
+| Playwright | `~/.cache/ms-playwright/`, requires `NODE_PATH=/home/jorge/ws/aaxis/rnd/node_modules` |
+| Git branch | `master` (not main) |
+| GitHub Pages | `https://metraton.github.io/` |
+
+Check if Jekyll is running: `ps aux | grep jekyll`
+
+## Visual Components Catalog
+
+All CSS lives inline in `_layouts/default.html` -- no external stylesheets.
+
+| Component | CSS Class | When to Use |
+|-----------|-----------|-------------|
+| Before/After Grid | `.file-structure-demo` | Comparing old vs new approaches, code transformations |
+| Card Grid | `.subagents-grid` / `.subagent-box` | Showing related concepts as cards (agents, types, categories) |
+| Skills Grid | `.skills-grid` | 5-column card grid with optional `.lead-agent` header |
+| Callout Box | `.callout` | Highlighted info, tips, key takeaways |
+| Blockquote | `<blockquote>` | Editorial quotes, citations, reflective text |
+| Chapter Layout | `.chapter` / `.chapter-layout` | Text + ASCII diagram side by side |
+| Code Block | `<pre><code>` | Actual code, config files, terminal output |
+| Table | `<table>` | Data comparison (note: limited CSS, consider cards instead) |
+
+## Publication
+
+```bash
+cd /home/jorge/ws/me/metraton.github.io
+git add _posts/YYYY-MM-DD-slug.html
+git commit -m "Add: article title"
+git push origin master
+# GitHub Pages deploys automatically
+```
+
+## LinkedIn Post Template
+
+```
+[1-3 sentence hook connecting to the article's core insight]
+
+https://metraton.github.io/<slug>/
+
+P.D.: Lo escribí en formato bilingüe (ES/EN), para que lo leas de la forma que prefieras.
+```
+
+Tone: conversational but technical. No aggressive hashtags. The article preview image does the heavy lifting -- text just hooks.
+