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 handbook call:

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

Quickstart

1. Read docs/AGENTS.md (and docs/handbook/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)
├── 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.

Rebase Strategy

Read and follow the handbook 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.