@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/open-source-release/evals/triggers.json

@@ -0,0 +1,15 @@
+{
+  "should_trigger": [
+    "We want to open-source our internal CLI tool. What do we need to do before making the repo public?",
+    "Make sure there are no old API keys or internal hostnames anywhere in the git history before we flip this GitHub repo to public",
+    "Prepare this company project for its first public release under an open licence, with SECURITY.md and a code of conduct",
+    "Use git filter-repo to strip the customer data that was committed three years ago, then check we can publish the repo"
+  ],
+  "should_not_trigger": [
+    "Cut version 2.3.0 and write the release notes from the merged PRs",
+    "Scan the current change for vulnerabilities and leaked secrets before I push",
+    "Audit our npm dependencies for known CVEs and typosquatted packages",
+    "Rewrite the README so new users can get started faster",
+    "Squash my last five commits into one before I open the pull request"
+  ]
+}

package/skills/open-source-release/references/history-scrub.md

@@ -0,0 +1,65 @@
+# History scrubbing, licence tools and final checklist
+
+## Fresh history (safest)
+
+```sh
+git clone <private-url> work && cd work
+# after cleaning the tree and committing:
+rm -rf .git && git init -b main && git add -A
+gitleaks dir -v .            # must be clean before the first commit
+git commit -m "Initial public release"
+```
+
+Keep the private repository as the archive of old history.
+
+## Rewriting history with git filter-repo
+
+Rotate secrets before you start. Work in a fresh clone.
+
+`replacements.txt`, one expression per line (literal by default; `regex:` and `glob:` prefixes allowed; `==>` sets the replacement, otherwise matches become `***REMOVED***`):
+
+```
+AKIAEXAMPLEKEY==>REDACTED
+regex:[a-z0-9-]+\.corp\.example\.com==>internal.example
+```
+
+```sh
+git filter-repo --sensitive-data-removal --replace-text ../replacements.txt
+git filter-repo --sensitive-data-removal --invert-paths --path config/prod.env --path dumps/
+git filter-repo --replace-message ../message-replacements.txt   # same format, for commit messages
+git filter-repo --mailmap ../mailmap                             # rewrite author/committer names and emails
+```
+
+- `--sensitive-data-removal` fetches all refs first, reports the first changed commits and orphaned LFS objects, and prints cleanup steps for the remote and other clones.
+- Keep `replacements.txt` outside the repository; it contains the secrets.
+- Re-run `gitleaks git -v --log-opts="--all"` and the manual searches until clean.
+- If the private remote must also be cleaned: `git push --force --mirror origin` only with the user's sign-off; hosts block some refs (`refs/pull/*`) and keep cached views, so follow the host's sensitive-data removal guide and contact its support to purge them. Every other clone must be re-cloned or cleaned.
+
+## Third-party licence inventory
+
+| Ecosystem | Tool |
+|---|---|
+| npm / pnpm / Yarn | `npx license-checker-rseidelsohn --summary` (or the maintained checker the project uses) |
+| Python | `pip-licenses --format=markdown` in the project's environment |
+| Go | `go-licenses report ./...` |
+| Rust | `cargo deny check licenses` with an allow-list in `deny.toml` |
+| Java / Kotlin | Gradle or Maven licence plugins the build already uses |
+| Any | `licensee detect` for the repository's own licence; `reuse lint` for REUSE compliance |
+
+Also check for an SBOM requirement; `syft` or the ecosystem's SBOM tool can produce one.
+
+## Final checklist (all must be yes)
+
+- [ ] Owner approval recorded
+- [ ] Every found secret rotated, and scans of tree and full history are clean
+- [ ] No PII, customer data, internal hostnames, IPs, account IDs or internal URLs remain
+- [ ] `LICENSE` present, SPDX id in manifests, third-party licence flags resolved by a qualified person
+- [ ] README quick-start works from a clean clone on a machine without internal network access
+- [ ] Build and tests pass without private registries, internal services or company VPN
+- [ ] CONTRIBUTING, SECURITY (with a real contact), CODE_OF_CONDUCT (with a real contact)
+- [ ] Public CI green; secret scanning, push protection and branch protection enabled
+- [ ] Internal-only workflows, runbooks and deploy config removed
+- [ ] Trademarks and project name cleared by the owner
+- [ ] Publishing to a new public repository, or, if flipping the existing one, issues, PRs, wiki, releases and Actions logs reviewed
+- [ ] Commit authors, emails and messages reviewed (fresh history, or `--mailmap` / `--replace-message` applied)
+- [ ] User gave explicit sign-off to change visibility

package/skills/parallel-agent-orchestration/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: parallel-agent-orchestration
+description: Fans a large coding job out to several subagents at once and merges the results. Covers cutting the job into independent units with disjoint file ownership, writing a self-contained brief and return contract for each worker, isolating writers in separate git worktrees or branches, and checking every result before integrating it. Use when work splits naturally into pieces that can run side by side (many modules, many packages, a survey plus several fixes), or when the user asks to run agents in parallel or orchestrate a team of subagents.
+license: MIT
+compatibility: Any Agent Skills host that can start subagents. Worktree isolation needs git 2.17 or later (for git worktree remove).
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: meta
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "git"
+  kete-loom/owner: "Kete-org"
+---
+
+# Parallel agent orchestration
+
+You are the orchestrator. Workers do the units; you own the plan, the contracts, the merge and the final verification. Parallelism only pays when units are truly independent. Two agents editing the same file is a merge conflict you chose.
+
+## 1. Decide whether to parallelise
+
+Parallelise only if all are true:
+
+- The work splits into 2 or more units that don't need each other's output to start.
+- Each unit can be checked on its own (a test, a lint, a build, a clear review question).
+- The units touch different files, or are read-only.
+
+Otherwise do it sequentially, or run a read-only survey in parallel and the edits in sequence. If the split is unclear, **stop and propose the split to the user** before starting workers.
+
+## 2. Cut the units
+
+1. Search the codebase to map what each unit touches. Write the plan as a table:
+
+   | Unit | Goal | Owns (may edit) | May read | Check command |
+   |---|---|---|---|---|
+
+2. Give every file at most one owner. Shared files (lockfiles, `package.json`, route tables, barrel `index` files, generated catalogs, changelogs) belong to **you**: workers report what they need there and you apply it at merge time.
+3. Do shared groundwork first and yourself: interfaces, types, config that several units depend on. Commit it, then start workers from that commit.
+4. Keep the count small. Three to six workers is easier to verify than twenty. More units than that: run in waves.
+
+## 3. Isolate writers
+
+- Read-only workers (search, review, research) can share the working tree.
+- Writing workers each get their own worktree and branch, so they can't clobber each other:
+
+  ```
+  git worktree add -b work/<unit> ../<repo>-<unit> <base-sha>
+  ```
+
+  Start every worktree from the groundwork commit of step 2. If the host creates worktrees for its subagents itself, use those instead. Remove them after merging with `git worktree remove ../<repo>-<unit>`.
+- If the host runs workers in the same tree, ownership from step 2 is the only protection: state it in every brief.
+
+## 4. Write each brief
+
+A worker starts with none of your context. Every brief contains:
+
+```
+Goal: <one sentence, the outcome>
+Context: <the 3-6 facts it needs: paths, conventions, decisions already made>
+You own: <files/folders you may edit>. Do not edit anything else.
+Do not: <push / commit anywhere but work/<unit> / install dependencies / touch shared files / ask the user>
+Done when: <check command> passes and <acceptance criteria>
+Return exactly:
+  status: done | blocked | partial
+  changed: list of paths
+  check: <command> -> <result>
+  needs_from_orchestrator: shared-file changes or decisions, or "none"
+  notes: max 5 lines
+```
+
+Ask for a fixed, short return format. Free-form essays are hard to merge and eat your context.
+
+## 5. Run and watch
+
+- Start the independent workers together. Don't start a worker whose inputs aren't ready.
+- If a worker returns `blocked`, decide yourself or **ask the user**; don't let it guess.
+- Don't re-run a failed worker with the same brief. Fix the brief (missing context, wrong ownership) first.
+
+## 6. Verify every result
+
+Treat worker output as a claim, not a fact:
+
+1. Check `changed` against ownership: `git diff --name-only <base-sha>..work/<unit>`, plus `git -C ../<repo>-<unit> status --short` for anything left uncommitted. Any file outside its ownership: reject or redo that part.
+2. Re-run the unit's check command yourself.
+3. Read the diff. Look for skipped or deleted tests, stubs, TODOs and silent scope creep.
+
+## 7. Merge
+
+1. Merge units one at a time onto the integration branch, in dependency order.
+2. Apply the `needs_from_orchestrator` changes to shared files yourself.
+3. After each merge run the affected checks; after the last, run the project's full check (tests, lint, build).
+4. On a conflict, resolve it yourself with both briefs in mind, or redo the smaller unit on top of the merged result. Never pick a side blindly.
+
+## Report
+
+```
+Units: <n> (<n> done, <n> redone, <n> dropped)
+Merged: <branch> at <sha>
+Full check: <command> -> <result>
+Left over: <blocked items and open questions>
+```
+
+## Never
+
+- Never give two workers write access to the same file.
+- Never merge a unit you haven't re-checked yourself.
+- Never let workers commit to the integration branch or push.
+- Never parallelise a task whose steps depend on each other's results just to go faster.

package/skills/parallel-agent-orchestration/evals/triggers.json

@@ -0,0 +1,14 @@
+{
+  "should_trigger": [
+    "Spin up several subagents to migrate each of our 8 packages to ESM at the same time",
+    "Split this big refactor across parallel workers without them stepping on each other's files",
+    "Run one agent per service to add health checks, then merge everything into one branch",
+    "How should I divide this job between a team of agents and combine what they produce"
+  ],
+  "should_not_trigger": [
+    "Keep retrying the flaky integration test fix overnight until CI is green",
+    "Design the message queue so our worker processes handle jobs concurrently",
+    "The context keeps overflowing when I read this monorepo, help me budget it",
+    "Plan the implementation steps for the new invoicing feature"
+  ]
+}

package/skills/patent-research/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: patent-research
+description: Patent and trademark search groundwork across USPTO Patent Public Search and Trademark Search, EPO Espacenet, Google Patents and WIPO PATENTSCOPE and Global Brand Database, covering breaking an invention into searchable features, keyword and CPC classification queries, prior-art and freedom-to-operate lead lists, reading independent claims element by element, checking legal status, family and expiry, and knockout trademark screens by Nice class, with every result labelled as leads for a registered patent attorney or trademark lawyer to assess. Use when checking whether an idea looks new before filing, looking for patents that might block a product launch, mapping competitors' patent filings, summarising what a patent actually claims, or screening a brand name before adopting it.
+license: MIT
+compatibility: Any Agent Skills host. Needs network access to the public patent and trademark databases. Not legal advice; novelty, patentability, infringement, validity and registrability opinions need a qualified patent attorney or trademark lawyer.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: compliance
+  kete-loom/risk: network
+  kete-loom/owner: "Kete-org"
+---
+
+# Patent and trademark research
+
+Find the documents a professional should look at, explain what they claim in plain language, and hand over a search record they can rely on. You produce leads and summaries; you never give an opinion that something is patentable, infringing, invalid, or free to use.
+
+## Attorney-review gate
+
+Every output carries: `Search leads only, not a legal opinion. Have a registered patent attorney or agent (or a trademark lawyer for marks) review before any filing, launch or licensing decision.`
+
+**Stop and tell the user they need a qualified professional now** when:
+
+- They plan to file, launch, invest, or respond to a demand letter based on the result.
+- A lead looks close to their product or invention (a claim where most elements seem present). Do not write an infringement or validity analysis; list the lead and say why it needs review.
+- They received a cease-and-desist, an infringement claim, or an office action.
+- They ask whether they can safely use a mark or a technology.
+
+Also warn the user, before they describe an unfiled invention: public disclosure can destroy patent rights in many countries (Europe has no general grace period; the US has a limited one-year inventor grace period). Keep details in a confidential setting and do not paste unpublished invention details into services the user has not approved.
+
+## 0. Define the question
+
+Ask, then restate:
+
+1. Search type: novelty or prior art (before filing), freedom to operate (FTO, before launch), landscape (who files what), single-patent summary, or trademark knockout.
+2. The invention or product as features: what it is, the problem it solves, how it works, each technical feature separately.
+3. Jurisdictions that matter (where they will file, make or sell). FTO is per country: only patents in force there matter.
+4. Dates: the user's earliest filing or disclosure date for novelty; launch date for FTO.
+
+## 1. Build the search
+
+1. Split the invention into 3 to 6 key concepts. For each, list synonyms, broader and narrower terms, and how a patent drafter would say it ("fastening member" for "screw").
+2. Find the CPC classes: search keywords, open the most relevant hits, note the CPC codes they share, then read the class definitions on the CPC scheme (cooperativepatentclassification.org) to confirm. Search by class and keyword together.
+3. Run the search in at least two databases. What each one is good for, and query syntax, are in `references/databases-and-queries.md`.
+4. Follow citations both ways from the best hits (what they cite, and what cites them), and check the family to find versions in other languages and jurisdictions.
+5. Record every query, database, date and number of hits. A search nobody can repeat is worth little.
+
+Remember the blind spot: applications usually publish about 18 months after their earliest priority date, so the most recent filings cannot be found yet.
+
+For novelty, prior art also includes non-patent literature: papers, standards, product manuals, websites. Search those too (for example Google Scholar) and note the publication date.
+
+## 2. Screen and read
+
+1. Screen titles, abstracts and drawings first; keep anything plausibly relevant.
+2. For each kept document, read the **claims**, not the abstract. The claims define the rights; the description only explains them.
+3. Find the independent claims (those that do not refer to another claim). Break each into elements (preamble, then each "comprising" feature).
+4. Make a claim chart: one row per element, with where the same feature appears in the user's product or invention (for FTO) or in the prior art (for novelty). Mark each as `present`, `absent`, or `unclear`. This is a reading aid for the attorney, not a conclusion.
+5. Note claim language that matters: "comprising" (open) versus "consisting of" (closed), means-plus-function language, numeric ranges.
+
+## 3. Check status and dates
+
+For each lead that matters for FTO:
+
+- Granted or only an application? Applications are not enforceable until granted, and pending claims can change.
+- Legal status: in force, lapsed for non-payment, expired, withdrawn, revoked. Use the official register (EP Register, USPTO Patent Center, national registers) and Espacenet's INPADOC legal status; Google Patents' status is a hint, not a record.
+- Expiry: usually 20 years from the patent's filing date (in the US, from the earliest US non-provisional or PCT application whose benefit it claims; provisionals and foreign Paris Convention priority do not start the clock), adjusted for term adjustments, extensions, terminal disclaimers and lapses. Give the estimate with the reasoning, and say a professional must confirm it.
+- Where it is in force: list the family members and their countries.
+
+## 4. Trademark knockout screen
+
+1. Identify the goods and services and their Nice classes.
+2. Search identical and similar marks (spelling variants, sound-alikes, translations, design elements) in the target registers: USPTO Trademark Search (tmsearch.uspto.gov), EUIPO and national offices through TMview, and the WIPO Global Brand Database, plus common-law use (web, app stores, company registries, domain names).
+3. List live marks in the same or related classes as conflicts to review; note dead marks separately.
+4. A clean knockout screen does not mean the mark is available; a full clearance search and lawyer opinion are needed before launch.
+
+## Rules
+
+- Never say something is "new", "patentable", "not infringing", "invalid" or "free to use". Say what you found and what needs review.
+- Never rely on the abstract or title for what a patent covers; read the claims.
+- Never state a legal status or expiry date without the source and the date checked.
+- Do not paste confidential invention details into a public search tool the user has not approved; search with generic concept terms.
+- Quote claims exactly when you cite them, with the publication number and claim number.
+
+## Report
+
+```
+Search: <type> | question: <one line> | jurisdictions: <list> | date run: <date>
+Search log: database | query | hits | reviewed
+Leads (most relevant first):
+  <pub number> | title | assignee | priority date | status (source, date) | est. expiry | CPC | why relevant
+  Claim chart for independent claim <n>: element | present / absent / unclear | where
+Trademark screen: mark | register | class | status | similarity note
+Gaps: unpublished applications, databases not searched, non-patent literature not covered
+Search leads only, not a legal opinion. Needs review by a registered patent attorney or trademark lawyer.
+```

package/skills/patent-research/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Before we file, search Espacenet and Google Patents for prior art on our self-cleaning water bottle cap",
+    "We launch a smart thermostat in the US and Germany next year, find patents in force that could block it",
+    "Summarise what claim 1 of US patent 10,123,456 actually covers and when it expires",
+    "Map which competitors are filing patents in CPC class H01M 10 for battery cooling",
+    "Screen the brand name Lumora for conflicting trademarks in class 9 and 42 before we adopt it"
+  ],
+  "should_not_trigger": [
+    "Draft an NDA to share our invention with a manufacturer",
+    "Add an open source licence and NOTICE file to our repository",
+    "Check our npm dependencies for licences that conflict with commercial use",
+    "Write the brand voice guidelines for our new product line",
+    "Classify our products with HS codes for export to Canada"
+  ]
+}

package/skills/patent-research/references/databases-and-queries.md

@@ -0,0 +1,52 @@
+# Databases and query patterns
+
+Read this when building a search (section 1). Syntax changes; if a query fails, check the database's own help page and note the syntax you used in the search log.
+
+## Patent databases
+
+| Database | URL | Best for |
+|---|---|---|
+| USPTO Patent Public Search | ppubs.uspto.gov | full text of US grants and published applications; Basic and Advanced search with field codes |
+| USPTO Patent Center | patentcenter.uspto.gov | US file wrappers, status, fees paid |
+| Global Dossier | via the USPTO site | file histories across the main patent offices for one family |
+| EPO Espacenet | worldwide.espacenet.com | worldwide coverage, families (simple and INPADOC), CPC browsing, INPADOC legal status |
+| European Patent Register | register.epo.org | authoritative status of European applications and patents |
+| Google Patents | patents.google.com | fast full-text search with machine translation, CPC filters, citations, "similar documents"; status is not authoritative |
+| WIPO PATENTSCOPE | patentscope.wipo.int | PCT international applications, national collections, cross-lingual search |
+| CPC scheme | cooperativepatentclassification.org | class definitions and titles (CPC is run jointly by the EPO and USPTO) |
+
+## Trademark databases
+
+| Database | URL | Notes |
+|---|---|---|
+| USPTO Trademark Search | tmsearch.uspto.gov | replaced TESS in November 2023; different syntax from TESS |
+| TMview | via tmdn.org | EUIPO and many national and international registers in one search |
+| WIPO Global Brand Database | branddb.wipo.int | international registrations (Madrid) and many national collections |
+| Nice Classification | WIPO site | goods and services classes; check the edition in force |
+
+## Query patterns
+
+Build each query as concept blocks joined with AND, synonyms inside a block joined with OR, and a class block when you have one.
+
+Espacenet Smart search (field identifiers such as `ti` title, `ab` abstract, `ta` title or abstract, `cl` claims, `cpc` classification, `pa` applicant, `pd` publication date; `txt` covers different fields in different interfaces, and a `/low` qualifier widens a CPC symbol to its child groups; check the current help page):
+
+```
+ta=(drone OR "unmanned aerial") AND ta=(parcel OR package) AND cpc=B64U
+pa="acme" AND pd>=2018
+```
+
+Google Patents (search box terms plus filters; `cpc:B64U` includes child codes, `CPC=B64U/low` is the field form; `TI=`, `AB=`, `CL=`, `TAC=` restrict to title, abstract, claims or all three; the advanced form shows the date and country syntax it generates):
+
+```
+(drone OR "unmanned aerial vehicle") (parcel OR package) (winch OR tether)
+cpc:B64U  before:priority:20200101  country:US,EP
+```
+
+USPTO Patent Public Search: use the Advanced search with field codes (for example `.ti.` title, `.ab.` abstract, `.clm.` claims, `.cpc.` classification) and proximity operators such as `ADJ`, `NEAR` and `SAME`; the system's help lists the full set.
+
+## Tips
+
+- Start broad, then add a block at a time; record hit counts at each step.
+- Search claims text separately for FTO; a feature that appears only in the description is not claimed.
+- Use applicant searches for competitors, then harmonise name variants (subsidiaries, old names).
+- Check translations of non-English hits before dismissing them.

package/skills/paystack-integration/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: paystack-integration
+description: Builds and reviews Paystack payment integrations, including transaction initialisation, server-side verification, webhooks with HMAC-SHA512 signature checks, idempotent fulfilment, and Ghana mobile money (MTN, Telecel, AT) charges. Use when adding Paystack checkout, card or mobile money payments, handling Paystack webhooks, or debugging a Paystack payment flow.
+license: MIT
+compatibility: Any Agent Skills host. Needs network access to api.paystack.co for live calls. Examples are TypeScript (Node 18+); the rules apply to any backend language.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: integrations
+  kete-loom/risk: network
+  kete-loom/owner: "Kete-org"
+---
+
+# Paystack integration
+
+Build a payment flow that can't be faked from the browser and never gives value twice. These rules cover cards, bank and mobile money.
+
+## Ground rules
+
+1. **The secret key stays on the server.** Read it from the environment (`PAYSTACK_SECRET_KEY`). Only the public key (`pk_...`) may reach the browser or app.
+2. **Amounts are in the currency's subunit**: pesewas for GHS, kobo for NGN, cents for USD, KES and ZAR. GHS 25.50 is `2550`. Use integers, never floats.
+3. **The server decides the price.** Compute the amount from your own database (order total, plan price). Never trust an amount sent by the client.
+4. **Value is given only after verification.** Either a webhook with a valid signature, or a call to the Verify Transaction endpoint, must confirm `status: "success"` **and** that the amount and currency match what you expected.
+5. **Fulfilment is idempotent.** Store the `reference` with a unique constraint and process each reference once, because Paystack retries webhooks and users refresh pages.
+6. **Test keys first.** Use `sk_test_` / `pk_test_` until the full flow, including failures, works end to end.
+
+## Flow
+
+```
+client ──(order id)──▶ server: create order, compute amount, POST /transaction/initialize
+server ──(authorization_url or access_code)──▶ client: redirect or open Popup
+customer pays on Paystack
+Paystack ──(charge.success webhook)──▶ server: verify signature, verify amount, fulfil once
+client returns to callback_url ──▶ server: GET /transaction/verify/:reference, show result
+```
+
+The callback page only *shows* status. Fulfilment happens in the webhook (or a verify call), guarded by the idempotency check, so it is safe whichever arrives first.
+
+## Implementation steps
+
+1. **Initialise** with `POST https://api.paystack.co/transaction/initialize`, `Authorization: Bearer <secret key>`, and a body containing `email`, `amount` (subunit), `currency`, a `reference` you generate and store, `callback_url`, and `metadata` (for example the order id). See `references/api.md` for request and response shapes.
+2. **Webhook endpoint**: follow `references/webhooks.md` exactly. Verify the signature on the **raw** body, return `200` quickly, and do the work asynchronously.
+3. **Verify** with `GET https://api.paystack.co/transaction/verify/:reference` on the callback page and as a fallback when no webhook arrives.
+4. **Mobile money (Ghana)**: use the Charge API or the standard checkout, and follow `references/mobile-money.md` for the `pay_offline` pending flow and the 180-second approval window.
+5. **Persist** an order and payment record holding `reference`, expected amount and currency, status, the Paystack transaction id, and timestamps.
+
+## Reviewing an existing integration
+
+Check each ground rule above, then look for these common bugs:
+
+- Signature computed over re-serialised JSON instead of the raw bytes.
+- Webhook does heavy work before responding, which causes timeouts and duplicate retries.
+- Fulfilment keyed on `id` from the client, or done in the callback page without verification.
+- Float arithmetic on amounts (`25.5 * 100`), or amounts in cedis instead of pesewas.
+- Secret key committed in code or exposed in a `NEXT_PUBLIC_`/`VITE_` variable.
+- No handling for `failed`, `abandoned` or `reversed` transactions.
+
+## Before you finish
+
+Confirm field names and endpoints against Paystack's current docs at paystack.com/docs when generating new code; this skill gives the rules and the shape, the docs are the final word on the API. Then test: successful payment, declined payment, a duplicate webhook delivery, a webhook with a bad signature (must be rejected), and mobile money approval timing out.

package/skills/paystack-integration/evals/triggers.json

@@ -0,0 +1,14 @@
+{
+  "should_trigger": [
+    "Add Paystack checkout to our Next.js shop so Ghanaian customers can pay",
+    "My Paystack webhook says invalid signature every time, can you fix it?",
+    "Let users pay with MTN MoMo through Paystack in the mobile app",
+    "Customers are getting their orders twice when Paystack retries the webhook"
+  ],
+  "should_not_trigger": [
+    "Integrate Stripe subscriptions into the billing page",
+    "Review my last commit for security vulnerabilities",
+    "Write a blog post about mobile money adoption in West Africa",
+    "Build an invoice PDF generator for the accounting module"
+  ]
+}

package/skills/paystack-integration/references/api.md

@@ -0,0 +1,73 @@
+# Paystack API shapes used by this skill
+
+Base URL: `https://api.paystack.co`. All server calls send `Authorization: Bearer <PAYSTACK_SECRET_KEY>` and `Content-Type: application/json`. Responses look like `{ "status": true, "message": "...", "data": { ... } }`; `status` there means the API call succeeded, not that a payment did.
+
+Confirm fields against paystack.com/docs/api before shipping; this is a working summary.
+
+## Initialise a transaction
+
+`POST /transaction/initialize`
+
+```json
+{
+  "email": "customer@example.com",
+  "amount": 2550,
+  "currency": "GHS",
+  "reference": "ord_8f2c1a",
+  "callback_url": "https://app.example.com/pay/callback",
+  "channels": ["card", "mobile_money"],
+  "metadata": { "order_id": "8f2c1a" }
+}
+```
+
+Response `data`: `authorization_url` (redirect the customer here), `access_code` (for the inline Popup), `reference`.
+
+## Verify a transaction
+
+`GET /transaction/verify/:reference`
+
+Check in `data`:
+
+| Field | Expect |
+|---|---|
+| `status` | `"success"` (others: `failed`, `abandoned`, `reversed`, `pending`) |
+| `amount` | equals the amount you stored, in subunits |
+| `currency` | equals the currency you stored |
+| `reference` | the reference you generated |
+| `id` | Paystack transaction id; store it |
+| `channel` | `card`, `mobile_money`, `bank`, ... |
+
+## Minimal server client (TypeScript)
+
+```ts
+const BASE = 'https://api.paystack.co';
+
+async function paystack<T>(path: string, init: RequestInit = {}): Promise<T> {
+  const res = await fetch(`${BASE}${path}`, {
+    ...init,
+    headers: {
+      authorization: `Bearer ${process.env.PAYSTACK_SECRET_KEY}`,
+      'content-type': 'application/json',
+      ...init.headers,
+    },
+  });
+  const body = await res.json();
+  if (!res.ok || body.status !== true) throw new Error(`Paystack ${path} failed: ${body.message ?? res.status}`);
+  return body.data as T;
+}
+
+export const initialize = (input: object) =>
+  paystack<{ authorization_url: string; access_code: string; reference: string }>('/transaction/initialize', {
+    method: 'POST',
+    body: JSON.stringify(input),
+  });
+
+export const verify = (reference: string) =>
+  paystack<{ status: string; amount: number; currency: string; reference: string; id: number }>(
+    `/transaction/verify/${encodeURIComponent(reference)}`
+  );
+```
+
+## References
+
+Generate references on the server, unique per payment attempt (for example `ord_<orderId>_<random>`). A retry after a failure gets a new reference; the order keeps a list of attempts.

package/skills/paystack-integration/references/mobile-money.md

@@ -0,0 +1,50 @@
+# Ghana mobile money with Paystack
+
+Two ways to accept mobile money:
+
+1. **Standard checkout** (simplest): initialise a transaction with `currency: "GHS"`, and optionally `channels: ["mobile_money"]`. The customer picks the network and approves on their phone. Fulfil from the webhook as usual.
+2. **Charge API** (your own UI): `POST https://api.paystack.co/charge` with your secret key.
+
+## Charge API request
+
+```json
+{
+  "email": "customer@example.com",
+  "amount": 2550,
+  "currency": "GHS",
+  "reference": "ord_8f2c1a",
+  "mobile_money": {
+    "phone": "0551234987",
+    "provider": "mtn"
+  }
+}
+```
+
+Provider codes for Ghana:
+
+| Code | Network |
+|---|---|
+| `mtn` | MTN Mobile Money |
+| `vod` | Telecel Cash |
+| `atl` | AT Money / Airtel Money |
+
+`amount` is in pesewas (`2550` = GHS 25.50).
+
+## Pending flow
+
+1. The response usually has `data.status: "pay_offline"` and a `data.display_text`. Show that text to the customer ("Approve the prompt on your phone...").
+2. The customer has about **180 seconds** to approve on their handset; the networks set this limit.
+3. Wait for the `charge.success` webhook. Do not fulfil on the initial response.
+4. If no webhook arrives within ~180 seconds, call `GET /transaction/verify/:reference`. A failure reason is in `data.message`. Let the customer retry with a **new** reference.
+
+Other statuses you may see on the charge response include `send_otp` and `pending`; follow the `display_text` and the Charge API docs for the submit endpoint each one requires.
+
+## UX notes
+
+- Validate the phone number format before calling the API, and make sure the chosen provider matches the number's network.
+- Show a countdown and a "Check status" button rather than polling Paystack aggressively.
+- Make clear that the customer must approve on their phone, and that no PIN is ever entered in your app.
+
+## Testing
+
+Use test keys and the mobile money test numbers on Paystack's Test Payments page. Cover approved, declined and timed-out approvals.

package/skills/paystack-integration/references/webhooks.md

@@ -0,0 +1,80 @@
+# Paystack webhooks
+
+## What Paystack sends
+
+- `POST` with a JSON body, for example `{ "event": "charge.success", "data": { ... } }`.
+- Header `x-paystack-signature`: HMAC SHA512 of the request body, keyed with your **secret key**, hex encoded.
+- Paystack treats anything other than `200 OK` as a failed delivery and retries. In live mode it retries every 3 minutes for the first 4 tries, then hourly for 72 hours.
+- Paystack documents a fixed set of source IPs you can additionally allow-list; check the webhooks page for the current list.
+
+## Handler rules
+
+1. Read the **raw body bytes** before any JSON parsing. Re-serialising parsed JSON changes whitespace and key order and breaks the signature.
+2. Compute `HMAC_SHA512(secretKey, rawBody)` as hex and compare with the header using a **constant-time** comparison. Mismatch → respond `401` and stop.
+3. Respond `200` immediately after the signature check, then process the event asynchronously (a queue or background job).
+4. In the processor: look up your order by `data.reference`, check `data.status === "success"`, and check `data.amount` and `data.currency` equal what you stored. Then mark the order paid **in the same transaction** as an idempotency check (unique `reference`, or `UPDATE ... WHERE status = 'pending'`).
+5. Log the event id and reference. Never log card data or the secret key.
+
+## Express (TypeScript)
+
+```ts
+import crypto from 'node:crypto';
+import express from 'express';
+
+const app = express();
+const SECRET = process.env.PAYSTACK_SECRET_KEY!;
+
+app.post('/webhooks/paystack', express.raw({ type: 'application/json' }), (req, res) => {
+  const signature = req.header('x-paystack-signature') ?? '';
+  const expected = crypto.createHmac('sha512', SECRET).update(req.body).digest('hex');
+  const valid =
+    signature.length === expected.length &&
+    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
+  if (!valid) return res.sendStatus(401);
+
+  res.sendStatus(200); // acknowledge first
+  const event = JSON.parse(req.body.toString('utf8'));
+  queue.add('paystack-event', event); // process asynchronously and idempotently
+});
+```
+
+## Next.js route handler
+
+```ts
+import crypto from 'node:crypto';
+
+export async function POST(req: Request) {
+  const raw = Buffer.from(await req.arrayBuffer());
+  const signature = req.headers.get('x-paystack-signature') ?? '';
+  const expected = crypto.createHmac('sha512', process.env.PAYSTACK_SECRET_KEY!).update(raw).digest('hex');
+  if (signature.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
+    return new Response('invalid signature', { status: 401 });
+  }
+  const event = JSON.parse(raw.toString('utf8'));
+  await enqueue(event); // keep this fast
+  return new Response('ok', { status: 200 });
+}
+```
+
+## Python (FastAPI)
+
+```python
+import hashlib, hmac, os
+from fastapi import FastAPI, Request, Response
+
+app = FastAPI()
+SECRET = os.environ["PAYSTACK_SECRET_KEY"].encode()
+
+@app.post("/webhooks/paystack")
+async def paystack_webhook(request: Request):
+    raw = await request.body()
+    expected = hmac.new(SECRET, raw, hashlib.sha512).hexdigest()
+    if not hmac.compare_digest(expected, request.headers.get("x-paystack-signature", "")):
+        return Response(status_code=401)
+    enqueue(raw)  # process asynchronously and idempotently
+    return Response(status_code=200)
+```
+
+## Local testing
+
+Webhooks can't reach `localhost`. Use a tunnel (for example `cloudflared` or `ngrok`) and set the tunnel URL in the Paystack dashboard for test mode. Use the dashboard's resend option, or the Webhook Events API, to replay an event and confirm your handler is idempotent.