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

), treat it as a handbook call:

Check
```
docs/handbook/**/20.01-*.md
```
in the project — if it exists, read and follow it.
If no local file exists, read
```
handbook/20-git/20.01-*.md
```
from this skill's directory.
Follow the instructions literally.

Quickstart

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

Wiki Discovery

Check in order — first match wins:

```
docs/
```
— primary
```
docs/wiki/
```
— nested variant
```
wiki/
```
— root alternative
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)
├── handbook/              # Process/tooling docs (Johnny Decimal)
│   ├── AGENTS.md          # Rules for this directory
│   ├── README.md          # Area index
│   ├── 10-docs/           # Documentation workflows
│   ├── 15-planning/       # Planning workflows and tooling
│   ├── 20-git/            # Git merge pipeline and branch handlers
│   ├── 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
```
)

Handbook (Canonical Entries)

The skill provides canonical handbook entries. Projects can override any entry by creating a local file at the same Johnny Decimal ID in

docs/handbook/

Lookup: local file wins → skill fallback.

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

Rebase Strategy

Read and follow the handbook in

20-git

. Use critical sanity check if circumstances deviate. In case of doubt, ask the Hooman.

```
20.01
```
Rebase Preparations
```
20.02
```
Rebase

ALWAYS CONFIRM REBASE WITH EXPLICIT

[R]

Merge Strategy

ONLY MERGE IF EXPLICITLY REQUESTED.

```
20.03
```
Merge
```
20.04
```
Post-Merge

ALWAYS CONFIRM MERGE WITH EXPLICIT

[M]

Change Tracking (No LWW)

Specs, plans, and code are updated intentionally and together:

Open or reference a
```
tk
```
ticket.
Update the relevant spec/plan.
Update the code.

Add a changelog entry:

tinychange -I new -k <kind> -m "t-XXXX: message" -a AUTHOR

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

Specs describe behavior (what). Plans describe implementation (how).
All references are wiki links. Broken links = sync signal.
Update changelog via
```
tinychange
```
immediately. Never hand-edit.
One spec per feature/component.
Research before deciding — use oracles.
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`

obsidian-plan-wiki

NPX Install

Tags

SKILL.md Content