---
name: obsidian-plan-wiki
description: Create and manage behavior specification wikis in Obsidian format. Use when creating specs, documenting features, or when user mentions "wiki", "spec", "feature", or "Obsidian".
---

# Obsidian Spec Wiki

Obsidian-compatible markdown wikis. Feature areas capture **what** the system does (specs) and **how** to build it (plans). Load only what you need.

## 00.00 Johnny Lookup (CRITICAL)

If the human gives you **only** an ID like `20.01` (or `2001`), treat it as a **playbook call**:

1. Replace the dot with a hyphen: `20.01` → `20-01`
2. Check `docs/playbook/**/20-01-*/SKILL.md` in the project — if it exists, read and follow it.
3. If no local file exists, read `playbook/**/20-01-*/SKILL.md` from **this skill's directory**.
4. Follow the instructions literally.

## Quickstart

1. Read `docs/AGENTS.md` (and `docs/playbook/README.md` if present).
2. Identify structure: `features/` or `workstreams/` (treat workstreams as feature areas).
3. Use Johnny Decimal with two-digit decimals (`NN.NN`).
4. Apply open-questions format (`🙋‍♂️/🤖/✅`) with block IDs.
5. Track changes via `tk` and `tinychange`.

## Wiki Discovery

Check in order — first match wins:
1. `docs/` — primary
2. `docs/wiki/` — nested variant
3. `wiki/` — root alternative
4. Plan tickets (tagged `plan`) — via `tk list --tag plan`

Always use `docs/` for new wikis.

## Directory Structure

```
docs/
├── README.md              # Index with feature table (Johnny Decimal)
├── AGENTS.md              # Symlink → AGENTS.md
├── AGENTS.md              # Agent instructions
├── changelog.md           # Keep a Changelog (generated by tinychange)
├── playbook/              # Process/tooling docs (Johnny Decimal, SKILL.md per entry)
│   ├── AGENTS.md          # Rules for this directory
│   ├── README.md          # Area index
│   ├── 10-docs/           # Documentation workflows
│   │   └── 10-01-open-questions-system/SKILL.md
│   ├── 15-planning/       # Planning workflows and tooling
│   ├── 20-git/            # Git merge pipeline and branch handlers
│   │   └── 20-01-methodic-rebase-merge/SKILL.md
│   ├── 30-refactor/       # Refactor guidance and checklists
│   ├── 50-testing/        # Testing workflows and verification
│   └── 80-agent-behaviour/# Agent autonomy and behaviour rules
│   # Plans: use tickets tagged `plan` (no plans/ directory)
│   # Postmortems: use tickets tagged `postmortem` (no postmortems/ directory)
├── reference/             # Architecture + research (Johnny Decimal)
│   ├── AGENTS.md          # Rules for this directory
│   ├── README.md          # Area index
│   └── decisions/         # ADRs (Johnny Decimal IDs)
├── features/              # Feature areas (Johnny Decimal)
│   └── NN-name/           # Area (10-19, 20-29, ...)
│       ├── README.md      # Area summary + spec/plan tables
│       ├── AGENTS.md      # Optional: area-specific rules
│       ├── NN.NN-spec.md  # Behavior spec (what)
│       └── NN.NN-plan.md  # Implementation plan (how)
│   # Research: use tickets tagged `research` (no research/ directory)
```

**Plan locations (both valid):**
- Feature-scoped: `docs/features/NN-area/NN.NN-*-plan.md`
- Cross-cutting: tickets tagged `plan` (created via `todos_oneshot`)

## Playbook (Canonical Entries)

The skill provides canonical playbook entries — each is a SKILL.md (standard format understood by LLM agents). Projects can override any entry by creating a local file at the same Johnny Decimal ID in `docs/playbook/`.

**Lookup: local file wins → skill fallback.**

| ID | Entry | Skill Path |
|----|-------|------------|
| `10.01` | Open questions system | `playbook/10-docs/10-01-open-questions-system/SKILL.md` |
| `10.02` | Question archive | `playbook/10-docs/10-02-question-archive/SKILL.md` |
| `10.03` | Obsidian documentation flow | `playbook/10-docs/10-03-obsidian-flow/SKILL.md` |
| `15.02` | Spec divergence audit | `playbook/15-planning/15-02-spec-divergence/SKILL.md` |
| `15.03` | Ticket divergence audit | `playbook/15-planning/15-03-ticket-divergence/SKILL.md` |
| `15.04` | Review-to-tickets | `playbook/15-planning/15-04-review-to-tickets/SKILL.md` |
| `20.01` | Rebase preparations (investigate) | `playbook/20-git/20-01-methodic-rebase-merge/SKILL.md` |
| `20.02` | Rebase (execute) | `playbook/20-git/20-02-authoritative-main-rebase/SKILL.md` |
| `20.03` | Merge (execute) | `playbook/20-git/20-03-merge-local-safe/SKILL.md` |
| `20.04` | Post-merge hygiene | `playbook/20-git/20-04-post-merge-hygiene/SKILL.md` |
| `20.05` | Debrief | `playbook/20-git/20-05-debrief/SKILL.md` |
| `15.05` | Pre-mortem | `playbook/15-planning/15-05-premortem/SKILL.md` |
| `30.01` | Full refactor guide | `playbook/30-refactor/30-01-full-refactor-guide/SKILL.md` |
| `30.02` | Convergence audit | `playbook/30-refactor/30-02-convergence-audit/SKILL.md` |
| `50.01` | Video-based NHITL testing | `playbook/50-testing/50-01-video-based-nhitl-testing/SKILL.md` |
| `80.01` | Autonomous work | `playbook/80-agent-behaviour/80-01-autonomous-work/SKILL.md` |
| `80.02` | Document feature | `playbook/80-agent-behaviour/80-02-document-feature/SKILL.md` |
| `80.03` | Stale trees | `playbook/80-agent-behaviour/80-03-stale-trees/SKILL.md` |

### Rebase Strategy

Read and follow the playbook in `20-git`. Use critical sanity check if circumstances deviate. In case of doubt, ask the Hooman.

1. `20.01` Rebase Preparations
2. `20.02` Rebase

ALWAYS CONFIRM REBASE WITH EXPLICIT `[R]`.

### Merge Strategy

ONLY MERGE IF EXPLICITLY REQUESTED.

1. `20.03` Merge
2. `20.04` Post-Merge

ALWAYS CONFIRM MERGE WITH EXPLICIT `[M]`.

## Change Tracking (No LWW)

Specs, plans, and code are updated intentionally and together:
1. Open or reference a `tk` ticket.
2. Update the relevant spec/plan.
3. Update the code.
4. Add a changelog entry: `tinychange -I new -k <kind> -m "t-XXXX: message" -a AUTHOR`
5. Link the ticket and feature ID in the entry.

## Codebase AGENTS.md

Every top-level code folder needs an `AGENTS.md`: purpose, feature area IDs, boundaries, entry points, tests.

## Best Practices

1. Specs describe behavior (what). Plans describe implementation (how).
2. All references are wiki links. Broken links = sync signal.
3. Update changelog via `tinychange` immediately. Never hand-edit.
4. One spec per feature/component.
5. Research before deciding — use oracles.
6. AGENTS.md is always a symlink to AGENTS.md.

## Reference Files (Load on Demand)

Read these **only when you need them**. Do not preload.

| When | Read |
|------|------|
| Need Johnny Decimal rules, open questions format, tk workflow, tinychange commands | `references/core-principles.md` |
| Need spec template, plan template, bulletproof plan rules, AGENTS.md template, README template | `references/templates.md` |
| Creating a wiki, adding specs/plans, research workflow, updating specs, link format | `references/workflows.md` |
| Writing a postmortem, postmortem template, when to write one | `references/postmortems.md` |
| Open questions system details and Dataview index | `references/obsidian-open-questions-system.md` |
| AGENTS.md / AGENTS.md template (compact version) | `references/claude-template.md` |