SkardiLabs
diff --git a/‎docs/superpowers/skills/README.md‎
Lines changed: 18 additions & 0 deletions b/‎docs/superpowers/skills/README.md‎
Lines changed: 18 additions & 0 deletions
diff --git a/‎docs/superpowers/skills/source-pack/SKILL.md‎
Lines changed: 160 additions & 0 deletions b/‎docs/superpowers/skills/source-pack/SKILL.md‎
Lines changed: 160 additions & 0 deletions
diff --git a/‎docs/superpowers/skills/source-pack/references/contract-reconciliation.md‎
Lines changed: 135 additions & 0 deletions b/‎docs/superpowers/skills/source-pack/references/contract-reconciliation.md‎
Lines changed: 135 additions & 0 deletions
@@ -0,0 +1,18 @@
+# Shared agent skills
+
+Reusable Claude Code skills maintained with the repo. `.claude/` is
+personal workspace configuration and stays untracked — install a shared
+skill into your own setup with a symlink (one-time, per clone):
+
+```bash
+mkdir -p .claude/skills
+ln -s ../../docs/superpowers/skills/source-pack .claude/skills/source-pack
+```
+
+The skill then auto-triggers in your Claude Code sessions (or invoke it
+explicitly, e.g. `/source-pack`), and `git pull` keeps it current since
+the link points into the repo.
+
+| Skill | Purpose |
+| --- | --- |
+| [source-pack](source-pack/SKILL.md) | Develop a new Open Connector source pack end-to-end: live contract reconciliation, implementation under the admission gate, self-review against the repo's review standards, PR submission. |
@@ -0,0 +1,160 @@
+---
+name: source-pack
+description: >-
+  Develop a new Open Connector source pack for Skardi end-to-end: research the
+  provider's live gateway contract, implement the pack (tables, fixtures,
+  fingerprints, tests, docs), self-review against this repo's accumulated
+  review standards, and submit a PR. Use this skill whenever the user asks to
+  add, support, integrate, or onboard a data source or SaaS provider (Notion,
+  Jira, Gmail, HubSpot, Discord, Feishu, …) as SQL tables, mentions "source
+  pack", a "milestone 5.x" task, or wants any provider reachable through Open
+  Connector — even if they never say the words "source pack".
+---
+
+# Developing an Open Connector source pack
+
+You are implementing one milestone of the Open Connector integration: a
+**source pack** — static, Skardi-reviewed relational contracts over a
+provider's read actions, exposed as SQL tables. The GitHub pack (raw
+passthrough rows) and Slack pack (normalized rows) are the two reference
+implementations; read them before writing anything.
+
+The single most important lesson baked into this repo, learned the hard
+way: **the wire contract is Open Connector's, not the provider's raw
+API.** The GitHub pack originally shipped with `per_page`, `issue_number`,
+a nonexistent action ID, the wrong execute endpoint, and the wrong
+response envelope — all plausible from GitHub's own docs, all wrong
+against the real gateway, and all invisible to CI because the mocks
+encoded the same wrong assumptions. Every phase below exists to prevent
+that class of failure.
+
+## Required reading (before phase 1)
+
+1. `docs/superpowers/specs/2026-07-11-open-connector-integration-design.md`
+   — especially the **source-pack admission gate**: complete terminating
+   pagination, deterministic schema, read-only allowlist, documented
+   authz/rate limits, bounded safety defaults, null/empty/nested/
+   schema-mismatch fixtures, docs. The gate is the definition of done.
+2. `docs/superpowers/specs/2026-07-11-open-connector-integration-tasks.md`
+   — the milestone map; entries 5.1 (GitHub) and 5.2 (Slack) are the
+   template for what your milestone entry must eventually say.
+3. `crates/skardi/src/sources/providers/open_connector/packs/github.rs`
+   and `packs/slack.rs` — read the module docs top to bottom; every design
+   decision a pack makes is recorded there with its rationale, and yours
+   must be too.
+4. `docs/open-connector.md`, `docs/open-connector-github.md`,
+   `docs/open-connector-slack.md` — the documentation shape you will add
+   to.
+
+## Phase 1 — Reconcile the contract against a live gateway
+
+Do this FIRST, before designing tables. Read
+[references/contract-reconciliation.md](references/contract-reconciliation.md)
+for the concrete steps: starting the local gateway, probing the real API,
+reading the provider's executor source in the Open Connector repo, and
+validating generated inputs without provider credentials.
+
+Non-negotiable outputs of this phase:
+
+- The exact action IDs that exist (never assume a name; `github.
+  list_repositories` did not exist).
+- Every input key, verbatim from `inputSchema` (camelCase, and
+  `additionalProperties: false` means a wrong key is a hard 400).
+- The row shape: does the executor pass provider rows through raw
+  (GitHub-style) or rebuild them normalized (Slack-style)? Only the
+  executor source answers this — declared output schemas can be lax
+  (`additionalProperties: true`) while the executor passes through fields
+  the schema never mentions.
+- How pagination is emitted (top-level `nextCursor`? sibling
+  `total_count`? authoritative `paging.pages`?) and how in-band provider
+  errors are handled (most OC executors consume them and return a failure
+  envelope; `error_path` is only for gateways that forward them).
+- Captured output schemas for fingerprint pinning (phase 3).
+
+## Phase 2 — Design the tables
+
+Read [references/implementation.md](references/implementation.md) §Design
+before deciding anything. Summary of the rules that have survived review:
+
+- Choose read-only list actions with **complete terminating pagination**
+  only. An action whose pagination cannot be completed (Slack message
+  history, at the time of 5.2) is deferred and documented as absent, not
+  shipped incomplete.
+- Every design decision (a pinned input, an unmapped filter, an excluded
+  table, a nullability choice) is written into the module doc with its
+  why. Reviewers here read module docs as claims to be verified.
+- If the user named specific resources ("I want Notion pages and
+  databases"), scope to those; otherwise propose the natural first wave
+  (list-shaped, high-value, gate-passing) the way 5.1 chose 8 tables and
+  5.2 chose 3.
+
+## Phase 3 — Implement
+
+Follow [references/implementation.md](references/implementation.md)
+§Implementation for the full checklist: pack file, registry entry, the
+six fixture categories (including schema-mismatch), fingerprint pinning
+(capture → pin → sync test → contract-serving mocks → drift-refusal
+e2e), per-declaration end-to-end tests through `MockGateway`, and the
+three documentation targets (pack doc, spec entry with counted
+verification, `docs/open-connector.md` status).
+
+Engine extensions are allowed when the pack genuinely needs them (5.1
+added `Fidelity` and list plucking; 5.2 added `total_pages_path`,
+`ValueFormat`, `TimestampSecondsUtc`) — keep them backward-compatible
+(optional fields, `None` defaults) and test them at both the engine and
+the pack level.
+
+## Phase 4 — Self-review before any PR
+
+This phase is why the submitted code is good. Work through
+[references/review-checklist.md](references/review-checklist.md) — it is
+the distillation of every review round the existing packs went through.
+Treat it the way you would treat a human reviewer's findings: verify each
+item against the actual code, fix what fails, and be honest about
+severity. Then:
+
+1. `cargo fmt` and `cargo clippy` clean.
+2. `cargo test -p skardi --lib` — the FULL library suite, not just the
+   pack filter (engine changes ripple).
+3. Count tests with the documented methodology
+   (`cargo test -p skardi --lib sources::providers::open_connector` and
+   the pack-scoped filter) and make every count in docs/spec match.
+4. Run the repo's code review on your own diff (the `review` /
+   `/code-review` skill if available) and fix or consciously rebut every
+   finding. A finding you disagree with gets a verified technical
+   rebuttal, not silence — reviews here have been wrong before (cited
+   line numbers stale, counts miscounted), and verifying against the
+   code before acting is part of the standard.
+
+## Phase 5 — Submit the PR
+
+- Branch `feature/open-connector-<provider>-pack` off latest `main`
+  (fetch first). If the work must stack on an unmerged PR's branch,
+  stack — and recommend Draft until the base merges.
+- Commits: conventional style (`feat(sources): …`), detailed bodies that
+  explain *why* (look at `git log` for the house voice), ending with the
+  repo's standard co-author trailer.
+- Tick the milestone entry in the tasks spec with a verification blurb
+  matching 5.1/5.2's density (decisions, live-reconciliation status,
+  counted tests with the counting command).
+- PR body modeled on the merged pack PRs (#168-level per-module detail):
+  what shipped per module, design decisions with rationale, engine
+  extensions, verification section with test counts, live-reconciliation
+  status, and any deliberate deferrals (e.g. fingerprint pins pending,
+  tables gated on upstream support).
+- `gh pr create` with that body; use Draft when stacked or when the user
+  asked for in-progress visibility.
+
+## Working style
+
+- Evaluate before you fix: when review feedback arrives (from the user or
+  your own phase-4 pass), first verify the claim against the code —
+  some findings are already fixed, stale, or wrong, and saying so with
+  evidence is as valuable as a fix.
+- No credentials in Skardi, ever. Provider credentials live in the
+  gateway; tests use `EnvVarGuard` with per-test-unique variable names;
+  tokens never appear in YAML, logs, `Debug`, or errors.
+- Errors carry identity (action, table, page, row, column) and JSON
+  *kinds*, never values; snippets stay bounded.
+- When you and the user have live-gateway access, prefer one real probe
+  over an hour of speculation.
@@ -0,0 +1,135 @@
+# Phase 1 — Live contract reconciliation
+
+The provider's public API docs describe the provider. Skardi talks to
+**Open Connector**, whose action contracts rename keys (camelCase),
+reject unknown inputs (`additionalProperties: false`), sometimes rebuild
+rows entirely, and consume provider error envelopes. Everything below is
+about observing the real gateway instead of assuming.
+
+## 1. Start a local gateway
+
+Look for a local checkout of
+[oomol-lab/open-connector](https://github.com/oomol-lab/open-connector)
+(historically `~/Workspace/open-connector`); clone it if absent. Then:
+
+```bash
+cd <open-connector-checkout>
+npm install          # once
+OOMOL_CONNECT_DATA_DIR=/tmp/oc-data \
+OOMOL_CONNECT_RUNTIME_TOKEN=skardi-live-test-token \
+PORT=3000 npm run start
+```
+
+Health check (the runtime token is required once configured):
+
+```bash
+curl -s -H 'Authorization: Bearer skardi-live-test-token' \
+  http://localhost:3000/v1/health
+```
+
+Run the server in the background and remember to stop it when done.
+
+## 2. Know the real HTTP surface (verified v1.3.1)
+
+These facts cost a full client rewrite to learn; do not regress them:
+
+- Every `/v1` response uses the uniform envelope
+  `{"success": bool, "message": str, "data": …, "meta": {…}}` (+
+  `errorCode` on failures; `meta.executionId` once execution started).
+- Execute is `POST /v1/actions/:actionId` — there is **no** `/execute`
+  suffix. Success payload is under `data`.
+- Discovery is `GET /v1/actions/:actionId` — `data.inputSchema`,
+  `data.outputSchema`, `data.execution.locallyExecutable`,
+  `data.execution.noAuthRunnable` (all camelCase, `execution` nested).
+- The connection-alias header is `x-oo-connector-alias` (or
+  `x-oomol-connector-alias`; `?alias=` also works).
+- There is **no read/write classification** in action metadata — the
+  raw-scan gate (`open_connector_scan`) refuses by default-deny against
+  today's gateway. Pack tables are unaffected (read-only by Skardi's
+  review).
+- Input validation runs BEFORE credential lookup, which enables the
+  no-credential trick below.
+
+Skardi's client (`open_connector/client.rs`) and `testutil.rs` mocks
+already speak this protocol; if the live gateway ever disagrees with
+them, that is a finding to fix in the client, not to absorb in the pack.
+
+## 3. Probe the provider's actions
+
+```bash
+TOK='Authorization: Bearer skardi-live-test-token'
+# What exists — never assume an action ID:
+curl -s -H "$TOK" "http://localhost:3000/v1/actions?service=<provider>"
+# Per-action contract:
+curl -s -H "$TOK" "http://localhost:3000/v1/actions/<provider>.<action>"
+# Human-readable guide (input examples, scopes, connection identity):
+curl -s http://localhost:3000/api/actions/<provider>.<action>/agent.md
+```
+
+For each candidate action record: exact ID, `inputSchema` properties +
+`required` + `additionalProperties`, `outputSchema` top-level keys (row
+array key = your row path), pagination inputs (`perPage`/`page`?
+`cursor`/`limit`?), and `execution.requiredAuthTypes`.
+
+## 4. Read the executor source — the row-shape authority
+
+`<open-connector-checkout>/src/providers/<service>/` contains the
+executors. This is the only reliable answer to:
+
+- **Passthrough vs normalized rows.** GitHub's executors return the
+  provider's raw objects (so fields the declared schema omits — e.g.
+  `updated_at` — still arrive, because `additionalProperties: true`).
+  Slack's executors REBUILD rows (camelCase keys, flattened profiles,
+  renamed row arrays, cursor moved to top-level `nextCursor`). Mapping
+  Slack's raw field names would have produced all-NULL columns that no
+  provider doc would explain.
+- **In-band provider errors.** If the executor raises on the provider's
+  in-band error (Slack's `assertSlackPayload` throws on `ok: false`),
+  the gateway returns a failure envelope and the pack declares
+  `error_path: None`. Only a gateway that FORWARDS in-band errors needs
+  `error_path` (the engine checks it before row extraction; the mock
+  pack models it).
+- **Which inputs actually reach the provider** and under what names —
+  the executor's `compactObject({...})` mapping is the ground truth for
+  filter pushdown fidelity.
+- **Emitted output construction** — where the row array, totals, and
+  cursors really live.
+
+## 5. Validate generated inputs without provider credentials
+
+The gateway validates input against the action schema BEFORE touching
+credentials, so a wrong key is distinguishable from a missing login:
+
+```bash
+# Wrong key → HTTP 400, errorCode invalid_input, names the bad property:
+curl -s -X POST -H "$TOK" -H 'content-type: application/json' \
+  -d '{"input":{"owner":"a","repo":"b","per_page":5}}' \
+  http://localhost:3000/v1/actions/github.list_repository_issues
+# Correct keys, no connection → HTTP 403, "Configure … credentials first.":
+curl -s -X POST -H "$TOK" -H 'content-type: application/json' \
+  -d '{"input":{"owner":"a","repo":"b","perPage":5}}' \
+  http://localhost:3000/v1/actions/github.list_repository_issues
+```
+
+Reaching the credential wall proves the pack's generated inputs
+(pagination params, fixed inputs, filter keys, resource keys) pass the
+strict schema. Do this for every table's input set. Row-data validation
+additionally needs a configured connection
+(`PUT /api/connections/<service>` with `{authType, values}` — ask the
+user; never handle their credentials yourself) and provider egress
+(note: fake-IP DNS environments block egress at the gateway's SSRF guard;
+contract-level validation above needs neither).
+
+## 6. Capture the contracts for fingerprint pinning
+
+For each chosen action, save `data.outputSchema` verbatim as a fixture:
+
+```
+crates/skardi/src/sources/providers/open_connector/packs/fixtures/<provider>/contracts/<action_name>.json
+```
+
+Phase 3 pins each table's `expected_fingerprint` to the BLAKE3 hash of
+the canonicalized schema (computed by
+`action_registry::fingerprint_schema` — never re-derive the
+canonicalization elsewhere) and locks pin ↔ fixture with a sync test.
+Record the gateway version you captured against.