cipherstash · coderdan · Aug 19, 2026 · Aug 19, 2026
@@ -0,0 +1,82 @@
+---
+name: meta-issue-creation
+description: How an agent files a GitHub issue on cipherstash repos — required structure (Background / Problem / Proposal), dumbed-down wording rules, and pre-filing checks. Use whenever drafting or filing an issue on this repo or a sibling CipherStash repo (encrypt-query-language, protectjs-ffi, …).
+---
+
+# Filing issues as an agent
+
+These are **internal** skills for agents working on CipherStash repos. They are
+deliberately outside `skills/` — everything in that directory ships to
+customers inside the `stash` tarball; nothing in `.claude/skills/` does.
+
+## Before filing anything
+
+1. **Search for existing coverage** — open *and* closed, this repo *and* the
+   sibling repo the problem might belong to:
+
+   ```bash
+   gh search issues --repo cipherstash/stack "<term>" --limit 30 --json number,title,state
+   ```
+
+   A closed issue that covers your problem is a finding, not a dead end — check
+   *why* it closed (linked PR? shipped artifact? silent close?) before filing a
+   duplicate. Reopening with a comment often beats a new issue.
+2. **Verify every mechanical claim** against code or the installed package
+   before asserting it. Cite `file:line`. Separate what you **verified** from
+   what is **plausible** — say which is which in the issue.
+3. **Pick the right repo.** A problem caused upstream (EQL SQL, prisma-next,
+   protect-ffi) gets its issue upstream, with a consumer-impact issue here only
+   if this repo needs its own mitigation. Cross-reference with the full
+   `owner/repo#N` form so links work from both sides.
+
+## Structure
+
+Required sections, in this order:
+
+- **Background** — orient a reader who is *new to CipherStash, stack, and EQL*.
+  One short paragraph: what the relevant piece does and why it exists. Define
+  every product term and acronym at first use ("EQL — the SQL library we
+  install into the customer's database as the `eql_v3` schema").
+- **Problem** — the mechanism (what actually happens, step by step), then the
+  impact (who hits it, when, how often), then why nothing catches it today.
+  A concrete failure narrative beats an abstraction: "queries slow from
+  instant to scan-every-row, silently" — not "performance degradation may
+  occur".
+- **Proposal** — numbered, concrete steps. If the full fix is large, include a
+  cheap interim step that could ship first. State the failure behaviour you
+  want ("fail loudly listing the statements — a loud failure beats a silent
+  deletion").
+
+Optional sections, when they earn their place:
+
+- **Affected versions** — when the problem is version-bounded.
+- **Evidence / Verification** — commands run, output observed, `file:line`.
+- **Relationship to other work** — links to sibling issues, and what each one
+  does/doesn't cover. After filing, leave a short cross-link comment **on the
+  related issues pointing back** — links must work in both directions or one
+  side is never found.
+
+## Wording
+
+Dumbed down, always. Assume the reader joined yesterday:
+
+- Short sentences. Plain verbs. No internal shorthand or codenames.
+- Every acronym expanded at first use, even "obvious" ones (EQL, ZeroKMS, PSL).
+- Say what breaks in the user's world, not just in the code's world.
+- Titles are symptom-first and name the command or package:
+  `` `stash eql upgrade` silently deletes search indexes — save and restore them ``
+  beats "Improve EQL upgrade robustness".
+- Write `#N` **only** for a real GitHub issue or PR reference — GitHub
+  autolinks every `#N`, so "step #2 of the plan" mints a bogus link to issue 2.
+  Write "step 2", "item 3" instead.
+- **Never** reference internal Linear issues (`CIP-…` numbers) anywhere on
+  GitHub — issues, PRs, comments, commit messages. GitHub is public; Linear is
+  not. GitHub refs are fine.
+
+## Mechanics
+
+- `gh issue create --repo cipherstash/<repo> --title '…' --label <label> --body "…"`.
+- Reuse existing labels (`enhancement`, `bug`, `SDK`, …) — check with
+  `gh label list` rather than inventing new ones.
+- Sibling skill: [meta-pr-creation](../meta-pr-creation/SKILL.md) for the PR
+  that eventually closes the issue.
@@ -0,0 +1,83 @@
+---
+name: meta-pr-creation
+description: How an agent authors branches, commits, and pull requests on cipherstash/stack — naming, signed commits, the changeset/skills/meta-file checklist, and PR body structure with dumbed-down wording. Use when committing work or opening/updating a PR.
+---
+
+# Authoring PRs as an agent
+
+Internal skill — lives in `.claude/skills/` on purpose. `skills/` ships to
+customers inside the `stash` tarball; this must not.
+
+## Branch and commits
+
+- Branch names are type-prefixed slugs: `docs/skill-psl-functional-indexes`,
+  `fix/…`, `feat/…`, `chore/…`. Never commit to `main`.
+- Commit subjects are conventional: `type(scope): imperative summary` —
+  `docs(skills): …`, `fix(stack-prisma): …`. The body explains **why** and the
+  mechanism, not a list of what changed (the diff shows that). Reference the
+  GitHub issue the commit serves.
+- **Commits must be signed.** `commit.gpgsign` is on, but verify before
+  pushing:
+
+  ```bash
+  git log --format='%h %G? %s' main..HEAD   # G = signed, N = unsigned
+  ```
+
+  An unsigned commit (`N`) in the stack: `git rebase --force-rebase main`
+  re-commits everything signed, then `git push --force-with-lease`. Always
+  `--force-with-lease`, never bare `--force`.
+
+## Before opening the PR
+
+The authoritative checklist is `AGENTS.md` § "Adding Features Safely" — read
+it, don't work from memory. The three most-missed items:
+
+1. **Changeset** — required when the change touches a published package's
+   surface, *including* a `skills/`-only change (those ship in the `stash`
+   tarball, so they need a `stash` patch changeset). A `.claude/`-only change
+   is internal: no changeset.
+2. **Skills check** — a change to a public API, CLI surface, or user-facing
+   workflow must fix the affected `skills/*/SKILL.md` in the same PR
+   (package→skill map in `AGENTS.md`).
+3. **Meta files** — adding/removing/renaming a package, example, skill, or
+   subpath export must update `AGENTS.md` Repository Layout and `SECURITY.md`.
+
+Then run: `pnpm run code:fix`, `pnpm --filter <pkg> build`,
+`pnpm --filter <pkg> test`.
+
+## PR body
+
+Same wording rule as [meta-issue-creation](../meta-issue-creation/SKILL.md):
+**dumbed down** — assume the reviewer is new to CipherStash, stack, and EQL.
+Define product terms at first use; say what breaks or improves in the user's
+world, not just the code's.
+
+Sections, in order:
+
+- **Summary** — what and why, two or three plain sentences. Lead with the
+  user-visible effect.
+- **Changes** — grouped by area, one line each.
+- **Verification** — exactly what was run and what it showed. Honest: a
+  failing or skipped check is stated, not omitted. "Verified against the 0.17
+  dist" beats "should work".
+- **Related** — `Closes #N` / `Refs #N` for the GitHub issues this serves;
+  cross-repo refs in full `owner/repo#N` form.
+- **Review notes** *(optional)* — where to look first, and anything
+  deliberately deferred with the reason.
+
+Reference wording traps (same as issues):
+
+- `#N` **only** as a real GitHub issue/PR reference — GitHub autolinks every
+  `#N`, so "option #2" mints a bogus link. Write "option 2".
+- **Never** reference internal Linear issues (`CIP-…`) in PRs, commits, or
+  comments — GitHub is public.
+
+## Mechanics
+
+- **Always open as a draft**: `gh pr create --draft --title '…' --body '…'`
+  (title follows the commit-subject convention). Mark it ready for review only
+  when the user says so — either ask, or rely on an explicit "open it ready" /
+  "mark it ready" from them. `gh pr ready <number>` flips it.
+- Force-pushing a branch with an open PR is fine (rebases, re-signs) — but
+  say so in a PR comment when the rewrite changes more than commit hashes.
+- Don't merge, close, or mark ready-for-review without being asked.