Bootstrap

Bootstrap LLM Wiki

Create a self-maintaining project wiki under wiki/ for the current repository. Ground every page in actual source files and git history. Do not invent architecture, data models, routes, or decisions.

Preconditions

• The current directory must be inside a git repository.
• QMD is optional but recommended. Use it when available; when missing, suggest installing it before falling back to rg.
• Merge existing agent settings and instructions. Do not overwrite existing config files blindly.
• Detect the main cross-project wiki when present. Check ~/wikis/master/wiki/, ~/wikis/main/wiki/, /wikis/master/wiki/, and /wikis/main/wiki/.
• Install wiki context for all supported agents. Only one agent owns headless scheduled and post-commit maintenance.

Step 1: Detect Project Shape

Read the project root and identify:

• Language/framework: Gemfile, package.json, go.mod, Cargo.toml, pyproject.toml, requirements.txt, composer.json, pom.xml, build.gradle, *.sln, *.csproj, or equivalents.
• Persistence: schema files, migrations, ORM models, SQL files, or absence of a database.
• Entry points: routes, API specs, CLI commands, GraphQL schemas, gRPC protos, or main files.
• Architecture: services, domain modules, packages, jobs, queues, middleware, dependency injection, or monorepo boundaries.
• Tests, dependency files, CI/CD, Docker, and deploy config.
• Parent of project: dirname "$(git rev-parse --show-toplevel)".
• Main cross-project wiki: whether any default path exists. Check in this order:
• ~/wikis/master/wiki/
• ~/wikis/main/wiki/
• /wikis/master/wiki/
• /wikis/main/wiki/
• If no main cross-project wiki exists, ask the user to either provide an existing main wiki folder or create a new master wiki at /wikis/master/wiki/. Wait for the user's answer before continuing.
• If creating a new main wiki, create the directory and seed index.md, patterns.md, learnings.md, and log.md with minimal grounded headings. Do not invent cross-project facts.

Adapt all later page names and source reads to what the project actually uses.

Step 2: Create Wiki Skeleton

Create:

mkdir -p wiki raw/notes

Create or update:

• wiki/index.md: catalog of wiki pages.
• wiki/log.d/: directory of append-only -.md changelog fragments (one file per change — conflict-free across branches/worktrees).
• wiki/log.md: the COMPILED changelog, regenerated from wiki/log.d/*.md by .llm-wiki/compile-log.sh. Seed it with the header plus an empty generated block so the compiler is idempotent:

``` # Wiki Changelog

Append-only log of all wiki operations.

```

Never hand-edit the content between the markers. On an EXISTING project whose log.md predates fragments, leave the old hand-written ## entries in place below the markers — compile-log.sh preserves them as legacy and prepends compiled fragments above, so migration is lossless.

• wiki/gaps.md: open questions, missing coverage, and uncertainty.

Create stack-appropriate subdirectories only when useful, such as models/, controllers/, services/, components/, packages/, modules/, commands/, or apis/.

Add .qmd/ to .gitignore if it is not already ignored.

Step 3: Generate Grounded Pages

Read source files before writing. Prefer fewer, richer pages over many thin pages.

Before writing pages, search the detected or user-provided main cross-project wiki when it exists. Read relevant pages such as patterns.md, learnings.md, decisions.md, architecture.md, and index.md if present. Use this context to align project wiki structure and note reusable patterns, but only cite or summarize cross-project facts from pages actually read.

Generate pages that apply to the project:

• wiki/data-model.md: persistent entities, relationships, constraints, indexes, and Mermaid ER diagram when useful.
• wiki/routes.md, wiki/api.md, or wiki/commands.md: external interaction surface.
• wiki/architecture.md: major components, boundaries, patterns, integrations, and deployment clues.
• wiki/dependencies.md: key dependency choices and visible rationale.
• wiki/decisions.md: lightweight ADRs from source and git history.
• wiki/active-areas.md: recently active areas from git history.
• Stack-specific pages under the subdirectories created in Step 2.

Use this frontmatter for pages where it helps:

---
title: Page Title
type: architecture
source: path/to/source
created: YYYY-MM-DD
updated: YYYY-MM-DD
tags: [architecture]
---

Include a one-sentence TLDR near the top of each page. Use [[page-name]] backlinks between related pages.

Step 4: Build Gaps and Index

Read generated pages and compare them against the codebase.

Update wiki/gaps.md with:

• Source files or domains without wiki coverage.
• Patterns detected but not documented.
• Open questions and uncertainty.
• Areas that should be expanded later.

Update wiki/index.md with:

• Page count and date.
• Pages grouped by category.
• One-line summaries.

Write the bootstrap changelog entry as a fragment wiki/log.d/-bootstrap.md (then run .llm-wiki/compile-log.sh . to regenerate wiki/log.md):

## [TIMESTAMP] bootstrap

**Action:** Initial wiki bootstrap from codebase
**Pages created:** ...
**Pages updated:** ...
**Gaps found:** ...
**Source:** Codebase read + git history

Step 5: Add Agent Instructions

Create .llm-wiki/ if it does not exist, then create or update .llm-wiki/config.json.

Config shape:

{
  "headless_agent": "",
  "context_agents": ["claude", "codex", "pi"],
  "main_wiki_path": "",
  "created_by": ""
}

Rules:

• context_agents is the supported context list and should include claude, codex, and pi.
• If .llm-wiki/config.json is missing, first check for legacy automation from older llm-wiki versions before treating this as a first bootstrap.
• Infer legacy ownership by searching .llm-wiki/refresh-wiki.sh, .llm-wiki/post-commit-refresh.sh, .git/hooks/post-commit, known llm-wiki- systemd or launchd scheduler files, and existing cron entries for codex exec, claude -p, pi -p, or pi --print.
• If exactly one legacy owner is found, preserve it as headless_agent and record it in .llm-wiki/config.json.
• If more than one owner command is found, or no owner can be inferred from existing automation, ask the user which agent should own headless maintenance before installing or rewriting automation.
• On true first bootstrap with no existing automation, set headless_agent to the current tool: claude for Claude Code, codex for Codex, or pi for Pi.
• On later bootstrap runs, preserve the existing headless_agent unless the user explicitly asks to switch it.
• If the current tool differs from headless_agent, still update wiki context for the current tool, but do not change scheduler or post-commit ownership.
• Scheduled refresh and post-commit refresh must use only headless_agent.
• Never run more than one headless maintenance agent for the same project by default.

Add a wiki section to all agents listed in context_agents:

• Claude Code: CLAUDE.md
• Codex: AGENTS.md
• Pi: AGENTS.md

Create files if absent. Append or replace only the managed wiki section between the markers below. Do not replace unrelated instructions or any unmarked user-authored ## Wiki section. When both Codex and Pi are listed, update AGENTS.md once; do not duplicate the managed wiki block.

Legacy migration:

• Older llm-wiki versions wrote an unmarked generated ## Wiki section.
• If an unmarked ## Wiki section clearly matches the generated llm-wiki template, wrap or replace it with the managed marker block below.
• Treat a section as generated only when it contains the project wiki bullet list, wiki/index.md, wiki/log.md, wiki/gaps.md, raw/notes/, and the QMD/rg query protocol.
• Preserve unmarked ## Wiki sections that do not match the generated template, and add the managed block separately.

Instruction content:

## Wiki

This project has an LLM-maintained knowledge base in `wiki/`.

- `wiki/` — project knowledge pages maintained by the agent
- `wiki/index.md` — catalog of all pages
- `wiki/log.md` — compiled changelog (regenerated from `wiki/log.d/*.md` fragments; never hand-edited)
- `wiki/gaps.md` — known gaps and open questions
- `raw/notes/` — manually added reference material

Always check `wiki/` before answering questions about this project's architecture, patterns, or decisions.

When you learn something new about the project or make a decision:
1. Create or update the relevant page in `wiki/`
2. Update `wiki/index.md` if a new page was created
3. Add a `wiki/log.d/-.md` fragment (never hand-edit the compiled `wiki/log.md`; it is regenerated from fragments by `.llm-wiki/compile-log.sh`)

Never hallucinate. Ground everything in code or existing wiki pages. If unsure, note it in `wiki/gaps.md`.

Use `[[page-name]]` backlinks between wiki pages.

Query protocol:
1. Read `.llm-wiki/config.json` when it exists.
2. Run `qmd query ""` or `qmd search ""` when QMD is available.
3. Fall back to `rg "" wiki/`.
4. Check the configured `main_wiki_path` before making architectural decisions when it exists.
5. Also check default main cross-project wiki paths when they exist:
   - `~/wikis/master/wiki/`
   - `~/wikis/main/wiki/`
   - `/wikis/master/wiki/`
   - `/wikis/main/wiki/`

Step 6: Hooks, Scheduled Automation, and QMD

Install session context for supported agents separately from headless maintenance ownership.

Claude Code context:

• If .claude/settings.json exists, or it can be safely created, merge a SessionStart hook that prints wiki/index.md and recent wiki/log.md.
• Treat the Claude SessionStart hook as a context hook only. It does not mean Claude owns scheduled refresh.
• Never overwrite unrelated Claude settings.

Codex context:

• Ensure AGENTS.md contains the wiki section from Step 5.
• Codex currently receives repo context through AGENTS.md; do not invent a Codex hook system if one is not available.

Pi context:

• Ensure AGENTS.md contains the wiki section from Step 5.
• Pi loads project context from AGENTS.md and CLAUDE.md; treat AGENTS.md as the primary llm-wiki context surface for Pi.
• Do not create .pi/SYSTEM.md because it replaces Pi's default system prompt.
• Do not create .pi/APPEND_SYSTEM.md by default. Use AGENTS.md unless the user explicitly asks for Pi-specific system prompt customization.

Always ensure scheduled wiki refresh automation exists for the configured headless_agent. Do not ask whether to add it.

If the current tool is not the configured headless_agent, update session context for the current tool and validate/report the existing automation owner. Do not rewrite scheduler or post-commit ownership unless automation is missing, unsafe, or the user asks to repair or switch ownership.

The scheduler is a queue drainer, not an independent full-wiki writer. Install .llm-wiki/refresh-wiki.sh by copying the bundled ../../templates/refresh-wiki.sh relative to this SKILL.md, then make it executable. Do not generate a provider-specific scheduled script. The canonical wrapper resolves the repository's shared post-commit-refresh.sh and invokes it with --project --drain. Provider ownership remains in the validated shared config and transactional runner. Before executing either the shared or checkout-local candidate, the wrapper requires the canonical inert LLM_WIKI_RUNNER_CAPABILITIES: drain marker; missing or legacy runners fail closed with upgrade guidance instead of being probed by execution.

--drain must never infer or enqueue the scheduler checkout's HEAD. With no queued sources it exits before preparing a worktree or launching Codex, Claude Code, or Pi. With an open refresh circuit it retains the queue and launches no provider. When work is queued and the circuit is closed, it uses the same lock, limits, disposable llm-wiki/refresh worktree, validation, and receipts as the post-commit path. Never restore a direct codex exec, claude -p, or pi -p scheduled writer.

Install the best available scheduler without prompting:

• Linux with systemd user services: copy

../../templates/install-systemd-scheduler.sh to .llm-wiki/install-systemd-scheduler.sh, make it executable, and run it with --project . The installer resolves the repository's primary worktree, so all linked worktrees share exactly one timer and one canonical shared-Git runner. It migrates older units for the same repository, preserves an intentionally disabled timer, and records the service name beside the shared runner so post-commit hooks can hand work to the memory-bounded unit.

• macOS with launchd: create ~/Library/LaunchAgents/com.llm-wiki..plist with a 24 hour StartInterval, then run launchctl load.
• Other environments: install an equivalent cron entry that runs .llm-wiki/refresh-wiki.sh daily.

The Linux timer must use activation-relative daily scheduling with a randomized delay and must not use Persistent=true; missed runs never catch up in a boot stampede. The oneshot service uses a machine-wide nonblocking flock, MemoryMax=4G, and MemorySwapMax=0. Never create a timer per linked worktree. On non-systemd platforms use a stable ` from the repository identity, replace existing entries instead of adding duplicates, and serialize provider work across repositories. For cron, wrap the entry with # BEGIN LLM WIKI and # END LLM WIKI markers and replace that block on repeat bootstrap. If scheduler installation fails because the environment lacks systemd, launchd, cron, or permissions, keep .llm-wiki/refresh-wiki.sh, record the failure in wiki/gaps.md`, and report the exact command the user can run.

Also install post-commit wiki maintenance automation. Preserve existing hooks; do not overwrite unrelated hook logic. Install the canonical runtime in the shared Git directory and wire the common post-commit hook to pass the committing worktree explicitly.

Install .llm-wiki/refresh-wiki.sh, .llm-wiki/post-commit-refresh.sh, .llm-wiki/compile-log.sh, and .llm-wiki/install-systemd-scheduler.sh by copying the reference scripts bundled with this skill at ../../templates/refresh-wiki.sh, ../../templates/post-commit-refresh.sh, ../../templates/compile-log.sh, and ../../templates/install-systemd-scheduler.sh (resolve them relative to this SKILL.md), then chmod +x all four. Also copy the post-commit runner and compiler verbatim to $(git rev-parse --git-common-dir)/llm-wiki/post-commit-refresh.sh and compile-log.sh, and copy the validated project config there as config.json. The hook must invoke that shared runner as post-commit-refresh.sh --project "$(git rev-parse --show-toplevel)", falling back to the checkout-local runner only when the shared copy is absent. This makes one bootstrap or upgrade authoritative for every linked worktree, including older branches with stale ignored .llm-wiki files or config. compile-log.sh is the single source of truth for the changelog format: it regenerates wiki/log.md from the append-only wiki/log.d/*.md fragments, and the refresh runs it before committing. (Hive's Hive::WikiLog delegates here, so Ruby and shell callers share one implementation.) The bundled post-commit script reads the canonical shared headless_agent and dispatches to exactly one provider; never customize its provider function per project. Provider, QMD, and Git ref execution requires timeout or gtimeout so every potentially stuck command is bounded. When neither is available, the worker must fail before starting a provider. A repository-wide circuit stops automatic provider launches after two consecutive failed batches or when more than 25 sources are pending by default. A worker handles at most one batch of 10 sources with bou

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ivankuznetsov
• Source: ivankuznetsov/llm-wiki
• License: MIT

Install and usage instructions live in the source repository linked above.