Obsidian Plan Wiki

Create and manage modular project plans as Obsidian-compatible markdown wikis with progressive disclosure, task tracking, and research integration.

When to Use

• Creating new project plans, roadmaps, or documentation systems
• Working with existing plan wikis using %% [ ] %% task format
• User mentions "plan", "roadmap", "wiki", or "Obsidian"
• Need to organize complex multi-phase projects

Directory Structure

Initialize new plan wikis with this structure:

plan-name/
├── README.md           # Index - start here, links to everything
├── CLAUDE.md           # Rules for Claude working with this plan
├── changelog.md        # Amendment history (Keep a Changelog format)
├── deferred.md         # Preserved deferred work (optional)
├── phases/             # High-level phase overviews
│   ├── 01-phase-name.md
│   └── 02-phase-name.md
├── tasks/              # Individual task specifications
│   ├── 1.1-task-slug.md
│   └── 1.2-task-slug.md
├── reference/          # Supporting documentation
│   └── architecture.md
└── research/           # Oracle/Delphi research outputs
    ├── index.md
    └── topic-name.md

Core Principles

1. Progressive Disclosure

Load only what's needed for the current task:

User asks about camera → Read tasks/3.3-camera.md only
User asks about Phase 2 → Read phases/02-entity-system.md only
User asks for overview → Read README.md only

Never load the entire plan into context at once.

2. Task Tracking with Obsidian Comments

Track open questions and tasks using hidden Obsidian comments:

%% [ ] this is an open question/task %%
%% [x] this was completed → see [[research/result]] %%

To find all open tasks:

grep -r '%% \[ \]' path/to/plan/

When completing a task:

1. Change [ ] to [x]
2. Add arrow → with link to result
3. Add entry to changelog.md

3. Research Workflow

When a %% [ ] %% comment needs research:

Simple question: Launch single oracle agent (Task tool with general-purpose)

Complex/uncertain: Use Delphi pattern (3 parallel oracles + synthesis)

• Launch 3 agents with same question but different search angles
• Synthesize results into single research document
• Store in research/ directory

After research:

%% [x] question → Delphi complete: [[research/topic-delphi]] %%
> **Research:** See [[research/topic]] for details

4. Changelog Protocol

Every change must be logged in changelog.md using Keep a Changelog format:

## YYYY-MM-DD (Session N)

### Added
- [[path/to/file]] - Description

### Changed
- [[path/to/file]] - What changed and why

### Research
- **Topic:** Summary of findings

5. Wiki-Link Format

Use Obsidian wiki-links for all internal references:

[[tasks/1.1-project-structure]]           # Same directory
[[../research/unity-cinemachine]]         # Relative path
[[tasks/4.1-ui-framework|UI Framework]]   # With display text

File Templates

README.md Template

# Project Name

> **For Claude:** Read specific phase/task files as needed. Don't load everything at once.

**Goal:** [One sentence goal]

**Tech Stack:** [Key technologies]

---

## Quick Links

- [[CLAUDE]] - **Rules for Claude** (read first)
- [[changelog]] - Amendment history with links

## Research

- [[research/topic]] - Description

## Phases

| Phase | Description | File |
|-------|-------------|------|
| 1 | Phase Name | [[phases/01-name]] |
| 2 | Phase Name | [[phases/02-name]] |

## Task Index

### Phase 1: Name
- [[tasks/1.1-slug|1.1 Task Title]]
- [[tasks/1.2-slug|1.2 Task Title]]

Task File Template

# Task X.Y: Title

**Phase:** N - Phase Name
**Commit:** `type(scope): description`

%% [ ] any open questions %%

> **Research:** See [[../research/topic]] if applicable

## Overview
[Brief description]

## Files
- Create: `path/to/file.ext`
- Update: `path/to/existing.ext`

## Steps

### Step 1: Name
[Implementation details]

## Success Criteria
- [ ] Criterion 1
- [ ] Criterion 2

CLAUDE.md Template

See references/claude-template.md for the full template.

Workflow Patterns

Creating a New Plan

1. Create directory structure (see above)
2. Write README.md with phase overview
3. Create CLAUDE.md with plan-specific rules
4. Initialize changelog.md
5. Create phase files with task lists
6. Create individual task files as needed

Processing Open Tasks

1. Find open tasks: grep -r '%% \[ \]' path/to/plan/
2. For each task:
   • Read the file containing the task
   • Determine if research is needed
   • Execute research (oracle or Delphi)
   • Update task marker to [x] with result link
   • Update changelog

Adding Research

1. Create file in research/ directory
2. Use descriptive name: topic-name.md or topic-delphi.md for Delphi synthesis
3. Include metadata header:

   > **Research Type:** Oracle | Delphi
   > **Date:** YYYY-MM-DD
   > **Topic:** Brief description
   

4. Update research index if exists
5. Link from relevant task files
6. Add to changelog

Converting Diagrams to Mermaid

Replace ASCII art and text flow diagrams with Mermaid:

# Before (ASCII)
Phase 1 → Phase 2 → Phase 3

# After (Mermaid)
​```mermaid
graph LR
    P1[Phase 1] --> P2[Phase 2] --> P3[Phase 3]
​```

Preserve directory trees as-is (they're fine as ASCII).

Best Practices

1. Keep files focused - One topic per file, link to related content
2. Use consistent naming - {phase}.{task}-{slug}.md for tasks
3. Update changelog immediately - Don't batch changes
4. Preserve deferred work - Never delete, move to deferred.md
5. Version before major changes - Copy to {filename}.v{n}.md
6. Research before deciding - Use oracles for uncertain questions