Aim Wiki

aim-wiki — Project Wiki Generator & Maintainer

Creates and maintains a wiki of the current project under wiki/, in-session. Works on any project (new or existing) under AI Memory.

You (Claude Code) are the doc-gen agent. The Python engine (scripts/aim_wiki.py) does only deterministic work and hands you structured context; you do the reasoning — analyze the code and author/refresh the pages, grounding every claim in source. There is no separate LLM or provider — you are the model.

Split of responsibilities

• Engine (Python) → deterministic: project scoping, repo inventory, wiki scaffold, run-state (content-hash + gitHead + updatedAt), git-diff since last run, pointer injection, and the verifier manifest.
• You (Claude Code) → reasoning: author wiki/quickstart.md + section pages, refresh them surgically, and dispatch the read-only verifier.
• Correctness → a read-only verifier subagent: after authoring, cross-check page claims against source before acceptance.

The engine is invoked via run-with-env.sh (the AI-memory run-with-env convention). All modes accept --root PATH (override the project root; default = git toplevel, else cwd) and --json.

Grounding discipline (read before authoring)

Concepts adapted from OpenWiki's system prompt (MIT — paraphrased, not lifted).

• Do not invent files, modules, APIs, business rules, or behavior. Ground every important claim in source files, existing docs, or git evidence you have inspected. Include inline source references so a reader can verify.
• Discover efficiently. Do not read every file. Inspect the tree, package/config files, README-style docs, entrypoints, routing, schema/data files, and representative files per domain. Prefer Grep/Glob and short targeted reads over full-file reads. Do not glob **/* from the repo root; exclude .git, node_modules, dist, build, caches, and the wiki/ output itself.
• Use git for the "why". Use recent history and targeted git log/show/blame on high-signal files to explain why code exists, not just what it is. Do not over-index on ancient history or paste commit-hash lists into pages.
• Existing docs are primary source. Treat READMEs, docs/, runbooks, and SKILL.md files as source material — summarize and link rather than duplicate. If existing docs conflict with the code, flag the likely-stale doc and prefer current source.
• Subagents are read-only. You may dispatch read-only research/verifier subagents that only inspect and summarize with source paths; they must not create, edit, move, or delete files, and must not write under wiki/. You synthesize and own all writes.
• Security. Never read or document secret values, credentials, keys, tokens, or .env files. .env.example/samples only if they hold placeholders. Keep all docs under wiki/.
• Plan file. After discovery, before authoring, write wiki/_plan.md (intended pages, evidence per page, open questions). Delete it before finishing.

Full page-structure, page-count, thin-page, and canonical-home rules: references/page-structure.md — read before authoring.

Flows

init — create the wiki from the current project

1. Engine (prep):

   bash "${AI_MEMORY_INSTALL_DIR:-$HOME/.ai-memory}/scripts/memory/run-with-env.sh" \
     "${AI_MEMORY_INSTALL_DIR:-$HOME/.ai-memory}/_ai-memory/skills/aim-wiki/scripts/aim_wiki.py" \
     init [--force] [--json]
   

   Resolves the project root, guards an existing wiki (routes you to update unless --force), builds the repo inventory + git summary, and scaffolds wiki/. Read the emitted inventory and git_summary — that is your grounding.
2. You (author): write a wiki/_plan.md (evidence-linked), then author wiki/quickstart.md first and the linked section pages. ≤8 pages on the first run unless tiny; no thin pages; one canonical home per concept; ground every claim. Delete wiki/_plan.md when done.
3. Verify (below).
4. Review gate: present the wiki diff + the verifier's report; the user accepts or requests fixes (the in-session equivalent of OpenWiki's PR gate).
5. Engine (finalize) on acceptance — injects the pointer and records state:

   bash "${AI_MEMORY_INSTALL_DIR:-$HOME/.ai-memory}/scripts/memory/run-with-env.sh" \
     "${AI_MEMORY_INSTALL_DIR:-$HOME/.ai-memory}/_ai-memory/skills/aim-wiki/scripts/aim_wiki.py" \
     finalize --command init [--json]
   

   finalize exits 2 if a target CLAUDE.md/AGENTS.md has malformed AI-memory markers — it refuses that file's pointer write (writing nothing to it) but still records run-state. Detect a refusal via the pointer_files_refused field in --json, not the exit code alone (argparse also uses 2).

update — incremental maintenance

1. Engine (prep): aim_wiki.py update [--json] — reads state, computes the git-diff since the recorded gitHead (+ uncommitted), and flags whether the wiki was edited since the last record.
2. You (author): build a docs-impact plan (changed source → page → edit → why). Edit surgically — prefer replacing one stale sentence over adding paragraphs; do not reformat or refresh accurate pages. A no-op is valid: if nothing relevant changed, say the wiki is already current and stop. Soft budget: <5 changed source files → touch ≤1–2 pages. Also refresh the ## Project Wiki pointer only if it is missing or stale.
3. Verify → review gate → finalize --command update.

status — freshness only (no writes)

bash "${AI_MEMORY_INSTALL_DIR:-$HOME/.ai-memory}/scripts/memory/run-with-env.sh" \
  "${AI_MEMORY_INSTALL_DIR:-$HOME/.ai-memory}/_ai-memory/skills/aim-wiki/scripts/aim_wiki.py" \
  status [--json]

Reports last updatedAt, recorded gitHead, source changes since last run, and whether the wiki was edited since the last record. Never writes.

Verify — correctness

After authoring/refreshing, run the verifier manifest:

bash "${AI_MEMORY_INSTALL_DIR:-$HOME/.ai-memory}/scripts/memory/run-with-env.sh" \
  "${AI_MEMORY_INSTALL_DIR:-$HOME/.ai-memory}/_ai-memory/skills/aim-wiki/scripts/aim_wiki.py" \
  verify [--json]

The engine extracts every inline source citation from the wiki pages and checks each cited path exists (a deterministic dead-citation precheck — dead paths are immediate drift; fix them). A citation is a full file path or a trailing-/ directory reference (e.g. `src/handlers/`); both forms are checked. Then dispatch a read-only verifier subagent (via the Task tool, read-only) with the manifest: it cross-checks that each page's claims match the cited source — a claim can cite a real file yet misdescribe it. It inspects and reports only; it does not edit. One pass, not a multi-round loop. Surface all discrepancies (dead citations + ungrounded/drifted claims) in the review gate before acceptance.

Scope & invariants

• In-session only (v1). Multi-project: the wiki is written only under the resolved project's wiki/ — no cross-project bleed.
• Deterministic work stays in the engine; authoring/reasoning stays with you. No provider config, no keys, no deepagents.
• Writes are confined to wiki/ plus the top-level CLAUDE.md/AGENTS.md pointer section (owned by finalize). Never edit source outside these.
• Known v1 limitation: source-drift excludes the whole top-level CLAUDE.md/AGENTS.md, not just the injected pointer section — unrelated edits to those files don't register as drift. Pointer-section-scoped drift is a v2 refinement.
• Deferred seams (designed-for, not built in v1): memory-store integration of wiki pages, headless/CI mode + GitHub Action, and aim-sot doc-drift composition. Do not build these here.