From simpleapps
Wiki conventions for SimpleApps projects. Covers token budget, writing for three audiences, page conventions, maintenance rules, and git workflow. Use when reading, writing, or auditing wiki content.
npx claudepluginhub simpleapps-com/augur-skills --plugin simpleappsThis skill is limited to using the following tools:
The wiki is the **single source of truth** for how a project works. The wiki is the spec; the repo is the implementation.
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
The wiki is the single source of truth for how a project works. The wiki is the spec; the repo is the implementation.
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)
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
When code reveals the wiki is wrong or incomplete, update immediately. The wiki MUST reflect reality, not aspirations.
Wikis are not just for the current project. They build institutional knowledge across the organization:
Write as if someone on a different project will read this wiki to understand how you solved a similar problem. Tag sections (platform pattern) when the approach applies to all sites using the same stack, and (site-specific) when it's unique to this project.
Every page serves junior devs (explanations, examples), senior devs (quick reference, decisions), and AI agents (unambiguous specs, MUST/SHOULD/MAY). Write for all three:
simpleapps:writing-style — token-efficient, action verbs first, no fillerGetting-Started.md)_Sidebar.md for navigation[[Page-Name]] or [[Display Text|Page-Name]][[Versioning#version-bump-procedure]]), not just pages../../../wiki/Versioning.md)master (not main)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."
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.
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.
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.
| Knowledge type | Where it belongs |
|---|---|
| Behavioral guardrails and corrections | Skill (update the relevant skill) |
| Conventions, patterns, decisions | Wiki |
| Learnings from a task or session | Wiki |
| Architecture and process docs | Wiki |
| How a problem was solved | Wiki |
| 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 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.
All projects follow the same directory layout (see simpleapps:project-defaults). Every project's wiki is at a predictable path relative to the project root: {project}/wiki/. When the user asks you to check another project's wiki or code, use the project-defaults layout to find it.
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:
Read("{path-to-project}/wiki/Page.md")Grep(pattern: "...", path: "{path-to-project}/repo")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.
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:
~/.simpleapps/settings.json to get projectRootgit -C {projectRoot}/clients/*/wiki pull (one call per wiki, not a glob)git -C {projectRoot}/simpleapps/*/wiki pullGrep(pattern: "...", path: "{projectRoot}/clients", glob: "*/wiki/*.md")Grep(pattern: "...", path: "{projectRoot}/simpleapps", glob: "*/wiki/*.md")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.
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.
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 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").
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).
The wiki is a separate git repo at wiki/. No branch protection, no PRs.
git -C wiki add -A
# Write commit message using Write tool → tmp/commit-msg.txt
git -C wiki commit -F tmp/commit-msg.txt
rm tmp/commit-msg.txt
git -C wiki push