@simpleapps-com/augur-skills 2026.3.19 → 2026.3.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simpleapps-com/augur-skills",
-  "version": "2026.03.19",
+  "version": "2026.03.22",
   "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/context-efficiency/SKILL.md

@@ -51,6 +51,10 @@ Load Skill("git-safety") for full guardrails.
 
 The rule costs ~40 tokens per prompt. The skill costs nothing until invoked, then loads ~800 tokens of detailed guidance. This is 20x more efficient than putting the full content in the rule.
 
+### Wiki Links: Highest-ROI Pointer
+
+The cheapest pointer with the biggest payoff is a **wiki link in CLAUDE.md**. A link like `[Deployment](../../wiki/Deployment.md)` costs ~15 tokens but gives the agent instant access to a full page of detailed knowledge (~500-2000 tokens) on demand. CLAUDE.md SHOULD link to every wiki content page — it becomes the agent's table of contents. Missing a link means the agent must guess where to find information or ask the user.
+
 ## When to Use Each Layer
 
 | Question | Answer |

package/skills/simpleapps/deployment/SKILL.md

@@ -44,8 +44,9 @@ Not all projects need all three. Client sites may only have Submit and Deploy. P
 
 ## Guard Rails
 
+- **If `wiki/Deployment.md` does not exist, STOP IMMEDIATELY.** Do not guess, do not improvise, do not infer steps from the codebase. Tell the user to run `/curate-wiki` to generate it. Then do nothing else.
+- **If the relevant section (Submit, Deploy, or Publish) is missing from the page, STOP IMMEDIATELY.** Same rule — do not guess the steps.
 - 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)
 

package/skills/simpleapps/git-safety/SKILL.md

@@ -6,10 +6,43 @@ user-invocable: false
 
 # Git Safety
 
-MUST NOT commit, push, create PRs, or merge unless the user explicitly says to. This applies to ALL repos — the main repo, the wiki repo, and any other git repo. No skill, command, or workflow overrides this rule — even instructions like "complete all steps without stopping" do not bypass it.
+## The Rule
 
-After making changes: **report what was done, then stop.** Do not ask "want me to commit?" or "should I push?" — that wastes tokens. Just report and wait silently. The user will say "commit", "push", or equivalent when ready.
+MUST NOT run any git write operation unless the user explicitly approves it. Git write operations include: `commit`, `push`, `tag`, `merge`, `rebase`, `reset`, `cherry-pick`, `stash`, `branch -D`, and any `gh` command that creates or modifies PRs, issues, or releases.
 
-The pattern is always: **do the work → report results → wait.**
+`git add` (staging) is permitted as part of preparing to show the user what will be committed — but the commit itself requires approval.
+
+No skill, command, or workflow overrides this rule. Even instructions like "complete all steps without stopping" do not bypass it. This applies to ALL repos — the main repo, the wiki repo, and any other git repo.
+
+## Why
 
 Every git push, every PR, every wiki edit that hits GitHub is done under the user's credentials — their name, their reputation. The user is responsible for every action taken on their behalf. That is why they decide when to commit, not the agent.
+
+## How Approval Works
+
+The user gives approval in one of two ways:
+
+1. **Direct instruction** — the user says "commit", "push", "tag", or equivalent
+2. **Shipping commands** — the user invokes `/submit`, `/deploy`, or `/publish`. Invoking the command IS the approval for the git operations defined in that command's workflow.
+
+### Approval is scoped, not blanket
+
+Each approval covers ONE specific operation. Examples:
+
+- The user says "commit" → you may commit the current staged changes. You may NOT also push.
+- The user runs `/submit` → you may execute the Submit steps (commit + push or PR). You may NOT also tag or publish.
+- The user runs `/publish` → you may execute the Publish steps (bump, commit, tag, push). This does NOT carry forward to future commits.
+
+Previous approvals do NOT grant future permissions. If the user approved a commit earlier in the session, that does not mean you can commit again later without asking.
+
+### When /submit follows earlier work
+
+If you made changes and the user then runs `/submit`, the command starts fresh — it reads the Deployment page and follows those steps. There is no conflict with earlier work. The user chose to invoke `/submit` at this moment, and that is all the approval needed for the operations within it.
+
+Do NOT ask for redundant confirmation inside `/submit` if the user just invoked it. The invocation is the approval. But each discrete git operation within the flow (commit, then push) should still be reported before execution.
+
+## The Pattern
+
+**Do the work → report results → wait.**
+
+After making changes: report what was done, then stop. Do not ask "want me to commit?" or "should I push?" — that wastes tokens. Just report and wait silently. The user will say "commit", "push", or run a shipping command when ready.

package/skills/simpleapps/github/SKILL.md

@@ -107,6 +107,8 @@ Before adding a comment to a closed issue, check its state first with `gh issue
 
 ## Cross-Repo Issues
 
+Use `/file-issue` to automate this process — it creates the upstream issue, cross-links back to the local issue, and adds the `blocked` label. `/triage` surfaces blocked issues in its output.
+
 When a project hits a blocker that depends on another team's repo, create two issues and keep working:
 
 1. **Local issue** (in the site/project repo) — describe the impact and what's blocked

package/skills/simpleapps/wiki/SKILL.md

@@ -22,7 +22,7 @@ Check size: `wc -w wiki/*.md` (multiply by ~1.3 for token estimate)
 
 ## Core Principle
 
-Repo files (`.claude/CLAUDE.md`, `.claude/rules/`, `README.md`) MUST be minimal — orient then point to wiki. AI agents read wiki pages as local files via `Read wiki/<page>.md`. No network requests needed.
+Repo files (`.claude/CLAUDE.md`, `.claude/rules/`, `README.md`) MUST be minimal — orient then point to wiki. CLAUDE.md MUST link to every wiki content page — these links cost ~15 tokens total but make every page one Read away from always-loaded context. AI agents read wiki pages as local files via `Read wiki/<page>.md`. No network requests needed.
 
 ```
 Wiki defines → Code implements → Learnings update wiki → Repeat

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.