/llmwiki:make

/llmwiki:make

Recursively scans text files under a specified directory and generates/maintains an entity-based knowledge wiki through deterministic preprocessing + LLM compilation.

Prerequisites

• Python >= 3.12

Arguments

/llmwiki:make [path]

The path argument is optional. Resolution order for the input directory:

1. Explicit argument: /llmwiki:make <path>
2. Saved config: .llmwiki/config.json -> input_dir
3. Default: project root (current working directory)

Inform the user which input directory is being used.

Output

Output is written to .llmwiki/ directly under the project root. Created automatically on first run.

<project>/
  .llmwiki/
    config.json                # Persisted settings (input_dir, etc.)
    index.xml                  # Entity catalog (auto-generated)
    entities.json              # Entity dictionary (accumulated)
    entities/<category>/*.md   # Wiki pages (accumulated)
    syntheses/*.md             # Synthesized documents (generated by llmwiki:query)
    log.md                     # Session history (append-only)

Input File Contract

Item	Rule
Supported formats	All text files (binary files are auto-skipped via null byte detection in the first 8KB)
Encoding	UTF-8 (no BOM)
Directory structure	Flexible. All levels are scanned recursively
Exclusions	Paths listed in .gitignore + default exclusion patterns (.git/, node_modules/, __pycache__/, etc.)
Git integration	If .git/ exists in the input directory and the git command is available, uses git ls-files for fast retrieval. Otherwise falls back to parsing .gitignore files at each level
index.xml	Generated by makeindex.py. No manual placement needed

Phase 0: Deterministic Preprocessing

Step 0-0: Ensure Output Directory

Check whether .llmwiki/ exists under the project root. If it does not, create it together with the required subdirectory:

mkdir -p .llmwiki/entities

This guarantees that subsequent steps (index generation, preprocessing, wiki page writes) always have a valid output destination.

Step 0-1: Index Generation

python3 ${CLAUDE_PLUGIN_ROOT}/skills/make/scripts/makeindex.py --llmwiki-dir .llmwiki

Generates a summary catalog from wiki pages under .llmwiki/entities/ as .llmwiki/index.xml.

Step 0-2: Preprocessing Execution

python3 ${CLAUDE_PLUGIN_ROOT}/skills/make/scripts/llmwiki_preprocess.py <input_dir> --llmwiki-dir .llmwiki > /tmp/llmwiki_preprocess.xml

Performs the following and outputs XML:

• Recursively scans all text files under the specified directory
• Routes to parsers by file extension (.json, .md, .csv/.tsv, .hcl/.yaml/.yml, .sh)
• Entity matching using the .llmwiki/entities.json dictionary (case-insensitive, word boundary, longest match first)
• Scans frontmatter of existing wiki pages (ingested sources, related, wikilinks)
• Lint: orphan pages, broken links, stale pages (over 30 days), uncovered files

Step 0-3: Triage

Read /tmp/llmwiki_preprocess.xml and report to the user.

• If stats.new_files == 0 and stats.updated_files == 0 and stats.missing_sources == 0 and lint is all clean, report "no updates needed" and stop
• If stats.new_files + stats.updated_files > 20, report the count and confirm with the user before proceeding
• If stats.missing_sources > 0, report the disappeared sources and affected entities
• If lint has issues, report the list

Phase 1: LLM Ingestion

For each file in new_files and updated_files:

1. Load file content with Read (LLM directly reads JSON/MD/CSV/HCL/YAML/sh)
2. Determine source_type from the file path and content (see schema.md guidelines: primary / secondary / derived)
3. Extract new entities and relationships in addition to dictionary-matched entities (known_entities)
4. If a wiki page already exists, update it following the merge rules in ${CLAUDE_PLUGIN_ROOT}/skills/make/llmwiki/schema.md. Otherwise create a new page from the template
5. Add new entities to .llmwiki/entities.json (lowercase kebab-case, aliases in both Japanese and English)
6. Add relationships bidirectionally (if adding A->B, also add B->A)
7. Record the file's SHA-256 hash in frontmatter sources[].sha256 and the determination result in sources[].source_type

For updated_files (files whose sha256 has changed):

• Update the sha256 and ingested of the corresponding source in the existing page
• Update Key Facts and Overview based on content differences
• If contradicting previous descriptions, include both values with dates and add a "needs review" flag

Dormant page promotion:

• If the file to be ingested corresponds to a page with status: dormant, perform the following:
  1. Remove status: dormant from the frontmatter
  2. Remove "status": "dormant" from the corresponding entity in entities.json
  3. Add to Changelog: "YYYY-MM-DD: Reactivated to active (promotion due to new source ingestion)"
  4. Update frontmatter updated to today

For missing_sources (disappeared sources):

• Record "source disappeared" in the Source Files table of wiki pages that depend on the source
• Do not delete the page itself. If other sources remain, content is preserved

Wiki page save location: .llmwiki/entities/<category>/<entity-id>.md

Constraints

• Input directory files are read-only. Do not modify or delete
• Never delete wiki pages. Only flag stale/orphan
• The LLM does not resolve contradictory information. Retain both values with source dates and flag
• If a session cannot process all files, prioritize the most recent files and report the remaining count

Phase 2: Validation

Step 2-1: Re-run Lint

python3 ${CLAUDE_PLUGIN_ROOT}/skills/make/scripts/llmwiki_preprocess.py <input_dir> --llmwiki-dir .llmwiki > /tmp/llmwiki_preprocess_post.xml

Read the result and check the lint section.

Step 2-2: Contradiction Check

Read updated wiki pages and verify if any "needs review" flags are needed. If contradictions exist, include both values with dates and add "needs review".

Step 2-3: Synthesis Quality Check

For the top 3 updated pages, verify:

• Whether the Overview is accurate and self-contained
• Whether Relations are set bidirectionally
• Whether the Source Files table is correct

Step 2-4: Final Report

Report the following:

• Number of files processed
• Number of wiki pages created/updated
• Number of new entities added
• Remaining lint issues
• Remaining unprocessed items (if any)

Step 2-5: Persist Config

Save (or update) .llmwiki/config.json with the input directory used in this run.

If the file does not exist yet, initialize it with the full default schema:

{
  "input_dir": "<absolute path to input directory>",
  "auto_approve": {
    "query_save_synthesis": true
  }
}

If the file already exists, merge only the input_dir value. Do not overwrite existing auto_approve settings.

config.json Schema

Key	Type	Default	Description
input_dir	string	(project root)	Absolute path to the input directory
auto_approve.query_save_synthesis	bool	true	Skip user confirmation when saving synthesized answers to syntheses/

Step 2-6: Log Entry

Append an entry to .llmwiki/log.md in the following format (if the file does not exist, create it with a # llmwiki Log header):

## [YYYY-MM-DD] make | Processed <file count> files, created <new page count>, updated <updated page count>