Rules for changing this repository (package, tests, docs, CI). Not vault workflows — those live in CLAUDE.md / AGENTS.md.
Table of contents
- TL;DR rules of contribution
- Code of conduct
- Dev setup
- Project structure
- Agent instruction files
- Commit + PR rules
- Adding a new adapter
- Static-site error handling
- CLI error strings and the doctor heal catalog
- Privacy rules
- Markdown conventions
- Site look and feel
- Linting
- After you push
- Testing
TL;DR rules of contribution
- One concern per PR. Don't mix a bug fix with a new feature.
- Commit prefixes:
feat:/fix:/docs:/chore:/test:/refactor:/perf:/security:/release:— e.g.feat(v0.7): tool-calling bar chart. - Never commit real session data.
raw/sessions/is gitignored. Fixtures must be synthetic or heavily redacted. - No new runtime deps. Stdlib +
markdownonly. Viewer loads highlight.js from a CDN — no server-side parser needed. - Tests must pass. Run
python3 -m pytest tests/ -qbefore pushing. CIlint-and-testverifies Python 3.12 on both a minimal-deps install and a leg with optional[add]+[graph]extras installed. - Every PR ships docs + CHANGELOG + release-note bullet. For every user-visible change update (a)
CHANGELOG.mdunder## [Unreleased], (b) anydocs/tutorials/*/docs/reference/*/README.md/ inline--helpthat describes the touched surface, and (c) a one-line release-note bullet either in the CHANGELOG entry or in the PR body sogh release createcan pick it up. If the surface you change exists only under## [Unreleased](added or changed since the last release), edit that existing entry so it describes the final behaviour instead of adding a Fixed / Changed entry about it: release notes describe what ships, not how it got there. New Fixed / Changed entries are for behaviour a published release already has. PRs adding a new CLI subcommand, slash command, config key, or lint rule MUST add the matching row todocs/reference/*.mdin the same PR. CI enforces the CHANGELOG check; reviewers check the rest. - Verify old issues before fixing them. Before changing code for a stale issue: (a) reproduce the problem on current
main— shell command, click-path, or test that fails; (b) re-read the issue's linked code paths to confirm they still exist. If the bug is gone, close with a one-line comment citing the commit that resolved it (gh issue close N --reason completed --comment "resolved in <sha>"); if the description is wrong but there's a real bug nearby, file a new precise issue and link to the old one. Never ship a speculative fix — if you can't reproduce, say so in the PR body. - Open an issue first for anything bigger than a one-file fix. Keeps scope aligned.
- Never fail silently in the browser. Every runtime failure in the static site must be visible on the page, not just in the console — see Static-site error handling.
- No personal vault details in PR text. Absolute home paths, OS usernames, vault roots, and personal session examples stay out of PR bodies / commits / CHANGELOG — use placeholders. See Privacy rules.
- Lint before you push.
ruff check llmwiki tests scripts. A committedpre-pushhook checks the Python files in your push; see Linting. - Wait for CI after every push. Local green is not enough — after
git push(new PR or update), watch GitHub Actions on that head SHA, report the result, and fix/repush if anything failed. See After you push. - Product PRs update AWOS notes. When a PR changes
llmwiki/,tests/,.github/workflows/,docs/maintainers/, ordocs/reference/, it must also change something undercontext/. Path filters alone decide when notes are required — there is no label escape hatch. Tutorials, scripts, packaging, guides, examples, and similar areas stay exempt. CI enforces this on every PR. - Rewording user-facing errors updates the doctor heal catalog. Changing exception text, CLI
error:lines, or install/heal hints that users may paste intollmwiki doctor --errorrequires a same-PR update tollmwiki/doctor/heal_kb.jsonso it matches this package’s strings. Prefer durable error codes. Code ↔ catalog drift is a bug. See CLI error strings and the doctor heal catalog.
Code of conduct
Be kind. Respect privacy. Prefer plain English to jargon. No scope creep.
Dev setup
git clone https://github.com/AlexanderMakarov/llm-wiki.git
cd llm-wiki
./setup.sh # installs markdown, scaffolds raw/ wiki/ site/,
# wires the pre-push lint hook
python3 -m pytest tests/ -q
setup.sh points core.hooksPath at the committed .githooks/ directory. If you set the repo up by hand, enable the hook yourself:
git config core.hooksPath .githooks
Requirements:
- Python ≥ 3.12 (
requires-python = ">=3.12"inpyproject.toml). Installs on 3.13+ are accepted; CIlint-and-testverifies 3.12 only, so regressions on newer interpreters are untested until reported. markdown(required — the only runtime dep;graphis an optional extra)ruff(dev — lint)pytest(dev — tests)
No other runtime deps. That's a hard rule. Syntax highlighting runs in the browser via highlight.js loaded from a CDN, so the build pipeline stays stdlib-only.
Project structure
See docs/architecture.md for the full breakdown. TL;DR:
llmwiki/ # Python package
├── cli.py # argparse entry (`llmwiki --help`)
├── convert.py # .jsonl → markdown
├── build.py # markdown → HTML
├── render/ # emitted site assets (css.py, js.py, data.py)
├── agent_kit/ # packaged /wiki-* commands + user skills (`install-agent-kit`)
├── adapters/ # session-store adapters (one per agent)
└── mcp/ # MCP server (stdio transport)
.claude/ # contributor commands, skills, rules (awos, release, …)
.cursor/rules/ # Cursor project rules (allowlisted in .gitignore)
.kiro/steering/ # always-loaded Kiro rules
.githooks/ # committed git hooks (pre-push lint)
docs/ # user-facing + maintainer docs
tests/ # fixtures + tests
context/ # AWOS product/roadmap/specs (contributor tooling only)
context/ is contributor tooling. It holds the AWOS product definition, roadmap, and the per-feature specifications and delivery records that drive /awos:*. It is not part of the llmwiki product, is not shipped in the package, and never appears in a user's vault.
The repository root is not a vault. It carries a .llmwiki-source-checkout marker, and the vault-writing subcommands (init, sync, synth, synthesize, add, build, all, watch) refuse to run against a directory carrying it unless you name a vault — --vault <path> on the command line, or vault.default_path in your gitignored config.json. Use --vault demo for the example vault that ships with the repo, and a throwaway path such as --vault .worktree-vault for scratch runs. Installed packages carry no marker, so this never affects users.
Agent instruction files
This repo serves two audiences. Getting them mixed up is the usual failure mode for agents.
| File / surface | Audience | Role |
|---|---|---|
Root CLAUDE.md, AGENTS.md |
Agents maintaining a user vault | Product schema: raw/ → wiki/ → site/, page formats, ingest/query. Ship with the product. Never put repo/PR/process rules here. |
CONTRIBUTING.md (this file) |
Humans and agents changing llmwiki itself | Authoritative process, privacy, lint, test, and PR rules. |
.claude/rules/contributing.md |
Claude Code | Short pointer; loads when the agent touches listed paths (paths: frontmatter: llmwiki/, tests/, scripts/, docs/, CI/hooks, root build files, etc.). |
.cursor/rules/contributing.mdc |
Cursor | Short pointer; alwaysApply: true. |
.kiro/steering/contributing-rules.md |
Kiro | Short pointer; load: always. |
.cursor/rules/awos-cursor-runtime.mdc |
Cursor | AWOS→Cursor tool mapping (Cursor-specific runtime). Privacy for git artifacts lives in this file (Privacy rules), not a Cursor-only duplicate. |
.kiro/steering/page-format.md, .kiro/steering/verification-rules.md |
Kiro | Vault page format and verification — product schema adjacent, not CONTRIBUTING. |
Root CLAUDE.md / AGENTS.md each carry a short callout that points here when the work is repo code, not a vault.
Rules for maintaining the pointers:
- Pointers, not copies. Distil non-negotiables and link back here. Process rules change in
CONTRIBUTING.mdfirst; update a pointer only when its summary is wrong. - No machine-specific detail in shared rules.
.cursor/*is gitignored except for an allowlist in.gitignore(currentlyrules/contributing.mdc,rules/awos-cursor-runtime.mdc, plus commands/skills/agents/mcp). Local-only Cursor scratch stays untracked. Add a new shared Cursor rule by allowlisting it deliberately. Do not re-introduce Cursor-only copies of process rules that already live in this file — every agent reads CONTRIBUTING.
User-facing /wiki-* slash commands and skills live in llmwiki/agent_kit/ and ship in the package. Contributors who want them locally (so Claude Code discovers /wiki-sync from this clone) run:
python3 -m llmwiki install-agent-kit --dest .claude
That copies commands/ and skills/ under .claude/. Re-run after pulling an upgrade: a copy an older install left behind is reported as outdated and replaced in place, while a file you edited is saved as <file>.bak beside it before the packaged version lands.
Optional: AWOS (spec → hire → implement)
Maintainer loop for Cursor / Claude Code: docs/maintainers/AWOS-CURSOR.md. Install/update with ./scripts/update-awos.sh (Layer A); add --plugin for marketplace extras. Contributor tooling, not the vault schema.
Commit + PR rules
Adapted from the parent Open Source Project Framework:
Identity
git config user.name "Your Name"(use your own GitHub identity)
PR size
- One intent per PR. Don't mix "add a new adapter" with "fix a CSS bug". Split before opening.
- Atomic commits. Each commit tells a clear story; renames isolated from behavior changes.
PR title format
Conventional Commits. Types we accept:
| Type | When | Version bump |
|---|---|---|
feat |
New user-visible capability | minor |
fix |
Bug fix | patch |
chore |
Maintenance, deps, CI, version bumps | patch |
docs |
Docs only | patch |
test |
Tests only | patch |
refactor |
Internal restructuring, no behavior change | patch |
perf |
Performance improvement | patch |
security |
Security fix or hardening | patch |
release |
Version bump + CHANGELOG promotion | — |
Optionally scope with a version: feat(v0.8): tool chart.
Linking issues. Use Closes #<n> in the PR body only when this PR fully completes that issue. If the PR is partial, related, or preparatory, write Relevant to #<n> (or list several) — never Closes / Fixes / Resolves for a partial, or GitHub will auto-close the issue on merge. Judge completeness against the issue's own requested changes and acceptance criteria: work the issue explicitly assigns to another issue is out of its scope, so leaving it undone does not make the PR partial. Over-cautious Relevant to leaves a finished issue open — and the maintainer ready-issue loop waits until it closes.
PR body — pre-merge checklist
Every applicable box must be checked (or have a one-line waiver). .github/PULL_REQUEST_TEMPLATE.md is the authoritative list; it covers:
- One intent (no mixing concerns)
- CI green
- Linked issue —
Closes #Nonly when the PR completes the issue; otherwiseRelevant to #N(or a one-line waiver if no issue) - Conventional-commit title
- Tests added/updated (happy path + edge case)
- CHANGELOG under Unreleased
- Breaking changes flagged + labeled
breaking - No new runtime deps (stdlib +
markdownonly) - AWOS context updated — PRs that change
llmwiki/,tests/,.github/workflows/,docs/maintainers/, ordocs/reference/must also change something undercontext/(no label bypass; tutorials, scripts, and similar paths exempt) - No real session data in
raw/or fixtures - No machine-specific paths or secrets
- Docs updated for user-visible changes
- Release notes drafted — one line fit for the next
gh release create --notes - UI verified in light AND dark mode (for CSS/UI changes) — screenshots attached; match
docs/maintainers/brand-system.md - A11y verified — keyboard nav, focus rings, WCAG 2.1 AA (≥ 4.5:1 contrast)
- Reviewer has read every changed line (no rubber-stamping)
Branch protection
- Default branch is
main; never push directly — PR required. - CI must pass before merge.
- Required check display name
AWOS context updated(job in.github/workflows/pr-lint.yml) must be listed in repo settings → branch protection so a red gate blocks merge. - Branch must be up-to-date with
mainbefore merge.
Adding a new adapter
See docs/framework.md §5.25 Adapter Flow for the full contract. Minimum requirements:
-
One file under
llmwiki/adapters/<agent>.pythat: - SubclassesBaseAdapter- Registers itself via@register("<agent>")- Setssession_store_pathto the agent's default location(s) - DeclaresSUPPORTED_SCHEMA_VERSIONS -
At least one fixture under
tests/fixtures/<agent>/minimal.jsonl— synthetic or heavily redacted. -
One snapshot test under
tests/snapshots/<agent>/minimal.md— the expected markdown output. -
One test under
tests/test_<agent>_adapter.pythat runs the converter against the fixture and diffs against the snapshot. -
One documentation page at
docs/adapters/<agent>.md. -
A CHANGELOG entry under
## [Unreleased]. -
One line in
README.mdunder "Works with".
Cross-platform path requirement
Default store paths (often exposed as default_roots(), default_vault_paths(), or default_session_store_path() on the adapter class) must work on macOS, Linux, and Windows. Two patterns are acceptable:
- Dot-directory (
Path.home() / ".agent" / ...) -- works on all three platforms by default; a single entry is fine. - OS-specific directories (e.g.
~/Library/Application Support/...,~/.config/...,~/AppData/Roaming/...) -- you need at least one entry per platform. Use inline comments to label which path is for which OS.
Never evaluate Path.home() at import time for those defaults — build the list inside a classmethod (or equivalent) so the per-test HOME sandbox in tests/conftest.py applies. Always use Path.home() inside that helper — never hardcode /Users/, /home/, or C:\Users\. The test in tests/test_cross_platform_paths.py enforces cross-platform coverage. An autouse guard in tests/session_store_guard.py fails the suite if code opens, stats, or directory-lists paths under the developer's real session-store prefixes during pytest.
Adapters with no default paths (like pdf, where the user must configure roots) are exempt.
Review checklist for adapter PRs
- [ ] Adapter declares
SUPPORTED_SCHEMA_VERSIONS - [ ] Default paths (classmethod helpers) cover macOS + Linux + Windows (see above)
- [ ] Fixture is under 50 KB and contains no real PII
- [ ] Snapshot test passes locally
- [ ]
docs/adapters/<agent>.mdexists and is linked from README - [ ] Graceful degradation: unknown record types are skipped, not crashed on
- [ ] No new runtime deps introduced
Static-site error handling
The viewer is vanilla JS with no error boundary and no telemetry — a swallowed failure is one nobody ever hears about. A broken search index and an empty corpus can look identical. Rules for any JS the build emits (llmwiki/render/js.py):
- No silent
catch. Report throughwindow.__llmwikiReportError(context, err)— it logs and renders a dismissiblerole="alert"bar. Name the capability that broke ("Related pages unavailable"), not the function. - Say "broken", not "empty". An empty result list must never be the only signal that loading failed; the palette renders a
.palette-noterow instead. - Degrade partially. One missing search chunk drops that project and reports it rather than aborting the whole index.
- Keep the error surface independent of what it reports. The bar is styled inline, so it survives a broken stylesheet.
- Test the failure path — see
tests/test_file_protocol_search.py. - Never
fetchbuild-emitted data. Blocked overfile://, and users do double-clickindex.html. Emit a.jssidecar withwrite_js_sidecar()(llmwiki/render/data.py), load it viawindow.__llmwikiLoadData(url, key).
CLI error strings and the doctor heal catalog
llmwiki doctor heals from a release-shipped catalog (llmwiki/doctor/heal_kb.json) that ships inside the same package version as the code that emits errors. The catalog must describe only current failures of that version — not a museum of retired or deprecated messages from older releases. The default heal loop keys off stable finding ids from detectors and lint; doctor --error matches pasted stderr via fingerprints and patterns against current strings. There is no doctor-specific semantic search. Any drift between code and heal_kb.json is a bug (same-PR miss or stale catalog).
Rules for any PR that changes user-visible failure text in the CLI package (exceptions, error: / hint strings, install_hint prose, migrate/synth refusal messages, and similar):
- Same PR keeps the catalog current. Update the entry’s
message,fix, andpatternsso they match the new wording this package emits. Replace outdated patterns; do not keep retired/deprecated entries or long historical alias lists for removed error text. - Prefer stable codes. New or rewritten errors should include a durable token (catalog
idor an explicit code substring) that detectors and--errorcan key on. Rewords that keep the same failure keep the sameidand refreshpatternsto the current string set. - Split or remove failure modes by editing the live catalog. Splitting one problem into two ⇒ add the new ids and delete the old entry (or rewrite it into one of the new ones). Removing a failure mode from the product ⇒ delete its catalog entry in the same PR. Pastes from older package versions that no longer match fall through to unknown-assist — that is expected.
- Detectors stay consistent with the catalog. Every doctor check or lint→heal mapping that emits an
idmust resolve inheal_kb.json. Every user-facing error string that doctor is expected to match should appear in some entry’spatterns(or be keyed by a stable code the tests assert). Actionable entries need a non-emptyfixand arunnerconsistent with theirtier(guided/ unknown ⇒runner: null). - Do not teach doctor by writing the catalog from a live vault. Unmatched symptoms use the unknown-assist path (anonymized issue draft + AI prompt). Maintainers add real entries in-repo after review — never commit personal vault paths or usernames into
heal_kb.jsonexamples (use<vault>,<user>,<path>). - This is repo process, not vault schema. Keep these rules in
CONTRIBUTING.md(and the short agent pointers that summarize it). Do not put them in rootAGENTS.md/CLAUDE.md— those files describe a user’s wiki loop, not llmwiki development. Agents that start fromAGENTS.mdalready get a pointer here when the work is package code.
Full matching and runner design: context/spec/327-doctor/technical-considerations.md.
Vault I/O scalability
Hot paths (sync, build, Analytics refresh) must care about how many files an operation opens and writes, not only CPU. Prefer a small bounded set of aggregate files under usage/ (or similar) over one metrics file per session or walking every raw/sessions/*.md solely to recompute a headline. Session Tokens (usage/session-tokens.json) are the reference pattern: many session stubs may live inside one JSON file, but the operation still opens O(1) paths. Do not introduce new per-entity files for aggregates on the daily loop without an explicit design review.
Privacy rules
llmwiki processes session transcripts that may contain PII, API keys, file paths, and secrets. These rules are non-negotiable:
- Secret redaction is on by default. API keys, tokens, passwords, and emails are redacted before anything hits
raw/. Home-path usernames stay real unlessredaction.redact_username: true, which you set before sharing or committingraw/or publishing the site. - Never commit real session data.
raw/is gitignored. Fixtures undertests/fixtures/must be synthetic or heavily redacted. - Never commit machine-specific paths. No
.claude/settings.local.json, no.ingestion-state.json, no.framework/, no.temp/. - Privacy grep runs in the test suite (
tests/test_privacy_username.py): tracked.md/.pymust not contain the upstream maintainer's real username (fixtures useUSER). - No telemetry, ever. The tool never calls home.
- Localhost-only binding by default. The server binds to
127.0.0.1unless the user explicitly passes--host 0.0.0.0. - No local vault / personal machine details in PRs or commits. PR bodies, commit messages, issue comments, and CHANGELOG entries must not include absolute home paths, OS usernames, vault roots, or personal session examples. Use placeholders (
/home/USER/…,<vault>,<user>). Ready-to-paste smoke-confirm or live-vault shell blocks in operator chat are not those surfaces — when the real worktree and vault paths are known on this machine, put the real paths in the paste block so the human can run them; redact only when writing text that will be committed or pasted into a PR/issue.
Markdown conventions
Never hard-wrap prose at a fixed column. One paragraph is one line, however long. Line width is the renderer's job, not the file's.
Wrapping is fine inside fenced code blocks, tables, and anywhere the line is not prose.
Site look and feel
Changing how the generated site looks (CSS tokens, typography, colour, motion, export surfaces) must follow docs/maintainers/brand-system.md — that file is the source of truth and is checked against llmwiki/render/css.py by tests/test_brand_system_doc.py. Docs prose voice is separate: docs/style-guide.md.
Linting
ruff check llmwiki tests scripts # lint (must exit 0)
ruff check --fix llmwiki tests scripts # only with an explicit --select for safe families — see below
Ruff config lives in pyproject.toml under [tool.ruff]: line length 120, target py312, selecting E, F, I, B, UP, and PLC0415 (import-outside-top-level). E501 and E402 stay ignored. PLC0415 is enforced everywhere except scripts/** (one-off maintenance scripts; exempt via per-file-ignores).
Run lint before you push. The committed pre-push hook checks the Python files in your push and rejects it on violations; git push --no-verify bypasses it, but say why in the PR. CI runs ruff check llmwiki tests scripts and fails the build on findings.
Agent kit / inner AI markdown. When you change llmwiki/agent_kit/ or inner .claude/skills, .claude/agents, or .claude/commands, run the scoped commands in docs/maintainers/AI-LINTING.md. CI runs the same paths as the AI tooling lint job in .github/workflows/pr-lint.yml.
Do not run bare ruff check --fix. F401 deletes deliberate package-surface re-exports. Prefer mechanical families first (--select UP,I,F541,…), and only run --select F401 after every intentional re-export carries # noqa: F401. Two conventions the linter can't fully check on its own:
- Imports belong at the top of the module. Deferred imports inside a function are legitimate only for (1) an optional extra (
trafilatura,markitdown,graphifyy,networkx, …) or (2) a proven import cycle — and the reason goes in a# noqa: PLC0415comment on the line. Stdlib modules are never deferred. - A deliberate re-export needs
# noqa: F401. Prefer importing from the owning module over growing facade re-exports.ruff --fixwill otherwise delete an import that looks unused in its own module but is part of that module's public surface. - Prefer low-level imports from the owning module. Do not reach for helpers via a high-level facade (
from llmwiki.build import md_to_html) when the symbol lives in a dedicated module.
After you push
Local ruff + pytest are necessary but not sufficient. Coding agents (and humans) working on this repository must wait for GitHub Actions on the pushed head SHA before treating a PR as ready or ending the turn after a push.
- After
git pushthat creates or updates a PR branch, poll checks until they finish (or fail). Do not stop at "pushed successfully." - Prefer:
gh pr checks <n> --watch(orgh run watchfor the latest run on the branch). For a one-shot status:gh pr checks <n>/gh run list --branch <branch> --limit 5. - Report the outcome to the user (green / red / cancelled). If anything required is red, fetch failing logs (
gh run view <id> --log-failedor the job URL), fix, push again, and wait again. - Do not declare the PR merge-ready, ask for review as "done," or move on to unrelated work while required checks are still pending — unless the user explicitly tells you not to wait.
Testing
How to run the suite and what CI gates. Agent-facing quality rules (usefulness, layout, skips, when to write the failing test first) live only in docs/CODING_STANDARDS.md — do not restate them here.
# Everyday unit suite (fast; e2e ignored and @pytest.mark.slow deselected via pyproject addopts)
python3 -m pytest tests/
# Quieter local run
python3 -m pytest tests/ -q
# One file
python3 -m pytest tests/test_convert.py
# Same unit suite + coverage (what CI gates at 87%)
python3 -m pip install -e '.[dev]'
python3 -m pytest tests/ --cov=llmwiki --cov-report=term-missing
# Wall-clock lint_perf budgets — CI runs these on the performance-budget job
python3 -m pytest tests/test_lint_perf.py -m slow -o addopts=
# Smoke checks (not pytest)
python3 -m llmwiki build
python3 -m llmwiki --version
# E2E is separate (needs [e2e] extras + Playwright browsers); not part of the 87% gate
python3 -m pip install -e '.[e2e]'
python3 -m playwright install chromium
python3 -m pytest tests/e2e/
Coverage floor. pyproject.toml sets [tool.coverage.report] fail_under = 87 on llmwiki for the default unit invocation above. CI also reports branch coverage, uploads coverage.xml, and applies the same 87% line floor via scripts/check_unit_coverage.py (see docs/CODING_STANDARDS.md for why). Dropping below 87 fails CI. If a change trips the gate, restore coverage with meaningful tests — or state in the PR body why the drop is justified (deleted surface, moved code, etc.) so reviewers can accept it. E2E stays out of this number (separate workflow).
Suite autouse in tests/conftest.py isolates the default vault and gives every test its own home directory and operator config.json. A test that needs settings prepares them through the settings_sandbox fixture (write_operator, home, …) instead of patching paths or HOME; a pytest run that changes your real config.json, llmwiki's settings in your home directory, or a tracked file fails at the end and lists what changed. Rules: docs/CODING_STANDARDS.md (Isolation).
No unresolved merge conflict markers in commits. Git’s <<<<<<< … / ======= / >>>>>>> … marker lines in any tracked text file fail the No merge conflict markers job in .github/workflows/pr-lint.yml. The changelog “must be updated” check only verifies CHANGELOG.md was touched; it does not validate content.
Every adapter must ship with:
- A fixture (synthetic or heavily redacted)
- A snapshot test
- A graceful-degradation test (passes an unknown record type)