feat(skills): add the source-pack skill for AI-driven pack development

[bakey]

Summary

Adds a shared Claude Code skill — docs/superpowers/skills/source-pack/ — that lets an AI session take "add as a data source" all the way to a review-ready PR, by encoding the methodology the GitHub (#168) and Slack (#172) packs were built and reviewed with.

.claude/ is personal workspace configuration and stays untracked. Shared skills live in the repo under docs/superpowers/skills/; each developer installs one with a one-line symlink (see docs/superpowers/skills/README.md):

mkdir -p .claude/skills
ln -s ../../docs/superpowers/skills/source-pack .claude/skills/source-pack

After that the skill auto-triggers on "onboard/integrate " requests, or explicitly via /source-pack.

What the skill encodes

SKILL.md — the six-phase workflow

1. Live contract reconciliation first. The load-bearing lesson: the wire contract is Open Connector's, not the provider's raw API. The GitHub pack originally shipped per_page, issue_number, a nonexistent action ID, the wrong execute endpoint, and the wrong response envelope — all plausible from GitHub's docs, all wrong live, all invisible to CI because the mocks encoded the same assumptions.
2. Table design under the source-pack admission gate (complete terminating pagination or defer; every decision recorded in the module doc with rationale).
3. Implementation against a concrete checklist (below).
4. Real-data integration verification — the second load-bearing lesson, learned on the Notion pack (feat(sources): Notion source pack (milestone 5.3) #177): the declared contract is not column truth either. That pack passed every contract-level check and still mapped columns that were always-NULL on the real wire, because declared schemas under-declare, misname (archived vs is_archived), or anyOf-hide the fields passthrough executors emit. No pack is submission-ready until every table has scanned real rows end to end.
5. Self-review before any PR — the requirement that submitted code has already survived this repo's review standards.
6. PR submission in the house style (branch naming, conventional commits, 5.1/5.2-density spec entries, feat(sources): GitHub source pack for Open Connector (milestone 5.1) #168-level PR bodies, Draft when stacked).

references/contract-reconciliation.md — running the local gateway; the verified /v1 surface (uniform {success, message, data, meta} envelope, POST /v1/actions/:id with no /execute suffix, camelCase strict schemas, x-oo-connector-alias, no read/write classification); enumerating and probing actions; reading the OC provider executor source as the row-shape authority (GitHub-style passthrough vs Slack-style normalization); the 400-vs-credential-wall trick that validates every generated input against the strict schema without provider credentials; capturing output schemas for fingerprint pinning.

references/implementation.md — the design rules that survived review (authoritative total_pages_path over the short-page heuristic, every string-enum push is Inexact, boundary-row protections, ValueFormat, fixed-input pins, conservative nullability, error_path only for forwarding gateways); the six fixture categories including schema-mismatch; the fingerprint recipe (capture → pin → sync test → contract-serving mocks → drift-refusal e2e); the per-declaration e2e floor (tables sharing a strategy constant still get their own wire pins); the three documentation targets.

references/live-verification.md — the phase-4 recipe distilled from #177's review cycle: real credentials configured by the USER in the gateway (PUT /api/connections/<service>; the agent never touches the secret, and a pasted secret triggers a rotation reminder); per-action live probes with the pack's exact inputs (a pinned enum that returns zero rows looks healthy — Notion's version-coupled data_source vs database); both-direction diffs of real row keys vs mapped columns; end-to-end scans of every table through skardi-server (fingerprint gate against LIVE discovery, every mapped column non-NULL somewhere, real multi-page pagination); fixture re-derivation as redacted live captures with a mechanical redaction audit; recording the gateway's pinned provider API version.

references/review-checklist.md — the distilled record of every review round both packs went through, organized by failure class: silent-truncation/termination correctness, contract honesty, test quality (structural JSON assertions, row identity over cardinality, both sides of every gate, negative-space guards), information discipline (kinds never values, bounded snippets), docs/spec sync (counts with the counting command), and code hygiene. Each item traces to a real defect caught in this repo.

Verification

• Docs-only change (a skill is markdown); no code paths or .gitignore touched — nothing under .claude/ is tracked.
• Symlink install verified locally: the skill resolves and loads through .claude/skills/source-pack → docs/superpowers/skills/source-pack.
• First real exercise: milestone 5.3 (Notion pack, feat(sources): Notion source pack (milestone 5.3) #177) ran phases 1–3 with this skill; its review cycle then produced phase 4 (real-workspace verification), which was executed on feat(sources): Notion source pack (milestone 5.3) #177 and fed back into this PR — the skill now encodes both the method and its first field correction.

Dependencies

The skill references the milestone-5.2 engine baseline (PaginationCursorInvalid, total_pages_path, ValueFormat, TimestampSecondsUtc, FixedValue::StrList, error_path, testutil::EnvVarGuard) — none of which exist on main until #172 merges. The implementation reference now opens with an Engine baseline section (verify-by-git grep, and the rule that a missing invariant is prerequisite engine work, not an assumption), so the skill is safe to merge in either order — but merging #172 first is the intended sequence, and the first real exercise (5.3 via /source-pack notion) should start only after both land.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[abbccdda]

Review blocked on a missing dependency

The skill content is strong and I verified its concrete claims against the code (fingerprint_schema, EnvVarGuard, MockGateway, envelope_ok/err, discovery_ok, total_pages_path, ValueFormat, Fidelity, error_path, the /v1 HTTP surface — all real; github.rs has exactly the deep module docs the skill points agents to).

But the skill is not yet self-adequate on this branch. It names two reference implementations as required reading ("read them before writing anything") and leans on both repeatedly — GitHub (passthrough rows) and Slack (normalized rows). On this branch:

• packs/slack.rs — missing (lives only on feature/open-connector-slack-pack, PR feat(sources): Slack source pack (milestone 5.2) + built-in packs as embedded YAML #172, not yet merged)
• docs/open-connector-slack.md — missing
• fixtures/github/contracts/ — does not exist; github.rs states "No fingerprint pins yet."

So the skill's entire normalized-row path and its entire fingerprint-pinning recipe (phase 3's capture → pin → sync test → contract-serving mocks → drift-refusal e2e) have no working exemplar on this branch — only Slack demonstrates both. An agent onboarding a cursor-paginated, normalized provider (e.g. Notion) would be sent to a file that isn't there.

This branch was cut from the merged GitHub PR (#168), so merge order is the real issue: if this skill reaches main before Slack, it ships pointing at four nonexistent paths.

Request: land the Slack pack (#172) first, then I'll re-review this skill with all of its referenced artifacts actually present.