Home

github-wiki-llm-writer

An agent skill and toolchain that turns a repository URL into a complete, fact-verified GitHub Wiki. An LLM agent walks four phases — research, wiki architecture, writing, QA and delivery — while the kit's fourteen tools do what tools do best: inventory the subject, run it, capture evidence, scaffold QA-clean pages, audit every link, anchor, diagram and shell block to zero errors, and package a pushable commit plus a verified git bundle.

Important

The one rule: a claim enters the wiki only if it is traced to a source line, or reproduced by running the software. The kit exists because an agent asked to "write a wiki" transcribes the README — and the reference subject's README claimed syntax highlighting (no highlighter existed in the repository) and nested lists (they rendered as literal text). Reading code tells you what software intends; running it tells you what it does.

Contents

• Key features
• Quick start — five minutes
• How it is put together
• What a finished run looks like
• Requirements
• Wiki navigation
• Project facts
• See also

---

Key features

• Verification-first research — scan/repo_scan.py inventories any repository in one pass (git metadata, license, dependencies or their absence, external hosts, security signals, config surface); lib/serve.py stages a throwaway instance on a verified-free port; probe/webapp_probe.py fires declarative batteries (20 path-traversal payloads, 26 injection payloads, header and flag checks, upload matrices) and records every result as evidence. Measured: the full reference battery runs in 0.46 seconds.
• Provenance as a data structure — research/facts.json carries a source on every value (code:file:line, git, test:name, web:url); sources.md §D records claims deliberately not made, which become the enforced ban list.
• QA-clean scaffolding — scaffold/new_page.py emits a wiki skeleton that passes the auditor unfilled: H1, lead paragraph, computed Contents anchors, See also, derived sidebar/footer links, filenames with spaces (the rule that keeps [[wiki-links]] alive).
• An auditor that proves it can fail — qa/qa_wiki.py runs 16 check families (links, GitHub-slug anchors, alerts, fence nesting, mermaid validity, bash -n, compile(), filler, emoji, bans with negation-awareness, terminology) and ships a 22-detection self-test, because three earlier checker bugs produced 381, 12 and 235 phantom errors in real runs.
• Sandbox-hardened delivery — publish/publish.sh QA-gates, handles the master-branch .wiki.git model, never prompts, never force-pushes, and hands over a commit + verified bundle + PUBLISH.md when credentials are absent — the normal case in agent sandboxes.
• Recovery built in — STATE.md, PROGRESS.json, REWORK-STATE.md and phase-boundary snapshots let a fresh agent resume after context loss; in the reference run an interruption in mid-Phase-4 cost zero work.
• Field-hardened doctrine — setup/PITFALLS.md documents 31 traps ordered by time wasted, examples/ ships two complete reference runs (73,013 words and 41,623 words, both delivered at 0 QA errors), and CI enforces the kit's own rules with negative controls.

Quick start — five minutes

Every command below was executed during the preparation of this wiki.

git clone https://github.com/paulmann/github-wiki-llm-writer.git
cd github-wiki-llm-writer

# 1. environment: idempotent; prints a capability + egress report
bash setup/bootstrap.sh

# 2. inventory the subject (any repository)
git clone https://github.com/OWNER/REPO workspace/repo/SUBJECT
python3 scan/repo_scan.py workspace/repo/SUBJECT --brief -o workspace/research/scan.json

# 3. RUN it and probe it (web app shown; CLI/library paths in the wiki)
python3 probe/webapp_probe.py --repo workspace/repo/SUBJECT \
    --entry / --suite generic -o workspace/research/probe.json --md workspace/research/probe.md

# 4. design the page tree (PROGRESS.json), then scaffold
python3 scaffold/new_page.py workspace/wiki/OWNER.REPO.wiki --init \
    --project SUBJECT --repo-url https://github.com/OWNER/REPO \
    --pages "Home,Getting Started,Configuration Reference,Architecture,Troubleshooting,FAQ,Glossary"

# 5. write the pages, then audit — the self-test first, always
python3 qa/qa_wiki.py --self-test
python3 qa/qa_wiki.py workspace/wiki/OWNER.REPO.wiki --strict

# 6. deliver: QA gate -> commit -> verified bundle -> PUBLISH.md
bash publish/publish.sh workspace/wiki/OWNER.REPO.wiki OWNER/REPO

How it is put together

flowchart LR
    P1["1 RESEARCH ~40%<br/>bootstrap - clone -<br/>scan - run - probe"] --> P2["2 ARCHITECTURE ~3%<br/>page tree -<br/>ban.json - terms.json"]
    P2 --> P3["3 WRITING ~45%<br/>scaffold -<br/>fill pages"]
    P3 --> P4["4 QA and DELIVERY ~12%<br/>audit - re-run commands -<br/>commit - bundle - report"]

Loading

Zero declared dependencies: Python 3.8+ stdlib, bash and git; PHP only when the subject is a PHP app (any runtime works via --serve-cmd). The kit makes no model API calls — the intelligence is the agent operating it. Full detail: Architecture and Tool Reference.

What a finished run looks like

	Reference run (MD.Viewer)	Second field run (MD.Scribe)
Pages	20 + sidebar + footer	23
Words	73,013	41,623
Mermaid diagrams	27	9
Internal wiki-links	341, all resolving	252
Empirical checks	137 shell blocks syntax-clean	249 (234 pass / 15 findings)
QA errors at delivery	0	0
Doc-vs-code corrections	incl. 2 false README claims	14 verified

Sample artefacts ship in examples/; the mechanics are on Features and Verification Model.

Requirements

Requirement	Detail
Runtime	Python 3.8+ (CI: 3.9/3.11/3.12; this wiki verified on 3.11.2), bash, git
Subject runtime	per subject — PHP CLI for PHP web apps; --serve-cmd adapts anything
Optional	curl, jq, ripgrep, shellcheck (bootstrap installs); node for mermaid-cli/JS subjects
Network	github.com for clone/publish; distro mirrors for bootstrap; probes stay on localhost

Wiki navigation

Page	What it covers
Getting Started	zero to audited skeleton, command by command
Features and Verification Model	the one rule, the evidence model, measured capabilities
Comparison with Alternatives	DeepWiki, SSGs, bare agents — by mechanism
Installation and Setup	requirements, bootstrap internals, runtime gate
Configuration Reference	every flag, JSON schema, env var and default
The Four Phase Workflow	the pipeline and its discipline
Research and Probing Guide	batteries, custom suites, stateful flows, research files
Writing Pages Guide	page anatomy, filename rule, GFM devices, house style
QA and Audit Guide	16 check families, self-test doctrine, tuning ban/terms
Publishing and Delivery	.wiki.git mechanics, bundles, the two traps, REPORT.md
Security Considerations	authorized use, payload inventories, the kit's own surface
Sandbox Survival Guide	the 31 PITFALLS, recovery files, snapshots
Extending the Kit	suites, serve commands, new tools, the CI contract
Tool Reference	all fourteen tools: flags, exit codes, internals
Architecture	components, data flow, design decisions, CI
Troubleshooting	exact error strings → cause → fix
FAQ	fifteen questions before and during a run
Changelog and Versioning	1.0.0 → 1.2.1, no tags, changelog-driven
Glossary	the canonical vocabulary

Project facts

Repository	https://github.com/paulmann/github-wiki-llm-writer
Version documented	1.2.1 (CHANGELOG head; no git tags exist — pin by commit)
Verified at commit	7e17a11 (main, 2026-10-14)
License	MIT
Dependencies	none declared — Python stdlib + bash + git
Size at this commit	44 files · 5,523 code lines · 15 code files
This wiki	20 pages; every behavioural claim traced to source or reproduced by execution (test IDs T0–T18 in the run's evidence log)

---

See also

• Getting Started — your first run
• The Four Phase Workflow — the doctrine in one page
• Tool Reference — the complete tool surface
• FAQ — quick answers
• Glossary — vocabulary