Skip to content

v1.2.2 — first tagged release: 14 tools, a 22-page wiki, and the defects the kit found in itself

Latest
Latest

Choose a tag to compare

View all tags
@paulmann paulmann released this 14 Oct 18:58
· 5 commits to main since this release
v1.2.2
d8780c9

github-wiki-llm-writer v1.2.2

An agent skill and toolchain that turns a repository URL into a complete, fact-verified GitHub Wiki. This is the first tagged release; it collects 1.0.0 through 1.2.2 as published on main.

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.

What it does

Four phases — research, wiki architecture, writing, QA and delivery — with tooling at each step:

Phase Tools Output
1 Research setup/bootstrap.sh, scan/repo_scan.py, lib/serve.py, probe/webapp_probe.py, lib/session.py, setup/check_runtime.py research/{summary,architecture,domain-notes}.md, facts.json, sources.md
2 Architecture templates/* page tree in PROGRESS.json, ban.json, terms.json
3 Writing scaffold/new_page.py, qa/fix_toc.py the wiki pages
4 QA + delivery qa/qa_wiki.py, qa/verify_commands.py, publish/publish.sh 0-error audit, commit, verified bundle, REPORT.md

Cross-cutting: lib/evidence.py (probe evidence survives a write failure), setup/snapshot.sh and templates/REWORK-STATE.md.tmpl (recovery after context loss).

Verified, not asserted

  • qa/qa_wiki.py: 16 check families — wiki-link targets, GitHub-slug anchors, sidebar/footer coverage, alert types, fence nesting, mermaid validity, bash -n on every shell block, compile() on every Python block, marketing filler, decorative emoji, banned claims with negation-awareness, terminology. Ships a 22-detection self-test, because three earlier checker bugs produced 381, 12 and 235 phantom errors in real runs.
  • The wiki delivered for this project audits at 0 errors / 0 warnings with --terms and --ban active.
  • Two complete reference runs ship as evidence: MD.Viewer (73,013 words) and MD.Scribe (41,623 words, 249 empirical checks, stateful admin surface).

Fixed since 1.0.0

  • 1.0.1 — --ban treated its own template's documentation keys as banned phrases (three phantom errors on the reference wiki, while genuine bans went unchecked); self-test grew to 15 detections; CI never ran the documented --terms/--ban command at all.
  • 1.0.2 / 1.2.1 — the two checks added above could not run: one aborted on its own intentional failure, the other failed on pipefail alone. templates/ban.json no longer bans its own structural keys. Six tools added in 1.1.0/1.2.0 were invisible to CI and are now covered, together with a step that refuses to publish a run workspace.
  • 1.2.2 — scaffold/new_page.py wrote no _Footer.md whenever a grouping was given (--progress or --groups): the branch returned before the footer write, and because the footer renders on every page the delivered wiki shipped without its version/commit line. CI could not see it — the round-trip used only the heuristic path and a missing footer is a warning, not an error. Both branches now share one footer helper, the reported file count is taken from what was actually written, and the round-trip exercises all three grouping sources.
  • examples/research/facts.json shipped as Markdown with a json fence while four documents called it the machine-readable fact base; it is now valid JSON.
  • lib/evidence.py's self-test used /proc/..., which on Windows resolves to a writable C:\proc and reported FAILED for every Windows user while CI stayed green.

Requirements

Python 3.8+ and bash. PHP only when the subject is a PHP application (any runtime works through ServedApp's --serve-cmd). The kit makes no model API calls — the intelligence is the agent operating it.

Quick start

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

bash setup/bootstrap.sh                      # environment + capability report
git clone <REPO_URL> workspace/repo/SUBJECT  # the subject, any repository
python3 scan/repo_scan.py workspace/repo/SUBJECT --brief -o workspace/research/scan.json
python3 probe/webapp_probe.py --repo workspace/repo/SUBJECT \
        --entry / --suite generic -o workspace/research/probe.json --md workspace/research/probe.md

python3 scaffold/new_page.py workspace/wiki/OWNER.REPO.wiki --init \
        --project SUBJECT --pages "Home,Getting Started,Configuration Reference,Architecture,Troubleshooting,FAQ,Glossary"

python3 qa/qa_wiki.py --self-test            # prove the checker can fail, always
python3 qa/qa_wiki.py workspace/wiki/OWNER.REPO.wiki --strict
bash publish/publish.sh workspace/wiki/OWNER.REPO.wiki OWNER/REPO

For an agent, the entry point is SKILL.md; for a human driving an agent, PROMPT.md — a ready-to-paste task prompt where only the repository URL changes.

Documentation

  • SKILL.md — the four-phase workflow
  • AGENTS.md — phase-to-tool mapping and the tool reference
  • setup/PITFALLS.md — 31 traps, ordered by time wasted
  • CHANGELOG.md — every release states what was verified and how, including negative controls
  • Wiki — 22 pages including the tool reference, QA and audit guide, and a worked example of a defect found by using the kit on itself

Credits

Extracted from a completed run that delivered a 22-page, 73,013-word wiki for paulmann/MD.Viewer with zero outstanding QA errors.

Assets 2
Loading