@damiangilgonzalez/harness 1.3.7

package/skills/tiktok-api/references/oauth-setup.md

@@ -0,0 +1,105 @@
+# OAuth v2 setup, scopes, audit gate, and token lifecycle
+
+Everything needed to go from "no app" to "an authed, self-refreshing TikTok client."
+There is **no official TikTok SDK** — all calls are raw REST.
+
+## 1. Register the app and enable products
+
+1. Create a developer app in the TikTok for Developers portal.
+2. Add **products** the job needs — each is a separate toggle:
+   - **Login Kit** — the OAuth v2 flow (required for everything).
+   - **Content Posting API** — to publish/upload video.
+   - **Display API** — to read your own profile + basic video counters.
+3. **Business insights are separate.** Watch time, completion, and impression sources
+   come from the **TikTok API for Business**, enabled through the business portal /
+   business account access — not the standard developer-app product toggles.
+4. Set an exact **redirect URI** (must match byte-for-byte at authorize + exchange time).
+
+## 2. The three gates (the part that surprises people)
+
+| Gate | Controls | How you pass it |
+| --- | --- | --- |
+| Content Posting **audit** | Public posting for arbitrary users | Submit app for review; until then **SELF_ONLY + test users only** |
+| Display **scope** | Reading your own video counts | Request `video.list`; user authorizes it |
+| Business **portal** access | Watch time / completion / impression sources | Enable business account access separately |
+
+Unaudited apps can only post **privately** (`privacy_level: "SELF_ONLY"`) and only to a
+limited set of registered test users. This is the #1 "works in dev, breaks in prod"
+failure — public posting for real users requires the audit to pass first.
+
+## 3. Scope catalog
+
+| Scope | Grants |
+| --- | --- |
+| `user.info.basic` | open_id, display name, avatar |
+| `video.list` | Read your own videos + basic counters (Display API) |
+| `video.publish` | Direct Post to the public feed (audit-gated) |
+| `video.upload` | Upload to drafts/inbox for the user to finalize |
+
+Request least privilege. A read-only daily-pull cron needs only `video.list`
+(+ `user.info.basic`); add `video.publish` only on the path that actually posts.
+
+## 4. Authorize → exchange
+
+Send the user to the authorize URL:
+
+```text
+https://www.tiktok.com/v2/auth/authorize/
+  ?client_key=<CLIENT_KEY>
+  &scope=video.publish,video.list,user.info.basic
+  &response_type=code
+  &redirect_uri=<EXACT_REDIRECT_URI>
+  &state=<csrf_token>
+  &code_challenge=<S256>&code_challenge_method=S256   # PKCE recommended
+```
+
+Exchange the returned `code` for tokens:
+
+```python
+import requests, os
+r = requests.post("https://open.tiktokapis.com/v2/oauth/token/", data={
+    "client_key": os.environ["TIKTOK_CLIENT_KEY"],
+    "client_secret": os.environ["TIKTOK_CLIENT_SECRET"],
+    "grant_type": "authorization_code",
+    "code": code,
+    "redirect_uri": REDIRECT_URI,
+    "code_verifier": pkce_verifier,        # if you used PKCE
+}, headers={"Content-Type": "application/x-www-form-urlencoded"})
+tok = r.json()
+# { access_token, expires_in: 86400, refresh_token, refresh_expires_in: 31536000, open_id, scope }
+```
+
+## 5. Token lifecycle — the load-bearing rule
+
+- **Access token: 24 hours** (`expires_in: 86400`).
+- **Refresh token: 365 days** (`refresh_expires_in: 31536000`); refresh needs no
+  user re-consent and **rotates** the refresh token each time.
+
+Therefore:
+
+- A daily cron MUST refresh the access token **every run** (see the `access_token()`
+  helper in SKILL.md §2) and **persist the new refresh_token** returned each time.
+- An account left idle past **365 days** silently dies at the refresh-token boundary —
+  the only fix is re-running the OAuth consent flow.
+
+## 6. PULL_FROM_URL domain verification
+
+`PULL_FROM_URL` publishing requires the source domain or URL-prefix to be verified in
+the portal before any init succeeds:
+
+- Add the domain/URL-prefix in the portal; complete **DNS TXT signature** or
+  **URL-prefix** verification.
+- The source URL must be **HTTPS**, **no redirects**, and download within the
+  **1-hour** timeout.
+- An unverified domain returns `url_ownership_unverified` on every init.
+
+## 7. Troubleshooting
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `scope_not_authorized` | Scope not granted or app not approved for it | Re-consent with the scope; check app approval |
+| `access_token_invalid` | 24h access token expired or wrong token | Refresh before the call; never hardcode |
+| Only `SELF_ONLY` posts succeed | App not audited | Submit for audit; use test users meanwhile |
+| `url_ownership_unverified` | PULL_FROM_URL domain not verified | Verify domain/URL-prefix (DNS TXT) |
+| Refresh returns an error after long idle | 365-day refresh token expired | Re-run the authorize → exchange flow |
+| Redirect mismatch at exchange | `redirect_uri` differs from the registered one | Match it byte-for-byte |

package/skills/tiktok-api/references/wiki-schema.md

@@ -0,0 +1,119 @@
+# Wiki schema for `docs/wiki/shortform/`
+
+How a TikTok pull becomes durable, queryable account history the shortform siblings
+read. The rule that matters: **append, never overwrite.** A snapshot that replaces
+yesterday's destroys the trend — and erases the 24–48h metric settling you only see
+across pulls.
+
+## File tree
+
+```text
+docs/wiki/shortform/
+  index.md                       # rolling pointer: latest snapshot per platform + open questions
+  tiktok-account-2026-06-02.md   # dated account snapshot, one file per pull
+  tiktok-account-2026-06-09.md
+  videos/
+    tiktok-<video_id>.md         # per-video running log, newest entry on top
+```
+
+### Why the `tiktok-` prefix
+
+The `shortform/` wiki may also hold Instagram and YouTube pulls (sibling transport
+skills write here too). Platform-namespacing the filenames keeps cross-platform pulls
+from colliding and lets a sibling grep `tiktok-*` for just this account.
+
+## Account snapshot entry (one file per pull)
+
+Frontmatter is **OKF v0.1 conformant**: a non-empty `type` is the only hard
+requirement; `title`/`tags`/`timestamp` are the recommended OKF surface. The
+domain keys (`date`, `range`, `account`, `platform`, `source`, `provisional`) are
+preserved verbatim — siblings parse them, and OKF tolerates arbitrary extra keys.
+`date` is the snapshot's reporting day; `timestamp` is the ISO 8601 moment the file
+was written. Keep both.
+
+```markdown
+---
+type: shortform-metrics
+title: TikTok account snapshot — 2026-06-02
+tags: [tiktok, metrics, snapshot]
+timestamp: 2026-06-02T09:00:00Z
+date: 2026-06-02
+range: 2026-05-26..2026-06-01
+account: <open_id>
+platform: tiktok
+source: display-api + business-account-api
+provisional: true            # set while inside the 24–48h metric-lag window
+---
+## KPIs
+views: 52,140 | likes: 3,902 | comments: 211 | shares: 488
+
+## Watch
+full_video_watched_rate: 28.4% | avg_time_watched: 6.1s | total_time_watched: 88h
+
+## Impression sources (top 3)
+For You 71% · Personal profile 14% · Search 7%
+
+## What changed since last pull
+completion +3.1pts after the tighter cold-open; FYP share up 5pts.
+```
+
+## Per-video running log (`videos/tiktok-<id>.md`)
+
+Newest entry on top, so a glance shows the latest. Each pull **prepends** a block —
+this is where the 24–48h settling becomes visible (the same video's
+`full_video_watched_rate` will drift between pulls). This is an OKF append-log:
+the frontmatter header is written once and stays immutable; new dated blocks are
+prepended **above** older ones (newest-first), past blocks are never edited, and
+dates are ISO 8601.
+
+```markdown
+---
+type: shortform-record
+title: tiktok-7399 — "cold open hook test"
+tags: [tiktok, video-log]
+timestamp: 2026-06-02T09:00:00Z
+video_id: "7399..."
+platform: tiktok
+posted: 2026-05-28
+duration: 21s
+---
+# tiktok-7399... — "cold open hook test"
+
+## 2026-06-02 (final-ish)
+views 52,140 | completion 28.4% | avg_watched 6.1s | FYP 71%
+
+## 2026-05-29 (provisional, <48h)
+views 18,900 | completion 24.1% | avg_watched 5.3s | FYP 64%
+```
+
+On each prepend, bump the header `timestamp` to the new pull's ISO moment; never
+edit a past dated block.
+
+## index.md
+
+A thin pointer, not a data dump. As an OKF **reserved** file it carries **no
+frontmatter**, and its cross-references are standard markdown links (never
+wikilinks), so an OKF consumer can follow them straight to the snapshot files:
+
+```markdown
+# shortform wiki — index
+- tiktok: latest snapshot → [tiktok-account-2026-06-02.md](./tiktok-account-2026-06-02.md)
+- open questions:
+  - is the cold-open change holding completion above 27%? (watch next 2 pulls)
+```
+
+## Rules
+
+- **Append, never overwrite.** New pull → new dated snapshot file + prepended per-video
+  block. Never edit a past snapshot in place.
+- **Mark provisional pulls.** Set `provisional: true` (or a label) while inside the
+  24–48h lag window; the next pull supersedes it without deleting it.
+- **Namespace by platform.** `tiktok-` prefix on every file so IG/YouTube pulls coexist.
+- **Numbers only, no interpretation.** "What changed" is a factual delta line, not a
+  recommendation — what to *do* about it belongs to `shortform-strategy`.
+- **OKF v0.1 conformant.** Every snapshot and per-video file carries YAML frontmatter
+  with a non-empty `type` (`shortform-metrics` / `shortform-record`) plus the OKF
+  `title`/`tags`/`timestamp` surface; domain keys like `date` are kept additively. The
+  reserved `index.md` carries no frontmatter. All cross-references are standard markdown
+  links — never `[[wikilinks]]` — so the `shortform/` tree is a portable OKF bundle the
+  siblings (and any OKF consumer) read without translation.

package/skills/tiktok-api/scripts/verify.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# verify.sh — static, no-network preflight linter for TikTok API integration code.
+# Read-only. Flags the patterns this skill bans. Exits 0 on a clean/empty target,
+# non-zero with file:line on any hit.
+#
+# Usage: scripts/verify.sh [TARGET_DIR]   (default: current directory)
+
+set -euo pipefail
+
+TARGET="${1:-.}"
+hits=0
+
+if [ ! -d "$TARGET" ]; then
+  echo "verify.sh: target '$TARGET' is not a directory" >&2
+  exit 2
+fi
+
+report() { echo "FAIL [$1] $2"; hits=$((hits + 1)); }
+
+# Files we scan: source + config, skipping vendored/build/VCS dirs. (bash 3.2 compatible)
+FILES=()
+while IFS= read -r _f; do
+  [ -n "$_f" ] && FILES+=("$_f")
+done < <(
+  find "$TARGET" \
+    \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/dist/*' \
+       -o -path '*/build/*' -o -path '*/.venv/*' -o -path '*/venv/*' \) -prune -o \
+    -type f \( -name '*.py' -o -name '*.js' -o -name '*.ts' -o -name '*.mjs' \
+       -o -name '*.json' -o -name '*.env' -o -name '*.yaml' -o -name '*.yml' \) -print 2>/dev/null
+)
+
+# (1) Committed TikTok secrets: a tracked token file containing a refresh_token.
+while IFS= read -r f; do
+  [ -n "$f" ] || continue
+  if grep -lqs 'refresh_token' "$f" 2>/dev/null; then
+    report "tracked-token" "$f: token file contains a refresh_token — do not commit it (gitignore it)"
+  fi
+done < <(find "$TARGET" \( -path '*/.git/*' \) -prune -o -type f \
+           \( -name '*tiktok*token*.json' -o -name 'tiktok_token.json' -o -name 'token*.json' \) -print 2>/dev/null)
+
+# Per-file content scans.
+for f in ${FILES[@]+"${FILES[@]}"}; do
+  [ -f "$f" ] || continue
+
+  # (1b) Hardcoded client_secret literal in source.
+  while IFS= read -r line; do
+    report "client-secret" "$f:$line client_secret assigned a literal — load from env/secret store"
+  done < <(grep -niE 'client_secret[[:space:]]*[:=][[:space:]]*["'"'"'][A-Za-z0-9_-]{8,}' "$f" 2>/dev/null \
+            | grep -viE 'os\.environ|process\.env|getenv|<|placeholder|your_|example|xxxx' | cut -d: -f1)
+
+  # (2) Hardcoded access_token / Bearer literal instead of a refreshable credential object.
+  while IFS= read -r line; do
+    report "hardcoded-token" "$f:$line hardcoded access_token/Bearer literal — use a refreshable credential (24h expiry)"
+  done < <(grep -niE 'access_token[[:space:]]*[:=][[:space:]]*["'"'"'][A-Za-z0-9._-]{12,}|Bearer[[:space:]]+[A-Za-z0-9._-]{20,}' "$f" 2>/dev/null \
+            | grep -viE 'os\.environ|process\.env|getenv|access_token\(\)|\{|\$|f"|`|<|your_|example|placeholder' | cut -d: -f1)
+
+  # Code-structure checks only meaningful in source files, not config/prose.
+  case "$f" in
+    *.py|*.js|*.ts|*.mjs) ;;
+    *) continue ;;
+  esac
+
+  # (3) FILE_UPLOAD publish path with no Content-Range chunked PUT and no status poll.
+  if grep -qsE 'post/publish/.*init/' "$f" 2>/dev/null && grep -qs 'FILE_UPLOAD' "$f" 2>/dev/null; then
+    if ! grep -qsE 'Content-Range' "$f" 2>/dev/null; then
+      ln=$(grep -nE 'FILE_UPLOAD' "$f" 2>/dev/null | head -1 | cut -d: -f1)
+      report "no-chunked-put" "$f:${ln:-1} FILE_UPLOAD init but no Content-Range chunked PUT (transfer step missing)"
+    fi
+    if ! grep -qsE 'status/fetch|publish_id' "$f" 2>/dev/null; then
+      ln=$(grep -nE 'FILE_UPLOAD' "$f" 2>/dev/null | head -1 | cut -d: -f1)
+      report "no-status-poll" "$f:${ln:-1} publish init but no status/fetch poll on publish_id (async result unconfirmed)"
+    fi
+  fi
+
+  # (4) Wrong-API assumption: reading watch-time/completion fields off the Display video/query response.
+  if grep -qsE 'video/query' "$f" 2>/dev/null; then
+    while IFS= read -r line; do
+      report "wrong-api" "$f:$line watch-time/completion field near Display video/query — those come from the Business API, not Display"
+    done < <(grep -nE 'average_time_watched|full_video_watched_rate|total_time_watched|impression_sources' "$f" 2>/dev/null | cut -d: -f1)
+  fi
+
+  # (5) Publish/status calls with no backoff/throttle helper around the 6/min cap.
+  if grep -qsE 'post/publish/.*(init|status/fetch)' "$f" 2>/dev/null; then
+    if ! grep -qsiE 'sleep|backoff|retry|throttle|rate.?limit|time\.sleep|setTimeout' "$f" 2>/dev/null; then
+      ln=$(grep -nE 'post/publish/' "$f" 2>/dev/null | head -1 | cut -d: -f1)
+      report "no-throttle" "$f:${ln:-1} publish/status calls with no sleep/backoff/throttle (6 req/min cap → rate_limit_exceeded)"
+    fi
+  fi
+done
+
+if [ "$hits" -gt 0 ]; then
+  echo "verify.sh: $hits issue(s) found" >&2
+  exit 1
+fi
+echo "OK: no banned TikTok-API patterns found in '$TARGET'"
+exit 0

package/skills/to-questionnaire/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: to-questionnaire
+description: "Turns a decision you cannot answer alone into a questionnaire for someone else to fill in."
+tags: ["planning", "questionnaire", "decision-making"]
+disable-model-invocation: true
+profiles: [core, ui, full]
+---
+
+Convierte algo que el usuario no puede responder solo en un **cuestionario**: un documento Markdown que entrega a una persona para rellenarlo de forma asíncrona, o para completarlo juntos en una reunión. El destinatario tiene un conocimiento que al usuario le falta; el cuestionario se lo extrae.
+
+**Interroga sobre el envío, no sobre el tema.** Pregunta al usuario solo sobre el *envío*, que siempre puede responder: a quién va dirigido y qué necesita a cambio. Las preguntas del documento apuntan entonces a la **brecha** entre lo que sabe el destinatario y lo que necesita el usuario.
+
+1. **¿A quién va dirigido?** Pregunta, en un solo intercambio, el rol, la experiencia y la relación del destinatario con el usuario. Esto fija el tono del cuestionario y cuánto contexto debe llevar. Terminado cuando sabes quién es el destinatario y qué sabe que el usuario no sabe.
+
+2. **¿Qué necesitas de vuelta?** Pregunta, en un solo intercambio, las decisiones o hechos concretos que el usuario no puede resolver solo y que necesita de esta persona. Terminado cuando tienes una lista concreta de lo que el usuario debe poder hacer o decidir al recibir las respuestas.
+
+3. **Escribe el cuestionario.** Redacta preguntas dirigidas a la brecha de los pasos 1-2, siguiendo la estructura de documento de abajo. Escríbelo en `to-questionnaire-<slug>.md` en el directorio actual (el slug sale del tema) e informa de la ruta. Terminado cuando el fichero existe y cada punto que el usuario nombró en el paso 2 está cubierto por una pregunta.
+
+## Estructura del documento
+
+Enmarca el documento como un **cuestionario de descubrimiento**: al usuario le falta contexto, el destinatario lo tiene. Ordena las preguntas de más a menos importante, ya que al ser asíncrono puede que solo tengas una pasada, y agrúpalas bajo encabezados `##` por tema en cuanto haya más de un puñado. Escríbelo con la plantilla de abajo.
+
+<plantilla-cuestionario>
+
+# <Título del cuestionario>
+
+**Propósito:** por qué existe este cuestionario y qué decisión depende de él.
+
+**De:** <el usuario>, **Para:** <el destinatario>, **Cómo se usarán tus respuestas:** <a dónde van>
+
+## Contexto
+
+Un párrafo que oriente a un destinatario que no estaba en la cabeza del usuario. Suficiente para responder bien, no una página.
+
+## Cómo responder
+
+Plazo y esfuerzo aproximado. Las respuestas parciales y los "no lo sé" son útiles: marca lo que no tengas claro en vez de saltártelo.
+
+## <Encabezado del tema>
+
+Una sección `##` por tema. Debajo, sus preguntas, de más a menos importante. Cada pregunta es una sola idea, nunca compuesta, con un hueco de respuesta justo debajo, y una línea de _por qué importa_ solo donde la pregunta se pueda malinterpretar o invite a una respuesta de relleno.
+
+<ejemplo-pregunta>
+### ¿Qué carga se espera que soporte el sistema en el lanzamiento?
+
+_Por qué importa: decide si aprovisionamos para picos de tráfico ahora o lo aplazamos._
+
+>
+</ejemplo-pregunta>
+
+## ¿Algo más?
+
+Un cierre general: ¿algo que no hayamos preguntado y deberíamos saber?
+
+</plantilla-cuestionario>

package/skills/to-questionnaire/evals/cases.yaml

@@ -0,0 +1,32 @@
+skill: to-questionnaire
+
+should_trigger:
+  - prompt: "No puedo responder esto solo, convierte la decision en un cuestionario para el equipo."
+    why: "Disparador directo de to-questionnaire."
+  - prompt: "Necesito que otra persona rellene un cuestionario sobre esta decision."
+    why: "Disparador directo de to-questionnaire."
+  - prompt: "Convierte estas preguntas abiertas en un cuestionario para enviar."
+    why: "Disparador directo de to-questionnaire."
+  - prompt: "Turn this open decision into a questionnaire someone else can fill in."
+    why: "Disparador directo de to-questionnaire."
+  - prompt: "Prepara un cuestionario para que el cliente decida esto."
+    why: "Disparador directo de to-questionnaire."
+
+should_not_trigger:
+  - prompt: "Responde tu mismo a esta pregunta con lo que ya sabes."
+    route_to: "none"
+    why: "Fuera del alcance de to-questionnaire."
+  - prompt: "Implementa la funcion que ya se decidio."
+    route_to: "implement"
+    why: "Implementar la funcion ya decidida es el trabajo de implement, no de to-questionnaire."
+  - prompt: "Escribe la spec de este proyecto."
+    route_to: "to-spec"
+    why: "Escribir la spec del proyecto es el trabajo de to-spec, no de to-questionnaire."
+  - prompt: "Haz una lista de tickets a partir del plan."
+    route_to: "to-tickets"
+    why: "Generar tickets a partir del plan es el trabajo de to-tickets, no de to-questionnaire."
+
+capability:
+  - scenario: "El usuario necesita delegar una decision a otra persona mediante un cuestionario."
+    must_include:
+      - "cuestionario"

package/skills/to-spec/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: to-spec
+description: "Turns the current conversation into a spec (PRD) and publishes it to the project's issue tracker — no interview, just a synthesis of what has already been discussed."
+tags: ["spec", "prd", "issue-tracker"]
+disable-model-invocation: true
+profiles: [core, ui, full]
+---
+
+
+# To Spec
+
+Esta skill toma el contexto de la conversación actual y el entendimiento del codebase y produce una spec (puede que conozcas este documento como PRD). NO entrevistes al usuario — solo sintetiza lo que ya sabes.
+
+El issue tracker y el vocabulario de etiquetas de triaje deberían haberte sido proporcionados. Si no hay tracker configurado, guarda la spec como archivo local (p. ej. `.scratch/<slug-de-la-feature>/spec.md`).
+
+## Proceso
+
+1. Explora el repo para entender el estado actual del codebase, si no lo has hecho ya. Usa el vocabulario del glosario de dominio del proyecto en toda la spec, y respeta los ADRs del área que tocas.
+
+2. Boceta las costuras (seams) por las que vas a testear la feature. Se prefieren las costuras existentes a las nuevas. Usa la costura más alta posible. Si hacen falta costuras nuevas, propónlas en el punto más alto que puedas. Cuantas menos costuras haya en el codebase, mejor — el número ideal es una.
+
+Confirma con el usuario que esas costuras coinciden con sus expectativas.
+
+3. Escribe la spec usando la plantilla de abajo y publícala en el issue tracker del proyecto. Aplica la etiqueta de triaje `ready-for-agent` — no hace falta más triaje.
+
+<plantilla-spec>
+
+## Planteamiento del problema
+
+El problema que enfrenta el usuario, desde la perspectiva del usuario.
+
+## Solución
+
+La solución al problema, desde la perspectiva del usuario.
+
+## Historias de usuario
+
+Una lista LARGA y numerada de historias de usuario. Cada historia de usuario debe seguir el formato:
+
+1. Como <actor>, quiero <feature>, para <beneficio>
+
+<ejemplo-historia-usuario>
+1. Como cliente de banca móvil, quiero ver el saldo de mis cuentas, para tomar decisiones mejor informadas sobre mi gasto
+</ejemplo-historia-usuario>
+
+Esta lista de historias de usuario debe ser extremadamente extensa y cubrir todos los aspectos de la feature.
+
+## Decisiones de implementación
+
+Una lista de las decisiones de implementación tomadas. Puede incluir:
+
+- Los módulos que se construirán/modificarán
+- Las interfaces de esos módulos que se modificarán
+- Aclaraciones técnicas del desarrollador
+- Decisiones arquitectónicas
+- Cambios de schema
+- Contratos de API
+- Interacciones concretas
+
+NO incluyas rutas de archivo concretas ni snippets de código. Pueden quedar obsoletos muy rápido.
+
+Excepción: si un prototipo produjo un snippet que codifica una decisión con más precisión que la prosa (máquina de estados, reducer, schema, forma de un tipo), inclúyelo dentro de la decisión correspondiente y anota brevemente que salió de un prototipo. Recórtalo a las partes ricas en decisión — no una demo funcional, solo lo importante.
+
+## Decisiones de testing
+
+Una lista de las decisiones de testing tomadas. Incluye:
+
+- Una descripción de qué hace bueno a un test (testear solo comportamiento externo, no detalles de implementación)
+- Qué módulos se testearán
+- Precedentes para los tests (es decir, tests de tipo similar ya existentes en el codebase)
+
+## Fuera de alcance
+
+Una descripción de lo que queda fuera del alcance de esta spec.
+
+## Notas adicionales
+
+Cualquier nota adicional sobre la feature.
+
+</plantilla-spec>

package/skills/to-spec/evals/cases.yaml

@@ -0,0 +1,32 @@
+skill: to-spec
+
+should_trigger:
+  - prompt: "Convierte esta conversacion en una spec y publicala en el tracker."
+    why: "Disparador directo de to-spec."
+  - prompt: "Necesito un PRD con lo que ya hemos discutido, sin entrevistarme de nuevo."
+    why: "Disparador directo de to-spec."
+  - prompt: "Sintetiza esta charla en una spec formal."
+    why: "Disparador directo de to-spec."
+  - prompt: "Turn this conversation into a spec and publish it to the issue tracker."
+    why: "Disparador directo de to-spec."
+  - prompt: "Escribe el PRD de lo que acabamos de acordar."
+    why: "Disparador directo de to-spec."
+
+should_not_trigger:
+  - prompt: "Entrevistame desde cero sobre una idea nueva."
+    route_to: "none"
+    why: "Fuera del alcance de to-spec."
+  - prompt: "Descompon esta spec en tickets."
+    route_to: "to-tickets"
+    why: "Romper una spec en tickets es el trabajo de to-tickets, no de to-spec."
+  - prompt: "Implementa el codigo de esta funcionalidad."
+    route_to: "implement"
+    why: "Implementar el codigo es el trabajo de implement, no de to-spec."
+  - prompt: "Interrogame sobre este plan."
+    route_to: "grilling"
+    why: "Interrogar un plan es el trabajo de grilling, no de to-spec."
+
+capability:
+  - scenario: "El usuario quiere convertir la conversacion en una spec publicada."
+    must_include:
+      - "spec"

package/skills/to-tickets/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: to-tickets
+description: "Breaks down a plan, a spec, or the current conversation into a set of \\"tracer bullet\\" tickets (vertical slices), each declaring which tickets block it, and publishes them to the configured tracker — as local files (one per ticket) or as issues with native blocking links in a real tracker."
+tags: ["tickets", "planning", "issue-tracker"]
+disable-model-invocation: true
+profiles: [core, ui, full]
+---
+
+
+# To Tickets
+
+Descompone un plan, una spec o una conversación en un conjunto de **tickets** — vertical slices tipo "bala trazadora" (tracer bullet), cada uno declarando los tickets que lo **bloquean**.
+
+El issue tracker y el vocabulario de etiquetas de triaje deberían haberte sido proporcionados. Si no hay tracker configurado, usa por defecto el modo de archivos locales descrito más abajo.
+
+## Proceso
+
+### 1. Reunir contexto
+
+Trabaja con lo que ya haya en el contexto de la conversación. Si el usuario pasa una referencia como argumento (ruta de una spec, número o URL de un issue), recupérala y lee su cuerpo completo y sus comentarios.
+
+### 2. Explorar el codebase (opcional)
+
+Si aún no has explorado el codebase, hazlo para entender el estado actual del código. Los títulos y descripciones de los tickets deben usar el vocabulario del glosario de dominio del proyecto y respetar los ADRs del área que tocas.
+
+Busca oportunidades de "prefactorizar" el código para facilitar la implementación. "Haz que el cambio sea fácil, y luego haz el cambio fácil."
+
+### 3. Bocetar los vertical slices
+
+Divide el trabajo en tickets **bala trazadora**.
+
+<reglas-vertical-slice>
+
+- Cada slice corta un camino estrecho pero COMPLETO a través de todas las capas (schema, API, UI, tests) — vertical, NO una rebanada horizontal de una sola capa
+- Un slice completado es demoable o verificable por sí solo
+- Cada slice está dimensionado para caber en una sola ventana de contexto fresca
+- Cualquier prefactorización debe hacerse primero
+
+</reglas-vertical-slice>
+
+Da a cada ticket sus **aristas de bloqueo** — los otros tickets que deben completarse antes de que pueda empezar. Un ticket sin bloqueadores puede empezar de inmediato.
+
+**Los refactors anchos son la excepción al vertical slicing.** Un **refactor ancho** es un único cambio mecánico — renombrar una columna, retipar un símbolo compartido — cuyo **radio de impacto** se extiende por todo el codebase, de modo que una sola edición rompe miles de call sites a la vez y ningún vertical slice puede aterrizar en verde. No lo fuerces a ser una bala trazadora; secuéncialo como **expand–contract**. Primero expande: añade la forma nueva junto a la vieja para que nada se rompa. Luego migra los call sites por lotes dimensionados según el radio de impacto (por paquete, por directorio), cada lote como su propio ticket bloqueado por el expand, manteniendo la CI en verde de lote en lote porque la forma vieja sigue existiendo. Finalmente contrae: borra la forma vieja cuando no quede ningún caller, en un ticket bloqueado por todos los lotes de migración. Cuando ni siquiera los lotes puedan mantenerse en verde por sí solos, conserva la secuencia pero deja que compartan una rama de integración que todos bloquean hacia un ticket final de integrar-y-verificar — el verde solo se promete allí.
+
+### 4. Interrogar al usuario
+
+Presenta la descomposición propuesta como una lista numerada. Para cada ticket, muestra:
+
+- **Título**: nombre corto y descriptivo
+- **Bloqueado por**: qué otros tickets (si los hay) deben completarse antes
+- **Qué entrega**: el comportamiento de extremo a extremo que este ticket hace funcionar
+
+Pregunta al usuario:
+
+- ¿La granularidad se siente correcta? (¿demasiado gruesa / demasiado fina?)
+- ¿Las aristas de bloqueo son correctas — cada ticket depende solo de tickets que genuinamente lo condicionan?
+- ¿Habría que fusionar algún ticket o dividirlo más?
+
+Itera hasta que el usuario apruebe la descomposición.
+
+### 5. Publicar los tickets en el tracker configurado
+
+Publica los tickets aprobados. El **cómo** depende del tracker configurado — los tickets son los mismos en ambos casos, solo cambia la forma de las aristas de bloqueo:
+
+- **Archivos locales** → escribe un archivo por ticket en `.scratch/<slug-de-la-feature>/issues/<NN>-<slug>.md`, numerados desde `01` en orden de dependencias (bloqueadores primero). El "Bloqueado por" de cada archivo lista los números/títulos de los que depende. Usa la plantilla de ticket-por-archivo de abajo — un ticket por archivo, nunca un único archivo combinado.
+- **Un issue tracker real (GitHub, Linear, …)** → publica un issue por ticket en orden de dependencias (bloqueadores primero) para que las aristas de bloqueo de cada ticket puedan referenciar identificadores reales. Usa la relación nativa de bloqueo / sub-issue de la plataforma si la tiene; si no, pon en el "Bloqueado por" de cada ticket los issues que lo bloquean. Aplica la etiqueta de triaje `ready-for-agent` salvo instrucción en contra — los tickets son agarrables por un agente por construcción.
+
+Trabaja la **frontera**: cualquier ticket cuyos bloqueadores estén todos hechos. Para una cadena puramente lineal, eso significa de arriba a abajo.
+
+NO cierres ni modifiques ningún issue padre.
+
+<plantilla-ticket-local>
+
+# <NN> — <Título del ticket>
+
+**Qué construir:** el comportamiento de extremo a extremo que este ticket hace funcionar, desde la perspectiva del usuario — no una lista de implementación capa por capa.
+
+**Bloqueado por:** los números/títulos de los tickets que condicionan este, o "Ninguno — puede empezar de inmediato".
+
+**Estado:** ready-for-agent
+
+- [ ] Criterio de aceptación 1
+- [ ] Criterio de aceptación 2
+
+</plantilla-ticket-local>
+
+<plantilla-issue>
+
+## Padre
+
+Una referencia al issue padre en el tracker (si el origen fue un issue existente; si no, omite esta sección).
+
+## Qué construir
+
+El comportamiento de extremo a extremo que este ticket hace funcionar, desde la perspectiva del usuario — no implementación capa por capa.
+
+## Criterios de aceptación
+
+- [ ] Criterio 1
+- [ ] Criterio 2
+
+## Bloqueado por
+
+- Una referencia a cada ticket que lo bloquea, o "Ninguno — puede empezar de inmediato".
+
+</plantilla-issue>
+
+En cualquiera de las dos formas, evita rutas de archivo concretas o snippets de código — se quedan obsoletos rápido. Excepción: si un prototipo produjo un snippet que codifica una decisión con más precisión que la prosa (máquina de estados, reducer, schema, forma de un tipo), inclúyelo y anota brevemente que salió de un prototipo. Recórtalo a las partes ricas en decisión — no una demo funcional, solo lo importante.

package/skills/to-tickets/evals/cases.yaml

@@ -0,0 +1,32 @@
+skill: to-tickets
+
+should_trigger:
+  - prompt: "Descompon este plan en tickets bala trazadora y publicalos."
+    why: "Disparador directo de to-tickets."
+  - prompt: "Convierte esta spec en un conjunto de tickets con bloqueos."
+    why: "Disparador directo de to-tickets."
+  - prompt: "Necesito tickets a partir de la conversacion actual."
+    why: "Disparador directo de to-tickets."
+  - prompt: "Break this spec down into tracer-bullet tickets in the tracker."
+    why: "Disparador directo de to-tickets."
+  - prompt: "Genera los tickets de este plan con sus dependencias."
+    why: "Disparador directo de to-tickets."
+
+should_not_trigger:
+  - prompt: "Escribe la spec original antes de descomponerla."
+    route_to: "to-spec"
+    why: "Escribir la spec original es el trabajo de to-spec, no de to-tickets."
+  - prompt: "Implementa uno de los tickets ya creados."
+    route_to: "implement"
+    why: "Implementar un ticket ya creado es el trabajo de implement, no de to-tickets."
+  - prompt: "Revisa el codigo de un ticket cerrado."
+    route_to: "code-review"
+    why: "Revisar el codigo de un ticket cerrado es el trabajo de code-review, no de to-tickets."
+  - prompt: "Interrogame sobre este plan antes de descomponerlo."
+    route_to: "grilling"
+    why: "Interrogar sobre el plan es el trabajo de grilling, no de to-tickets."
+
+capability:
+  - scenario: "El usuario quiere descomponer un plan en tickets publicados."
+    must_include:
+      - "ticket"