llm-wiki

LLM Wiki

Repo-local project memory for LLM agents. The wiki is plain Markdown in llm-wiki/, so Claude, Codex, Cursor, GPT, and humans can share the same current state, decisions, findings, and handoff notes without relying on chat history.

Trigger Rule

Use this skill in any workspace where llm-wiki/ exists before non-trivial project work and after meaningful project work. Non-trivial means research, planning, debugging, refactoring, multi-file edits, implementation, or anything continuing prior project context.

Also use it when the user asks to initialize or maintain persistent project memory, references previous sessions, says to remember something, asks for handoff/current-state/wiki/log/decision/findings updates, or switches between Claude and Codex.

Skip it for pure casual conversation, general non-project Q&A, formatting one snippet, or when the user explicitly says not to use the wiki.

Core Contract

• The project-specific contract lives in llm-wiki/AGENTS.md; read it first when present.
• Wiki documents are written in Korean by default unless the project or user explicitly asks for another language.
• Keep code identifiers, file paths, commands, API fields, database names, package names, and error messages in their original form.
• current-state.md is mutable and should fit on one screen.
• log.md is append-only.
• decisions/ and findings/ are append-mostly: supersede with a new file instead of rewriting old records.
• wiki/ contains durable topic pages and can be updated as knowledge improves.
• index.md is the curated routing table and table of contents. Use it to choose relevant files; do not read the whole wiki by default.
• Prefer sparse loading: read current-state.md plus the top few index-routed files relevant to the user's intent, then deep-read more only when needed.
• If you create a new file under wiki/, decisions/, or findings/, updating index.md in the same turn is mandatory. Treat the new file and index entry as one change.
• If the bundled scripts/check_index.sh exists, run it after adding durable wiki files or before claiming the wiki is fully updated.
• If a workspace-wide wiki hub is configured and reachable, reindex it after successful wiki writes so cross-repo search sees the new documents. If the hub server is down, do not block the wiki update; tell the user that hub indexing still needs to run.
• Never record secrets, real .env values, credentials, tokens, cookies, private keys, or session IDs.

Optional Parent Workspace Wiki

Some workspaces have a parent ecosystem wiki above repo-local wikis, for example /Users/winter.e/adaptive/llm-wiki plus repo-local wikis such as titan/llm-wiki or kint-dashboard/llm-wiki. Parent wiki support is optional and must never break repos that do not participate.

Use a parent wiki only when at least one of these is true:

• The user explicitly asks about cross-repo impact, upstream/downstream data flow, ecosystem context, or parent/total wiki behavior.
• The repo-local llm-wiki/AGENTS.md declares a parent wiki or ecosystem wiki.
• You are working under a known workspace root that has its own llm-wiki/ sibling/ancestor and the task could affect another repo through data contracts, APIs, dashboards, agents, ETL, or deployment.

When a parent wiki applies:

1. Read the current repo wiki first: llm-wiki/AGENTS.md, current-state.md, index.md.
2. Then read only the parent wiki index.md and the 1-3 routed files relevant to the task, such as repo-catalog, data-flow, impact-checklist, or contracts.
3. If the parent wiki is missing, not indexed, or irrelevant, skip it silently and continue with the repo-local wiki.
4. If another repo is identified as upstream/downstream, read only that repo wiki's current-state.md, index.md, and 1-3 relevant routed files.

Parent wiki content is not limited to verified cross-repo contracts. Use the parent wiki for three layers:

• Ecosystem landscape: repo roles, domain inventory, major DAG/output catalogs, and how the workspace is organized. This can include unverified but clearly scoped inventory.
• Candidate/needs-verification links: suspected or partial producer/consumer relationships, known outputs with missing scheduler evidence, and open gaps to investigate.
• Verified contracts: producer and consumer evidence from code/config/SQL plus transport/store, key fields, grain, and freshness/schedule. Only this layer requires full bilateral evidence.

Do not omit important repo/domain inventory from the parent wiki just because no downstream consumer is verified yet. Instead, place details in the repo-local wiki and summarize parent-worthy inventory or gaps in parent pages such as repo-catalog, ecosystem-map, data-flow, contracts, or open-gaps when they exist.

After work:

• Write repo-internal implementation, test, and execution knowledge to the current repo wiki.
• Write durable cross-repo data flow, contract, or impact knowledge to the parent wiki only if it exists and the user has not said to avoid it.
• If the parent wiki does not exist, record parent-worthy findings in the current repo wiki instead of failing or creating a parent wiki unprompted.

Pre-Work Checklist

Before meaningful work:

1. Confirm llm-wiki/ exists at the workspace root. If missing and persistent memory is useful, ask once whether to bootstrap it.
2. Read llm-wiki/AGENTS.md if present.
3. Read llm-wiki/current-state.md.
4. Read llm-wiki/index.md.
5. Use the index's routing table first. Read only the relevant wiki/, decisions/, or findings/ files for the current task.
6. If log.md is short, skim it; otherwise read the last 1-3 entries.

Then proceed with the user's actual task.

Post-Work Checklist

Before reporting back after meaningful work, update only what applies:

1. Append a dated entry to llm-wiki/log.md.
2. Update llm-wiki/current-state.md if goals, status, blockers, or next actions changed.
3. Add decisions/000N-<slug>.md if a durable design, scope, tooling, or workflow decision was made.
4. Add findings/YYYY-MM-DD-<slug>.md for operational knowledge, gotchas, verified constraints, or tool behavior future agents need.
5. Add or update wiki/<topic>.md for durable topic knowledge.
6. If any new wiki/, decisions/, or findings/ file was added, update llm-wiki/index.md before reporting back.
7. Before reporting back, quickly compare the files you added against llm-wiki/index.md. Prefer running bash <skill>/scripts/check_index.sh llm-wiki when available. Do not claim the wiki is updated if a new durable file is missing from the index.
8. If wiki files changed and scripts/reindex_workspace_hub.sh exists, run it after index validation. If it reports the hub server is unreachable, mention that the wiki is updated but workspace-wiki-hub indexing still needs to be run after the server starts.

If no durable knowledge was produced, skip wiki writes rather than adding noise.

Optional Workspace-Wiki-Hub Reindex

Some workspaces expose repo-local and parent wikis through a separate workspace-wiki-hub search server. This integration is optional and must not break normal repo-local wiki use.

After meaningful wiki writes:

1. Run scripts/check_index.sh for every wiki you changed.
2. If scripts/reindex_workspace_hub.sh exists, run it. It uses WORKSPACE_WIKI_HUB_URL, then WIKI_SEARCH_URL, then http://127.0.0.1:38894.
3. If reindex succeeds, no special note is needed unless the user asked.
4. If the hub server is unreachable, report this explicitly: wiki files were updated, but hub search will not see them until the server is started and incremental indexing runs.
5. If the workspace has no hub, skip this silently.

Do not start long-running hub servers just to satisfy post-work reindex unless the user asked you to set up or run the hub.

Bootstrapping

When initializing a project wiki:

1. Create llm-wiki/ at the workspace root.
2. Use the bundled templates and scripts when available:
   • scripts/init_wiki.sh
   • templates/AGENTS.md
   • templates/current-state.md
   • templates/index.md
   • templates/root-AGENTS.md
   • templates/root-CLAUDE.md
3. Customize placeholders immediately. At minimum capture:
   • project name and workspace path
   • Korean as the wiki language unless the user says otherwise
   • source layout, such as fe/, be/, apps/, packages/, or external repo paths
   • git/repo topology, especially nested independent repos
   • test/dev commands that future agents should prefer
   • out-of-scope files or directories
4. Add root-level agent entrypoints during initialization:
   • AGENTS.md for Codex and other agents
   • CLAUDE.md for Claude Code
   • Use templates/root-AGENTS.md and templates/root-CLAUDE.md when available.
   • Never overwrite existing root entrypoints; if they exist, tell the user to merge the llm-wiki entrypoint text.

Root entrypoints are required for automatic-feeling behavior. They should be tiny and point agents to llm-wiki/AGENTS.md, current-state.md, and index.md before meaningful work, then require post-work wiki updates when warranted.

Where To Put Information

Information	File
Current status, active goal, next actions	current-state.md
Chronological task record	log.md
Durable architecture/scope/tooling decision	decisions/000N-<slug>.md
Debugging result, environment gotcha, verified constraint	findings/YYYY-MM-DD-<slug>.md
Topic knowledge such as architecture, auth, deployment, API contracts	wiki/<topic>.md
Routing table, navigation, and links to durable records	index.md
Agent behavior rules and project-specific constraints	AGENTS.md

Index Routing Pattern

Keep index.md useful as a first-stop router, not just a link dump:

• Add an "Intent Routing" or "작업별 라우팅" section.
• Each route maps a likely task to 1-3 files to read first.
• Use concrete triggers such as auth/session, deployment, streaming/SSE, dbt, Trino, frontend/admin.
• Keep summaries one line. Move long explanations into wiki/, findings/, or decisions/.
• When a file becomes stale, update or remove its route. A stale route is worse than no route.

Cross-Agent Use

Claude plugin, Codex plugin, and repo-local .claude/skills or Codex plugin installs should all use the same skills/llm-wiki/SKILL.md. The plugin is generic; each project becomes specific through its generated llm-wiki/AGENTS.md, current-state.md, and index.md.

When switching agents, read the wiki instead of asking the user to restate context.

References

Read only when needed:

• references/file-roles.md for detailed file-role guidance.
• references/triggers.md for trigger examples and edge cases.
• references/karpathy-pattern.md for the background pattern.
• templates/ for project initialization.
• scripts/ for deterministic wiki helpers.