AGENTS — wiki-llm

1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

Before implementing:

• State your assumptions explicitly. If uncertain, ask.
• If multiple interpretations exist, present them - don't pick silently.
• If a simpler approach exists, say so. Push back when warranted.
• If something is unclear, stop. Name what's confusing. Ask.

2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

• No features beyond what was asked.
• No abstractions for single-use code.
• No "flexibility" or "configurability" that wasn't requested.
• No error handling for impossible scenarios.
• If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

3. Surgical Changes

Touch only what you must. Clean up only your own mess.

When editing existing code:

• Don't "improve" adjacent code, comments, or formatting.
• Don't refactor things that aren't broken.
• Match existing style, even if you'd do it differently.
• If you notice unrelated dead code, mention it - don't delete it.

When your changes create orphans:

• Remove imports/variables/functions that YOUR changes made unused.
• Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

4. Goal-Driven Execution

Define success criteria. Loop until verified.

Transform tasks into verifiable goals:

• "Add validation" → "Write tests for invalid inputs, then make them pass"
• "Fix the bug" → "Write a test that reproduces it, then make it pass"
• "Refactor X" → "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

Mirror: same content as AGENTS.md (canonical for Codex); keep them in sync when changing the tool list or plugin overview. Plugin workflows are maintained in docs/AGENTS.shared.md and synced with bin/llm-wiki sync-agent-docs (or python3 scripts/sync_agent_docs.py).

Repo summary

This repo is the llm-wiki plugin: a Python CLI (bin/llm-wiki), slash-command prompts (commands/), skills (skills/*/SKILL.md), and agent personas (agents/, prompts/PERSONA.md). Vault layout is raw/ (sources) → wiki/ (curated markdown) + optional outputs/ (drafts/reports); see ETHOS.md and WORKFLOWS.md. First-time setup: docs/QUICKSTART.md (vault vs plugin repo, five-minute path, basic/intermediate/advanced tiers).

Common workflows (all tools)

1. CLI — bin/llm-wiki (works from any cwd if invoked by absolute path) or python3 scripts/llm_wiki.py from the repo root for setup, ingest, validate, lint / diff / compile / knowledge-test, raw validate / raw record / raw finish (validate + log + [prepare] commit; raw/memory/ skipped), build-site, graph, git, research-loop, memory {save|log|list|show|recall|prune} (session memory under raw/memory/ when memory.enabled, opt-in), etc. /llm-wiki:setup (see commands/setup.md; full wizard in skills/wiki-setup/SKILL.md) is the slash entry for wiki-setup: combined vault + optional session memory (Section 8c), or vault-only / memory-only tracks. /llm-wiki:configure (see commands/configure.md) is the slash entry for quick config tweaks after setup (MCP wiki_configure, llm-wiki configure -i, or previewed edits). /llm-wiki:status (see commands/status.md) is the slash entry for wiki-status (vault health: MCP wiki_status, llm-wiki integrations status, skill dashboard). (Do not use PYTHONPATH=scripts—relative PYTHONPATH can crash Python 3.14+ at startup; the script adds scripts/ to sys.path automatically.)
2. Commands as prompts — Open commands/<name>.md; same text as /llm-wiki:….
3. Skills — wiki-pipeline (end-to-end vault flow), wiki-maintainer, wiki-ingest, wiki-raw-prepare, wiki-query, wiki-lint, wiki-status, wiki-setup, wiki-research (ad-hoc topic), wiki-research-loop (batch tasks), wiki-retro, wiki-learn (.agent-memory.md), wiki-session-memory (raw/memory/ per-chat notes), wiki-upgrade (plugin repo pull) in skills/*/SKILL.md. Pipeline artifacts: skills/references/pipeline-artifacts.md.
4. Context — WORKFLOWS.md, ETHOS.md, prompts/PERSONA.md.
5. Agent doc sync (this plugin repo only) — After editing docs/AGENTS.shared.md, run bin/llm-wiki sync-agent-docs to refresh AGENTS.md, CLAUDE.md, and rules/llm-wiki.mdc. Before merge, bin/llm-wiki sync-agent-docs --check (or bin/llm-wiki check --plugin-repo) must pass. Equivalent: python3 scripts/sync_agent_docs.py from the repo root. Do not commit a .claude/ tree under the plugin root (except nothing, or only gitignored locals): it prevents Claude Code from loading skills/ in the plugin (anthropics/claude-code#44120).

MCP server: bin/llm-wiki mcp starts a stdio JSON-RPC server (default) exposing vault tools (search, knowledge graph, ingest, validate, session memory, etc.). bin/llm-wiki mcp --transport sse --port 8891 starts an HTTP listener on mcp.host/mcp.port (default 127.0.0.1:8891): POST / or /mcp with a JSON-RPC body, application/json response (stdlib scripts/mcp_sse.py). Plugin marketplace installs auto-register stdio via mcpServers in .claude-plugin/plugin.json and .cursor-plugin/plugin.json. Manual install: bin/llm-wiki mcp install. Config in llm-wiki/config.json: mcp.enabled, mcp.transport (stdio | sse), mcp.port / mcp.host, mcp.search_backend (fts5 default — BM25 via stdlib sqlite3 | grep | chromadb — semantic embeddings; requires pip install chromadb, falls back to grep if missing | hybrid — FTS5 + Chroma reciprocal-rank fusion; requires Chroma, falls back to fts5 if missing), mcp.hybrid_rrf_k (RRF k for hybrid only, default 60), optional mcp.tools_mode / mcp.tools_allowlist / mcp.max_response_chars / mcp.configure_allowlist / mcp.benchmark_tool_enabled / mcp.ingest_enabled / mcp.sse_require_loopback / mcp.sse_token (trust model and HTTP hardening — skills/references/mcp-and-kg.md), knowledge_graph.backend (json | sqlite), knowledge_graph.auto_update_on_ingest (runs kg rebuild after ingest post-processing), memory.enabled / memory.dir / memory.max_sessions (opt-in session memory). Prefer CLI when running locally; use MCP when the host only exposes tools.

Knowledge graph CLI: bin/llm-wiki kg {add|query|invalidate|timeline|stats|rebuild|conflicts} — entity-relationship triples in llm-wiki/.kg.json (default) or .kg.sqlite3 when knowledge_graph.backend=sqlite. Optional knowledge_graph.aliases / allowed_predicates. Shared reference: skills/references/mcp-and-kg.md.

Knowledge compiler: bin/llm-wiki {lint|diff|compile|knowledge-test} (+ MCP wiki_lint, wiki_compile, wiki_knowledge_test). After wiki merge: compile; surgical compile --raw <path>.

Session memory CLI: bin/llm-wiki memory {save|log|list|show|recall|prune} — per-chat files under llm-wiki/raw/memory/ when memory.enabled; hooks write llm-wiki/.current-session for --current.

Benchmark CLI: bin/llm-wiki benchmark {run|suites|report|history|compare|analyze} — retrieval benchmarks (LME / LoCoMo / ConvoMem) and metrics under benchmark.*. Guide: benchmarks/README.md.

Static viewer “Open file”: In llm-wiki/config.json, set viewer.open_file_scheme to cursor or vscode when you want wiki links to open the editor.

Python: Match existing style in scripts/; run tests or python3 -m compileall if you touch CLI code. Personal/demo scripts belong in scripts/.tmp/ (gitignored), not tracked scripts/. Optional pip deps (requirements-optional.txt, e.g. Chroma): use a venv; PEP 668 / externally managed interpreters often block global pip install — see README.

When editing the vault template under templates/llm-wiki/, keep llm-wiki/CLAUDE.md and config.json schema consistent with README.md and WORKFLOWS.md.

How each tool uses this repository

This file (CLAUDE.md) mirrors AGENTS.md for tools that read CLAUDE.md instead of AGENTS.md. Cursor still loads rules/*.mdc automatically when you open the repo; the rule body matches the shared block above.

Claude Code (first-class)

Install the plugin from the marketplace (see README.md), then use /llm-wiki:… commands. Each command’s text lives in commands/<name>.md (same content as the slash command).

Cursor (editor + optional Marketplace plugin)

• Clone and open: Rules live in rules/llm-wiki.mdc. AGENTS.md (this file) is extra context if you paste it or if your team mirrors it into rules.
• Marketplace: Cursor plugins bundle rules, skills, MCP, hooks, subagents (announcement). This repo ships .cursor-plugin/plugin.json next to /.claude-plugin/ so maintainers can submit the same codebase to the Cursor Marketplace (curated review). Until listed, use clone + rules/ like any project.

There is no separate “VS Code extension” for llm-wiki — automation is the CLI + agent instructions above.

OpenAI Codex CLI

Codex loads AGENTS.md before tasks (discovery order). Use bin/llm-wiki from a terminal and commands/*.md as manual prompts. If instructions exceed the byte budget, raise project_doc_max_bytes in ~/.codex/config.toml or .codex/config.toml, or split overrides across nested AGENTS.override.md files.

User projects (after llm-wiki setup)

A scaffolded vault lives under llm-wiki/ with llm-wiki/CLAUDE.md (vault rules). If your tool only reads AGENTS.md at the project root, copy or summarize the relevant rules from llm-wiki/CLAUDE.md so Codex-style agents see the same constraints. You can also add CLAUDE.md to Codex’s project_doc_fallback_filenames if you standardize on that filename.