@damiangilgonzalez/harness 1.3.7

package/skills/huggingface/references/endpoints-and-spaces.md

@@ -0,0 +1,99 @@
+# Dedicated Endpoints & Spaces
+
+## Dedicated Inference Endpoints
+
+Your own autoscaling deployment of a model on managed HF infra. Graduate here from the router
+when you need fixed latency/SLA or the router's pay-as-you-go cost stops being predictable.
+
+### Pricing (billed per minute, shown hourly)
+
+| Tier | From |
+|---|---|
+| CPU | ~$0.032 / core / hr |
+| GPU (entry) | ~$0.50 / hr |
+| GPU A10G | ~$1.00 / hr |
+| GPU H100 | ~$6.40–8.00 / hr |
+
+### Scale-to-zero
+
+Enable scale-to-zero so the endpoint parks at **$0 when idle** and cold-starts on the next
+request — the right default for bursty traffic. A bursty 100–1000 req/day workload typically
+lands at **$20–60/mo**. The trade-off is cold-start latency on the first request after idle; keep
+a minimum replica > 0 only if you cannot tolerate that.
+
+### Deploy from the UI
+
+1. Model page → **Deploy → Inference Endpoints**, pick cloud/region/hardware.
+2. Set **Autoscaling**: min replicas (`0` for scale-to-zero), max replicas, scale-to-zero idle
+   timeout.
+3. Set security (Protected/Public) and create. Copy the endpoint URL.
+
+### Deploy with `huggingface_hub`
+
+```python
+from huggingface_hub import create_inference_endpoint
+
+ep = create_inference_endpoint(
+    name="llama-31-8b",
+    repository="meta-llama/Llama-3.1-8B-Instruct",
+    framework="pytorch",
+    task="text-generation",
+    accelerator="gpu",
+    instance_size="x1",
+    instance_type="nvidia-a10g",
+    vendor="aws",
+    region="us-east-1",
+    min_replica=0,          # scale-to-zero
+    max_replica=2,
+)
+ep.wait()                   # block until the endpoint is running
+print(ep.url)
+```
+
+Call it like any provider endpoint:
+
+```python
+from huggingface_hub import InferenceClient
+client = InferenceClient(base_url=ep.url, api_key=os.environ["HF_TOKEN"])
+```
+
+### Cost worksheet
+
+```text
+monthly_cost ≈ active_minutes/month × (hourly_rate / 60)
+# scale-to-zero ⇒ active_minutes ≈ requests × seconds_per_request / 60, plus cold starts
+# Example: 500 req/day × 2s × 30 days = 500 min ≈ 8.3 hr/mo on A10G ($1/hr) ≈ $8/mo + cold starts
+```
+
+## Spaces
+
+A Space hosts a demo app at a public `*.hf.space` URL. Pick the SDK by need:
+
+| SDK | Use for | ZeroGPU? |
+|---|---|---|
+| Gradio | ML demos, the default | **Yes** |
+| Streamlit | data-app UIs | No |
+| Docker | arbitrary servers/full control | No |
+| Static | HTML/JS front-ends | No |
+
+### ZeroGPU
+
+Dynamic GPU allocation: an **H200 MIG slice (3g.71gb, ~70GB)** is grabbed only while a decorated
+function runs and released when idle. **Gradio SDK only.**
+
+```python
+import spaces
+import gradio as gr
+
+@spaces.GPU                       # GPU acquired for the duration of this call
+def generate(prompt: str) -> str:
+    # load/run your model here
+    return run_model(prompt)
+
+gr.Interface(fn=generate, inputs="text", outputs="text").launch()
+```
+
+- Free accounts get a daily ZeroGPU quota; **PRO ($9/mo)** gives **8x daily quota**, queue
+  priority, and up to **10 owned ZeroGPU Spaces**.
+- Keep `@spaces.GPU` functions short — the slice is held for the whole call, so quota burns with
+  wall-clock GPU time.

package/skills/huggingface/references/hub-and-cli.md

@@ -0,0 +1,85 @@
+# Hub & the `hf` CLI
+
+The CLI was renamed `huggingface-cli` → **`hf`**, shaped `hf <resource> <action>`. The legacy
+name still works but prints a deprecation warning — use `hf` in all new scripts.
+
+## Command map
+
+```bash
+hf auth login                 # interactive token store; or export HF_TOKEN=...
+hf auth whoami                # confirm identity + token scope
+hf download <repo>            # pull a repo (model/dataset/space) to the local cache
+hf upload <repo> <path>       # push files to a repo
+hf repo create <repo>         # create a new repo (--repo-type model|dataset|space)
+hf jobs run <image> -- <cmd>  # run a containerized/uv job on HF infra (PRO)
+```
+
+## Download patterns
+
+```bash
+# Only the weights you need, not the whole repo:
+hf download meta-llama/Llama-3.1-8B-Instruct --include "*.safetensors" "config.json"
+
+# A dataset:
+hf download HuggingFaceH4/ultrachat_200k --repo-type dataset
+```
+
+```python
+from huggingface_hub import snapshot_download, hf_hub_download
+
+# Whole repo (resumable, cached):
+local = snapshot_download("BAAI/bge-small-en-v1.5")
+
+# A single file:
+cfg = hf_hub_download("BAAI/bge-small-en-v1.5", filename="config.json")
+```
+
+## Upload patterns
+
+```bash
+hf repo create my-org/my-model --repo-type model
+hf upload my-org/my-model ./checkpoints --commit-message "v1 weights"
+```
+
+```python
+from huggingface_hub import HfApi
+api = HfApi()
+api.create_repo("my-org/my-model", repo_type="model", private=True)
+api.upload_folder(repo_id="my-org/my-model", folder_path="./checkpoints",
+                  commit_message="v1 weights")
+```
+
+## Model cards
+
+A model card is the repo's `README.md` with YAML front-matter. Ship one on every upload — an
+uncarded repo is unsearchable and unusable by others.
+
+```markdown
+---
+license: apache-2.0
+pipeline_tag: text-generation
+base_model: meta-llama/Llama-3.1-8B
+tags: [llama, fine-tune, instruct]
+language: [en]
+---
+
+# my-model
+
+What it is, what it was trained on, intended use, limitations, and how to load it.
+```
+
+## Gated & licensed models
+
+- **Gated** repos (Llama, Gemma, many others): accept the terms on the model page first, then use
+  a token with **read** scope. Without acceptance the download/inference returns `403`.
+- Read the `license` field before shipping: Apache-2.0/MIT are permissive; Llama/Gemma carry
+  commercial conditions; `cc-by-nc`/"research-only" means you cannot ship it commercially.
+
+## `hf jobs run`
+
+Run a one-off containerized or `uv`-script job on HF infra (a PRO feature) — the path for an
+eval, a batch convert, or a fine-tune without standing up an Endpoint or a Space.
+
+```bash
+hf jobs run python:3.12 -- python -c "print('runs on HF infra')"
+```

package/skills/huggingface/references/inference-providers.md

@@ -0,0 +1,115 @@
+# Inference Providers — client recipes & routing
+
+The router (`https://router.huggingface.co/v1`, or `InferenceClient`) is the unified, serverless
+entry point — formerly "Inference API (serverless)". One token reaches 200+ models across partner
+providers (Cerebras, Together, Fireworks, Replicate, DeepInfra, Public AI, …) plus `hf-inference`.
+HF passes the provider's price through with **no markup**.
+
+All snippets read the token from `os.environ["HF_TOKEN"]` — never hardcode `hf_...`.
+
+## Chat / LLM
+
+```python
+import os
+from huggingface_hub import InferenceClient
+
+client = InferenceClient(api_key=os.environ["HF_TOKEN"])
+resp = client.chat.completions.create(
+    model="meta-llama/Llama-3.1-8B-Instruct",
+    messages=[{"role": "user", "content": "Explain MoE in one line."}],
+    provider="together",      # omit to let HF auto-route to an available provider
+    max_tokens=256,
+)
+print(resp.choices[0].message.content)
+```
+
+Streaming:
+
+```python
+for chunk in client.chat.completions.create(
+    model="meta-llama/Llama-3.1-8B-Instruct",
+    messages=[{"role": "user", "content": "Count to five."}],
+    stream=True,
+):
+    delta = chunk.choices[0].delta.content
+    if delta:
+        print(delta, end="", flush=True)
+```
+
+## Embeddings (feature_extraction)
+
+```python
+vecs = client.feature_extraction(
+    "Retrieval-augmented generation grounds answers in sources.",
+    model="BAAI/bge-small-en-v1.5",
+    provider="hf-inference",   # embeddings are a CPU task — hf-inference is correct here
+)
+# vecs is a numpy array of shape (dim,) or (n_tokens, dim) depending on the model
+```
+
+## Text-to-image
+
+```python
+image = client.text_to_image(
+    "a minimalist line drawing of a fox",
+    model="black-forest-labs/FLUX.1-dev",
+    provider="replicate",
+)
+image.save("fox.png")   # returns a PIL.Image
+```
+
+## Speech-to-text (ASR)
+
+```python
+text = client.automatic_speech_recognition(
+    "sample.flac",
+    model="openai/whisper-large-v3",
+)
+print(text.text)
+```
+
+## OpenAI-compatible drop-in
+
+```python
+import os
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="https://router.huggingface.co/v1",   # exact host; anything else won't route
+    api_key=os.environ["HF_TOKEN"],
+)
+resp = client.chat.completions.create(
+    model="meta-llama/Llama-3.1-8B-Instruct:together",  # optional :provider suffix
+    messages=[{"role": "user", "content": "hi"}],
+)
+```
+
+## Provider selection & the hf-inference niche
+
+- `provider="auto"` (default when omitted) routes to an available partner for the model.
+- Name a partner explicitly (`together`, `fireworks-ai`, `cerebras`, `replicate`,
+  `deepinfra`, …) when you need a specific backend's pricing or features.
+- **`hf-inference`** (the old serverless API) as of July 2025 focuses on CPU tasks: embeddings,
+  text-ranking, text-classification, and small historic LLMs (BERT, GPT-2). Do **not** route a
+  big LLM there — it 404s or stalls. Send 8B/70B/405B chat to a partner provider.
+
+## Billing & org headers
+
+- Monthly Inference-Providers credits: **Free $0.10**, **PRO $2.00**, **Team/Enterprise $2.00 per
+  seat** (shared across the org). Past credits → pay-as-you-go (you must purchase credits).
+- A **Custom Provider Key** (your own key for a partner) bypasses HF billing — the provider bills
+  you directly and HF credits do not apply.
+- Bill an organization instead of your personal account:
+
+```python
+client = InferenceClient(api_key=os.environ["HF_TOKEN"], bill_to="my-org")
+# or, with the OpenAI client, set the header:  X-HF-Bill-To: my-org
+```
+
+## Errors & rate limits
+
+- `402` / out-of-credits → buy credits or switch to a Custom Provider Key.
+- `404` on a big LLM via `hf-inference` → wrong provider; pick a partner.
+- `429` rate limit → back off and retry with jitter; the router does not retry for you.
+- Always read the token from env and catch `huggingface_hub.errors.HfHubHTTPError` to surface the
+  provider's message.

package/skills/huggingface/scripts/verify.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+#
+# verify.sh — static linter for Hugging Face integration code/config.
+#
+# Usage:
+#   ./scripts/verify.sh [TARGET_PATH]   (default: current directory)
+#
+# Read-only. No network, no HF token, nothing executed from the target. It greps emitted
+# CODE/CONFIG artifacts (.py/.sh/.toml/.yaml/.yml) for the hard mistakes this skill warns
+# about and exits non-zero only on HARD violations. Soft issues print a yellow WARN and do not
+# fail. Prose docs (.md/.txt) are NOT scanned — they legitimately quote anti-patterns as
+# examples, so scanning them would false-positive. This script and the skill's own files are
+# skipped. An empty or clean target exits 0 — never a false failure.
+#
+# Compatible with stock macOS bash 3.2: no mapfile, no associative arrays, find|while loop.
+
+set -euo pipefail
+
+TARGET="${1:-.}"
+
+if [ -t 1 ]; then
+  RED=$'\033[0;31m'; GREEN=$'\033[0;32m'; YELLOW=$'\033[0;33m'; RESET=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; RESET=''
+fi
+fail_msg() { printf '%sFAIL%s %s\n' "$RED" "$RESET" "$*"; }
+warn_msg() { printf '%sWARN%s %s\n' "$YELLOW" "$RESET" "$*"; }
+ok_msg()   { printf '%sOK%s   %s\n' "$GREEN" "$RESET" "$*"; }
+
+if [ ! -e "$TARGET" ]; then
+  warn_msg "target '$TARGET' does not exist — nothing to check"
+  exit 0
+fi
+
+HARD=0
+
+# Collect candidate files (skip VCS and dependency dirs).
+FILES=""
+while IFS= read -r f; do
+  FILES="$FILES
+$f"
+done <<EOF
+$(find "$TARGET" \
+    \( -name .git -o -name node_modules -o -name .venv -o -name venv -o -name __pycache__ \) -prune -false \
+    -o -type f \( -name '*.py' -o -name '*.sh' \
+                  -o -name '*.toml' -o -name '*.yaml' -o -name '*.yml' \) \
+    ! -name 'verify.sh' -print 2>/dev/null)
+EOF
+
+# Trim leading blank line.
+FILES="$(printf '%s\n' "$FILES" | sed '/^$/d')"
+
+if [ -z "$FILES" ]; then
+  ok_msg "no HF-related source/config files found — clean"
+  exit 0
+fi
+
+scan() { # scan <regex> <label>; returns 0 if a match was found
+  printf '%s\n' "$FILES" | while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    grep -nE "$1" "$f" 2>/dev/null | sed "s#^#$f:#"
+  done
+}
+
+# --- HARD: InferenceClient.post() was removed ---
+HITS="$(scan '\.post\s*\(' || true)"
+if printf '%s' "$HITS" | grep -q .; then
+  # only treat as HF .post if the file mentions InferenceClient
+  PHITS="$(printf '%s\n' "$FILES" | while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    if grep -q 'InferenceClient' "$f" 2>/dev/null; then grep -nE '\.post\s*\(' "$f" 2>/dev/null | sed "s#^#$f:#"; fi
+  done)"
+  if printf '%s' "$PHITS" | grep -q .; then
+    fail_msg "InferenceClient.post() is removed (hub v0.31.0) — use task methods (chat.completions.create / feature_extraction):"
+    printf '%s\n' "$PHITS"
+    HARD=1
+  fi
+fi
+
+# --- HARD: hardcoded hf_ token literal ---
+THITS="$(scan '["'\'']hf_[A-Za-z0-9]{8,}' || true)"
+if printf '%s' "$THITS" | grep -q .; then
+  fail_msg "hardcoded hf_ token literal — read os.environ[\"HF_TOKEN\"] instead:"
+  printf '%s\n' "$THITS"
+  HARD=1
+fi
+
+# --- HARD: big LLM routed to hf-inference (CPU/small-model niche) ---
+BHITS="$(scan 'provider\s*=\s*["'\'']hf-inference["'\'']' || true)"
+if printf '%s' "$BHITS" | grep -q .; then
+  BIG="$(printf '%s\n' "$BHITS" | grep -iE '(-|_)(7b|8b|13b|34b|70b|72b|405b)|llama-?3|mixtral|qwen2|deepseek' || true)"
+  if printf '%s' "$BIG" | grep -q .; then
+    fail_msg "large LLM routed to provider=\"hf-inference\" (CPU/small-model niche; will 404/stall) — use a partner provider:"
+    printf '%s\n' "$BIG"
+    HARD=1
+  fi
+fi
+
+# --- HARD: wrong OpenAI-compat router host ---
+URLHITS="$(scan 'router\.huggingface\.co' || true)"
+if printf '%s' "$URLHITS" | grep -q .; then
+  BADURL="$(printf '%s' "$URLHITS" | grep -E 'router\.huggingface\.co' | grep -vE 'router\.huggingface\.co/v1([^A-Za-z0-9]|$)' || true)"
+  if printf '%s' "$BADURL" | grep -q .; then
+    fail_msg "router host must be https://router.huggingface.co/v1 for OpenAI-compat:"
+    printf '%s\n' "$BADURL"
+    HARD=1
+  fi
+fi
+
+# --- SOFT: legacy huggingface-cli in shell/scripts ---
+CLIHITS="$(scan 'huggingface-cli ' || true)"
+if printf '%s' "$CLIHITS" | grep -q .; then
+  warn_msg "legacy 'huggingface-cli' is deprecated — prefer 'hf <resource> <action>':"
+  printf '%s\n' "$CLIHITS"
+fi
+
+if [ "$HARD" -ne 0 ]; then
+  fail_msg "hard violations found"
+  exit 1
+fi
+
+ok_msg "no hard violations"
+exit 0

package/skills/implement/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: implement
+description: "Implements a piece of work from a spec or a set of tickets."
+tags: ["implementation", "spec", "tickets"]
+disable-model-invocation: true
+profiles: [core, ui, full]
+---
+
+
+Implementa el trabajo descrito por el usuario en la spec o los tickets.
+
+Usa TDD (superpowers:test-driven-development) donde sea posible, en las costuras (seams) acordadas de antemano.
+
+Ejecuta el typechecking con regularidad, archivos de test sueltos con regularidad, y la suite de tests completa una vez al final.
+
+Al terminar, usa /code-review para revisar el trabajo.
+
+Commitea tu trabajo en la rama actual.

package/skills/implement/evals/cases.yaml

@@ -0,0 +1,32 @@
+skill: implement
+
+should_trigger:
+  - prompt: "Implementa esta pieza de trabajo a partir de la spec."
+    why: "Disparador directo de implement."
+  - prompt: "Coge este conjunto de tickets y empieza a implementarlos."
+    why: "Disparador directo de implement."
+  - prompt: "Necesito que se escriba el codigo de esta spec."
+    why: "Disparador directo de implement."
+  - prompt: "Implement this piece of work from the spec we just wrote."
+    why: "Disparador directo de implement."
+  - prompt: "Pon en marcha la implementacion de este ticket."
+    why: "Disparador directo de implement."
+
+should_not_trigger:
+  - prompt: "Escribe la spec antes de implementar nada."
+    route_to: "to-spec"
+    why: "Escribir la spec es el trabajo de to-spec, no de implement."
+  - prompt: "Revisa el codigo que ya se implemento."
+    route_to: "code-review"
+    why: "Revisar el codigo ya implementado es el trabajo de code-review, no de implement."
+  - prompt: "Descompon el plan en tickets primero."
+    route_to: "to-tickets"
+    why: "Descomponer el plan en tickets es el trabajo de to-tickets, no de implement."
+  - prompt: "Documenta la decision de arquitectura tomada."
+    route_to: "write-adr"
+    why: "Documentar una decision de arquitectura es el trabajo de write-adr, no de implement."
+
+capability:
+  - scenario: "El usuario quiere implementar una pieza de trabajo a partir de una spec o tickets."
+    must_include:
+      - "implementa"