@simpleapps-com/augur-skills 2026.4.8 → 2026.4.10

package/skills/simpleapps/project-defaults/SKILL.md

@@ -24,9 +24,9 @@ All projects live under `~/projects/` in two groups:
 
 - Internal repos go in `~/projects/simpleapps/`
 - Client site repos go in `~/projects/clients/`
-- Workspace files go in `~/projects/workspaces/` — one `.code-workspace` per project
+- Workspace files go in `~/projects/workspaces/`, one `.code-workspace` per project
 
-macOS APFS is case-insensitive by default. `~/Projects/` and `~/projects/` resolve to the same directory. Do NOT flag path casing differences as errors — only flag paths that genuinely do not resolve.
+macOS APFS is case-insensitive by default. `~/Projects/` and `~/projects/` resolve to the same directory. Do NOT flag path casing differences as errors. Only flag paths that genuinely do not resolve.
 
 ## Project Directory Layout
 
@@ -44,7 +44,7 @@ Every project MUST use this layout:
 └── .simpleapps/        # Config, credentials, site profile (not in git)
 ```
 
-The parent `{project}/` is NOT a git repo — it keeps code and wiki side-by-side. The git repo is always at `repo/`. Use `git -C repo` for git operations from the project root.
+The parent `{project}/` is NOT a git repo. It keeps code and wiki side-by-side. The git repo is always at `repo/`. Use `git -C repo` for git operations from the project root.
 
 | Content | Location | Examples |
 |---------|----------|---------|
@@ -53,16 +53,16 @@ The parent `{project}/` is NOT a git repo — it keeps code and wiki side-by-sid
 | Repo `.claude/rules/` | `repo/` | Minimal summaries referencing wiki |
 | Repo `.claude/CLAUDE.md` | `repo/` | Quick reference + wiki links |
 | Active task context | `wip/` | `{issue-number}-{short-desc}.md` files |
-| Temporary files | `tmp/` | Scratch space — commit msgs, PR bodies, intermediate output. Full access. |
+| Temporary files | `tmp/` | Scratch space: commit msgs, PR bodies, intermediate output. Full access. |
 | SimpleApps config | `.simpleapps/` | Settings, site profile, credentials (see below) |
 
 **WIP**: Research, plans, decisions, test results. MUST NOT contain secrets, final docs, or code.
 
-**tmp/**: Fully available for scratch work — commit messages, PR bodies, issue comments, intermediate output, and any throwaway files. Read, write, and delete freely without asking. Create the folder if missing. Clean up files after use.
+**tmp/**: Fully available for scratch work: commit messages, PR bodies, issue comments, intermediate output, and any throwaway files. Read, write, and delete freely without asking. Create the folder if missing. Clean up files after use.
 
 ## Plugin Rules
 
-The plugin ships rule templates in `plugins/simpleapps/rules/` that MUST exist in every project's `repo/.claude/rules/`. Rules are always loaded into context — they enforce baseline guardrails (like git safety) without depending on a skill being invoked. The `/project-init` command copies missing rules from the plugin into the project.
+The plugin ships rule templates in `plugins/simpleapps/rules/` that MUST exist in every project's `repo/.claude/rules/`. Rules are always loaded into context. They enforce baseline guardrails (like git safety) without depending on a skill being invoked. The `/project-init` command copies missing rules from the plugin into the project.
 
 ## .simpleapps/ Configuration
 
@@ -86,7 +86,7 @@ Two scopes, project overrides user:
 | File | Scope | Purpose | Read by |
 |------|-------|---------|---------|
 | `settings.json` | Global + project | Infrastructure config | All skills via project-defaults |
-| `site.json` | Project only | Site profile — defaults, search terms, PII, auth | Skills needing site context |
+| `site.json` | Project only | Site profile: defaults, search terms, PII, auth | Skills needing site context |
 | `basecamp.json` | Global + project | Basecamp MCP credentials | Basecamp MCP server |
 | `augur-api.json` | Global + project | Augur API MCP credentials | Augur API MCP server |
 
@@ -98,11 +98,11 @@ Two scopes, project overrides user:
 }
 ```
 
-Resolution: read `{project}/.simpleapps/settings.json` first, fall back to `~/.simpleapps/settings.json`, fall back to defaults. Field-level override — project wins for any field it defines.
+Resolution: read `{project}/.simpleapps/settings.json` first, fall back to `~/.simpleapps/settings.json`, fall back to defaults. Field-level override: project wins for any field it defines.
 
 ### site.json
 
-One per client project. Consistent structure across all sites — same fields, different values. Replaces the old `{siteId}.json` pattern.
+One per client project. Consistent structure across all sites: same fields, different values. Replaces the old `{siteId}.json` pattern.
 
 ```json
 {
@@ -115,9 +115,9 @@ One per client project. Consistent structure across all sites — same fields, d
 
 ### Rules
 
-- MUST NOT commit `.simpleapps/` to git — contains PII and credentials
-- MUST NOT save site data to wiki or memory — PII
-- MUST NOT create `{siteId}.json` files — use `site.json` instead
+- MUST NOT commit `.simpleapps/` to git. Contains PII and credentials.
+- MUST NOT save site data to wiki or memory (PII)
+- MUST NOT create `{siteId}.json` files. Use `site.json` instead.
 - If old `{siteId}.json` files exist, `/project-init` will flag them for migration to `site.json`
 
 ## Symlink Setup
@@ -180,17 +180,17 @@ Every project SHOULD configure `.claude/settings.local.json` with these deny rul
 
 Why each is denied:
 
-- **`awk`** — Use the Edit tool instead.
-- **`cat`** — Use the Read tool instead.
-- **`cd`** — MUST NOT use in any Bash command, including compound commands (`cd /path && git`). Use `git -C repo` for git, path arguments for everything else. Compound cd+git commands trigger an unblockable Claude Code security prompt that interrupts the user even when `cd` is denied.
-- **`find`** — Use the Glob tool instead.
-- **`for`** — Shell loops are unnecessary; use dedicated tools or make multiple tool calls instead.
-- **`grep`** — Use the Grep tool instead.
-- **`head`/`tail`** — Use the Read tool with `offset` and `limit` parameters instead.
-- **`kill`/`pkill`** — Use `TaskStop` to manage background processes. `TaskStop` cleanly shuts down the task and updates Claude Code's internal tracking.
-- **`rg`** — Use the Grep tool instead (it uses ripgrep internally).
-- **`sed`** — Use the Edit tool instead.
-- **`sleep`** — Unnecessary; use proper sequencing or background tasks.
+- **`awk`**: Use the Edit tool instead.
+- **`cat`**: Use the Read tool instead.
+- **`cd`**: MUST NOT use in any Bash command, including compound commands (`cd /path && git`). Use `git -C repo` for git, path arguments for everything else. Compound cd+git commands trigger an unblockable Claude Code security prompt that interrupts the user even when `cd` is denied.
+- **`find`**: Use the Glob tool instead.
+- **`for`**: Shell loops are unnecessary; use dedicated tools or make multiple tool calls instead.
+- **`grep`**: Use the Grep tool instead.
+- **`head`/`tail`**: Use the Read tool with `offset` and `limit` parameters instead.
+- **`kill`/`pkill`**: Use `TaskStop` to manage background processes. `TaskStop` cleanly shuts down the task and updates Claude Code's internal tracking.
+- **`rg`**: Use the Grep tool instead (it uses ripgrep internally).
+- **`sed`**: Use the Edit tool instead.
+- **`sleep`**: Unnecessary; use proper sequencing or background tasks.
 
 ## Bin Scripts (PATH)
 

package/skills/simpleapps/quality/SKILL.md

@@ -17,8 +17,8 @@ These tools keep codebases healthy. When working in a project, check whether the
 | **Prettier** | Consistent formatting | `.prettierrc*`, `prettier.config.*` | `pnpm format` |
 | **TypeScript** | Type safety | `tsconfig.json` | `pnpm typecheck` |
 | **Vitest** / **Jest** | Tests | `vitest.config.*`, `jest.config.*` | `pnpm test` |
-| **knip** | Dead code — unused exports, deps, and files | `knip.json`, `knip.ts` | `pnpm knip` |
-| **Lefthook** | Pre-commit hooks — run checks before push | `lefthook.yml` | auto on commit |
+| **knip** | Dead code: unused exports, deps, and files | `knip.json`, `knip.ts` | `pnpm knip` |
+| **Lefthook** | Pre-commit hooks: run checks before push | `lefthook.yml` | auto on commit |
 
 Also check `repo/package.json` for scripts containing: `lint`, `format`, `typecheck`, `test`, `check`, `validate`.
 
@@ -38,32 +38,32 @@ If any are missing, flag them:
 
 ```
 Missing quality tooling:
-- [ ] Linting — suggest: eslint / ruff / phpstan
-- [ ] Formatting — suggest: prettier / black / php-cs-fixer
-- [ ] Testing — suggest: vitest / pytest / phpunit
-- [ ] Dead code detection — suggest: knip
-- [ ] Pre-commit hooks — suggest: lefthook
+- [ ] Linting: suggest eslint / ruff / phpstan
+- [ ] Formatting: suggest prettier / black / php-cs-fixer
+- [ ] Testing: suggest vitest / pytest / phpunit
+- [ ] Dead code detection: suggest knip
+- [ ] Pre-commit hooks: suggest lefthook
 ```
 
-Do not install or configure tools without the user's approval. Flag what's missing and explain why it helps — let the user decide.
+Do not install or configure tools without the user's approval. Flag what's missing and explain why it helps. Let the user decide.
 
 ## When to suggest
 
-- **Setting up a new project** — suggest the full set
-- **Reviewing code with unused imports/exports** — suggest knip
-- **Seeing inconsistent formatting** — suggest prettier
-- **No tests for changed code** — suggest vitest
-- **No pre-commit hooks** — suggest lefthook
+- **Setting up a new project**: suggest the full set
+- **Reviewing code with unused imports/exports**: suggest knip
+- **Seeing inconsistent formatting**: suggest prettier
+- **No tests for changed code**: suggest vitest
+- **No pre-commit hooks**: suggest lefthook
 
 ## Fix everything, hide nothing
 
-See work-habits: "Leave it better than you found it" and "Resolve, never hide." Both apply fully to quality checks. Fix every issue regardless of who introduced it. NEVER suppress checks — fix the code.
+See work-habits: "Leave it better than you found it" and "Resolve, never hide." Both apply fully to quality checks. Fix every issue regardless of who introduced it. NEVER suppress checks. Fix the code.
 
 When reviewing code, scan for existing suppressions (`eslint-disable`, `@ts-ignore`, `.skip`, `noqa`, `phpcs:ignore`, etc.) and flag every instance to the user. These are hidden technical debt.
 
 ## pnpm lockfile sync
 
-In pnpm workspace projects, the root `pnpm-lock.yaml` and site-level lockfiles MUST stay in sync. CI uses `--frozen-lockfile` and will reject mismatched lockfiles — this is the most common cause of deploy failures.
+In pnpm workspace projects, the root `pnpm-lock.yaml` and site-level lockfiles MUST stay in sync. CI uses `--frozen-lockfile` and will reject mismatched lockfiles. This is the most common cause of deploy failures.
 
 After ANY `pnpm install`, `pnpm update`, or `pnpm add` in a workspace, run `pnpm install` at the repo root to regenerate the root lockfile. Commit both lockfiles together. If you forget, the next deploy will fail.
 

package/skills/simpleapps/wiki/SKILL.md

@@ -14,15 +14,27 @@ allowed-tools:
 
 The wiki is the **single source of truth** for how a project works. The wiki is the spec; the repo is the implementation.
 
+## Why This Design
+
+The wiki is a **git-backed markdown folder** (`wiki/`) living next to the code repo (`repo/`), read by agents as local files via `Read wiki/*.md`. Every design choice answers a specific failure mode:
+
+- **Markdown in git**: the docs live where the work lives and version alongside the code. Diffs show what changed and why. No login, no API, no stale snapshot.
+- **Separate `wiki/` repo, not embedded in the code repo**: the wiki ships independently of code releases. Doc fixes do not wait on code review cycles, and code commits stay clean of doc noise.
+- **Local file reads, not network fetches**: the agent loads the full wiki at session start with zero latency. No rate limits, no auth, works offline.
+- **20K token budget**: small enough to fit the whole wiki in context while leaving 90% for working memory. Forces ruthless editing; a 200K-token wiki that cannot be loaded helps no one.
+- **Process and principles, not code snippets**: code in the wiki rots the day it is pasted. Link to the source file instead, so the wiki stays true as the code evolves.
+
+The payoff: **the agent and the user share the same model of the project.** Less re-explaining, fewer guesses, fewer "I assumed..." mistakes. Work goes faster because the agent already knows the conventions, and safer because the agent is not improvising decisions the wiki already settled.
+
 ## Token Budget
 
-A wiki MUST NOT exceed **20K tokens** (~15K words, ~60KB). This is 10% of the AI agent's 200K context window — enough for the agent to load the entire wiki at session start while leaving 90% for working context.
+A wiki MUST NOT exceed **20K tokens** (~15K words, ~60KB). This is 10% of the AI agent's 200K context window, enough for the agent to load the entire wiki at session start while leaving 90% for working context.
 
 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. 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.
+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
@@ -34,7 +46,7 @@ When code reveals the wiki is wrong or incomplete, update immediately. The wiki
 
 Wikis are not just for the current project. They build institutional knowledge across the organization:
 
-- **Site → Site**: Other projects using the same tools learn from this wiki. Document what worked, what didn't, and why — future sites benefit from your experience.
+- **Site → Site**: Other projects using the same tools learn from this wiki. Document what worked, what didn't, and why. Future sites benefit from your experience.
 - **Site → Packages**: The packages team reads site wikis to understand real usage patterns, pain points, and gaps. Your wiki helps them build better shared tools.
 - **Packages → Site**: Package docs and conventions flow back into site wikis as shared patterns.
 
@@ -44,15 +56,15 @@ Write as if someone on a different project will read this wiki to understand how
 
 Every page serves junior devs (explanations, examples), senior devs (quick reference, decisions), and AI agents (unambiguous specs, MUST/SHOULD/MAY). Write for all three:
 
-- Lead with a summary — seniors and agents get it fast, juniors get orientation
+- Lead with a summary so seniors and agents get it fast and juniors get orientation
 - Explain *why* before *how*
 - Use tables for reference, code blocks for copy-paste, RFC 2119 keywords for requirements
 - Each page SHOULD be self-contained
-- Follow `simpleapps:writing-style` — token-efficient, action verbs first, no filler
+- Follow `simpleapps:writing-style` for token-efficient prose, action verbs first, no filler
 
 ## Content Rules
 
-- The wiki documents **process and principles**, not code. Minimize code examples — describe the pattern, then link to a real file in the repo that demonstrates it. A link to working code is always better than a pasted snippet that can go stale.
+- The wiki documents **process and principles**, not code. Minimize code examples. Describe the pattern, then link to a real file in the repo that demonstrates it. A link to working code is always better than a pasted snippet that can go stale.
 - If a code block is necessary (e.g., a command to run), keep it to 1-3 lines max.
 - The wiki documents *what* and *why*. The repo is the source of truth for *how*.
 
@@ -63,19 +75,53 @@ Every page serves junior devs (explanations, examples), senior devs (quick refer
 - Links: `[[Page-Name]]` or `[[Display Text|Page-Name]]`
 - Anchor links MUST target specific sections (`[[Versioning#version-bump-procedure]]`), not just pages
 - Repo references: use relative paths (`../../../wiki/Versioning.md`)
-- Default branch: `master` (not `main`)
+- Wiki repo default branch: `master` (GitHub's `.wiki.git` convention; applies to the `wiki/` repo only, not the code repo). Code repos may use `main` or `master`. Check with `git -C repo branch --show-current`.
 
 ## Cross-Linking
 
-Cross-linking is the most important structural feature of a wiki. Without it, a wiki is just a collection of files. With it, a wiki becomes a **knowledge graph** — each link is an attention signal that tells readers (human and AI) "this concept connects to that one."
+Cross-linking is the most important structural feature of a wiki. Without it, a wiki is just a collection of files. With it, a wiki becomes a **knowledge graph** where each link is an attention signal that tells readers (human and AI) "this concept connects to that one."
+
+Pages MUST link to related sections on other pages using `[[Page-Name#section]]`. Link to specific sections, not just pages. Every concept that is explained in more detail elsewhere MUST have a cross-link.
+
+Cross-linking also eliminates duplication. If two pages explain the same concept, one MUST become the source of truth and the other MUST link to it. Never duplicate content across pages; link instead. This keeps the wiki lean and ensures updates happen in one place.
+
+### Link strategy: contextual, not link-farm
+
+A link is only as useful as the words around it. The same rule serves both audiences:
+
+- **Humans** scan anchor text and surrounding prose to decide whether to click. This is basic SEO; descriptive anchors win.
+- **LLMs** weight links via the attention mechanism, which uses the surrounding tokens to decide what the link is about. A bare title in a "Related" list has no context to anchor against.
+
+A link farm starves both readers. Humans see undifferentiated blue text; the LLM sees a list of titles with no relevance signal.
+
+**MUST: place links inline, in the prose, at the moment the concept is mentioned.** That sentence is the link's context for both readers.
+
+```
+✅ Versioning follows [[Versioning#calver|CalVer (YYYY.MM.seq)]]. See the
+   procedure for [[Versioning#version-bump-procedure|bumping all version files together]].
+
+❌ ## Related
+   - [[Versioning]]
+   - [[Deployment]]
+   - [[Architecture]]
+```
 
-Pages MUST link to related sections on other pages using `[[Page-Name#section]]`. Link to specific sections, not just pages. Every concept that is explained in more detail elsewhere MUST have a cross-link. When writing or reviewing a page, actively look for opportunities to connect it to related pages — the denser the link graph, the faster a reader builds understanding.
+**MUST: anchor text describes what the link is about**, not "click here" or "see also" or the bare page title with no context. The reader (human or AI) should understand the destination from the anchor text alone.
 
-Cross-linking also eliminates duplication. If two pages explain the same concept, one MUST become the source of truth and the other MUST link to it. Never duplicate content across pages — link instead. This keeps the wiki lean and ensures updates happen in one place.
+```
+✅ [[Skill-Format#required-frontmatter|the required SKILL.md frontmatter fields]]
+❌ [[Skill-Format|click here]]
+❌ [[Skill-Format]]   ← acceptable if the surrounding sentence supplies the context;
+                       avoid as the only signal.
+```
+
+**SHOULD NOT: create "Related", "See also", or "Further reading" sections as link dumps.** If a connection matters, work it into the prose where it matters. The exception is genuine navigation pages (`Home.md`, `_Sidebar.md`, `llms.txt`); those exist to be link indexes.
+
+When auditing a page, count the trailing-list links vs. inline links. If trailing-list links outnumber inline links, the page is a directory entry, not a knowledge page. Rewrite to put the connections where the reader needs them.
 
 ## Wiki Over Memory
 
-When asked to save, document, or record knowledge — use the wiki, MUST NOT use memory. The wiki is shared across all agents, all projects, and all computers. Memory is personal to one user on one machine — invisible to everyone else.
+When asked to save, document, or record knowledge, use the wiki. MUST NOT use memory. The wiki is shared across all agents, all projects, and all computers. Memory is personal to one user on one machine and invisible to everyone else.
 
 | Knowledge type | Where it belongs |
 |---------------|-----------------|
@@ -87,9 +133,27 @@ When asked to save, document, or record knowledge — use the wiki, MUST NOT use
 | Personal preferences (writing style, response length) | Memory |
 | User role and background | Memory |
 
-If the user corrects your behavior, update the relevant **skill** — not memory. A correction saved to memory only helps one agent on one machine. A correction in a skill helps every agent on every project.
+If the user corrects your behavior, update the relevant **skill**, not memory. A correction saved to memory only helps one agent on one machine. A correction in a skill helps every agent on every project.
+
+If in doubt, it belongs in the wiki or a skill. The cost of putting shared knowledge in memory is that it dies with the session; no other agent, project, or computer will ever see it.
+
+### Versioned sources win over memory
+
+When a recalled memory conflicts with the wiki, a rule, CLAUDE.md, or a skill, you MUST follow the versioned source and ignore the memory. Memory is:
+
+- **Personal**: lives on one machine, invisible to other agents and teammates
+- **Unauditable**: the user cannot easily review or version-control what an agent has saved
+- **Often wrong**: agents save memories from misunderstandings, outdated context, or half-formed rules
+
+Anything checked into git (wiki pages, `.claude/rules/*.md`, `CLAUDE.md`, skills) is the contract. Memory is at most a personal hint. YOU MUST NOT use memory to downgrade, override, or work around a MUST from a versioned source. If memory says X but the wiki says MUST NOT X, the wiki wins, every time.
+
+When you detect a conflict:
+
+1. Follow the versioned source
+2. Remove or rewrite the offending memory file (update `MEMORY.md` index too)
+3. Report the conflict to the user so they know memory was incorrect
 
-If in doubt, it belongs in the wiki or a skill. The cost of putting shared knowledge in memory is that it dies with the session — no other agent, project, or computer will ever see it.
+"The memory told me otherwise" is never a valid reason to deviate from the wiki, a rule, or a skill. If you catch yourself reaching for that reasoning, stop. The memory is the problem, not the directive.
 
 ## Cross-Project Wiki Access
 
@@ -98,16 +162,16 @@ All projects follow the same directory layout (see `simpleapps:project-defaults`
 **Before reading another project's wiki, pull the latest:**
 `git -C {path-to-project}/wiki pull`
 
-**MUST use dedicated tools for cross-project access — MUST NOT use shell commands:**
+**MUST use dedicated tools for cross-project access. MUST NOT use shell commands:**
 - Read files: `Read("{path-to-project}/wiki/Page.md")`
 - Search code: `Grep(pattern: "...", path: "{path-to-project}/repo")`
 - Find files: `Glob(pattern: "{path-to-project}/repo/**/*.ts")`
 
-MUST NOT use `find`, `grep`, `cat`, `ls`, or any shell command to explore other projects. The paths are known — use the dedicated tools directly.
+MUST NOT use `find`, `grep`, `cat`, `ls`, or any shell command to explore other projects. The paths are known; use the dedicated tools directly.
 
 ### Search all wikis
 
-Every wiki on the machine is a local knowledge base. When looking for how something was solved, search across ALL wikis — not just the current project:
+Every wiki on the machine is a local knowledge base. When looking for how something was solved, search across ALL wikis, not just the current project:
 
 1. Read `~/.simpleapps/settings.json` to get `projectRoot`
 2. Pull the latest for all wikis before searching:
@@ -120,19 +184,19 @@ Every wiki on the machine is a local knowledge base. When looking for how someth
 
 Use Glob to discover which projects have wikis: `Glob(pattern: "{projectRoot}/clients/*/wiki")` and `Glob(pattern: "{projectRoot}/simpleapps/*/wiki")`.
 
-The wikis are kept fresh by `/curate-wiki` runs across projects. Searching locally is instant and requires no internet access — the knowledge is already on the machine.
+The wikis are kept fresh by `/curate-wiki` runs across projects. Searching locally is instant and requires no internet access; the knowledge is already on the machine.
 
-**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.
+**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 MUST 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.
+Every project wiki MUST 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 MUST 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` MUST add testing knowledge learned during the session (new edge cases, failure patterns, test data) to the Testing page.
+Every project wiki MUST 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` MUST add testing knowledge learned during the session (new edge cases, failure patterns, test data) to the Testing page.
 
-A good Testing page covers: test tiers (automated vs manual), test data (items, accounts, cards), and an E2E checklist organized by page area (homepage, listing, detail, cart, checkout, etc.). Each checklist item is a concrete, verifiable condition — not vague ("works") but specific ("price shows $9.26").
+A good Testing page covers: test tiers (automated vs manual), test data (items, accounts, cards), and an E2E checklist organized by page area (homepage, listing, detail, cart, checkout, etc.). Each checklist item is a concrete, verifiable condition, not vague ("works") but specific ("price shows $9.26").
 
 ## Keep It Lean
 
@@ -143,7 +207,7 @@ A good Testing page covers: test tiers (automated vs manual), test data (items,
 
 ## Maintenance
 
-Cross-check wiki against code before updating. Staleness-prone: versions, file counts, CI workflows, TODO markers, API surfaces. **Never echo what the wiki says — read the code, then write.**
+Cross-check wiki against code before updating. Staleness-prone: versions, file counts, CI workflows, TODO markers, API surfaces. **Never echo what the wiki says. Read the code, then write.**
 
 When adding/removing pages, MUST update: `Home.md`, `_Sidebar.md`, `llms.txt` (if present).
 

package/skills/simpleapps/work-habits/SKILL.md

@@ -11,7 +11,7 @@ Do not add features, refactor surrounding code, or "improve" beyond the request.
 
 ## Use the right tool
 
-Prefer dedicated tools over Bash equivalents — they are faster, need no permissions, and produce cleaner output:
+Prefer dedicated tools over Bash equivalents. They are faster, need no permissions, and produce cleaner output:
 - Read not `cat`/`head`/`tail`
 - Grep not `grep`/`rg`
 - Glob not `find`/`ls`
@@ -19,11 +19,11 @@ Prefer dedicated tools over Bash equivalents — they are faster, need no permis
 
 Reserve Bash for commands that have no dedicated tool equivalent.
 
-MUST NOT use `cd` in any Bash command — not even in compound commands like `cd /path && git log`. Use `git -C repo` for git, and path arguments for everything else. The `cd` deny rule does not suppress Claude Code's built-in security prompt for compound cd+git commands, so any `cd` usage will interrupt the user.
+MUST NOT use `cd` in any Bash command, not even in compound commands like `cd /path && git log`. Use `git -C repo` for git, and path arguments for everything else. The `cd` deny rule does not suppress Claude Code's built-in security prompt for compound cd+git commands, so any `cd` usage will interrupt the user.
 
 ## Check site.json first
 
-Before asking the user for credentials, tokens, siteId, domain, or any site-specific configuration, read `.simpleapps/site.json`. It is the single source of truth for site-level data — credentials, auth tokens, defaults, and identifiers. If what you need is not there, ask the user to add it to `site.json` rather than providing it in chat (chat data is ephemeral; `site.json` persists across sessions).
+Before asking the user for credentials, tokens, siteId, domain, or any site-specific configuration, read `.simpleapps/site.json`. It is the single source of truth for site-level data: credentials, auth tokens, defaults, and identifiers. If what you need is not there, ask the user to add it to `site.json` rather than providing it in chat (chat data is ephemeral; `site.json` persists across sessions).
 
 ## Read the error first
 
@@ -42,15 +42,41 @@ Code that compiles is not code that works. After making changes, verify they act
 
 1. Run tests (`pnpm test` or equivalent)
 2. If the project has a Testing page in the wiki, suggest `/verify` to walk through the E2E checklist in the browser
-3. If you changed UI, check it visually — load the page in Chrome and confirm it looks right
+3. If you changed UI, check it visually. Load the page in Chrome and confirm it looks right.
 
-YOU MUST NOT mark work complete without verification. Suggesting `/submit` or `/quality` before verifying the code works is backwards — broken code that passes lint is still broken code. Verify first, then let the user decide next steps.
+YOU MUST NOT mark work complete without verification. Suggesting `/submit` or `/quality` before verifying the code works is backwards: broken code that passes lint is still broken code. Verify first, then let the user decide next steps.
 
 ## Leave it better than you found it
 
-Every agent interaction should leave the codebase in a better state. If you encounter a broken test, a console error, an error overlay, a lint warning, or any other issue while working — fix it. This applies whether or not you caused it and whether or not it is related to your current task.
+Every agent interaction should leave the codebase in a better state. If you encounter a broken test, a console error, an error overlay, a lint warning, or any other issue while working, fix it. This applies whether or not you caused it and whether or not it is related to your current task.
 
-Do not classify issues as "pre-existing" to justify skipping them — context compaction erases your memory of changes made earlier in the session, so what looks pre-existing is often something you introduced. Even if you truly did not cause it, the goal is zero issues, not blame assignment. Fix it anyway. Do not argue with the user about whether an issue is yours to fix. It is.
+Do not classify issues as "pre-existing" to justify skipping them. Context compaction erases your memory of changes made earlier in the session, so what looks pre-existing is often something you introduced. Even if you truly did not cause it, the goal is zero issues, not blame assignment. Fix it anyway. Do not argue with the user about whether an issue is yours to fix. It is.
+
+## Versioned sources win over memory
+
+When a recalled memory conflicts with the wiki, a `.claude/rules/*.md` file, `CLAUDE.md`, or a skill, YOU MUST follow the versioned source and ignore the memory. Memory is personal, unauditable, and often wrong. Agents save memories from misunderstandings or outdated context, and the user cannot easily review what's been saved.
+
+Anything checked into git is the contract. Memory is at most a personal hint. "My memory says otherwise" is never a valid reason to deviate from a wiki page, a rule, or a skill. If you catch yourself reasoning that way, the memory is the problem.
+
+When you detect a conflict: follow the versioned source, remove the offending memory file (and its `MEMORY.md` entry), and report the conflict so the user knows.
+
+See `simpleapps:wiki` "Wiki Over Memory" for the full priority rules.
+
+## RFC 2119 keywords are binding
+
+When a wiki page, skill, rule, spec, or issue uses MUST, MUST NOT, SHALL, or SHALL NOT, you MUST comply literally. YOU MUST NOT downgrade a MUST to a SHOULD because:
+
+- it would take longer
+- an example in the current session shows otherwise
+- the codebase appears inconsistent
+- you judge the requirement unnecessary
+- it is inconvenient
+
+If a MUST seems wrong, impossible, or in conflict with another MUST, STOP and ask the user. Do not silently relax it and proceed. The writer chose the keyword deliberately; overriding it is the agent substituting its judgment for the writer's. SHOULD allows deviation only with a factual justification about the current situation. Convenience and time pressure are never valid justifications.
+
+Session examples do not override written directives. If code in the session contradicts a MUST from the wiki or a skill, the session code is the problem. Flag it, do not use it as permission to violate the MUST.
+
+See `simpleapps:writing-style` for the full reading-compliance rules.
 
 ## Resolve, never hide
 
@@ -62,15 +88,19 @@ When a check fails, the solution is ALWAYS to fix the underlying code. NEVER:
 - Suppress warnings, lower coverage thresholds, or modify quality configs
 - Add `--no-verify`, `--force`, or flags that bypass checks
 
-These actions hide problems — they do not fix them. If a rule or test seems wrong, investigate why it exists before concluding it should change. Rules exist for reasons. If after investigation it genuinely does not apply, explain the reasoning to the user and let them decide — do not unilaterally disable it.
+These actions hide problems; they do not fix them. If a rule or test seems wrong, investigate why it exists before concluding it should change. Rules exist for reasons. If after investigation it genuinely does not apply, explain the reasoning to the user and let them decide. Do not unilaterally disable it.
+
+## Check the branch before non-trivial work
+
+Several lifecycle commands (`/wip`, `/investigate`, `/implement`, `/submit`) repeat the same check: run `git -C repo branch --show-current` and warn the user if the branch is unexpected (not `main`, not a feature branch named after the issue). This is a shared hygiene step. If you find yourself doing meaningful work on an unexpected branch, stop and confirm with the user before continuing. Branching mistakes compound silently.
 
 ## Track progress
 
-Use TodoRead/TodoWrite on multi-step tasks. Mark items in-progress before starting, completed after verifying.
+Use TaskCreate/TaskUpdate/TaskList on multi-step tasks. Mark items in_progress before starting, completed after verifying. Do NOT batch completions; update each task as it finishes so the list reflects real state.
 
 ## Never prompt for git actions
 
-MUST NOT ask "want me to commit?", "should I submit?", "ready for a PR?", "want me to push?", or ANY variation after completing work. Do not hint at it either — "if you're happy with this, you can run /submit" is the same thing with extra words. The user knows their own workflow. They will say "commit", `/submit`, or equivalent when they are ready.
+MUST NOT ask "want me to commit?", "should I submit?", "ready for a PR?", "want me to push?", or ANY variation after completing work. Do not hint at it either: "if you're happy with this, you can run /submit" is the same thing with extra words. The user knows their own workflow. They will say "commit", `/submit`, or equivalent when they are ready.
 
 After completing work: report what changed, suggest `/verify` if untested, then stop. That is the entire post-work protocol. No git prompts. No shipping suggestions.
 
@@ -82,12 +112,12 @@ After completing work: report what changed, suggest `/verify` if untested, then
 
 ## Be persistent with browser automation
 
-When using Chrome tools, do not give up after the first failure. Pages are dynamic — elements may not be visible yet, selectors may need adjusting, or the page may need time to load.
+When using Chrome tools, do not give up after the first failure. Pages are dynamic: elements may not be visible yet, selectors may need adjusting, or the page may need time to load.
 
-Accessibility features make sites machine-readable — the same semantic HTML, ARIA labels, landmark roles, and alt text that help screen reader users also help you navigate pages during Chrome automation. When looking for elements, prefer ARIA roles and labels over brittle CSS selectors. When reviewing or writing frontend code, strong accessibility is not just a user concern — it directly improves your ability to automate and verify the site, and search engines benefit from the same semantic signals.
+Accessibility features make sites machine-readable. The same semantic HTML, ARIA labels, landmark roles, and alt text that help screen reader users also help you navigate pages during Chrome automation. When looking for elements, prefer ARIA roles and labels over brittle CSS selectors. When reviewing or writing frontend code, strong accessibility is not just a user concern; it directly improves your ability to automate and verify the site, and search engines benefit from the same semantic signals.
 
 Before giving up on a browser task:
-- Look for ARIA labels, roles, and semantic elements first — they are the most reliable selectors
+- Look for ARIA labels, roles, and semantic elements first; they are the most reliable selectors
 - Try a different selector or approach (text search, CSS selector, coordinates)
 - Scroll to reveal elements that may be off-screen
 - Wait for the page to finish loading, then retry
@@ -98,9 +128,9 @@ Two failed attempts with the *same* approach means change strategy, not stop ent
 
 ## Good enough is done
 
-Working code that meets the requirements is good enough — ship it. Do not chase diminishing returns by over-polishing, refactoring working code, or improving what already works. The cost of continued refinement exceeds its value. Stop when the task is done, not when you run out of improvements to make.
+Working code that meets the requirements is good enough; ship it. Do not chase diminishing returns by over-polishing, refactoring working code, or improving what already works. The cost of continued refinement exceeds its value. Stop when the task is done, not when you run out of improvements to make.
 
-The distinction: polishing task-specific code is local optimization — it makes one site marginally better but does not move the system forward. Extracting custom code into shared packages removes a system constraint — every site that would have reimplemented the same thing benefits. Local optimization is waste. Removing system constraints compounds. Flag extraction opportunities per "Improve the system" below, but do not polish the task code itself.
+The distinction: polishing task-specific code is local optimization. It makes one site marginally better but does not move the system forward. Extracting custom code into shared packages removes a system constraint; every site that would have reimplemented the same thing benefits. Local optimization is waste. Removing system constraints compounds. Flag extraction opportunities per "Improve the system" below, but do not polish the task code itself.
 
 ## Recover from mistakes
 
@@ -108,6 +138,6 @@ Wrong approach? Stop, revert, try differently. Do not keep layering fixes on a b
 
 ## Improve the system, not just the output
 
-Removing daily work is more important than doing daily work. While completing a task, notice friction: unnecessary manual steps, repeated patterns that could be shared, error-prone processes that could be automated, custom code that duplicates a package export. When you spot these, flag them — suggest a package addition, a script, a skill improvement, or a workflow change. The value of eliminating a step that runs every day far exceeds the value of completing it one more time.
+Removing daily work is more important than doing daily work. While completing a task, notice friction: unnecessary manual steps, repeated patterns that could be shared, error-prone processes that could be automated, custom code that duplicates a package export. When you spot these, flag them. Suggest a package addition, a script, a skill improvement, or a workflow change. The value of eliminating a step that runs every day far exceeds the value of completing it one more time.
 
-This is not scope creep on the code. "Do exactly what was asked" still applies to the task. But improving the system the task runs in — making skills clearer, workflows smoother, shared code more complete — is always in scope. File an issue, update a skill, or mention it in your report.
+This is not scope creep on the code. "Do exactly what was asked" still applies to the task. But improving the system the task runs in (making skills clearer, workflows smoother, shared code more complete) is always in scope. File an issue, update a skill, or mention it in your report.

package/skills/simpleapps/workflow/SKILL.md

@@ -14,7 +14,7 @@ allowed-tools:
 1. **Client request** arrives in Basecamp (todo, message, or comment)
 2. **Read and summarize** the Basecamp todo to understand the request
 3. **Create a GitHub issue** with technical details for implementation
-4. **Cross-link** — Basecamp todo URL in the GitHub issue body, GitHub issue URL in Basecamp todo comments
+4. **Cross-link**: Basecamp todo URL in the GitHub issue body, GitHub issue URL in Basecamp todo comments
 5. **Do the work** in code, referencing the GitHub issue
 6. **Report back** through Basecamp for the client; keep implementation details in GitHub
 
@@ -25,9 +25,9 @@ allowed-tools:
 | **Basecamp** | Client-facing | Task requests, status updates, client communication |
 | **GitHub Issues** | Developer-facing | Technical details, implementation, internal findings |
 
-Basecamp todos and GitHub issues SHOULD cross-link (many-to-many — one todo MAY relate to multiple issues and vice versa).
+Basecamp todos and GitHub issues SHOULD cross-link (many-to-many: one todo MAY relate to multiple issues and vice versa).
 
-**Note**: GitHub access is granted on request. If the user does not have repo access, skip steps 3-5 above and use Basecamp only. Do not assume access — check with `gh` or ask the user.
+**Note**: GitHub access is granted on request. If the user does not have repo access, skip steps 3-5 above and use Basecamp only. Do not assume access. Check with `gh` or ask the user.
 
 ## Tooling
 
@@ -50,7 +50,7 @@ gh issue create --repo simpleapps-com/<repo> \
 <basecamp_todo_url>
 
 ## Client
-<client/project name> — <domain> (siteId: <siteId>)
+<client/project name>: <domain> (siteId: <siteId>)
 
 ## Summary
 <technical summary of what needs to be done>
@@ -78,7 +78,7 @@ The full workflow from task to delivery, each step feeding the next:
 | Scaffold | `/wip` | Create a WIP file from Basecamp or GitHub issue |
 | Research | `/investigate` | Explore codebase, update WIP with findings |
 | Align | `/discuss` | Conversational alignment before acting |
-| Build | `/implement` | Execute the plan — code changes only, no commits |
+| Build | `/implement` | Execute the plan: code changes only, no commits |
 | Code checks | `/quality` | Lint, typecheck, test, package freshness |
 | Solution audit | `/sanity-check` | Did we solve the right problem without commission/omission errors? |
 | Browser checks | `/verify` | Walk through wiki's Testing.md checklist in Chrome |
@@ -86,9 +86,9 @@ The full workflow from task to delivery, each step feeding the next:
 | Stage | `/deploy` | Deploy to staging (merge PRs, trigger staging build) |
 | Release | `/publish` | Version bump, tag, release to production (with verification) |
 
-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.
+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.
+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.