Commit 6a3a62
2026-03-13 01:36:04 Claude (Dev): [mcp] [system] Create Wiki Usage Guide for dev wiki agents| /dev/null .. meta/wiki usage guide.md | |
| @@ 0,0 1,164 @@ | |
| + | --- |
| + | category: reference |
| + | tags: [meta] |
| + | last_updated: 2026-03-12 |
| + | confidence: high |
| + | --- |
| + | |
| + | # Wiki Usage Guide for Agents |
| + | |
| + | ## What this is |
| + | |
| + | This wiki tracks the development of wikibot.io — a serverless wiki-as-a-service platform. Both human developers and Claude agents (phase managers) read and write to this wiki. It serves as the persistent state store across agent sessions, tracking what's been built, what decisions were made, and what's next. |
| + | |
| + | The wiki is backed by Git. Every edit is a commit with full version history. |
| + | |
| + | ## Available tools |
| + | |
| + | You have 12 MCP tools, prefixed with "dev-wiki" in Claude Code. |
| + | |
| + | ### Reading |
| + | |
| + | **`read_note(path)`** — Read a single page. Returns frontmatter, content, and WikiLinks (outgoing and incoming). Use `revision` to read a historical version. |
| + | |
| + | ### Navigating |
| + | |
| + | **`list_notes()`** — List all pages. Returns name, path, category, tags, word count, and last updated date. All filters are optional and compose with AND: `prefix`, `category`, `tag`, `updated_since`. |
| + | |
| + | **`get_links(path)`** — Get incoming and outgoing WikiLinks for a page. |
| + | |
| + | **`get_recent_changes(limit=20)`** — Git changelog across all pages. |
| + | |
| + | **`find_orphaned_notes()`** — Pages not linked from any index page. |
| + | |
| + | ### Searching |
| + | |
| + | **`search_notes(query)`** — Full-text keyword search. |
| + | |
| + | **`semantic_search(query, n=5)`** — Conceptual similarity search. |
| + | |
| + | ### Writing |
| + | |
| + | **`write_note(path, content, commit_message, revision?)`** — Create or overwrite a page. Omit `revision` for new pages. Supply `revision` from `read_note` when updating (optimistic locking). |
| + | |
| + | **`edit_note(path, revision, old_string, new_string, commit_message?)`** — Targeted find-and-replace within a page. `old_string` must match exactly once. |
| + | |
| + | **`rename_note(path, new_path, commit_message?)`** — Rename/move a page. Updates all incoming WikiLinks atomically. |
| + | |
| + | **`delete_note(path, commit_message)`** — Delete a page. |
| + | |
| + | ### History |
| + | |
| + | **`get_history(path, limit=10)`** — Revision history for a page. |
| + | |
| + | ## Session start protocol (for phase managers) |
| + | |
| + | At the beginning of every session: |
| + | |
| + | 1. **`read_note("Home")`** — Load the master index. See what exists. |
| + | 2. **`read_note("Dev/Phase N Status")`** — Resume state from the last session. |
| + | 3. **`get_recent_changes(limit=10)`** — See if the human made changes since last session. |
| + | 4. Load the relevant spec pages for your phase (Agent Conventions, Task Graph). |
| + | 5. Proceed with work. |
| + | |
| + | ## Page conventions |
| + | |
| + | ### Frontmatter |
| + | |
| + | Every page should have YAML frontmatter: |
| + | |
| + | ```yaml |
| + | --- |
| + | category: spec | dev | reference | index | meta |
| + | tags: [relevant, tags] |
| + | last_updated: 2026-03-12 |
| + | confidence: high |
| + | --- |
| + | ``` |
| + | |
| + | **Categories for this wiki:** |
| + | - `spec` — Design specifications and implementation guides |
| + | - `dev` — Development status tracking and decision logs |
| + | - `reference` — Project documents (PRDs, external references) |
| + | - `index` — The Home page and navigation pages |
| + | - `meta` — Wiki usage and conventions |
| + | |
| + | ### Page organization |
| + | |
| + | ``` |
| + | Home — master index |
| + | Specs/ — implementation specs |
| + | Agent Conventions — how agents work |
| + | Task Graph — work units and dependencies |
| + | Phase Gates — exit criteria per phase |
| + | Docs/ — project documents |
| + | PRD — serverless SaaS PRD |
| + | Original PRD — single-tenant system PRD |
| + | Dev/ — development tracking |
| + | Phase N Status — living status per phase |
| + | Phase N Summary — final summary per phase |
| + | Decision Log — architectural decisions |
| + | Meta/ — wiki meta |
| + | Wiki Usage Guide — this page |
| + | ``` |
| + | |
| + | ### Cross-references |
| + | |
| + | Use WikiLinks: `[[Page Path]]` or `[[Page Path|display text]]`. Target path comes first, display text second. |
| + | |
| + | ### Commit messages |
| + | |
| + | Format: `[source] action: description` |
| + | |
| + | Sources: |
| + | - `[system]` — automated/setup operations |
| + | - `[P0]` through `[P4]` — phase-specific work |
| + | - `[manager]` — phase manager status updates |
| + | |
| + | ## Dev tracking conventions |
| + | |
| + | ### Status pages (`Dev/Phase N Status`) |
| + | |
| + | Living document updated each session. Contains: |
| + | - Current state (tasks complete, in progress, blocked) |
| + | - Active decisions or blockers |
| + | - Next parallelism group to execute |
| + | |
| + | ### Summary pages (`Dev/Phase N Summary`) |
| + | |
| + | Written once when the phase completes: |
| + | - What was implemented (repo/branch references) |
| + | - Decisions made and rationale |
| + | - Deviations from the task graph |
| + | - New tasks discovered |
| + | - Lessons learned |
| + | |
| + | ### Decision log (`Dev/Decision Log`) |
| + | |
| + | Append-only. Each entry: date, decision, context, alternatives considered, rationale. |
| + | |
| + | ## Things to watch out for |
| + | |
| + | **Optimistic locking.** Always read before writing. Supply the `revision` SHA when updating. If someone else edited since your read, you'll get a conflict — re-read and retry. |
| + | |
| + | **Choose `edit_note` vs `write_note` carefully.** `edit_note` for small changes. `write_note` for structural rewrites. For multi-part updates, multiple `edit_note` calls are safer. |
| + | |
| + | **Keep Home current.** When you create a new page, update Home in the same session. |
| + | |
| + | **Semantic search may lag** web UI edits by up to 60 seconds. Full-text `search_notes` is always current. |
| + | |
| + | ## Quick reference |
| + | |
| + | | I want to... | Use... | |
| + | |---|---| |
| + | | Start a session | `read_note("Home")` then `read_note("Dev/Phase N Status")` | |
| + | | Find a page by topic | `semantic_search(query="...")` | |
| + | | Find a page by keyword | `search_notes(query="...")` | |
| + | | See what changed recently | `get_recent_changes(limit=10)` | |
| + | | See all specs | `list_notes(prefix="Specs/")` | |
| + | | See dev status | `list_notes(prefix="Dev/")` | |
| + | | Create a new page | `write_note(path, content, commit_message)` | |
| + | | Update an existing page | `read_note` then `write_note` with revision SHA | |
| + | | Make a small targeted edit | `edit_note(path, revision, old_string, new_string)` | |
| + | | Check a page's history | `get_history(path, limit=10)` | |
| + | | Find unindexed pages | `find_orphaned_notes()` | |
| \ | No newline at end of file |