@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/speckit-checklist/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: speckit-checklist
+description: Build and run the quality gate for a feature plan before implementation. Use after speckit-plan and before speckit-tasks.
+license: MIT
+compatibility: Requires the Spec Kit layout under .specify/ and specs/.
+metadata:
+  author: onna
+  version: "1.0"
+---
+
+Decide whether the plan is safe to implement.
+
+**Input**: `spec.md`, `plan.md` and the project constitution.
+
+**Steps**
+
+1. Create `checklist.md` with one section per gate:
+   - `## Constitución` — every principle checked.
+   - `## Cobertura` — every requirement mapped to a component and test.
+   - `## Seguridad` — secrets, permissions, input validation, destructive operations.
+   - `## Compatibilidad` — platforms, data migration, rollback.
+   - `## Observabilidad` — logs, metrics and failure signals.
+2. Mark each item `PASS`, `FAIL` or `N/A` with one line of evidence.
+3. A single `FAIL` blocks implementation; return to `plan` or `specify`.
+
+**Artifacts**: `specs/<feature>/checklist.md`
+
+**Exit states**
+- `PASS` — no blocking findings.
+- `NEEDS_FIX` — at least one `FAIL`; name the artifact to revise.
+
+**Guardrails**
+- Do not mark `PASS` from intention; cite the plan or test that proves it.
+- Do not add new requirements in the checklist.
+- Never waive a security or data-loss finding without a human decision.

package/skills/shared/speckit-clarify/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: speckit-clarify
+description: Resolve ambiguities in an existing specification by asking targeted questions and encoding the answers. Use when speckit-specify left open questions or inconsistent requirements.
+license: MIT
+compatibility: Requires the Spec Kit layout under .specify/ and specs/.
+metadata:
+  author: onna
+  version: "1.0"
+---
+
+Turn ambiguity into a decision the implementation can follow.
+
+**Input**: `specs/<feature>/spec.md` with open questions or disputed requirements.
+
+**Steps**
+
+1. List every ambiguity as a question with the requirement it affects.
+2. Ask at most five questions per round, each answerable with a fact or a choice.
+3. For each answer, update the requirement and its scenario; do not append a parallel note.
+4. Record the decision and the discarded alternative in `## Decisiones`.
+5. Remove the resolved question from `## Preguntas abiertas`.
+
+**Artifacts**: `specs/<feature>/spec.md`
+
+**Exit states**
+- `RESOLVED` — no open questions remain and requirements are consistent.
+- `OPEN` — a question still needs a human decision; list the blocker.
+
+**Guardrails**
+- Do not answer a product question on the user's behalf.
+- Do not change scope silently while clarifying; surface any new behavior.
+- Every answer must land in the spec, not only in the conversation.

package/skills/shared/speckit-constitution/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: speckit-constitution
+description: Create or update the project constitution that every Spec Kit artifact must obey. Use before specifying a feature, or when the team ratifies a new non-negotiable rule.
+license: MIT
+compatibility: Requires the Spec Kit layout under .specify/.
+metadata:
+  author: onna
+  version: "1.0"
+---
+
+Establish the rules that outrank every feature decision.
+
+**Input**: the project's values, non-negotiables and any existing `.specify/memory/constitution.md`.
+
+**Steps**
+
+1. Read the current constitution and the repository conventions. Do not invent rules the team has not accepted.
+2. Write or update `.specify/memory/constitution.md`:
+   - `## Principios` — numbered, each with a one-line rationale.
+   - `## Restricciones técnicas` — stack, compatibility, security, data handling.
+   - `## Calidad` — test thresholds, review gates, definition of done.
+   - `## Gobierno` — who can change the constitution and how.
+3. Mark every principle as `MUST`, `MUST NOT` or `SHOULD`; avoid vague language.
+4. Record the version and the date of ratification.
+
+**Artifacts**: `.specify/memory/constitution.md`
+
+**Exit states**
+- `CREATED` — first constitution written.
+- `UPDATED` — existing constitution amended with a recorded reason.
+
+**Guardrails**
+- Never overwrite a ratified principle without an explicit human decision.
+- Do not encode feature-specific requirements here; those belong to `spec.md`.
+- A constitution change invalidates prior approvals bound to it.

package/skills/shared/speckit-converge/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: speckit-converge
+description: Verify that the implemented codebase satisfies every requirement before archiving the change. Use after speckit-implement reports DONE.
+license: MIT
+compatibility: Requires the Spec Kit layout under .specify/, specs/ and the project test commands.
+metadata:
+  author: onna
+  version: "1.0"
+---
+
+Close the loop between what was specified and what exists.
+
+**Input**: `spec.md`, `plan.md`, `tasks.md`, `analysis.md` and the implemented code.
+
+**Steps**
+
+1. Read every requirement and locate its implementation and test.
+2. Run the full verification commands from the plan and record the result.
+3. Write `convergence.md`:
+   - `## Requisito → evidencia` — table with requirement, code path, test.
+   - `## Tareas` — every task checked; list any unchecked.
+   - `## Deriva` — behavior implemented but not specified.
+   - `## Veredicto` — `CONVERGED` or `NEEDS_WORK` with the exact gap.
+4. If `NEEDS_WORK`, return to `implement` or `specify`; do not patch here.
+5. On `CONVERGED`, hand off to the human approval gate and then archive.
+
+**Artifacts**: `specs/<feature>/convergence.md`
+
+**Exit states**
+- `CONVERGED` — every requirement proven and every task complete.
+- `NEEDS_WORK` — a requirement lacks evidence or unspecced behavior exists.
+
+**Guardrails**
+- Never mark `CONVERGED` from a summary; cite code and test output.
+- Never delete or archive the feature while a task is open.
+- Do not rewrite the spec to match the implementation.

package/skills/shared/speckit-implement/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: speckit-implement
+description: Execute the approved task list in an isolated worktree and produce verified code. Use only after analysis passes and a human approved the spec hash.
+license: MIT
+compatibility: Requires the Spec Kit layout under .specify/, specs/ and a Git repository.
+metadata:
+  author: onna
+  version: "1.0"
+---
+
+Implement the tasks exactly as approved, with evidence.
+
+**Input**: `specs/<feature>/tasks.md`, `plan.md` and the approved SHA-256 of `spec.md + plan.md + tasks.md`.
+
+**Steps**
+
+1. Verify the approval hash still matches the three artifacts. If not, stop: the approval is invalid.
+2. Work in the assigned worktree or feature branch. Never implement on the trunk.
+3. For each task in order: make the smallest change, run its verification, and only then mark it `[x]`.
+4. Keep a trace in `.planning/impl_<feature>.md`: task, files, command, result.
+5. If a task needs scope beyond the spec, stop and return to `specify` or `plan`.
+
+**Artifacts**: source code, tests, `.planning/impl_<feature>.md` and updated `tasks.md`.
+
+**Exit states**
+- `DONE` — every task verified and the full suite is green.
+- `BLOCKED` — a task needs a design or scope decision; record why and stop.
+
+**Guardrails**
+- Never weaken a test to pass.
+- Never edit `spec.md`, `plan.md` or `tasks.md` to match what was built.
+- No `TODO`, placeholder or commented-out code.

package/skills/shared/speckit-plan/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: speckit-plan
+description: Produce the technical plan that implements an approved specification. Use after the spec is READY and before writing tasks.
+license: MIT
+compatibility: Requires the Spec Kit layout under .specify/ and specs/.
+metadata:
+  author: onna
+  version: "1.0"
+---
+
+Translate requirements into a design without changing them.
+
+**Input**: `specs/<feature>/spec.md` in state `READY` and the project constitution.
+
+**Steps**
+
+1. Read every requirement and scenario. Map each to a design element.
+2. Write `plan.md`:
+   - `## Contexto` — current behavior and constraints.
+   - `## Decisiones` — numbered, each with rationale and rejected alternatives.
+   - `## Componentes` — modules, responsibilities and data flow.
+   - `## Contratos` — APIs, schemas, events and error cases.
+   - `## Trazabilidad` — requirement id → component → test.
+   - `## Riesgos` — mitigation per risk.
+   - `## Migración` — rollout, rollback and compatibility.
+3. Verify every requirement has at least one component and one test.
+4. Keep the plan implementable in one change; split otherwise.
+
+**Artifacts**: `specs/<feature>/plan.md`
+
+**Exit states**
+- `READY` — every requirement is covered and no design decision is open.
+
+**Guardrails**
+- Never add a requirement that the spec does not contain.
+- Do not write task lists here; `tasks.md` owns sequencing.
+- Name the trade-off of every significant decision.

package/skills/shared/speckit-specify/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: speckit-specify
+description: Write the behavioral specification of a feature with EARS requirements and testable scenarios. Use after the constitution and before planning.
+license: MIT
+compatibility: Requires the Spec Kit layout under .specify/ and specs/.
+metadata:
+  author: onna
+  version: "1.0"
+---
+
+Describe what the system must do, not how it will do it.
+
+**Input**: the approved assessment or feature request and the project constitution.
+
+**Steps**
+
+1. Choose a kebab-case feature id and create `specs/<feature>/`.
+2. Write `spec.md`:
+   - `## Purpose` — one paragraph, user-visible outcome.
+   - `## Requisitos` — EARS statements using `MUST`, `MUST NOT`, `WHEN`, `IF`.
+   - `## Escenarios` — one block per requirement with exactly `#### Scenario:` and WHEN/THEN.
+   - `## Fuera de alcance` — what this feature deliberately excludes.
+   - `## Preguntas abiertas` — numbered; none may remain before approval.
+3. Give every requirement at least one scenario and a stable identifier (`R1`, `R2`, ...).
+4. Keep each requirement to one behavior; split compound requirements.
+
+**Artifacts**: `specs/<feature>/spec.md`
+
+**Exit states**
+- `DRAFT` — requirements exist but open questions remain.
+- `READY` — no open questions and every requirement has a scenario.
+
+**Guardrails**
+- No architecture, library choices or file paths in `spec.md`.
+- Never mark `READY` with an untestable requirement.
+- Do not modify the constitution from this skill.

package/skills/shared/speckit-tasks/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: speckit-tasks
+description: Break an approved plan into atomic, ordered, verifiable implementation tasks. Use after the checklist passes.
+license: MIT
+compatibility: Requires the Spec Kit layout under .specify/ and specs/.
+metadata:
+  author: onna
+  version: "1.0"
+---
+
+Produce the executable sequence the implementers will follow.
+
+**Input**: `spec.md`, `plan.md` and `checklist.md` in state `PASS`.
+
+**Steps**
+
+1. Create `tasks.md` grouped by phase (foundation, core, integration, release).
+2. Each task MUST be one checkbox with:
+   - a concrete action,
+   - the files or modules it touches,
+   - an explicit verification criterion.
+3. Order tasks by dependency; a task may only depend on earlier tasks.
+4. Map every requirement to at least one task; add a traceability table.
+5. Estimate nothing; split any task that cannot be verified in one run.
+
+**Artifacts**: `specs/<feature>/tasks.md`
+
+**Exit states**
+- `READY` — every task has a verification criterion and every requirement is covered.
+
+**Guardrails**
+- No `TODO`, "investigar" or unverifiable tasks.
+- Do not include implementation code in the task list.
+- Do not mark a task complete from this skill.

package/skills/shared/spreadsheet-ops/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: spreadsheet-ops
+description: "Use when working a spreadsheet programmatically — writing or repairing a formula, generating an .xlsx with Python including charts and conditional formats, driving Google Sheets from a script, building a read-transform-write pipeline, or writing an in-sheet macro or trigger. Covers formula errors, Sheets API quota, service-account permissions, and formulas that read back blank. NOT pure dedupe or normalisation with no sheet output (that is `data-cleaning`), NOT scraping a web table into rows (that is `data-scraper`), NOT multi-app event wiring (that is `automation-flows`)."
+tags: [spreadsheet, excel, google-sheets, openpyxl, gspread, apps-script, formulas, automation]
+recommends: [data-cleaning, data-scraper, automation-flows, google-workspace, reporting, duckdb, document-processing]
+origin: ai-hub
+---
+
+# spreadsheet-ops — the spreadsheet as a programmable surface
+
+A spreadsheet is a runtime, not a document. Your job is to emit a **checkable artifact** — a `.xlsx`
+file that opens, a script that compiles, a cell range you can re-read — never a hand-waved formula in
+prose. Pick the tool that matches the runtime (local file vs cloud sheet, one-shot vs event-driven),
+write the formula with comma arguments, and verify before you claim it works.
+
+The trap that bites everyone first: **openpyxl writes formulas but does not compute them.** The string
+is stored; Excel evaluates it on open. If you read the cell back with Python it is `None` until a real
+Excel/LibreOffice session has saved it. Internalize that before you touch a workbook.
+
+## Pick the tool first (this branches, so decide before coding)
+
+| Your situation | Reach for | Why |
+| --- | --- | --- |
+| Read **and** modify an existing local `.xlsx` | **openpyxl** | Only mainstream lib that round-trips an existing file. |
+| Write a new `.xlsx` rich with charts/conditional formats, possibly large | **xlsxwriter** (via pandas `ExcelWriter`) | Write-only but the richest formatting + low-memory `constant_memory` mode. |
+| Dump a DataFrame to a sheet, minimal fuss | **pandas** `df.to_excel(...)` | Wraps an engine; pass `engine=` explicitly so the result does not depend on what is installed. |
+| Read/write a cloud Google Sheet from a script | **gspread** (+ `gspread-formatting` for colors/rules) | Friendly wrapper over the Sheets API for CRUD. |
+| High-volume cloud writes, must beat quotas | **Sheets API v4** `batchUpdate` | One batched call counts as one request — survives the per-minute limit. |
+| In-sheet menus, time-driven triggers, custom functions | **Apps Script (V8)** | Runs inside the sheet; the only place for `onEdit`/menus. |
+
+Two you will confuse: **xlsxwriter cannot open an existing file** — if you need to edit one in place,
+that is openpyxl. And gspread vs the raw Sheets API is convenience vs throughput: reach for raw
+`batchUpdate` only when gspread's per-call writes would blow the quota.
+
+Versions seen on PyPI when this was written (2026-06-02): openpyxl **3.1.5**, gspread **6.2.1**
+(Python 3.8+), gspread-formatting **1.2.1**, pandas on the **3.x** line, Sheets API **v4**, Apps
+Script on the **V8** runtime. Treat these as a floor, re-check PyPI before pinning, and pin whatever
+you actually resolve — do not copy a point release from a doc as gospel.
+
+## Formula rules (each rule, one reason)
+
+1. **Arguments are comma-separated, always — never semicolons.** openpyxl and the file format use
+   commas regardless of your machine's locale; a semicolon is the single most common "my written
+   formula is broken" cause. Bad: `=SUM(A1;A2)` → Good: `=SUM(A1,A2)`.
+2. **A formula string must start with `=`.** `ws["A1"] = "SUM(1,1)"` stores literal text; `ws["A1"] =
+   "=SUM(1,1)"` stores a formula. No leading `=` means no calculation, ever.
+3. **Anchor references you intend to fill.** A lookup table dragged down breaks unless absolute: Bad:
+   `=VLOOKUP(A2,Sheet2!A:B,2,0)` → Good: `=XLOOKUP(A2,Sheet2!$A:$A,Sheet2!$B:$B)`.
+4. **Prefer XLOOKUP over VLOOKUP** — exact match by default, no magic column index to miscount, works
+   leftward. VLOOKUP's 4th arg silently defaulting to approximate match is a classic wrong-result bug.
+5. **Prefer dynamic arrays over Ctrl+Shift+Enter array formulas** — `=FILTER(...)`, `=SORT(...)`,
+   `=UNIQUE(...)` spill automatically and are readable. A spill blocked by data below it raises
+   `#SPILL!`; clear the range, do not array-enter.
+6. **Never deep-nest IFs.** Past two levels use `LET` (name sub-expressions once) or a helper column.
+   Bad: `=IF(A1>90,"A",IF(A1>80,"B",IF(A1>70,"C","D")))` → Good: a lookup table + `XLOOKUP`, or
+   `=LET(g,A1, IF(g>90,"A", IF(g>80,"B","C")))` kept shallow.
+
+When generating cross-sheet formulas, `SHEET()` returns a sheet's index and `SHEETS()` returns the
+sheet count — both have shipped in Excel for years (SHEET/SHEETS since Excel 2013) and exist in Google
+Sheets, so they are safe to emit. Full XLOOKUP/SUMIFS/LET patterns and the `#VALUE!/#REF!/#N/A/#NAME?`
+error decoder live in [`references/formula-cookbook.md`](references/formula-cookbook.md).
+
+## Python → Excel
+
+The no-compute trap, stated as code:
+
+```python
+from openpyxl import load_workbook
+wb = load_workbook("report.xlsx")
+ws = wb.active
+ws["C2"] = "=A2*B2"          # stores the FORMULA string, not a number
+wb.save("report.xlsx")
+# Re-reading C2 now returns "=A2*B2" (the formula), or with data_only=True
+# returns None — because no Excel has opened+saved the file to cache a value.
+back = load_workbook("report.xlsx", data_only=True)
+assert back.active["C2"].value is None   # last cached value: none yet
+```
+
+So: if a downstream step needs the computed number, either compute it in Python and write the value, or
+open the file once in Excel/LibreOffice headless to populate the cache. Do not assume openpyxl evaluated it.
+
+Append a sheet to an existing file (the only mode that does not silently truncate):
+
+```python
+import pandas as pd
+with pd.ExcelWriter("report.xlsx", engine="openpyxl", mode="a",
+                    if_sheet_exists="replace") as xl:
+    df.to_excel(xl, sheet_name="2026-Q2", index=False)
+```
+
+Charts and conditional formatting on a new file go through **xlsxwriter** (richer) — it is write-only,
+so never point it at a file you need to keep. Recipes (chart, conditional format, `write_only`/
+`constant_memory` for big files) are in [`references/python-excel.md`](references/python-excel.md).
+
+## Google Sheets from a script
+
+```python
+import gspread
+gc = gspread.service_account(filename="bot-key.json")  # service account
+sh = gc.open_by_key("SPREADSHEET_ID")
+ws = sh.worksheet("Orders")
+ws.append_rows([["2026-06-02", "INV-1001", 240.00]],
+               value_input_option="USER_ENTERED")      # parses formulas/dates
+```
+
+The failure that wastes the most time: **a service account has zero access until the sheet is shared
+with its email.** Open the key JSON, copy `client_email`, and share the sheet with it (Editor) — a
+`PermissionError`/`SpreadsheetNotFound` here is almost always an unshared sheet, not bad code.
+
+Quotas (as published 2026-06-02 — re-check Google's "Usage limits" page, these shift): **300 read
+req/min/project, 60 read req/min/user** (writes mirror this), refilled each minute, no daily cap under
+the per-minute ceiling. A `batchUpdate` — with all its sub-requests inside — counts as **one** request.
+So batch: build one `batchUpdate` body instead of N `update` calls, and wrap calls in exponential
+backoff on HTTP 429. Batching is the difference between a nightly job that survives and one that 429s.
+
+Creating the OAuth client or service account itself is [`google-workspace`](../google-workspace/SKILL.md)'s
+job; this skill assumes the credential exists and owns the Sheets surface. `batchUpdate` request shapes
+and backoff code are in [`references/sheets-api-appsscript.md`](references/sheets-api-appsscript.md).
+
+## In-sheet automation (Apps Script V8)
+
+Write for **V8** — Google deprecated the legacy Rhino runtime (Feb 2025) and set its retirement for on
+or after 2026-01-31, so new code should never target it. V8 has **no `fetch`, no timers, no streams**
+— use `UrlFetchApp.fetch()` (or `fetchAll()` for parallel) for HTTP. No ES6 `import/export`, no private
+`#fields`.
+
+Read and write the sheet in **one** range operation, never a per-cell loop — `getValue()`/`setValue()`
+inside a loop makes one API round-trip per cell and times out on real data:
+
+```javascript
+function colorOverdue() {
+  const sh = SpreadsheetApp.getActiveSheet();
+  const data = sh.getDataRange().getValues();   // ONE read, all rows
+  const out = data.map(r => r[3] === "OVERDUE" ? ["#fde0e0"] : ["#ffffff"]);
+  sh.getRange(1, 1, out.length, 1).setBackgrounds(out.map(c => c)); // ONE write
+}
+```
+
+Time-driven triggers (run nightly), `onEdit` simple triggers, and custom menus are covered in
+[`references/sheets-api-appsscript.md`](references/sheets-api-appsscript.md).
+
+## Pipeline pattern: read → transform → write
+
+A pipeline that reruns must not duplicate rows. Decide the write mode first:
+
+1. **Define a header contract** — the exact columns and order. Assert the live header matches before
+   writing; a shifted column silently corrupts everything downstream.
+2. **Choose the write mode:**
+   - *Full overwrite* — clear the data range, write all rows. Simple, safe when the sheet is yours alone.
+   - *Keyed upsert* — read existing keys (e.g. `order_id`) into a map, update matched rows, append the
+     rest. Idempotent: rerunning yields the same sheet, no duplicates.
+3. **Dry-run first.** Compute the diff (rows to add/update) and log it; only write when a `--apply` flag
+   is set. This catches a wrong key or a header drift before it touches the live sheet.
+4. **Batch the write** (`batchUpdate` / `setValues`) and back off on 429.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+| --- | --- | --- |
+| Semicolon arguments `=SUM(A1;A2)` | File format is comma-only; locale display fools you | Always commas `=SUM(A1,A2)` |
+| Formula string without leading `=` | Stored as literal text, never calculates | Start the string with `=` |
+| Assuming openpyxl computed the result | It only stores the formula; value is `None` until Excel opens it | Write the value, or open once to cache |
+| Per-cell `getValue()`/`setValue()` loop (Apps Script) | One round-trip per cell → timeout | `getValues()`/`setValues()` once per range |
+| N single `update` calls to the Sheets API | Blows 60/user-min, 300/project-min quota | One `batchUpdate`; backoff on 429 |
+| Service account not shared with the sheet | `PermissionError`, looks like a code bug | Share the sheet with `client_email` from the key |
+| Deep-nested `IF` chains | Unreadable, miscounted parens, hard to repair | `LET`, a lookup table, or a helper column |
+| xlsxwriter to modify an existing file | It is write-only; you lose the original | openpyxl for read+modify |
+| `df.to_excel("f.xlsx")` over an existing file | Default mode truncates the whole workbook | `ExcelWriter(..., mode="a")` to append |
+| VLOOKUP with a hardcoded column index | Index miscounts when columns move; approximate-match default | `XLOOKUP` with explicit ranges |
+
+## Verify
+
+Run `scripts/verify.sh` (read-only by default; pass a path to a generated `.py`/`.xlsx`). It
+`py_compile`s generated scripts, opens produced workbooks with openpyxl to confirm a sheet + header row,
+and lints formula strings for the semicolon-argument bug. Cloud paths are validated by structure, not
+live Google calls — no network or credentials required. On an empty/clean target it exits 0.
+
+References: [`python-excel.md`](references/python-excel.md) ·
+[`sheets-api-appsscript.md`](references/sheets-api-appsscript.md) ·
+[`formula-cookbook.md`](references/formula-cookbook.md).

package/skills/shared/spreadsheet-ops/evals/README.md

@@ -0,0 +1,33 @@
+# Eval harness — `spreadsheet-ops`
+
+Two things are graded: **triggering** (does the skill fire on real spreadsheet work and stay quiet on
+near-misses that belong to a sibling?) and **capability** (does loading the skill make the produced
+script measurably better?). Cases are in `cases.yaml`. They are graded by a human or a driver agent
+feeding prompts to a fresh session — not an automated runner. The executable check is
+`scripts/verify.sh`, which smoke-tests that generated artifacts actually compile/open and that formulas
+use comma arguments; the eval cases here grade judgment, not code.
+
+## Triggering
+
+For each prompt, start a fresh agent with only `spreadsheet-ops` discoverable, paste the prompt
+verbatim, and observe whether the agent reaches for this skill. Run 3–5 trials (the decision is
+stochastic). `should_trigger` passes if the skill fires in the majority of trials. `should_not_trigger`
+passes if it does **not** fire; each names a `route_to` sibling (`data-cleaning`, `data-scraper`,
+`automation-flows`, `google-workspace`, `reporting`) — sanity-check the agent would plausibly route
+there, though any not-this-skill route still passes the gate. Some routed siblings may not be built in
+this collection yet; the routing intent is what's graded. Pass bar: ≥ 90% trigger accuracy across cases.
+
+## Capability
+
+Run the scenario twice — WITHOUT the skill (clean agent) and WITH it — and grade each transcript against
+the `must_include` checklist, one point per bullet that is specifically and correctly covered (not just
+name-dropped). WITH the skill should cover ≥ 80% of bullets and clearly beat WITHOUT (target ≥ +30
+points or crossing fail→pass). If the script the WITH-skill agent emits is real, run it through
+`scripts/verify.sh` to confirm the comma-args and compile bullets objectively.
+
+## Notes
+
+Prompts are deliberately varied: several never say "spreadsheet" (the #VALUE! SUMIFS repair, the blank
+openpyxl cell, the service-account PermissionError), and one is in Spanish — these test intent over
+keywords. Record trial counts and per-bullet verdicts so a reviewer can audit; don't report a bare
+pass/fail.

package/skills/shared/spreadsheet-ops/evals/cases.yaml

@@ -0,0 +1,42 @@
+skill: spreadsheet-ops
+
+should_trigger:
+  - prompt: "Write a Python script that exports this DataFrame to an .xlsx with a column chart and conditional formatting on overdue rows."
+    why: "Core Python→Excel artifact generation with charts + conditional formats — the xlsxwriter/pandas path."
+  - prompt: "My SUMIFS keeps returning #VALUE! and I can't see why. Here's the formula."
+    why: "Symptom-led formula repair; the user names the error, not the skill. Mismatched range shapes is the classic cause."
+  - prompt: "Every night my job needs to append a few rows to a Google Sheet. What's the right way to do it from Python?"
+    why: "Cloud read→write pipeline via gspread/Sheets API, including append + quota awareness."
+  - prompt: "I set a formula with openpyxl and saved, but when I read the cell back it's blank. What's wrong?"
+    why: "Non-obvious no-compute trap: openpyxl stores the formula; data_only returns None until Excel opens the file."
+  - prompt: "Haz una macro de Google Sheets que coloree las filas según el estado de cada pedido."
+    why: "Spanish + in-sheet automation → Apps Script V8, batched setBackgrounds. Tests language + intent."
+  - prompt: "My service account gets PermissionError / SpreadsheetNotFound when it tries to open the sheet, but the key is valid."
+    why: "Non-obvious share trap — a service account has no access until the sheet is shared with its client_email."
+
+should_not_trigger:
+  - prompt: "These columns have mixed date formats and duplicate rows — clean and normalize them, no spreadsheet output needed."
+    route_to: data-cleaning
+    why: "Pure data hygiene with no spreadsheet artifact is data-cleaning's job."
+  - prompt: "Scrape this HTML pricing table from a webpage into structured rows."
+    route_to: data-scraper
+    why: "Extracting structured data from a web table is data-scraper, not spreadsheet authoring."
+  - prompt: "When a Typeform is submitted, post to Slack and add a row to a Sheet — wire the whole flow."
+    route_to: automation-flows
+    why: "Multi-app event chaining (Zapier/Make/n8n style) is automation-flows; spreadsheet-ops only owns the sheet step."
+  - prompt: "Set up OAuth and Drive access for my Google account so my app can authenticate."
+    route_to: google-workspace
+    why: "Credential/OAuth/Drive setup is google-workspace; this skill consumes the credential, it doesn't create it."
+  - prompt: "Build the recurring weekly stakeholder report deliverable for the leadership team."
+    route_to: reporting
+    why: "A finished recurring report deliverable is reporting; spreadsheet-ops stops at the programmable sheet."
+
+capability:
+  - scenario: "Given a CSV of orders (order_id, customer, amount, status, due_date), produce a runnable Python script that writes an orders.xlsx with a header row, a SUMIFS total of amounts where status is OPEN, conditional formatting highlighting OVERDUE rows, and an idempotent keyed upsert by order_id so rerunning does not duplicate rows."
+    must_include:
+      - "Formula arguments are comma-separated, never semicolons (=SUMIFS(...,...,...) with commas)"
+      - "Any formula string written into a cell starts with a leading '=' "
+      - "States/handles that openpyxl stores the formula and does NOT compute it (value None / data_only caveat), or writes computed values"
+      - "Chart and/or conditional formatting via the correct engine (xlsxwriter for a new rich file, or openpyxl rules), not hand-waved"
+      - "Idempotent upsert keyed by order_id — reads existing keys, updates matches, appends the rest; no duplicate rows on rerun"
+      - "Script is runnable: passes python -m py_compile (valid syntax, real imports)"

package/skills/shared/spreadsheet-ops/references/formula-cookbook.md

@@ -0,0 +1,70 @@
+# Formula cookbook
+
+Rule one, repeated because it causes the most broken formulas: **arguments are comma-separated, never
+semicolons** — the file format is comma-only regardless of your locale's display separator.
+
+## Lookups
+
+```text
+# Exact match, no column-index counting, works leftward:
+=XLOOKUP(A2, Sheet2!$A:$A, Sheet2!$B:$B, "not found")
+
+# Multi-criteria with FILTER (dynamic array):
+=FILTER(Orders!B:B, (Orders!A:A=A2)*(Orders!C:C="PAID"))
+
+# Avoid: VLOOKUP with a hardcoded index and approximate-match default
+# Bad:  =VLOOKUP(A2, Sheet2!A:B, 2)        ' 4th arg defaults to TRUE → wrong row
+# Good: =VLOOKUP(A2, Sheet2!$A:$B, 2, FALSE)  ' or just use XLOOKUP
+```
+
+## Conditional sums
+
+```text
+# Sum amount where region=EU AND status=OPEN:
+=SUMIFS(amount, region, "EU", status, "OPEN")
+
+# Common #VALUE! cause: the sum range and a criteria range are different sizes.
+# Bad:  =SUMIFS(B2:B100, C2:C50, "EU")     ' mismatched lengths → #VALUE!
+# Good: =SUMIFS(B2:B100, C2:C100, "EU")    ' all ranges identical shape
+```
+
+## Readability: LET and helper columns
+
+```text
+# Name a sub-expression once instead of recomputing it:
+=LET(rate, VLOOKUP(A2, Rates!$A:$B, 2, FALSE),
+     net,  B2 * (1 - rate),
+     ROUND(net, 2))
+
+# Replace a deep IF chain (Bad) with a lookup table + XLOOKUP (Good):
+# Bad:  =IF(A1>90,"A",IF(A1>80,"B",IF(A1>70,"C","D")))
+# Good: =XLOOKUP(A1, Bands!$A:$A, Bands!$B:$B, "F", -1)  ' -1 = exact-or-next-smaller
+```
+
+## Dynamic arrays
+
+```text
+=SORT(UNIQUE(FILTER(A2:A100, B2:B100<>"")))   ' spills automatically
+```
+A spill blocked by data in its target range raises `#SPILL!` — clear the cells below; do not
+Ctrl+Shift+Enter.
+
+## Error decoder
+
+| Error | Means | Usual fix |
+| --- | --- | --- |
+| `#VALUE!` | A wrong argument type, or mismatched range sizes in SUMIFS/array math | Make all ranges the same shape; coerce text-numbers with `VALUE()` |
+| `#REF!` | A reference no longer exists (deleted row/column/sheet) | Repoint the reference; check after structural edits |
+| `#N/A` | Lookup found nothing | Add the 4th arg / `if_not_found`: `XLOOKUP(...,"")` |
+| `#SPILL!` | A dynamic array cannot spill — something blocks the range | Clear the blocking cells below/right |
+| `#NAME?` | Unknown function or name — often a typo or a locale/semicolon artifact | Fix the name; switch semicolons to commas |
+| `#DIV/0!` | Division by zero/empty | Guard: `=IFERROR(a/b, 0)` or `=IF(b=0,0,a/b)` |
+| `#NUM!` | Invalid numeric argument (e.g. negative sqrt) | Validate the input range |
+
+## Cross-sheet helpers (long-standing — Excel since 2013, also in Google Sheets)
+
+```text
+=SHEET()          ' index of the current sheet
+=SHEET("Q2")      ' index of a named sheet
+=SHEETS()         ' count of sheets in the workbook
+```