wiki-setup

Wiki Setup

Initialize a persistent, interlinked wiki for the current codebase. The wiki lives inside Serena's memory system — all pages are Serena memories organized under the wiki/ topic.

CRITICAL: Serena is REQUIRED

This plugin uses Serena as the wiki's storage and CRUD layer. All wiki pages are Serena memories. Check that Serena MCP tools are available (prefixed mcp__plugin_serena_serena__).

If Serena is NOT available — STOP. Tell the user:

"Serena is required for this plugin. The wiki is stored as Serena memories and uses Serena for all read/write/search operations. Please install Serena first: /plugin install serena@claude-plugins-official Then re-run wiki-setup."

Do not proceed without Serena. There is no fallback.

Serena Memory Architecture

Wiki pages are stored as Serena memories with / topic organization:

Memory Name	Purpose
wiki/schema	Wiki conventions and rules
wiki/index	Categorized catalog of all pages
wiki/log	Chronological record of operations
wiki/overview	Project purpose, tech stack, layout
wiki/architecture/{topic}	System design, data flow, etc.
wiki/modules/{name}	Per-module deep dives
wiki/patterns/{name}	Code conventions, recurring patterns
wiki/decisions/{name}	ADR-style "why we built it this way"
wiki/external/{topic}	Web-enriched external context

CRUD operations — always use Serena:

• Create/Write: mcp__plugin_serena_serena__write_memory
• Read: mcp__plugin_serena_serena__read_memory
• Update: mcp__plugin_serena_serena__edit_memory
• Delete: mcp__plugin_serena_serena__delete_memory
• List/Browse: mcp__plugin_serena_serena__list_memories (with topic: "wiki" or subtopics)
• Search: mcp__plugin_serena_serena__search_for_pattern

Steps

1. Check for existing wiki

Use mcp__plugin_serena_serena__list_memories with topic: "wiki".

• If wiki memories already exist, inform the user: "A wiki already exists with N memories. Would you like to reset it or keep it?"
• If the user wants to reset, use mcp__plugin_serena_serena__delete_memory on each existing wiki memory
• If no wiki memories exist, proceed

2. Write wiki/schema

Use mcp__plugin_serena_serena__write_memory with memory_name: "wiki/schema":

# Wiki Schema

> This memory defines the conventions for maintaining this wiki.
> Read this before creating or editing any wiki memory.

## Memory Organization

All wiki content is stored as Serena memories under the `wiki/` topic:
- `wiki/schema` — this file (conventions and rules)
- `wiki/index` — categorized catalog of all wiki pages
- `wiki/log` — append-only chronological record
- `wiki/overview` — project overview
- `wiki/architecture/{topic}` — system design, data flow, diagrams
- `wiki/modules/{name}` — per-module deep dives
- `wiki/patterns/{name}` — code conventions, recurring patterns
- `wiki/decisions/{name}` — ADR-style decision records
- `wiki/external/{topic}` — web-enriched external context

## Page Format

Every wiki memory uses this structure:

    # Page Title

    > **Category**: architecture | module | pattern | decision | external
    > **Created**: YYYY-MM-DD
    > **Updated**: YYYY-MM-DD
    > **Status**: active | stale | deprecated

    ## Summary
    One-paragraph description.

    ## Content
    [Main body — varies by category]

    ## Related Pages
    - wiki/{category}/{name} — relationship description

    ## Sources
    - `path/to/file.ext` — what it contributes

## Category Sections

**Architecture**: Context, Components, Interactions, Diagrams (ASCII), Trade-offs
**Module**: Purpose, Key Symbols, Dependencies (imports/exports), Internal Structure, Notable Patterns
**Pattern**: Pattern Description, Examples (with file paths), When to Use, When Not to Use
**Decision** (ADR): Context, Decision, Options Considered, Consequences, Status
**External**: Source (URL + date), Summary, Relevance to This Project, Key Takeaways

## Index Rules

- Each entry: `- wiki/{category}/{name} — one-line summary`
- Grouped under ## headings matching the five categories
- Alphabetically sorted within each group
- Update wiki/index whenever a page is created, renamed, or deleted

## Log Format

- Append-only — never edit existing entries
- Format: `## [YYYY-MM-DD HH:MM] OPERATION | Description`
- Operations: SETUP, SCAN, UPDATE, LINT, ENRICH, QUERY, CREATE, DELETE

## Linking Rules

- Reference other wiki pages by memory name: `wiki/{category}/{name}`
- Every page must reference at least one related page
- Bidirectional: if A references B, B should reference A

## Source Attribution

- Every claim must trace to a file path or external URL
- The Sources section lists files that informed the page

## CRUD — Always Use Serena

- Create: `write_memory` with `memory_name: "wiki/{category}/{name}"`
- Read: `read_memory` with `memory_name: "wiki/{category}/{name}"`
- Update: `edit_memory` with `memory_name` + regex/literal replacement
- Delete: `delete_memory` with `memory_name`
- Browse: `list_memories` with `topic: "wiki"` or `topic: "wiki/{category}"`
- Search: `search_for_pattern` to find content across wiki and codebase

3. Write wiki/index

Use mcp__plugin_serena_serena__write_memory with memory_name: "wiki/index":

# Wiki Index

> Last rebuilt: [TODAY'S DATE]
> Total pages: 1

## Overview

- wiki/overview — Purpose, tech stack, and repository layout

## Architecture

_No pages yet. Run wiki-scan to populate._

## Modules

_No pages yet. Run wiki-scan to populate._

## Patterns

_No pages yet. Run wiki-scan to populate._

## Decisions

_No pages yet. Run wiki-scan to populate._

## External

_No pages yet. Run wiki-enrich to add external context._

Replace [TODAY'S DATE] with the actual date.

4. Write wiki/log

Use mcp__plugin_serena_serena__write_memory with memory_name: "wiki/log":

# Wiki Log

## [YYYY-MM-DD HH:MM] SETUP | Wiki initialized
- Created wiki memory structure with 5 categories
- Generated wiki/schema, wiki/index, wiki/log
- Generated wiki/overview from project root files

5. Write wiki/overview

Gather project information using Serena's code analysis tools:

1. Use mcp__plugin_serena_serena__list_dir with relative_path: ".", max_depth: 1
2. Use mcp__plugin_serena_serena__read_file on README.md, package.json, pyproject.toml, Cargo.toml, go.mod, or similar root config files
3. Extract: project name, description, tech stack, scripts/commands

Use mcp__plugin_serena_serena__write_memory with memory_name: "wiki/overview":

# Project Overview

> **Category**: overview
> **Created**: YYYY-MM-DD
> **Updated**: YYYY-MM-DD
> **Status**: active

## Summary

[One paragraph from README or inferred from structure]

## Tech Stack

| Layer | Technology |
|-------|-----------|
| Language | [e.g., TypeScript] |
| Framework | [e.g., React] |
| Database | [if identifiable] |

## Repository Layout

[Directory listing with brief descriptions]

## Build & Run

[Key commands from package.json scripts, Makefile, etc.]

## Related Pages

_Links will be added as more wiki pages are created._

## Sources

- `README.md` — project description
- `package.json` / `pyproject.toml` / etc. — tech stack

6. Verify

Use mcp__plugin_serena_serena__list_memories with topic: "wiki" to confirm all 4 memories were created (schema, index, log, overview).

7. Add Serena Wiki section to CLAUDE.md

Check if a CLAUDE.md file exists at the project root. If it does, read it. If it doesn't, create it.

Append the following section to CLAUDE.md (or add it if creating new). If a # Serena Wiki section already exists in CLAUDE.md, replace it. Otherwise append to the end.

# Serena Wiki

This project has a persistent wiki stored as Serena memories. The wiki documents architecture,
modules, patterns, decisions, and external context. It is maintained by the Serena Wiki plugin.

## How to use

- **Before answering questions about the codebase**, check the wiki first:
  use `mcp__plugin_serena_serena__read_memory` on `wiki/index` to find relevant pages,
  then `read_memory` on those pages. The wiki already has synthesized knowledge — don't
  re-derive what's already documented.

- **After implementing features or making changes**, update the wiki:
  say "update the wiki" or run `/wiki update` to capture what changed and why.

- **To browse the wiki**: `mcp__plugin_serena_serena__list_memories` with topic `"wiki"`

## Quick reference

| Task | What to do |
|------|-----------|
| Browse all wiki pages | `/wiki` or `list_memories` topic: `"wiki"` |
| Ask a question | Just ask — wiki-query skill activates automatically |
| Deep-scan codebase | `/wiki scan` (asks Full vs Partial) |
| Update after changes | `/wiki update` or "update the wiki" |
| Health check | `/wiki lint` |
| Add external docs | `/wiki enrich` |
| Read a specific page | `read_memory` with `"wiki/{category}/{name}"` |

## Wiki memory structure

All pages are Serena memories under `wiki/`:
- `wiki/schema` — conventions
- `wiki/index` — catalog of all pages
- `wiki/log` — operation history
- `wiki/overview` — project overview
- `wiki/architecture/*` — system design, data flow
- `wiki/modules/*` — per-module documentation
- `wiki/patterns/*` — code patterns and conventions
- `wiki/decisions/*` — architectural decision records
- `wiki/external/*` — external documentation context

This ensures that Claude Code knows about the wiki in every future session and uses it automatically when answering questions about the codebase.

8. Inform the user

Tell the user:

• Wiki initialized in Serena with 4 memories: wiki/schema, wiki/index, wiki/log, wiki/overview
• CLAUDE.md updated with Serena Wiki usage instructions
• All wiki content is stored as Serena memories — persistent across sessions
• Suggest: "Run wiki-scan to deep-scan the codebase and populate architecture, modules, patterns, and decisions."
• Mention: "You can browse the wiki anytime with list_memories topic wiki."

Tool Reference

All operations go through Serena. Every tool is prefixed mcp__plugin_serena_serena__:

Operation	Serena Tool
Write wiki page	write_memory (memory_name: wiki/{category}/{name})
Read wiki page	read_memory (memory_name: wiki/{category}/{name})
Update wiki page	edit_memory (memory_name, needle, repl, mode)
Delete wiki page	delete_memory (memory_name)
Browse wiki	list_memories (topic: wiki or wiki/{category})
List directory	list_dir
Read source file	read_file
Find symbols	get_symbols_overview, find_symbol
Trace dependencies	find_referencing_symbols
Search code/wiki	search_for_pattern