@simpleapps-com/augur-skills 2026.3.18 → 2026.3.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simpleapps-com/augur-skills",
-  "version": "2026.03.18",
+  "version": "2026.03.20",
   "description": "Install curated Claude Code skills",
   "license": "MIT",
   "type": "module",

package/skills/simpleapps/augur-packages/SKILL.md

@@ -13,18 +13,18 @@ Shared npm packages for Next.js ecommerce sites and React Native apps. Published
 
 Before writing custom code, check whether a package export already solves the problem.
 
-## Ground Truth: Read the Code
+## Ground Truth: Read the Docs
 
 This skill is a **stub, not an archive**. New packages are created, existing packages gain features, APIs evolve. This skill MUST NOT be treated as the complete picture.
 
-**Always read the installed packages in your project's `node_modules/`:**
+**Always read the installed packages' documentation in `node_modules/`:**
 
 1. Use `Glob("repo/node_modules/@simpleapps-com/*")` to discover ALL available packages — there may be packages not listed here
-2. Read `repo/node_modules/@simpleapps-com/<package>/package.json` for the `exports` field to find available sub-paths
-3. Read files in `repo/node_modules/@simpleapps-com/<package>/dist/` to understand the current API surface
-4. Do NOT look at the source repo or other folders — only read what is installed in your project's `node_modules/`
+2. Read `repo/node_modules/@simpleapps-com/<package>/llms.txt` — machine-readable, lists every export with descriptions and usage examples. This is the fastest path to discovering what exists.
+3. Read `repo/node_modules/@simpleapps-com/<package>/README.md` for full API docs, code examples, and "Replaces" guidance
+4. MUST NOT read `dist/`, `.d.ts`, or compiled JS files to discover capabilities — they are minified, chunked, and incomplete. The README and llms.txt are the source of truth.
 
-When this skill and the installed code disagree, **the installed code wins**. This skill exists to point you in the right direction, not to replace reading the code.
+When this skill and the installed docs disagree, **the installed docs win**. This skill exists to point you in the right direction, not to replace reading the docs.
 
 ## Known Packages
 
@@ -40,13 +40,37 @@ These are starting hints — not a complete list. Always check `node_modules/@si
 
 ## How to Check for Package Solutions
 
-When considering custom code:
+MUST follow this procedure before writing custom code or filing a package issue:
 
-1. Use `Glob("repo/node_modules/@simpleapps-com/*")` to see what's installed
-2. Read the package's `package.json` `exports` and its `dist/` files for available functions, hooks, and components
-3. Look for the hook triple pattern in augur-hooks: `use<Name>`, `get<Name>Options`, `get<Name>Key`
-4. Check augur-web for UI components before building custom ones
-5. Only use what is in your `node_modules/` — do not reference the source repo
+### Step 1: Read llms.txt
+
+For each installed `@simpleapps-com/augur-*` package, read its `llms.txt`:
+```
+Read("repo/node_modules/@simpleapps-com/<package>/llms.txt")
+```
+This lists every export with descriptions and usage examples.
+
+### Step 2: Read README.md for details
+
+If llms.txt shows a relevant export, read the README for full API, code examples, and "Replaces" guidance showing what site code it eliminates.
+
+### Step 3: MUST NOT grep compiled output
+
+MUST NOT read or grep `dist/`, `.d.ts`, `.js`, or any compiled files to discover package capabilities. These are minified build artifacts — unreliable for discovery. The README and llms.txt are the ONLY source of truth.
+
+### Step 4: Before filing a package issue
+
+Before creating an issue on `simpleapps-com/augur-packages` requesting a new feature:
+1. Search ALL package llms.txt files for the function/hook name
+2. Search ALL package README.md files for the concept
+3. If found, the problem is site adoption — not a package gap. Use the existing export.
+
+### Step 5: Before writing custom code
+
+Before creating a custom hook, utility, or action in a site:
+1. Search ALL package llms.txt files for similar functionality
+2. Check the augur-hooks README "Examples" section for the pattern
+3. If a package export exists, use it. If it does not work as expected, file a bug on the package — not a reimplementation in the site.
 
 ## What Stays Site-Specific
 

package/skills/simpleapps/deployment/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: deployment
+description: Project deployment conventions — reads the wiki Deployment page and executes submit, deploy, or publish steps. Refuses to operate without a Deployment page.
+user-invocable: false
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+  - Skill(git-safety)
+  - Skill(conventional-commits)
+  - Skill(github)
+---
+
+First, use Skill("git-safety") to load git guardrails.
+
+# Deployment
+
+This skill reads the project's `wiki/Deployment.md` and executes the steps defined there. Each project defines its own deployment workflow — this skill is the executor, the wiki is the config.
+
+## Deployment Page Format
+
+Every project wiki SHOULD have a `Deployment.md` page with up to three sections:
+
+```
+## Submit
+How to commit and create a PR for review.
+
+## Deploy
+How to deploy to staging.
+
+## Publish
+How to release to production.
+```
+
+Not all projects need all three. Client sites may only have Submit and Deploy. Package repos may have all three.
+
+## How It Works
+
+1. Read `wiki/Deployment.md`
+2. Find the section matching the requested action (Submit, Deploy, or Publish)
+3. If the page or section is missing, **refuse to operate** — tell the user to run `/curate-wiki` to generate it
+4. Execute the steps in that section, respecting git-safety at every git write operation
+
+## Guard Rails
+
+- MUST NOT guess deployment steps — only execute what the wiki defines
+- MUST NOT operate if the Deployment page is missing or the relevant section is absent
+- MUST load git-safety — every git write operation requires user approval
+- `/publish` MUST complete the verification gate before executing (see below)
+
+## Publish Verification Gate
+
+Before executing any Publish steps, MUST:
+
+1. Show the **current version** and the **proposed new version**
+2. Show **what changes** are included since the last release (`git log` from last tag)
+3. Show **CI/test status** if available (`gh run list` or local test run)
+4. Present a summary: version transition, commit count, test status
+5. Require the user to **explicitly confirm** the specific version going to production
+
+This is not just git-safety. It is an active verification checklist — the user MUST see exactly what they are releasing and confirm that specific version.

package/skills/simpleapps/wiki/SKILL.md

@@ -124,6 +124,10 @@ The wikis are kept fresh by `/curate-wiki` runs across projects. Searching local
 
 **What to search for:** testing patterns and checklists, architecture decisions, coding conventions, deployment procedures, and how specific features were implemented. Other sites have already solved many of the same problems — search before building from scratch.
 
+## Deployment Page
+
+Every project wiki SHOULD have a `Deployment.md` page with up to three sections: Submit, Deploy, and Publish. This page defines the project-specific steps that `/submit`, `/deploy`, and `/publish` commands execute. Run `/curate-wiki` to generate it from the codebase — the command scans CI workflows, package.json, deploy scripts, and asks the user about anything it cannot determine. See the `deployment` skill for the expected format.
+
 ## Testing Page
 
 Every project wiki SHOULD have a `Testing.md` page. This is the E2E verification checklist that `/verify` uses to walk through the site in Chrome. The page grows over time — `/curate-wiki` SHOULD add testing knowledge learned during the session (new edge cases, failure patterns, test data) to the Testing page.

package/skills/simpleapps/workflow/SKILL.md

@@ -69,7 +69,7 @@ gh issue create --repo simpleapps-com/<repo> \
 The full workflow from task to delivery, each step feeding the next:
 
 ```
-/triage → /wip → /investigate → /discuss → /implement → /quality → /verify → /curate-wiki
+/triage → /wip → /investigate → /discuss → /implement → /quality → /verify → /submit → /deploy → /publish
 ```
 
 | Phase | Command | What happens |
@@ -81,9 +81,13 @@ The full workflow from task to delivery, each step feeding the next:
 | Build | `/implement` | Execute the plan — code changes only, no commits |
 | Code checks | `/quality` | Lint, typecheck, test, package freshness |
 | Browser checks | `/verify` | Walk through wiki's Testing.md checklist in Chrome |
-| Capture | `/curate-wiki` | Update wiki with session learnings, audit CLAUDE.md/rules |
+| Submit | `/submit` | Commit and create a PR for review |
+| Stage | `/deploy` | Deploy to staging (merge PRs, trigger staging build) |
+| Release | `/publish` | Version bump, tag, release to production (with verification) |
 
-**Key principle:** each session generates knowledge. `/curate-wiki` captures it — including new testing patterns, edge cases, and failure modes discovered during `/implement` and `/verify`. This grows the wiki's Testing.md page over time, making future `/verify` runs more thorough. This is the learning organization in action.
+Not every task uses all steps. Most daily work ends at `/submit`. `/deploy` and `/publish` are used less frequently — `/publish` is intentionally rare and requires explicit verification of the exact version going to production.
+
+The three shipping commands (`/submit`, `/deploy`, `/publish`) read project-specific steps from `wiki/Deployment.md`. They refuse to operate if the Deployment page is missing — run `/curate-wiki` to generate it from the codebase.
 
 Commands like `/research` and `/discuss` can be used at any stage. `/quality`, `/verify`, `/curate-wiki`, and `/wiki-audit` can run independently.
 

package/skills/simpleapps/writing-style/SKILL.md

@@ -60,6 +60,14 @@ Every token costs time, money, and cognitive load. Be concise without losing cla
 
 Default to brief. Expand only when the reader cannot infer meaning from context. Two sentences that answer the question beat two pages that fill the context window.
 
+## Code Style
+
+Use descriptive variable and function names. Abbreviations save keystrokes but cost readability — the human reviewing your output MUST be able to understand the code without deciphering names.
+
+- MUST use full words: `$groupQuantity` not `$gq`, `cartItem` not `ci`
+- Loop counters (`i`, `j`, `k`) and well-known abbreviations (`id`, `url`, `db`) are fine
+- Function names SHOULD describe what they do: `calculateShippingCost` not `calcShip`
+
 ## Claude Code Keywords
 
 Thinking trigger words (`think`, `think hard`, `ultrathink`) are deprecated. Extended thinking is on by default. Use `/effort` (low/medium/high/max) for control.