claudetools/.claude/specs/wiki-layer/plan.md

Wiki Layer — Implementation Plan

Status: Phase 1 in progress (Cascades + GuruRMM seeded 2026-05-24)

---

Phase 0 — Structure (no code, low effort, high foundation value)

Goal: Create the directory skeleton and article templates. Nothing else runs yet.

Tasks

• Create wiki/ root with index.md stub
• Create wiki/clients/, wiki/projects/, wiki/systems/, wiki/patterns/ directories
• Write article templates (see standards.md)
• Add .gitkeep files so empty dirs commit
• Verify GrepAI watcher picks up wiki/ automatically (it should — it watches the repo root)
• Add wiki/ mention to CLAUDE.md context-loading section (read wiki/<topic>.md when topic is known)

Done when: Directory exists, templates written, GrepAI indexes it.

---

Phase 1 — Seed Pass (high effort, immediate ROI)

Goal: Compile first-pass wiki articles for the two highest-value targets: GuruRMM and Cascades.

Approach

Run /wiki-compile manually, read and correct output, commit. This is a supervised pass — we're validating the compilation quality before automating.

Tasks

• Compile wiki/projects/gururmm.md from projects/msp-tools/guru-rmm/session-logs/ + root session logs mentioning GuruRMM
• Compile wiki/clients/cascades.md from clients/cascades/session-logs/ + root logs mentioning Cascades
• Compile wiki/systems/ entries for Neptune, Jupiter, Pluto, Saturn (from session logs + credentials.md)
• Mike reviews each article, corrects factual errors, commits
• Run second seed pass for remaining active clients and projects

Done when: All active clients and systems have wiki articles. Mike has reviewed at least Cascades + GuruRMM.

---

Phase 2 — /wiki-compile Command

Goal: Implement the compile command as a repeatable skill.

Command behavior

/wiki-compile [scope]

Scopes:
  client:<name>        Compile from clients/<name>/session-logs/ + matching root logs
  project:<name>       Compile from projects/<name>/session-logs/ + matching root logs
  system:<name>        Compile from all logs mentioning the system name or hostname
  all                  Full pass — all articles, oldest-first by last_compiled date

Without scope: prompt user to select

Steps Claude takes when /wiki-compile is invoked

1. Identify scope from argument
2. Find relevant session logs (by directory + GrepAI keyword search)
3. Read existing wiki article if it exists (note last_compiled date)
4. Read session logs newer than last_compiled (or all if new article)
5. Read relevant CONTEXT.md and memory entries for cross-reference
6. Call Ollama (qwen3:8b) to generate/update the article
   • Summarize new information, merge with existing
   • Update backlinks section
   • Update last_compiled frontmatter
7. Present diff to user for review before writing
8. On approval: write article, update wiki/index.md

Tasks

• Write .claude/commands/wiki-compile.md (the skill file)
• Write Ollama prompt template for article compilation
• Implement index.md update logic
• Test with GuruRMM and Cascades

Done when: /wiki-compile client:cascades runs end-to-end, produces correct article, updates index.

---

Phase 3 — /context Integration

Goal: /context checks wiki before raw logs.

Updated /context flow

1. Search wiki/index.md for topic mentions
2. Read matching wiki/<type>/<name>.md articles (synthesized knowledge)
3. THEN search session logs for recent/specific detail not yet compiled
4. Check credentials.md for access details
5. Return synthesized answer: wiki content + relevant log excerpts

Tasks

• Update .claude/commands/context.md with wiki-first search step
• Add "Check wiki/index.md" as Step 1 in context command
• Add note: if topic has a wiki article, read it first; use logs only for recency

Done when: Running /context cascades returns the wiki article summary + any recent-session additions.

---

Phase 4 — /wiki-lint Command

Goal: Health-check the wiki for staleness and integrity issues.

Lint rules

Rule	What It Checks	Action
Stale IPs	IPs in wiki vs CONTEXT.md + credentials.md	Flag discrepancies
Rate conflicts	Billing rates in wiki vs memory entries	Flag conflicts
Orphaned articles	Wiki articles with no session log activity in 90+ days	Flag for review/archive
Missing articles	Clients/projects mentioned in recent logs with no wiki article	Suggest compile
Broken backlinks	[[links]] pointing to non-existent articles	Flag
Memory conflicts	Memory entries contradicting wiki facts	Flag with both versions

Tasks

• Write .claude/commands/wiki-lint.md
• Implement lint checks
• Decide: run as scheduled cron or manual-only? (recommend: manual initially, cron after 30 days)

Done when: /wiki-lint runs, produces a report with actionable issues.

---

Phase 5 — /save Integration (optional, lower priority)

After writing session log, detect which clients/projects/systems were mentioned, prompt:

Session log saved. Detected topics: GuruRMM, Cascades.
Update wiki for these topics? [y/n]

If y: run /wiki-compile for each detected topic before sync.

Tasks

• Add topic detection to /save (regex on session log content)
• Add post-save wiki update prompt
• Wire through to /wiki-compile

---

Migration Strategy

What	Risk	How
Session logs	None	Not touched, wiki reads from them
CONTEXT.md	None	Not touched, wiki reads from it
Memory entries	Low	Wiki links to memory; memory links to wiki
/context command	Low	Additive — wiki step added before log search
GrepAI index	None	Automatic — picks up wiki/ files on next index cycle
Cross-machine sync	None	Wiki is tracked in Git, syncs via normal sync.sh

No existing functionality is removed or broken. All changes are additive.

---

Recommended Start Order

1. Phase 0 (structure) — DONE 2026-05-24
2. Phase 1 seed:
   • Cascades of Tucson — wiki/clients/cascades-tucson.md — DONE 2026-05-24
   • GuruRMM — wiki/projects/gururmm.md — DONE 2026-05-24
   • Systems: neptune, jupiter, pluto, saturn
   • wiki/overview.md — compile AFTER systems are seeded (reads other wiki articles)
3. Phase 2 command — implement and test — 2-3 hours
4. Phase 3 context integration — 30 minutes
5. Phase 4 lint — schedule for after 30 days of real wiki use
6. Phase 5 save integration — nice-to-have, do if Phase 1-4 prove value

Overview Article (added 2026-05-24)

wiki/overview.md — scope /wiki-compile overview

The "cold-start" doc. Compiles from other wiki articles (not raw logs directly), so it is cheap to maintain.

Sections:

• Team — Mike (admin/owner), Howard (tech/employee), machines, roles
• Active Clients — one-liner per client with billing type, hours, primary open project, link to wiki article
• Active Projects — one-liner per project with version/status, link to wiki article
• Key Infrastructure — what runs where (Neptune, Jupiter, Pluto, Saturn, plus client-side infra)
• Tooling Stack — coord API, GrepAI, Ollama, SOPS vault, Gitea, Syncro PSA, GuruRMM
• State of the Business — current snapshot: active projects, open billing, near-term priorities

This article is the one Howard reads on a new machine before touching anything else.