@simpleapps-com/augur-skills 2026.4.11 → 2026.4.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simpleapps-com/augur-skills",
-  "version": "2026.04.11",
+  "version": "2026.04.13",
   "description": "Install curated Claude Code skills",
   "license": "MIT",
   "type": "module",
@@ -25,7 +25,7 @@
     "vitest": "^2.0.0"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=24.0.0"
   },
   "scripts": {
     "build": "tsup",

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

@@ -100,6 +100,8 @@ 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.
 
+`.simpleapps/` is gitignored and lives on one machine. MUST NOT store anything here that the team needs to share, anything that should travel with the repo (e.g., wiki token budget overrides; those go in `wiki/Home.md` as HTML comments), or anything that MUST be reproducible on a fresh clone.
+
 ### site.json
 
 One per client project. Consistent structure across all sites: same fields, different values. Replaces the old `{siteId}.json` pattern.

package/skills/simpleapps/quality/SKILL.md

@@ -47,6 +47,31 @@ Missing quality tooling:
 
 Do not install or configure tools without the user's approval. Flag what's missing and explain why it helps. Let the user decide.
 
+## Runtime Freshness
+
+Projects SHOULD target the current Active LTS of their language runtime. Maintenance LTS is acceptable. EOL runtimes SHOULD be flagged.
+
+Runtime freshness is advisory, not a hard failure. Legitimate exceptions exist: libraries with documented compatibility policies, hosting-locked client projects, migration-in-progress repos. Surface findings as a prompt and let the user decide.
+
+Check the current LTS from the language's official schedule, not memory (LTS designations rotate each October):
+
+- Node: https://nodejs.org/en/about/previous-releases
+- Python: https://devguide.python.org/versions/
+- PHP: https://www.php.net/supported-versions.php
+
+### Where to check
+
+- CI matrices in `.github/workflows/*.yml`
+- `engines` in `package.json`
+- `python_requires` in `pyproject.toml` / `setup.py`
+- `require` or `config.platform.php` in `composer.json`
+
+### Prompt template
+
+> "CI matrix includes Node 18 (EOL). Current Active LTS is Node 24. Drop EOL and add current LTS?"
+
+If the user cites a constraint (hosting, compatibility, library support policy), record it in the project's wiki so future sessions see the exception and skip the prompt.
+
 ## When to suggest
 
 - **Setting up a new project**: suggest the full set
@@ -54,6 +79,7 @@ Do not install or configure tools without the user's approval. Flag what's missi
 - **Seeing inconsistent formatting**: suggest prettier
 - **No tests for changed code**: suggest vitest
 - **No pre-commit hooks**: suggest lefthook
+- **CI matrix or `engines` pins an EOL runtime**: suggest dropping it and adding current Active LTS
 
 ## Fix everything, hide nothing
 

package/skills/simpleapps/wiki/SKILL.md

@@ -28,7 +28,18 @@ The payoff: **the agent and the user share the same model of the project.** Less
 
 ## Token Budget
 
-A wiki MUST NOT exceed **20K tokens** (~15K words, ~60KB). The budget is an editing constraint, not a capacity limit. It is small enough that agents load the whole wiki alongside working context with room to spare, small enough that humans actually read and maintain it, and strict enough to force pruning as the project grows.
+The default wiki budget is **20K tokens** (~15K words, ~60KB). The budget is an editing constraint, not a capacity limit. It is small enough that agents load the whole wiki alongside working context with room to spare, small enough that humans actually read and maintain it, and strict enough to force pruning as the project grows.
+
+Projects MAY raise the budget by adding two HTML comment markers near the top of `wiki/Home.md`:
+
+```
+<!-- wiki-token-budget: 25000 -->
+<!-- wiki-token-budget-reason: Complex integration catalog requires extended reference -->
+```
+
+HTML comments are invisible in the rendered wiki but parseable by agents. Storing the override in the wiki itself means it travels with the repo across machines and teammates; `.simpleapps/` and other gitignored local config are NOT acceptable locations because they do not sync.
+
+Raising the budget is its own decision, separate from any other command. MUST NOT raise the budget under the blanket approval of `/curate-wiki`, `/wiki-audit`, or any other command. The user MUST explicitly approve both the **specific new number** and author the **reason** in their own words. `/curate-wiki` surfaces the prompt and performs the edit only after the user names the number and provides the reason. Never raise the budget silently. Never infer a number the user did not state.
 
 Check size: `wc -w wiki/*.md` (multiply by ~1.3 for token estimate)
 
@@ -205,6 +216,91 @@ A good Testing page covers: test tiers (automated vs manual), test data (items,
 - Describe the pattern, give 1-2 examples, point to source for current list
 - Merge overlapping pages, archive obsolete ones
 
+## Progressive Disclosure via Colocated Markdown
+
+When a wiki topic grows detail that is only needed when actively working on that specific code path, relocate the detail into a markdown file colocated with the code. The wiki keeps a summary and a signpost; the colocated file becomes the source of truth. Every-session readers pay only for the summary; on-topic sessions load the full detail on demand.
+
+### When this fits
+
+- Module-level or subsystem depth (attribute system internals, pipeline stages, component APIs)
+- Content needed in a minority of sessions (rule of thumb: under 50%)
+- Detail that changes in the same commit as the code it describes
+
+### When it does not fit
+
+- Orientation, architecture, cross-cutting decisions (keep in the wiki)
+- Deployment, testing, onboarding (these are the wiki's core job)
+- Content not tied to a specific code path
+
+### Location convention
+
+Follow the codebase's existing doc-location convention. Do not impose a new one.
+
+- `<module>/README.md` if the codebase uses per-module READMEs
+- `<dir>/helpers/<topic>.md` if many siblings share a helpers folder
+- `<module>/docs/<topic>.md` for deep subsystems with several topics
+- `docs/<topic>.md` at repo root when the content does not map cleanly to one path
+
+If no convention exists, propose one and match it across similar topics in the same session.
+
+### Signpost format
+
+The wiki MUST link to the colocated file by exact repo path and state the load condition:
+
+```markdown
+## Attributes
+
+One-paragraph summary.
+
+**Detail file:** `repo/src/helpers/attributes.md`
+**Load when:** working in the attribute system (adding, editing, or debugging attributes).
+```
+
+The **Load when** clause is critical: without it, agents either ignore the signpost or load every signposted file at session start, defeating the budget win.
+
+Wiki signposts SHOULD include keywords the agent will recognize when searching or scanning: the subsystem name, common domain terms, the API the subsystem exposes. Keyword-rich signposts increase the chance an agent notices it has landed in a subsystem that has detail docs available, instead of re-deriving everything from code.
+
+### Subsystem doc hierarchies (index + leaves)
+
+Large monorepos often have subsystems with many sibling items (helpers, components, plugin rules, rule engines) where per-item detail has meaningful variance. A single colocated file does not scale; use a nested structure instead.
+
+**Structure:**
+
+- `<subsystem>/README.md` MUST exist as the entry point. It orients the reader, explains the subsystem's purpose and conventions, and indexes the items that have their own detail docs.
+- `<subsystem>/<item>.md` holds detail for individual items that are complex, non-obvious, or have subtle invariants.
+
+**Selection rule for detail docs:** NOT every item gets a doc. Only items where the *why* and *how* pay back the maintenance cost. Items whose name and signature are self-explanatory MUST NOT get a doc; a doc that restates what the code already says is drift waiting to happen.
+
+**Wiki signpost format** when a subsystem uses the nested pattern:
+
+```markdown
+## Attributes (attribute system, helpers)
+
+One-paragraph summary.
+
+**Entry point:** `repo/src/helpers/README.md`
+**Load when:** working in the attribute system — adding, editing, or debugging attributes, or extending the schema. The README indexes per-helper detail docs for complex items.
+```
+
+Keywords in the page heading and the Load-when clause (subsystem name, adjacent terms, verbs that match what the agent is likely doing) help the agent recognize the subsystem on sight. The signpost points at the README, not at every leaf: the README is the hub, and the agent follows it to individual item docs as needed.
+
+**Keep-current at both levels:** editing an item means updating its `.md` if it has one AND updating the README index when the item's entry there is now wrong (new complexity introduced, a doc was added or removed, an item was deleted). See `simpleapps:work-habits` "Leave it better than you found it" for the binding rule.
+
+### Keep-current invariant
+
+Colocated detail files are first-class code artifacts. When working on code that has one, agents MUST read it before editing, update it in the same commit when behavior it describes changes, and fix or flag it if it arrives stale. See `simpleapps:work-habits` "Leave it better than you found it" for the binding rule.
+
+### Migration: topics that already exist in both places
+
+When adopting this pattern for a topic that has a wiki page AND a stale colocated file (common if a colocated doc existed but drifted):
+
+1. Read both. Identify the source of truth by comparing against the code.
+2. Reconcile. Merge current-and-accurate content from both into a single updated version.
+3. Land the reconciled version in the colocated file. It is the source of truth going forward.
+4. Replace the wiki page body with the summary + signpost format above. Same commit (or paired commits across repos) so both sides land together.
+
+After migration, the colocated file wins any conflict with the wiki; the wiki summary gets fixed, not the colocated file.
+
 ## 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.**

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

@@ -52,6 +52,10 @@ Every agent interaction should leave the codebase in a better state. If you enco
 
 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.
 
+**Colocated detail files are first-class code artifacts.** When code has a colocated markdown file (a `README.md`, `helpers/<topic>.md`, `docs/<topic>.md`, or whatever convention the codebase uses) MUST read it before making changes, not after. If your change affects the behavior it describes, update the file in the same commit as the code change. If the file is already stale on arrival (contradicts current behavior before your change), fix or flag it; do not compound the drift. Touching code with a colocated detail file and not keeping the file current is the same category of bug as leaving a test broken.
+
+**Subsystem READMEs count the same way.** When a subsystem uses the index-and-leaves pattern (`<subsystem>/README.md` as entry point, plus per-item `<subsystem>/<item>.md` for complex items), read the README first when landing in the subsystem, then any item doc for the specific thing you are touching. Edits that change the subsystem's shape (add, remove, or significantly alter an item) MUST update the README index, not just the item doc. See `simpleapps:wiki` "Progressive Disclosure via Colocated Markdown" for the wiki-side signpost pattern and the subsystem-hierarchy conventions.
+
 ## 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.
@@ -138,6 +142,8 @@ 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.
+"Improving daily work is even more important than doing daily work." From Gene Kim's *The Phoenix Project* and *The DevOps Handbook*. This is the DevOps discipline we are practicing: continuous feedback, automation over heroics, and reducing the friction of future work as a first-class output of current 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. Eliminating or automating a step that runs every day compounds far beyond 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.

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

@@ -93,6 +93,23 @@ 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.
 
+## Name Sources to Activate Knowledge
+
+A canonical phrase paired with the author and work names a whole discipline's concept cluster in a handful of tokens. For an agent, this shifts the reasoning pool: "improving daily work" alone pulls from a generic improvement cluster; "Gene Kim's *The Phoenix Project*, the DevOps Second Way" activates feedback loops, toil reduction, blameless post-mortems, value streams, and the rest of the adjacent vocabulary. Cheap tokens, richer reasoning.
+
+**When it fits:**
+
+- The named discipline genuinely shapes the work. DevOps in `work-habits`. Goldratt's commission/omission errors in `/sanity-check`. RFC 2119 in `writing-style`. Each one names a body of thought the agent is expected to apply.
+- The attribution is compact: canonical phrase, author, source, and any shared vocabulary needed to anchor the cluster.
+
+**Anti-patterns:**
+
+- **Name-dropping without vocabulary.** "Gene Kim said improvement matters" activates almost nothing; you need the phrase, the work, and the domain terms together to hit the cluster.
+- **Citing disciplines that do not shape the work.** Invoking Agile Manifesto in a Bash-simplicity skill pulls in adjacent but misaligned concepts, and the cost is confused reasoning.
+- **Citing one source to decorate every skill.** If every skill attributes someone, attribution becomes ornamental and the activation effect dilutes. Keep it rare and deliberate.
+
+This is a technique, not a rule. Most skills should not invoke an external discipline at all. Use it when a skill's guidance genuinely derives from a named body of thought, and the agent will reason better for being told which one.
+
 ## Punctuation: Avoid the Em-Dash
 
 The em-dash (`—`) is one of the strongest tells of AI-generated text. LLMs over-produce it dramatically, far beyond how humans punctuate. Readers (especially developers and clients reading client-facing posts) increasingly read em-dashes as "this was written by AI."