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

package/skills/shared/tasks/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: tasks
+description: "Use when an approved plan needs slicing into an ordered task list before any code — the SDD `tasks` phase. Each row carries a literal done-check, dependencies, a parallel-safe marker and a spec trace, appended to the plan artifact. NOT writing the plan (that is `plan`), NOT the consistency gate (that is `analyze`), NOT executing the tasks (that is `implement`)."
+tags: [sdd, tasks, breakdown]
+recommends: [analyze, implement]
+profiles: [core, full]
+origin: ai-hub
+---
+
+# Tasks — turn an approved plan into a verifiable work list
+
+The `tasks` phase is the hinge between *thinking* and *doing*. The plan already
+decided the architecture, the interfaces, and the testing strategy. This phase
+slices that plan into the **smallest units a coding agent can finish, prove, and
+hand off** — each one ordered, each one carrying a *done-check* that a machine or
+a reviewer can run without trusting anyone's word.
+
+A task list is not a to-do list. A to-do list says "build the auth endpoint". A
+task list says "T004: implement `POST /login`; done when `pytest
+tests/auth/test_login.py` is green AND a 401 is returned for a bad password —
+depends on T002, T003; parallel-safe with T005." The difference is that the
+second one can be **handed to a subagent, executed, and verified** with no
+further questions. This phase writes zero runtime code; it produces one artifact,
+appended to the plan it was built from.
+
+## Model tier — `balanced` (opt-in routing)
+
+This phase's default tier is **`balanced`**: decomposing an approved plan is
+structured work, not architecture. Routing is off unless `models.enabled: true`
+in `02-DOCS/wiki/sdd/config.yaml`; when on, resolve the tier and apply it per
+`../sdd/references/model-routing.md`, which owns the resolution order and the
+announcement rules. Routing off or no profile → honor the session model silently.
+
+## Read the harness profile first
+
+Read `02-DOCS/wiki/harness/user-profile.md` before producing anything: its
+`technical_level` sets the register (technical terms, or plain words with
+analogies). The task table is always complete. In chat, speak in the `orient`
+voice: one line of *why this slicing*, then flag the risky tasks. No profile →
+use analogies and ask once "technical or with analogies?"; never invent one.
+
+## Inputs (refuse to start without them)
+
+You break down a **plan**, not an intent. Before slicing, confirm all three exist:
+
+1. **The plan** — `02-DOCS/wiki/sdd/plans/<slug>.md`, written by the `plan`
+   phase. It must contain the architecture, interfaces, and testing strategy.
+2. **The spec** — `02-DOCS/wiki/sdd/specs/<slug>.md`, so every task traces to a
+   requirement. A task with no spec line behind it is scope you are inventing.
+3. **The constitution** — `02-DOCS/wiki/sdd/constitution.md`, the non-negotiable
+   bars (stack canon, quality gates) every task must respect.
+4. **The SDD config** — `02-DOCS/wiki/sdd/config.yaml`, if present. Use its
+   `review_budget`, `delivery_strategy` and `testing.commands` when writing
+   done-checks and review forecasts. If it is missing on non-trivial work,
+   recommend `sdd-init`.
+
+If the plan is missing, **stop and route to `plan`**. If the plan exists but is
+vague on interfaces or testing, route back to `plan` to tighten it — do not
+paper over a thin plan with guesswork in the task list. That guesswork is the
+exact thing `analyze` will catch next, and you will have wasted the round trip.
+
+## What makes a task well-formed
+
+Every task is one row. A row is well-formed only when all six fields hold:
+
+| Field | Rule |
+| --- | --- |
+| **ID** | `T001`, `T002`, … — sequential, zero-padded, no hyphen (GitHub Spec Kit canon). Stable, never renumbered once written (downstream phases cite it). |
+| **[P]** | A **separate field after the ID**: `[P]` if the task is parallel-safe, blank otherwise. Never fold the marker into the ID. |
+| **Title** | One imperative verb + object. "Implement", "Add", "Wire", "Migrate" — not "Handle" or "Support". |
+| **Done-check** | The **literal** command or observation that proves done. Runnable, not a feeling. See below. |
+| **Depends-on** | The task IDs that must finish first, or `—` for none. Drives the ordering and the parallel markers. |
+| **Trace** | The spec section / acceptance criterion this task satisfies. Every task traces to one; if it can't, it's out of scope. |
+
+Put `[P]` (parallel-safe) in its own field only when the task shares **no files
+and no state** with another unblocked task. When in doubt, leave it blank — a
+false `[P]` causes the merge collisions `parallel` exists to prevent.
+
+## The done-check is the whole point
+
+A done-check has to be **executable evidence**, owned by the stack, not a
+self-graded claim. Delegate the *form* of the check to the relevant stack skill
+and quote the actual command:
+
+- Backend (Python/FastAPI) → a `pytest` invocation; route to `../fastapi/SKILL.md`.
+- Go services → a `go test ./...` target; route to `../go/SKILL.md`.
+- Frontend (Next.js) → a component/e2e test or a typed build; route to `../nextjs/SKILL.md`.
+- Flutter → a `flutter test` target; route to `../flutter/SKILL.md`.
+- Schema/migrations → a migration applies + a query returns expected rows; route to `../postgresdb/SKILL.md`.
+
+```text
+WEAK   done-check: "login works"
+STRONG done-check: pytest tests/auth/test_login.py::test_bad_password_returns_401  → green
+                   AND manual: POST /login {wrong pw} returns 401, no token in body
+```
+
+A done-check you cannot run is not a done-check. If the plan's testing strategy
+doesn't support a runnable check for a slice, that is a **plan gap** — name it
+and send it back, don't write a vague check to keep moving.
+
+## TDD-shaped slicing (default)
+
+The `implement` phase runs red → green → refactor. Slice so it can. For each
+behavioral unit, the natural shape is a test-first pair the implementer executes
+in order:
+
+1. **Txxx (test):** write the failing test for the behavior. *Done when the test
+   exists and fails for the right reason.*
+2. **Txxx+1 (impl):** implement until that test is green. *Done when the test
+   passes and nothing else regresses.*
+
+You don't have to split every task in two, but the done-check of an
+implementation task should always be *a test that was red and is now green*. This
+is where `tasks` and `implement` shake hands: the list you write is the list TDD
+will execute.
+
+## The slicing procedure
+
+```text
+1. WALK the plan top to bottom. List every concrete deliverable
+   (endpoint, model, migration, component, job, config).
+2. For each deliverable, ask: smallest slice that produces a runnable
+   done-check? Split until each task is verifiable on its own.
+3. ORDER by dependency. Foundations first: schema → data layer →
+   service → API → UI. A task never precedes what it depends on.
+4. MARK [P] only on tasks that share no files/state with another
+   unblocked task. Default to sequential.
+5. TRACE each task back to a spec line. No trace → cut it (scope creep)
+   or send the gap to `clarify`/`specify`.
+6. ADD the cross-cutting closers: a final "all done-checks pass" task
+   and a "verify.sh green" task that hands off to `verify`.
+7. ADD a review workload + delivery forecast before implementation.
+8. APPEND the table to the plan artifact (see below). Do not start a
+   new file; the list lives with the plan it came from.
+```
+
+## Where the artifact lives
+
+The task list is **not** a new document. Append it to the existing plan under a
+`## Tasks` heading:
+
+```text
+02-DOCS/wiki/sdd/plans/<slug>.md
+  ├─ ## Architecture        (from plan)
+  ├─ ## Interfaces          (from plan)
+  ├─ ## Testing strategy    (from plan)
+  └─ ## Tasks               ← you append this
+       T001 … T0NN as the table below, + a one-line "generated by tasks on <date>"
+```
+
+Then ensure the plan is indexed in `02-DOCS/wiki/index.md` (the Knowledge map;
+root `CLAUDE.md` keeps only a short pointer) under the `sdd/` topic — the `plan`
+phase usually added the row, so confirm it points at
+`02-DOCS/wiki/sdd/plans/<slug>.md` and add it if missing. Additive only: never
+delete a user's map entry.
+
+### The table format
+
+```markdown
+## Tasks
+<!-- generated by tasks on 2026-06-01; IDs are stable, do not renumber -->
+
+| ID | [P] | Task | Done-check | Depends-on | Trace |
+| --- | --- | --- | --- | --- | --- |
+| T001 |  | Add `users` table migration | `alembic upgrade head` applies clean; `\d users` shows email UNIQUE | — | spec §3 Data |
+| T002 | [P] | Add `sessions` table migration | migration applies; FK to users present | T001 | spec §3 Data |
+| T003 |  | Write failing test for `POST /login` | `pytest tests/auth/test_login.py` fails: no route | T001 | spec §4 Auth |
+| T004 |  | Implement `POST /login` | T003 test green; bad pw → 401 | T003 | spec §4 Auth |
+| ... | ... | ... | ... | ... | ... |
+| T0NN |  | All done-checks pass + `verify.sh` green | every row above checked; `scripts/verify.sh` exits 0 | all | spec §Acceptance |
+```
+
+### Per-task Interfaces (for context-isolated implementers)
+
+`implement` and `parallel` dispatch tasks to **context-isolated** workers (the `developer`
+subagent) that see *only their own task* — not the whole plan. Such a worker can't infer a
+neighbor's function signature, payload shape, or column name from a one-line row. For any task
+whose correctness depends on a contract it doesn't own, attach an **Interfaces block** right under
+its row. Trivial, self-contained tasks don't need one — don't add ceremony where there's no
+cross-task contract.
+
+```markdown
+**T004 — Interfaces**
+- Consumes: `auth.verifyPassword(plain: str, hash: str) -> bool` (from T003); `users.email UNIQUE`
+- Produces: `POST /login` → `200 {token}` | `401 {error}`; sets `Set-Cookie: sid=…; HttpOnly`
+```
+
+Quote **exact** signatures and shapes, not descriptions — the isolated worker copies them, it can't
+go look them up. "Returns the user" is invisible; `-> {id, email}` is usable. `Consumes` names what
+the task reads from a neighbor or the environment; `Produces` names the contract later tasks (and
+the per-task reviewer) will hold it to. The plan's **§0 Global Constraints** are inherited by every
+task implicitly — do **not** repeat them per task. Interfaces carry the *task-local* contract;
+Global Constraints carry the *project-wide* one. Together they are everything a blind implementer
+needs.
+
+## Review workload + delivery strategy forecast
+
+After the task table, append a short forecast. This protects the human reviewer
+before a giant diff exists.
+
+```markdown
+## Review Workload Forecast
+
+| Dimension | Forecast | Why |
+| --- | --- | --- |
+| Estimated changed lines | <number or range> | based on task count + touched areas |
+| Files / areas | <count and names> | modules, migrations, UI, tests, docs |
+| Review risk | low / medium / high | complexity, cross-stack scope, security/data changes |
+| Suggested delivery | single-pr / ask-on-risk / autochain / exception | matched to config.review_budget |
+```
+
+Pick the delivery strategy from the forecast: tiny change → `single-pr`; estimated
+lines over `config.sdd.review_budget.line_budget` (default 400) → recommend
+splitting or `ask-on-risk`; many areas or cross-stack contracts touched →
+`autochain` or a feature-track branch. A deadline or emergency that justifies a
+large review is marked `exception` and requires explicit user approval later.
+
+## Anti-patterns → STOP
+
+| Tempting move | Why it's wrong / Fix |
+| --- | --- |
+| "I'll write tasks straight from the user's intent" | You're skipping `plan`. Tasks slice a plan, not a wish. Route to `plan`. |
+| "Done-check: 'feature works'" | Not runnable, not evidence. Quote the literal test/command, or it's not a done-check. |
+| "One giant task: 'build the backend'" | Unverifiable, un-handoffable. Split until each slice has its own runnable check. |
+| "Mark everything `[P]` so it goes faster" | Shared files = merge collisions. `[P]` only when scope is truly disjoint. |
+| "This task has no spec line but we obviously need it" | That's scope creep wearing a hat. Trace it or cut it; if it's real, send it to `clarify`. |
+| "The plan is thin here, I'll guess the slice" | `analyze` will reject the guess next phase. Tighten the plan first. |
+| "I'll start coding the easy task while I list the rest" | This phase writes zero runtime code. Implementation is `implement`. |
+| "Renumber the IDs so they're contiguous" | Downstream phases cite IDs. They're stable once written. Append, don't renumber. |
+
+## Result envelope
+
+End with:
+
+```json result-envelope
+{
+  "status": "complete",
+  "executive_summary": "Task list and review workload forecast appended to the plan.",
+  "artifact": "02-DOCS/wiki/sdd/plans/<slug>.md",
+  "next_recommended": "analyze",
+  "risk": "low|medium|high",
+  "skill_resolution": {
+    "used": ["tasks"],
+    "missing": [],
+    "fallback": [],
+    "compact_rules": ["Every task needs a runnable done-check.", "Forecast review load before implementation."]
+  },
+  "evidence": ["task table appended", "review workload forecast appended"]
+}
+```
+
+## Next in the SDD chain
+
+The task list is now the contract for the rest of the build. Hand off to
+**`analyze`** — the consistency gate that cross-checks constitution ↔ spec ↔ plan
+↔ **tasks** and surfaces orphan tasks and untraceable scope — and then to
+**`implement`**, which executes the list TDD-style, using `parallel` for the `[P]`
+tasks and `worktrees` for isolation.
+
+Do not jump straight to `implement`. The whole point of writing a checkable list
+was to let `analyze` audit it cheaply *before* code exists.
+
+## Orientación (siempre)
+
+Habla con la voz de `orient`: frases cortas, una idea por frase, y cada respuesta se entiende sola. Registro técnico o con analogías según `technical_level` en `02-DOCS/wiki/harness/user-profile.md`. Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ➡️ siguiente, terminando en pregunta; ✅ y 🧭 cuando hay algo hecho o decidido). **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el "¿instalo la skill que falta?".)

package/skills/shared/tasks/evals/README.md

@@ -0,0 +1,70 @@
+# Eval harness — `tasks` skill
+
+Two things to check: that the skill **triggers** on the right prompts (and stays
+quiet on its SDD neighbours), and that it **measurably improves** the task
+breakdown an agent produces. Cases live in `cases.yaml`. There is no shell
+runner — triggering and breakdown quality are judgment calls, graded by an
+**agent harness** (a Claude Code agent with the skill catalog loaded) plus a
+human spot-check.
+
+## What's in `cases.yaml`
+
+- `should_trigger` — prompts that MUST load `tasks` (incl. Spanish and non-obvious phrasings).
+- `should_not_trigger` — near-misses that must route elsewhere (`route_to`), all on the
+  hard SDD-chain boundaries: `plan` (the step before), `analyze` (the gate after),
+  `implement` (the doing), and the stack skills a single task merely delegates to.
+- `capability` — one scenario with a `must_include` rubric to grade with vs without.
+
+## Triggering eval
+
+Goal: the skill fires when it should and never on a near-miss.
+
+1. Configure an agent with the **full catalog of skill descriptions** available
+   for routing — the other ai-hub Spec-Kit phases (`sdd`, `constitution`, `specify`,
+   `clarify`, `plan`, `analyze`, `implement`, `verify`, `review`, `ship`,
+   `debug`, `worktrees`, `parallel`) plus the stack/process skills (`fastapi`,
+   `nextjs`, `go`, `postgresdb`, `flutter`, `harness`, …) — so routing competes
+   realistically.
+2. For each `should_trigger` prompt: feed it cold, record whether `tasks` is the
+   skill the agent loads. Run **3–5 trials** per prompt (fresh context each).
+3. For each `should_not_trigger` prompt: confirm `tasks` does NOT load and that
+   the chosen skill matches `route_to`. Same 3–5 trials.
+4. Score: `triggered_correctly / total_trials` across both lists.
+
+**Pass bar: ≥ 90% trigger accuracy** over all prompts and trials, with **zero
+systematic false-positives** on the `plan`/`analyze`/`implement` near-misses.
+Those three are the known traps: a prompt to *write* the plan, to *gate* the
+artifacts, or to *execute* the work must not pull in `tasks`. If `tasks` keeps
+stealing `plan` or `implement` prompts, the description's NOT-clauses need
+sharpening.
+
+## Capability eval
+
+Goal: prove the skill changes the breakdown, not just the routing.
+
+1. For the `capability` scenario, run it **twice**:
+   - **WITHOUT** the skill (base agent, no `tasks` loaded).
+   - **WITH** the `tasks` skill loaded.
+2. Grade each output against the `must_include` checklist — one point per
+   checkable item covered. A human or grading agent marks each present / absent.
+3. Compute coverage = `items_covered / total_items` per run.
+
+**Pass bar: WITH the skill covers ≥ 80% of `must_include`; WITHOUT clearly
+lower** (target a ≥ 30-point gap). The skill must demonstrably add: runnable
+done-checks (not "it works"), dependency ordering, disciplined `[P]` marking,
+spec traces with no orphan tasks, TDD-shaped pairs, appending into the plan
+artifact (not a new file), and the handoff to `analyze`.
+
+## Notes on honesty
+
+- Trials are stochastic; report the raw fraction, not a rounded "pass".
+- The highest-signal capability check is the **done-check quality**: a correct
+  answer never emits a self-graded "feature works" — it quotes the literal
+  command. Treat a tidy-looking but unverifiable list as a **capability
+  failure** even if it reads well.
+- The second-highest signal is **refusing to slice from intent**: if no plan
+  exists, the correct behaviour is to STOP and route to `plan`, not to invent a
+  breakdown. A confident task list built from a fuzzy wish is a failure.
+- Re-run after any edit to `SKILL.md` — wording changes shift both triggering
+  and rubric coverage, especially the NOT-clauses that fence off `plan`/
+  `analyze`/`implement`.

package/skills/shared/tasks/evals/cases.yaml

@@ -0,0 +1,75 @@
+skill: tasks
+
+# Prompts that MUST load the `tasks` skill. It owns ONE job in the SDD chain:
+# turn an APPROVED plan into an ordered, independently-verifiable task list —
+# each task with a literal done-check, dependencies, a parallel-safe marker,
+# and a trace back to a spec line — appended into the plan artifact under
+# specs/<slug>/plan.md. It is NOT plan-writing (plan), NOT the
+# consistency gate (analyze), NOT execution (implement).
+should_trigger:
+  - prompt: "The plan for the billing feature is approved — break it into tasks we can actually execute."
+    why: "Slicing an approved plan into an executable task list is the skill's core and only job."
+
+  - prompt: "Descompón el plan de autenticación en una lista de tareas ordenada, cada una con su comprobación de hecho."
+    why: "Spanish phrasing for an ordered task breakdown where each task carries an explicit done-check — exactly this phase."
+
+  - prompt: "Give each step in the build a done-check so a subagent can run it and prove it's finished."
+    why: "Attaching a runnable done-check to every unit so it's independently verifiable is the defining feature of this skill, phrased without naming it."
+
+  - prompt: "We have the design doc and architecture — now sequence the work and tell me which parts can run in parallel."
+    why: "Ordering tasks by dependency and marking which are parallel-safe ([P]) is owned here; the user names sequencing/parallelism, not the skill."
+
+  - prompt: "Turn the plan into a numbered checklist where every item traces back to a requirement in the spec."
+    why: "Producing numbered, spec-traced tasks (Trace field, no orphan tasks) is precisely this phase's output and discipline."
+
+  - prompt: "Before we start coding, I want a task list off the approved plan with dependencies between tasks spelled out."
+    why: "Pre-implementation breakdown of an approved plan with explicit depends-on edges is the tasks phase; it sits between plan and analyze/implement."
+
+  - prompt: "Slice this implementation plan into the smallest units a coding agent can finish and hand off one at a time."
+    why: "Smallest-verifiable-unit slicing for handoff is the skill's stated method, even though 'tasks' is never said."
+
+# NEAR-MISS prompts that must NOT load `tasks`. Each routes to the genuinely
+# correct sibling. The recurring trap: anything in the SDD chain that is the
+# step BEFORE (plan), the gate AFTER (analyze), or the DOING (implement) — plus
+# stack-specific work that a single task merely delegates to.
+should_not_trigger:
+  - prompt: "We don't have a technical plan yet — design the architecture, interfaces, and testing strategy for the billing feature."
+    route_to: "plan"
+    why: "Writing the plan itself (architecture/interfaces/testing) is the `plan` phase; `tasks` slices a plan that already exists, it does not author one."
+
+  - prompt: "Cross-check the constitution, spec, plan, and task list for contradictions or scope drift before we write any code."
+    route_to: "analyze"
+    why: "The pre-implementation consistency gate over all four artifacts is `analyze`; `tasks` produces the list that analyze audits, it doesn't audit."
+
+  - prompt: "Start executing the task list — write the code for T004 and get its test green."
+    route_to: "implement"
+    why: "Executing tasks and writing runtime code (red → green → refactor) is `implement`; `tasks` writes no code, only the list."
+
+  - prompt: "Write the failing pytest and then the FastAPI route for the POST /login endpoint."
+    route_to: "fastapi"
+    why: "Concrete test+endpoint implementation in a specific stack is owned by the stack skill (fastapi) under implement; tasks only references such a command as a done-check, it doesn't write it."
+
+  - prompt: "Write the Alembic migration that adds the users table with a UNIQUE email constraint."
+    route_to: "postgresdb"
+    why: "Authoring the actual migration/schema is postgresdb's job; a tasks row merely cites 'migration applies clean' as a done-check."
+
+  - prompt: "The intent is fuzzy — there are unresolved edge cases in the spec we need to nail down before planning."
+    route_to: "clarify"
+    why: "Surfacing ambiguities and underspecified areas in the spec is the `clarify` gate; tasks refuses to start until the plan (downstream of clarify) is solid."
+
+# A concrete task the skill should guide, graded WITH vs WITHOUT it loaded.
+# A correct skill-guided answer enforces well-formed rows (runnable done-checks,
+# dependency order, [P] discipline, spec traces), appends to the plan artifact,
+# and hands off to analyze — not a flat unverifiable to-do list.
+capability:
+  - scenario: "An approved plan exists at specs/auth/plan.md (login + sessions + a users migration, pytest as the testing strategy) and a spec at specs/auth/spec.md. Break it into a task list."
+    must_include:
+      - "Confirms the inputs first: plan, spec, AND constitution must exist; if the plan were missing it would STOP and route to `plan` rather than slice from intent."
+      - "Reads the register from AGENTS.md and picks the register; the table is complete either way, and the chat adds only one line of why-this-slicing plus the risky tasks."
+      - "Emits sequential zero-padded stable IDs (T001, T002… — no hyphen, GitHub Spec Kit canon) with the six well-formed fields: ID, a separate [P] marker field after the ID, imperative title, done-check, depends-on, and a trace to a spec section."
+      - "Every done-check is a LITERAL runnable command or checkable observation (e.g. `pytest tests/auth/test_login.py` green; `alembic upgrade head` applies; bad password → 401) — never 'login works'."
+      - "Orders by dependency (migration/schema → data → service → API), so no task precedes what it depends on; marks `[P]` only on file/state-disjoint tasks and defaults to sequential when unsure."
+      - "Uses TDD-shaped slicing: a failing-test task before its implementation task, whose done-check is 'the test that was red is now green'."
+      - "Ensures every task traces to a spec line and cuts/flags any task with no trace as scope creep (route to clarify/specify), rather than inventing scope."
+      - "Appends the table under a `## Tasks` heading INSIDE specs/auth/plan.md (not a new file) and confirms the plan is indexed in the root AGENTS.md Knowledge map under sdd/."
+      - "Adds a final closer task gating on all done-checks passing plus `scripts/verify.sh` green, and hands off to `analyze` next (then implement) — not straight to implementation."

package/skills/shared/tauri/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: tauri
+description: "Use when building a lightweight cross-platform desktop (or v2 mobile) app with Tauri — a Rust core plus the OS-native WebView: Rust commands and IPC, streaming to the frontend, the default-deny capabilities/permissions ACL, bundling and signed auto-updates. NOT a Chromium+Node shell needing Node APIs in a main process (that is electron)."
+tags: [tauri, desktop, rust, cross-platform, ipc, webview]
+recommends: [rust, electron, react, secure-coding, github-actions]
+origin: ai-hub
+---
+
+# Tauri — Rust core, OS WebView, locked-down IPC, tiny binaries
+
+Tauri builds a desktop (and, since v2, mobile) app from a **Rust core** plus the
+**operating system's own WebView** — not a bundled browser. That is the whole value
+proposition: ~12MB installers and 30-50MB idle RAM, versus Electron's ~180MB installers
+and 150-300MB because it ships Chromium + Node. You write your UI in any web framework,
+expose privileged work as Rust commands, and the WebView talks to Rust over a sandboxed
+IPC bridge.
+
+**Always target v2.** Tauri 2.0 went stable in October 2024; the current line is 2.x
+(2.11.x as of mid-2026). v1 docs use a `tauri > allowlist` config that no longer exists —
+if you see `allowlist`, you are reading the wrong era. v2 also adds iOS/Android targets,
+so the same Rust core can ship to mobile.
+
+This skill owns the **shell**: commands, IPC, the security ACL, the bundler, the updater.
+It does **not** own the Rust language itself (that is the `rust` skill), the web UI inside
+the window (the `react`/`nextjs` skills), a Chromium+Node shell (`../electron/SKILL.md`), or
+app-code hardening beyond the IPC boundary (`../secure-coding/SKILL.md`).
+
+## Pick your starting shape
+
+| Situation | Do this |
+|-----------|---------|
+| Greenfield app, no UI yet | `npm create tauri-app@latest` — pick your frontend, get `src-tauri/` wired |
+| You already have a web app (Vite/Next/etc.) | `npx @tauri-apps/cli@latest init` inside it; point `build.frontendDist` at your build output |
+| Add mobile to an existing desktop app | `tauri ios init` / `tauri android init`; gate native bits behind `#[cfg(mobile)]` |
+| You see `tauri.conf.json > tauri > allowlist` | You are on v1 — migrate to v2 capabilities before adding anything |
+
+`src-tauri/` is its own Cargo crate: `Cargo.toml`, `tauri.conf.json`, `src/lib.rs`
+(the `run()` entry point), and `capabilities/`. The frontend is a sibling directory the
+bundler reads from `frontendDist`.
+
+## Commands & IPC — the core contract
+
+A command is a Rust function the frontend can call. Each rule below has a one-line *why*.
+
+- **Annotate and register.** `#[tauri::command]` on the fn, then list it in
+  `tauri::generate_handler![...]` inside `invoke_handler`. *Unregistered commands are not a
+  compile error — they fail at runtime when JS calls them.*
+- **Naming crosses the bridge.** JS `invoke('read_config', { filePath })` maps to Rust
+  `read_config(file_path: String)`. *Command names stay snake_case; args auto-map
+  camelCase (JS) ⇄ snake_case (Rust).*
+- **Fallible commands return `Result<T, E>` where `E: Serialize`.** *An `Err` becomes a
+  rejected JS promise; a panic instead crashes the command thread silently.*
+- **Never block the command thread.** Long or I/O work goes in an `async` command or a
+  spawned task. *Commands run on a shared IPC thread pool — a blocking call freezes other
+  IPC, which users see as a frozen UI.*
+- **Share state with `.manage(x)` + `State<'_, T>`.** *If a guard is held across an
+  `.await`, use `tokio::sync::Mutex`, not `std::sync::Mutex` — the std guard is not `Send`
+  and will not compile in an async command.*
+
+```rust
+// src-tauri/src/lib.rs
+use tauri::State;
+use tokio::sync::Mutex;
+
+#[derive(Default)]
+struct AppState { counter: u64 }
+
+#[tauri::command]                                   // registered below or it 404s at runtime
+async fn read_config(file_path: String) -> Result<String, String> {
+    tokio::fs::read_to_string(&file_path)           // async I/O — does not block the IPC pool
+        .await
+        .map_err(|e| e.to_string())                 // Err -> rejected JS promise
+}
+
+#[tauri::command]
+async fn bump(state: State<'_, Mutex<AppState>>) -> Result<u64, String> {
+    let mut s = state.lock().await;                 // tokio Mutex: guard is held across .await
+    s.counter += 1;
+    Ok(s.counter)
+}
+
+#[cfg_attr(mobile, tauri::mobile_entry_point)]      // same core compiles for iOS/Android
+pub fn run() {
+    tauri::Builder::default()
+        .manage(Mutex::new(AppState::default()))
+        .invoke_handler(tauri::generate_handler![read_config, bump])
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
+}
+```
+
+```javascript
+// frontend
+import { invoke } from '@tauri-apps/api/core';
+
+const text = await invoke('read_config', { filePath: '/app/config.toml' });
+// throws (rejected promise) if the command returns Err — wrap in try/catch
+```
+
+Bad → Good, the failure people hit most:
+
+```rust
+// Bad: std Mutex held across .await — won't compile in an async command, or you
+// "fix" it by dropping the guard early and create a race.
+async fn save(state: State<'_, std::sync::Mutex<AppState>>) { /* ... */ }
+
+// Good: async-aware lock.
+async fn save(state: State<'_, tokio::sync::Mutex<AppState>>) -> Result<(), String> { Ok(()) }
+```
+
+## Stream vs notify
+
+Two ways to push from Rust to the frontend — pick by ordering needs:
+
+- **`Channel<T>` for ordered streaming.** Download progress, file chunks, an HTTP body.
+  *Messages arrive in send order on one typed channel — the right tool for "report
+  progress as it happens."*
+- **`emit` / `listen` events for fire-and-forget pub/sub.** App-wide notifications, "data
+  refreshed," a tray action. *No ordering or backpressure guarantees; many listeners, no
+  reply.*
+
+```rust
+use tauri::ipc::Channel;
+
+#[derive(Clone, serde::Serialize)]
+struct Progress { downloaded: u64, total: u64 }
+
+#[tauri::command]
+async fn download(url: String, on_progress: Channel<Progress>) -> Result<(), String> {
+    // ... as bytes arrive:
+    on_progress.send(Progress { downloaded: 4096, total: 1_000_000 })
+        .map_err(|e| e.to_string())?;
+    Ok(())
+}
+```
+
+```javascript
+import { Channel, invoke } from '@tauri-apps/api/core';
+
+const onProgress = new Channel();
+onProgress.onmessage = (p) => updateBar(p.downloaded / p.total);
+await invoke('download', { url, onProgress });
+```
+
+## Security — the part people skip
+
+Tauri v2's IPC is an **Access Control List**, default-deny. The chain:
+
+**capabilities** (group windows/webviews) → grant **permissions** (named command sets) →
+**permissions map scopes** (what data/paths a command may touch). **A webview that matches
+no capability has zero IPC access.** This is the opposite of v1's opt-out allowlist —
+you grant exactly what each window needs.
+
+```json
+// src-tauri/capabilities/default.json — grant only what the main window uses
+{
+  "$schema": "../gen/schemas/desktop-schema.json",
+  "identifier": "main-capability",
+  "windows": ["main"],
+  "permissions": [
+    "core:default",
+    {
+      "identifier": "fs:allow-read-text-file",
+      "allow": [{ "path": "$APPCONFIG/*" }]   // scope: app config dir only, nothing else
+    }
+  ]
+}
+```
+
+Three more rules that bite real apps:
+
+- **CSP is only enforced if you set it** in `tauri.conf.json > app > security > csp`.
+  *No CSP = the WebView runs whatever it loads; local scripts are hashed, external ones get
+  a per-load nonce only once a CSP exists.*
+- **Use the isolation pattern when frontend code may be untrusted** (third-party deps,
+  plugins). *It injects a sandboxed iframe that can inspect/modify every IPC message before
+  it reaches Rust; messages are encrypted with SubtleCrypto using a key regenerated each
+  app start.*
+- **Treat the WebView as hostile.** *Anything in the frontend bundle ships to the user —
+  no API keys, tokens, or secrets in JS. Privileged work and secrets stay in Rust.*
+
+Full capabilities/permissions/scope JSON, fs/http scope globs, CSP dev-vs-prod recipes, and
+isolation-pattern setup live in `references/security.md`.
+
+## Bundle & ship
+
+`tauri build` produces native installers per OS — but unsigned binaries trigger
+"unidentified developer" / SmartScreen warnings, so signing is not optional for distribution.
+
+- **macOS:** sign with a Developer ID cert, then **notarize** — Gatekeeper blocks
+  un-notarized apps.
+- **Windows:** Authenticode-sign the `.exe`/MSI/NSIS or SmartScreen warns.
+- **Linux:** AppImage / `.deb` / `.rpm`; no central signing authority, but ship checksums.
+- **Auto-update:** the updater plugin needs a signing keypair (`tauri signer generate`);
+  the private key signs releases, the public key ships in config. *Without it the updater
+  refuses unsigned updates — by design.*
+- **Sidecar:** embed an external binary via `bundle.externalBin` to call it at runtime
+  (e.g. ship a CLI your app shells out to).
+
+Per-OS flags, notarization steps, updater config, sidecar setup, and a CI release matrix
+live in `references/bundling-distribution.md`. The CI runner matrix that *runs* those builds
+across three OSes is the `github-actions` skill's job; this skill defines what to build and sign.
+
+## Anti-patterns
+
+| Anti-pattern | Why it's wrong | Do instead |
+|--------------|----------------|------------|
+| One capability granting broad permissions to all windows | Any XSS gets the full IPC surface | Per-window capability, scoped to the commands that window needs |
+| Permission with no `allow`/scope on `fs`/`http` | Command can touch any path/host | Add an `allow` glob (`$APPCONFIG/*`) and deny the rest |
+| Blocking call (`std::fs`, sync HTTP) in a command | Freezes the IPC pool → frozen UI | `async fn` + `tokio` / spawn the work |
+| `.unwrap()` instead of returning `Result<T, E>` | Panic crashes the command thread silently | Return `Result`, `map_err` to a serializable error |
+| API keys/tokens in the frontend bundle | Ships to every user; trivially extracted | Keep secrets and privileged calls in Rust |
+| No CSP set in config | WebView runs any loaded script | Set `app.security.csp`; isolation pattern if deps are untrusted |
+| Copying a v1 `tauri.conf.json > allowlist` | That key does not exist in v2 | Use `capabilities/*.json` (ACL) |
+| Assuming bundled Chromium | It's the **OS** WebView (WebKit/WebView2) | Test rendering on each OS's engine; avoid Chromium-only CSS/JS |
+
+`scripts/verify.sh` is an advisory static lint over an `src-tauri/` tree that catches several of
+these: capabilities present, registered commands exist, no v1 `allowlist`, fallible-looking
+commands return `Result`.

package/skills/shared/tauri/evals/README.md

@@ -0,0 +1,12 @@
+# Evals — tauri
+
+These cases are a behavioral spec for routing and capability coverage, not a runtime test of
+Tauri itself — nothing here compiles Rust or builds an app. Run them through the repo's eval
+harness: `should_trigger` feeds the skill's `description` + body to the router and asserts it
+selects this skill (including the non-obvious "stream download progress" case, where the right
+answer is a `Channel<T>` and the word "Tauri" never appears); `should_not_trigger` asserts the
+router declines and routes to the named real sibling (electron, expo, rust, react,
+compose-multiplatform); the `capability` scenario prompts the agent and grades the answer against
+the `must_include` rubric (annotated + registered command, `Result<T, E>`, a scoped `fs` glob,
+the default-deny note, and the capability-vs-permission explanation). `scripts/verify.sh` is a
+separate standalone static lint over an `src-tauri/` tree and needs no harness.