wiki-init

Create a new shared wiki and link it to the current project.

Prerequisites

Condition	Action
CWD already has .wiki	Show current target, ask to reinitialize
Parent dir has wiki-like folder	Suggest using /wiki-connect instead

Workflow

1. Choose wiki location

Always ask the user via AskUserQuestion before creating anything.

• question: "Where should the wiki be created?"
• options:
  • label: "Same level as this project", description: "Creates a wiki folder next to the current project (e.g., ../my-wiki)"
  • label: "Inside this folder", description: "Creates a wiki folder inside the current directory"
  • label: "Custom path", description: "Specify a different location"

If user chooses "Inside this folder": Check if the current directory contains source code (e.g., package.json, src/, Cargo.toml, go.mod, etc.). If yes, warn the user: "This folder contains source code. The wiki should be a separate repository."

Ask for the folder name via AskUserQuestion. Default: wiki or {project-name}-wiki.

2. Create wiki structure

Create the following structure using Bash:

mkdir -p <wiki-path>/common <wiki-path>/projects

3. Create CONTRIBUTING.md

Write the following to <wiki-path>/CONTRIBUTING.md:

# Contributing to this Wiki

This file defines how documents are organized in this wiki.
Customize this to fit your project's needs.

## Directory Structure

.wiki/
├── common/           Shared across all projects (PRD, ERD, conventions)
├── projects/
│   ├── my-app/       Project-specific documents
│   └── my-api/       Project-specific documents
└── CONTRIBUTING.md   This file

## Rules

- **common/** — Documents relevant to all projects.
- **projects/{name}/** — Documents specific to one project.

## Commit Rule

When you modify any file in this wiki, ask the user before finishing:
- A) Commit now — commit changes to this wiki repository
- B) Commit and push — commit and push to remote
- C) Later — skip for now

Resolve the `.wiki` symlink to the actual wiki repository path
and run git commands there (not in the project repo).
Write a clear commit message describing what was changed.

## Sync Rule

During development, if any of the following happens, ask the user
whether to update the related wiki documents (PRD, spec, etc.):

- A requirement turns out to be wrong or incomplete
- A new requirement emerges that wasn't in the original plan
- The scope changes (feature added, removed, or deferred)
- A technical constraint makes the original requirement infeasible

## Customization

Add subdirectories as needed. This guide sets the starting point.
For high-volume files (tasks, logs), add a convention here
and the agent will follow it.

4. Create symlink

Create .wiki symlink using OS-appropriate command. Refer to references/symlink-guide.md for details.

• macOS/Linux: ln -s <absolute-wiki-path> .wiki
• Windows (Git Bash): cmd //c mklink //J ".wiki" "<absolute-wiki-path>"

Use absolute paths. Relative paths break when CWD changes.

5. Create project directory

mkdir -p .wiki/projects/$(basename $(git rev-parse --show-toplevel))

6. Set up AGENTS.md

Write or append the following ## Wiki section to AGENTS.md in the project root. If AGENTS.md already exists, append. If ## Wiki section already exists, skip.

## Wiki

This project uses a shared wiki via `.wiki` symlink.

### Wiki Focus

- .wiki/CONTRIBUTING.md

7. Agent bridge setup

Check which agent environment is active and set up AGENTS.md bridge:

Claude Code (detectable by .claude/ directory):

• Ensure CLAUDE.md contains @AGENTS.md. If not, add it.

Gemini CLI (detectable by .gemini/ directory):

• Add AGENTS.md to .gemini/settings.json context fileName.

Other agents (Codex, Copilot, Cursor, Windsurf, etc.):

• Read AGENTS.md natively. No bridge needed.

8. Post-setup

1. Add .wiki to .gitignore
2. Initialize git in wiki: cd <wiki-path> && git init && git add -A && git commit -m "Initial wiki setup"
3. Verify: check .wiki symlink is valid, AGENTS.md exists

9. Guide the user

• "Add shared documents to .wiki/common/"
• "Add project-specific documents to .wiki/projects/{repo-name}/"
• "Use /wiki-focus to manage which documents the agent sees"
• "To connect another repo, use /wiki-connect"

Reference

• references/adapter-protocol.md — External skill integration
• references/symlink-guide.md — OS-specific symlink details