wiki-init

Sets up a complete LLM wiki vault for any project.

When this skill finishes, the vault has:

• Folder structure adapted to the domain
• CLAUDE.md with the project architecture
• .claude/wiki-conventions.md with the chosen language and domain-specific tags
• wiki/sync-config.md so /wiki-sync knows which repos to watch
• wiki/index.md and wiki/log.md ready to receive pages
• First documentation generated by wiki-forge (optional)

Step 1 — Check initial state

Scan the current directory:

ls -la

If CLAUDE.md or wiki/ already exist (beyond what the framework ships), warn the user:

"This directory already has wiki files. The skill will create what's missing but won't overwrite existing content."

Step 2 — Project basics

Use AskUserQuestion with these 4 questions in a single call:

• "What is the name of this project / vault?" Header: "Vault name" — user types in "Other"
• "What language should all wiki pages be written in?" Header: "Wiki language" Options: English, Español, Português, Other
• "What type of project is this?" Header: "Project type" Options: SaaS / web app, API / backend, Mobile app, Notes / knowledge base
• "How many source code repositories does the project have?" Header: "Source repos" Options: None (documents only), 1, 2, Three or more

Store answers as VAULT_NAME, LANGUAGE, PROJECT_TYPE, REPO_COUNT.

Step 3 — Repository details

If REPO_COUNT is "None": skip to Step 4 with REPOS = [].

If there are repos: use AskUserQuestion with 2 questions:

• "List each repository, one per line. Format: name | relative-path | stack. Example: api | ../my-api | Laravel 11" Header: "Repositories" User types in "Other" with as many lines as needed.
• "Do you have documents, transcripts, or notes to ingest right now?" Header: "Initial sources" Options:
  • "Yes — they're in a folder I'll specify"
  • "Yes — I already put them in raw/"
  • "No — start with an empty vault"

Parse the repo answer line by line. For each line name | path | stack, create an object { name, path, stack }. Store as REPOS.

Store the sources answer as HAS_SOURCES.

Step 4 — Derive categories and domain tags

Based on PROJECT_TYPE and VAULT_NAME, generate:

Wiki categories (subdirectories of wiki/)

Domain area tags

Derive 8-12 business tags based on VAULT_NAME and PROJECT_TYPE. Think about the core entities and processes of the project. Examples:

• E-commerce → products, orders, payments, users, inventory, shipping
• EdTech → courses, students, instructors, payments, certificates, content
• Fintech → transactions, accounts, users, compliance, notifications, reports
• Generic SaaS → infer from the project name

Present the derived categories and tags to the user:

Based on your project, I'll create these wiki sections:
  [list of categories]

And these domain area tags:
  [list of tags]

Do these look right, or would you like to adjust anything?

Use AskUserQuestion:

• Question: "Do the categories and domain tags look right?"
• Header: "Structure"
• Options: "Yes, looks good", "Adjust categories", "Adjust tags", "Adjust both"

If adjustment needed, ask a free-text follow-up and apply the changes.

Store the final result as CATEGORIES (list of strings) and DOMAIN_TAGS (list of strings).

Step 5 — Create the vault structure

5.1 — Folders

mkdir -p wiki/sources wiki/logs raw local

For each category in CATEGORIES:

mkdir -p wiki/[category]

For each repo in REPOS:

mkdir -p raw/[repo.name]

5.2 — CLAUDE.md

If CLAUDE.md already exists with project content (not the framework's default), skip this step.

Read templates/wiki/wiki-md-template.md and replace:

• {{VAULT_NAME}} → VAULT_NAME
• {{PROJECT_DESCRIPTION}} → 1-2 sentence description inferred from project type and name, written in LANGUAGE
• {{LANGUAGE}} → LANGUAGE
• {{WIKI_CATEGORIES}} → list of categories with a one-line description each, in LANGUAGE:

    architecture/    → Technical patterns and design decisions
    modules/         → Per-module documentation
    ...

• {{RAW_STRUCTURE}} → for each repo: raw/[name]/ → Source: [path] ([stack])
• {{SOURCES_DESCRIPTION}} → markdown table with repos:

  | Repo | Relative path | Technology |
  | ---- | ------------- | ---------- |
  | [name] | [path] | [stack] |

  If no repos: a sentence in LANGUAGE describing the vault's content source.

Compose all prose in LANGUAGE. Save the result as CLAUDE.md.

5.3 — wiki-conventions.md

If .claude/wiki-conventions.md already exists, skip this step.

Read the canonical template at ../../templates/wiki/conventions-template.md (relative to this skill's directory) and replace:

• {{VAULT_NAME}} → VAULT_NAME
• {{LANGUAGE}} → LANGUAGE

Then append the tags section at the end of the file, writing all labels and descriptions in LANGUAGE:

## Tag vocabulary

Tags are the most direct retrieval signal. **Only use tags from this list.**
Never invent tags without updating this section first.

Each page carries exactly **1 category tag** + **0-3 area tags** + **0-1 role tag**.

### Category tags (required, exactly 1)

| Tag | When to use |
|-----|-------------|
[One row per category in CATEGORIES — descriptions in LANGUAGE]
| `[category]` | [one-line description] |

### Domain area tags (0-3, only those that apply)

| Tag | Covers |
|-----|--------|
[One row per tag in DOMAIN_TAGS — descriptions in LANGUAGE]
| `[tag]` | [one-line description] |

### Technical role tags (0-1, only if applicable)

| Tag | When to use |
|-----|-------------|
| `core` | Central to the business; high expected query frequency |
| `pattern` | Documents a reusable design pattern |
| `contract` | Defines an interface or agreement between layers |
| `setup` | Configuration or initialization instructions |

### Prohibitions

- **Never** use synonyms of existing tags.
- If a tag seems necessary but isn't in the list: add it here first, then use it.

Write the result to .claude/wiki-conventions.md.

5.4 — wiki/sync-config.md

Create wiki/sync-config.md. Write all labels in LANGUAGE.

If REPOS has repos:

# Wiki Sync — Repository Configuration

Read automatically by `/wiki-sync` at the start of each sync.
Edit this file to add, remove, or modify source repos.

---

## Repositories

| Name | Relative path | Stack |
|------|---------------|-------|
[One row per repo in REPOS]
| [name] | [path] | [stack] |

---

## Patterns with wiki impact

[For each repo, generate patterns based on its stack:]

### [repo-name] ([stack])

[Laravel / PHP]
- `app/Models/*.php`
- `app/Services/*.php`
- `app/Http/Controllers/*.php`
- `routes/api.php`
- `database/migrations/*.php`
- `composer.json`

[Angular / TypeScript]
- `src/app/**/*.ts`
- `package.json`

[Node / Express / NestJS]
- `src/**/*.ts`
- `routes/**/*.ts`
- `models/**/*.ts`
- `package.json`

[Django / Python]
- `**/models.py`
- `**/views.py`
- `**/serializers.py`
- `**/urls.py`
- `requirements.txt`

[Rails / Ruby]
- `app/models/**/*.rb`
- `app/controllers/**/*.rb`
- `config/routes.rb`
- `Gemfile`

[Go]
- `**/*.go` (exclude `*_test.go`)
- `go.mod`

[Unknown stack — use generic patterns]
- `src/**/*.{ts,js,py,php,rb,go,java}`
- `README.md`

---

## Patterns without wiki impact

- Tests: `tests/`, `*.spec.ts`, `*.test.ts`, `*_test.go`, `*Test.php`
- Assets: `*.svg`, `*.png`, `*.jpg`, `*.gif`, `*.ico`
- Lock files: `*.lock`, `package-lock.json`, `composer.lock`
- Build output: `dist/`, `build/`, `.next/`, `vendor/`, `node_modules/`
- IDE: `.vscode/`, `.idea/`, `*.iml`
- Translations: `lang/`, `i18n/`, `locales/`

If REPOS = []:

# Wiki Sync — Repository Configuration

This vault has no associated source repositories.
Content comes from documents placed in `raw/`.

To add repos in the future: add rows to the Repositories table
and define their wiki impact patterns.

---

## Repositories

(none)

5.5 — wiki/index.md

Write in LANGUAGE:

# Index — [VAULT_NAME]

Master catalog of all wiki pages.
Mandatory entry point for any query with `/wiki-query`.

---

[One section per category in CATEGORIES:]

## [Category]

| Page | Summary | Answers |
| ---- | ------- | ------- |
| *(empty — filled by `/wiki-forge`)* | | |

5.6 — wiki/log.md

Write in LANGUAGE:

# Operation Log — [VAULT_NAME]

History of ingest, lint, and sync operations.
Updated automatically by `/wiki-forge` and `/wiki-sync`.

---

5.7 — README in raw/[repo]

For each repo in REPOS, create raw/[repo.name]/README.md:

# [repo.name]

Source repository: `[repo.path]`
Stack: `[repo.stack]`

Files in this directory are immutable sources.
Do not modify directly — use `/wiki-forge` to ingest them.

5.8 — WIKI.md

Create WIKI.md at the project root. This file is the initialization marker read by the orchestrator at startup and the entry point for any agent that needs wiki instructions.

Write in LANGUAGE:

# Wiki — [VAULT_NAME]

This project has a knowledge wiki in `wiki/`.
Consult it before investigating the codebase.

## How to use

- **Query**: use `/wiki-query` or ask about any component, module, or pattern.
- **Sync**: use `/wiki-sync` to bring the wiki up to date with recent commits.
- **Ingest**: use `/wiki-forge` to process new documents placed in `raw/`.

## Entry point

`wiki/index.md` — master catalog of all documented pages, organized by category.

5.9 — CLAUDE.md wiki section

Ensure the project's CLAUDE.md instructs agents to always consult the wiki before reading source code.

If CLAUDE.md does not exist: create it with the following content (in LANGUAGE):

# [VAULT_NAME]

## Wiki

This project has a documented knowledge wiki. Before investigating the codebase for
any architecture, module, pattern, or domain question, **always read `WIKI.md` first**
and use `/wiki-query` to find documented information.
Do not grep the codebase for facts that may already be in the wiki.

- Entry point: `WIKI.md`
- Full catalog: `wiki/index.md`

If CLAUDE.md already exists: check whether it contains a ## Wiki section.

• If not present: append the following block at the end of the file (in LANGUAGE):

  ## Wiki
  
  This project has a documented knowledge wiki. Before investigating the codebase for
  any architecture, module, pattern, or domain question, **always read `WIKI.md` first**
  and use `/wiki-query` to find documented information.
  Do not grep the codebase for facts that may already be in the wiki.
  
  - Entry point: `WIKI.md`
  - Full catalog: `wiki/index.md`

• If already present: skip — do not duplicate.

Step 6 — Report and launch forge

Report to the user:

## Vault initialized: [VAULT_NAME]

Language: [LANGUAGE]
Type: [PROJECT_TYPE]
Repos configured: [list or "none"]

Files created:
  WIKI.md
  CLAUDE.md
  .claude/wiki-conventions.md
  wiki/sync-config.md
  wiki/index.md
  wiki/log.md
  wiki/[categories]/
  raw/[repos]/

Ready. The skills /wiki-forge, /wiki-sync and /wiki-query
are configured for this project.

Then ask:

• Question: "Do you want to run the initial ingest now to generate the first documentation?"
• Header: "Initial ingest"
• Options:
  • "Yes — ingest the source repos now"
  • "Yes — I have documents in raw/ to ingest"
  • "No — I'll run /wiki-forge manually later"

If they choose to ingest: run the INGEST (batch) operation of the wiki-forge skill pointing at raw/.

If they choose not to: finish with the message:

"Vault ready. When you want to create the initial documentation, run /wiki-forge."