Wiki Init

---
name: wiki-init
description: Initialize a new project wiki vault with WIKI.md, index, conventions, sync config, and starter structure.
allowed-tools: Read Glob Write Edit Bash AskUserQuestion
effort: high
---

# 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:

```bash
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/`)

| Project type | Suggested categories |
|-------------|---------------------|
| SaaS / web app | `architecture/`, `modules/`, `entities/`, `flows/`, `integrations/`, `configuration/` |
| API / backend | `architecture/`, `endpoints/`, `models/`, `integrations/`, `configuration/` |
| Mobile app | `architecture/`, `screens/`, `entities/`, `flows/`, `integrations/` |
| Notes / knowledge | Infer from vault name (courses → `concepts/`, `techniques/`, `resources/`; company → `processes/`, `team/`, `projects/`) |

### 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

```bash
mkdir -p wiki/sources wiki/logs raw local
```

For each category in `CATEGORIES`:
```bash
mkdir -p wiki/[category]
```

For each repo in `REPOS`:
```bash
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.

Write all prose in `LANGUAGE`. Write the result to `CLAUDE.md`.

---

### 5.3 — wiki-conventions.md

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

Read `.claude/skills/wiki-forge/references/conventions-template.md` 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`:

```markdown
## 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:**

```markdown
# 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 = []`:**

```markdown
# 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`:

```markdown
# 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`:

```markdown
# 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`:

```markdown
# [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`:

```markdown
# 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`):

```markdown
# [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`):

  ```markdown
  ## 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`."