Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .claude/skills/stackql-provider-development/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ The detail lives in `references/`; `scripts/` holds two generic helpers:
- **`all_services.csv` is the contract.** Committed and diffed on every regeneration; a method moving resource or a resource renamed is a breaking change to review, not noise.
- **Environment.** Linux, macOS or WSL (on Windows prefer WSL and the latest `stackql` release on its PATH). GNU make + bash. `stackql` resolves as `$STACKQL`, `./stackql`, then PATH.
- **Never touch production accounts.** Live tests run against a dedicated dev tenant, pace under the vendor's rate limit, name everything `stackql-smoke-<stamp>`, sweep breadcrumbs first, restore anything toggled.
- **Writing.** Applies to every piece of text the build generates, whoever or whatever reads it: README, docs headers and examples, NOTES, CLAUDE.md, code comments, commit messages, console output, inventory and CSV columns, mock fixtures, hand-over notes. No em dashes (use `-`), no `--` as a dash, no characters that are not on a QWERTY keyboard (no emoji, no typographic quotes, no arrows other than `->`), no stacked headings, measured copy, no hyperbole. Text the vendor owns - operation summaries, schema and parameter descriptions, examples carried from the upstream spec into the snapshot, `provider-dev/source`, the generated provider and `website/docs` - is passed through as the vendor wrote it; the only alteration is the MDX/JSX escaping `sanitize-docs` applies so the docs site builds.
- **Writing.** Applies to every piece of text the build generates, whoever or whatever reads it: README, docs headers and examples, NOTES, AGENTS.md, code comments, commit messages, console output, inventory and CSV columns, mock fixtures, hand-over notes. No em dashes (use `-`), no `--` as a dash, no characters that are not on a QWERTY keyboard (no emoji, no typographic quotes, no arrows other than `->`), no stacked headings, measured copy, no hyperbole. Text the vendor owns - operation summaries, schema and parameter descriptions, examples carried from the upstream spec into the snapshot, `provider-dev/source`, the generated provider and `website/docs` - is passed through as the vendor wrote it; the only alteration is the MDX/JSX escaping `sanitize-docs` applies so the docs site builds.

## Workflow

Expand All @@ -35,7 +35,7 @@ Work the steps in order. **Do not execute a step without having read its referen
7. **Wrap it in the Makefile** - [references/repo-layout-and-makefile.md](references/repo-layout-and-makefile.md). `make help` lists every step; `make build`, `make test`, `make all` need no credentials; `make smoke*` sources `.env`.
8. **Test in three credential-free layers, then live** - [references/testing.md](references/testing.md). Offline `SHOW`/`DESCRIBE`, a mock API with row-level and wire-level assertions, the meta-route walk; then the pystackql smoke suite with `--live` and a budget.
9. **Docs and CI** - [references/docs-and-ci.md](references/docs-and-ci.md). Docusaurus 3.10 microsite on the shared config with `showLastUpdateTime`, a getting-started page that leads with the queries the provider exists for, `sanitize-docs`, and the build-and-test / spec-drift workflows.
10. **Record and hand over** - [references/handover.md](references/handover.md). CLAUDE.md (settled decisions), NOTES.md (findings with evidence, plus the open questions the first live run must answer), README.md (numbered build guide with counts that match the artifacts), `.env.example`.
10. **Record and hand over** - [references/handover.md](references/handover.md). AGENTS.md (settled decisions; `CLAUDE.md` and `.github/copilot-instructions.md` are short entry points to it), NOTES.md (findings with evidence, plus the open questions the first live run must answer), README.md (numbered build guide with counts that match the artifacts), `.env.example`.

For an existing provider, start from [references/uplift-checklist.md](references/uplift-checklist.md) instead of step 1; it routes back into the steps above.

Expand All @@ -54,4 +54,4 @@ Verified against stackql v0.10.605 / any-sdk v0.5.4-alpha01 (2026-08). These cha

## Definition of done

`make all` green from a clean checkout (deps, pipeline, offline + integration + meta-route tests, docs, site build); `all_services.csv`, `provider-dev/source`, `provider-dev/openapi` and `website/docs` committed; CLAUDE.md, NOTES.md, README.md and `.env.example` current; the smoke suite runnable with `make smoke` / `make smoke-live` by someone with credentials, with its open questions listed. Publishing is the next skill.
`make all` green from a clean checkout (deps, pipeline, offline + integration + meta-route tests, docs, site build); `all_services.csv`, `provider-dev/source`, `provider-dev/openapi` and `website/docs` committed; AGENTS.md, NOTES.md, README.md and `.env.example` current; the smoke suite runnable with `make smoke` / `make smoke-live` by someone with credentials, with its open questions listed. Publishing is the next skill.
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## What to record where

- **CLAUDE.md** - the settled decisions (archetype, scoping variable, auth, the flagship mapping, skip codes, casing policy), the toolchain rules, where the findings live, the non-negotiables. Short; it is read every session.
- **AGENTS.md** - the settled decisions (archetype, scoping variable, auth, the flagship mapping, skip codes, casing policy), the toolchain rules, where the findings live, the non-negotiables. Short; it is read every session. It is the one tool-neutral guidance file: Codex reads it directly, `CLAUDE.md` imports it for Claude Code (an `@AGENTS.md` line) and `.github/copilot-instructions.md` points GitHub Copilot to it. Project rules go in AGENTS.md, never in the two entry points; those carry only what applies to their tool alone.
- **NOTES.md** - numbered findings with evidence (what was measured, against what, what was decided and why), a Blockers list of what only a live run can establish, and the testing requirements. It is the memory of the build; a future refresh reads it before touching a rule.
- **README.md** - the numbered build guide (steps 0-8: pin, inventory, split, mappings, normalize, generate, test, publish, docs) with counts that match the committed artifacts, the Makefile targets, credentials, and the CI description.
- **.env.example** - every live-test variable with a one-line comment; never a real value.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Reference repositories

Clone these next to the provider repo (shallow clones are fine) and grep them for any extension key to find a real, shipped example. Sibling build repos carry a NOTES.md (or CLAUDE.md) of findings - reuse them, do not re-derive.
Clone these next to the provider repo (shallow clones are fine) and grep them for any extension key to find a real, shipped example. Sibling build repos carry a NOTES.md (or AGENTS.md / CLAUDE.md) of findings - reuse them, do not re-derive.

| Repo | What to read |
|---|---|
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,11 +18,13 @@ tests/
smoke_test.py
website/ # Docusaurus microsite
.github/workflows/ # build-and-test.yml, prod-web-deploy.yml, test-web-deploy.yml
CLAUDE.md NOTES.md README.md SECURITY.md LICENSE .env.example
.github/copilot-instructions.md # GitHub Copilot entry point to AGENTS.md
AGENTS.md CLAUDE.md # the shared agent guidance and the Claude Code entry point that imports it
NOTES.md README.md SECURITY.md LICENSE .env.example
```

Makefile targets (bash shell, `.DEFAULT_GOAL := help`, `##` help comments): `deps`, `fetch-spec` (verify pin), `refresh-spec` (`--update`), `inventory`, `split`, `mappings` (rm CSV + analyze + map), `pre-normalize`, `normalize`, `generate` (rm output + generate + post-process), `post-process`, `build` (the chain), `test-offline`, `test-integration`, `test-meta` (start server; run; stop; preserve exit status), `test`, `venv`, `smoke`, `smoke-live`, `smoke-read-only`, `smoke-<gated-lifecycle>`, `smoke-cleanup`, `docs` (passes `--snake-case-aliases` and `--source-project $(SOURCE_PROJECT)`, the provider repository URL, `?=` so it can be overridden), `website`, `website-start`, `clean`, `all` = `deps build test docs website`. `make all` never needs credentials and never bills. The smoke targets source `.env` when present (`set -a; source <(tr -d '\r' < .env); set +a`).

package.json scripts wrap the two CLI entry points through `node ./node_modules/@stackql/provider-utils/bin/provider-dev-utils.mjs <cmd>` and `docgen-utils.mjs generate-docs` (never `.bin` shims); pass flags after `--`.

CLAUDE.md records the settled decisions and where the findings live; NOTES.md records the findings with evidence; README.md is the numbered build guide (steps 0-8) with counts that match the artifacts.
AGENTS.md records the settled decisions and where the findings live (`CLAUDE.md` and `.github/copilot-instructions.md` are short entry points to it, see handover.md); NOTES.md records the findings with evidence; README.md is the numbered build guide (steps 0-8) with counts that match the artifacts.
Original file line number Diff line number Diff line change
Expand Up @@ -6,5 +6,5 @@
4. Add what is missing against this list: env-var scoping, naive bodies, snake surface, pagination, pushdown, transforms, objectKeys, lifecycle EXECs attached to their resources, views, GraphQL merge, skip codes for what is not mappable.
5. Convert ad-hoc scripts into Makefile targets; add `make all`.
6. Write or extend the three test layers until they cover every archetype present; add the smoke suite with `--live`.
7. Refresh CLAUDE.md, NOTES.md, README.md, `.env.example`, the docs headers; bring `website/sidebars.js` and the `.sidebar-back-link` rules in `website/src/css/global.css` in line with the template (the `Back to StackQL Docs` link, see docs-and-ci.md); `make docs && make website`.
7. Refresh AGENTS.md (moving the guidance out of an existing CLAUDE.md and leaving `CLAUDE.md` and `.github/copilot-instructions.md` as the short entry points, see handover.md), NOTES.md, README.md, `.env.example`, the docs headers; bring `website/sidebars.js` and the `.sidebar-back-link` rules in `website/src/css/global.css` in line with the template (the `Back to StackQL Docs` link, see docs-and-ci.md); `make docs && make website`.
8. `make all` green from a clean checkout before handing over.
3 changes: 3 additions & 0 deletions .github/copilot-instructions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# GitHub Copilot instructions

GitHub Copilot entry point. The project guidance is in [AGENTS.md](../AGENTS.md) at the repository root; read it before starting any task in this repository and follow it. Project rules are maintained there, not here - add to this file only what applies to GitHub Copilot alone.
Loading
Loading