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
│   ├── 05-common-tools/   # Foundational tools (git, tickets)
│   │   ├── 05-00-git/SKILL.md
│   │   └── 05-01-ticket/SKILL.md
│   ├── 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
05.00	Git — commit format, rebase/merge, reverting	playbook/05-common-tools/05-00-git/SKILL.md
05.01	Ticket — lifecycle, deps, agent coordination	playbook/05-common-tools/05-01-ticket/SKILL.md
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.00	Refactor index	playbook/30-refactor/30-00-refactor-index/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
30.03	Test-driven refactoring	playbook/30-refactor/30-03-test-driven-refactoring/SKILL.md
30.04	Closure monolith decomposition (TS)	playbook/30-refactor/30-04-ts-closure-monolith-decomposition/SKILL.md
40.00	Architecture index	playbook/40-architecture/40-00-architecture-index/SKILL.md
40.01	State ownership	playbook/40-architecture/40-01-state-ownership/SKILL.md
40.02	Module boundaries	playbook/40-architecture/40-02-module-boundaries/SKILL.md
40.03	Dependency direction	playbook/40-architecture/40-03-dependency-direction/SKILL.md
40.04	Domain logic separation (TS)	playbook/40-architecture/40-04-ts-domain-logic-separation/SKILL.md
40.05	Singleton patterns (TS)	playbook/40-architecture/40-05-ts-singleton-patterns/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
80.04	Repo hygiene	playbook/80-agent-behaviour/80-04-repo-hygiene/SKILL.md
70.02	Concern ownership audit	playbook/70-project-health/70-02-concern-ownership-audit/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