obsidian-plan-wiki

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Obsidian Spec Wiki

Obsidian 规范Wiki

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

兼容Obsidian的Markdown维基。功能区域记录系统做什么（规范）以及如何构建（计划）。仅加载你需要的内容。

00.00 Johnny Lookup (CRITICAL)

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.

如果用户只提供类似

20.01

（或

）的ID，将其视为手册调用：

检查项目中的
```
docs/handbook/**/20.01-*.md
```
文件——如果存在，读取并遵循其中的说明。
如果本地文件不存在，读取本skill目录中
```
handbook/20-git/20.01-*.md
```
文件。
严格按照说明执行。

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
```
.

阅读
```
docs/AGENTS.md
```
（如果存在，同时阅读
```
docs/handbook/README.md
```
）。
确定结构：
```
features/
```
或
```
workstreams/
```
（将工作流视为功能区域）。
使用带两位小数的Johnny Decimal命名规则（
```
NN.NN
```
）。
应用开放式问题格式（
```
🙋‍♂️/🤖/✅
```
）并添加块ID。
通过
```
tk
```
和
```
tinychange
```
跟踪变更。

Wiki Discovery

Wiki 发现顺序

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.

按以下顺序检查——第一个匹配项优先：

```
docs/
```
—— 主目录
```
docs/wiki/
```
—— 嵌套变体
```
wiki/
```
—— 根目录替代方案
计划工单（标记为
```
plan
```
）—— 通过
```
tk list --tag plan
```
命令查看

新建维基请始终使用

docs/

目录。

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
```
)

docs/
├── README.md              # 带功能表格的索引（Johnny Decimal格式）
├── AGENTS.md              # 符号链接 → AGENTS.md
├── AGENTS.md              # Agent 说明文档
├── changelog.md           # 变更日志（由tinychange生成）
├── handbook/              # 流程/工具文档（Johnny Decimal格式）
│   ├── AGENTS.md          # 本目录规则
│   ├── README.md          # 区域索引
│   ├── 10-docs/           # 文档工作流
│   ├── 15-planning/       # 规划工作流与工具
│   ├── 20-git/            # Git 合并流水线与分支处理
│   ├── 30-refactor/       # 重构指南与检查清单
│   ├── 50-testing/        # 测试工作流与验证
│   └── 80-agent-behaviour/# Agent 自主性与行为规则
│   # 计划：使用标记为`plan`的工单（不设plans/目录）
│   # 事后分析：使用标记为`postmortem`的工单（不设postmortems/目录）
├── reference/             # 架构与研究文档（Johnny Decimal格式）
│   ├── AGENTS.md          # 本目录规则
│   ├── README.md          # 区域索引
│   └── decisions/         # 架构决策记录（ADRs，采用Johnny Decimal ID）
├── features/              # 功能区域（Johnny Decimal格式）
│   └── NN-name/           # 区域（10-19, 20-29, ...）
│       ├── README.md      # 区域摘要 + 规范/计划表格
│       ├── AGENTS.md      # 可选：区域特定规则
│       ├── NN.NN-spec.md  # 行为规范（做什么）
│       └── NN.NN-plan.md  # 实现计划（怎么做）
│   # 研究：使用标记为`research`的工单（不设research/目录）

计划存储位置（两种均有效）：

功能范围：
```
docs/features/NN-area/NN.NN-*-plan.md
```
跨领域：标记为
```
plan
```
的工单（通过
```
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`

本skill提供标准手册条目。项目可通过在

docs/handbook/

目录下创建相同Johnny Decimal ID的本地文件来覆盖任意条目。

查找规则：本地文件优先 → skill目录作为备选。

ID	条目	Skill 路径
`10.01`	开放式问题系统	`handbook/10-docs/10.01-open-questions-system.md`
`10.02`	问题归档	`handbook/10-docs/10.02-question-archive.md`
`10.03`	Obsidian 文档流程	`handbook/10-docs/10.03-obsidian-flow.md`
`15.02`	规范差异审计	`handbook/15-planning/15.02-spec-divergence.md`
`15.03`	工单差异审计	`handbook/15-planning/15.03-ticket-divergence.md`
`15.04`	评审转工单	`handbook/15-planning/15.04-review-to-tickets.md`
`20.01`	变基准备（调研）	`handbook/20-git/20.01-methodic-rebase-merge.md`
`20.02`	变基（执行）	`handbook/20-git/20.02-authoritative-main-rebase.md`
`20.03`	合并（执行）	`handbook/20-git/20.03-merge-local-safe.md`
`20.04`	合并后清理	`handbook/20-git/20.04-post-merge-hygiene.md`
`30.01`	完整重构指南	`handbook/30-refactor/30.01-full-refactor-guide.md`
`50.01`	基于视频的NHITL测试	`handbook/50-testing/50.01-video-based-nhitl-testing.md`
`80.01`	自主工作	`handbook/80-agent-behaviour/80.01-autonomous-work.md`
`80.02`	文档化功能	`handbook/80-agent-behaviour/80.02-document-feature.md`
`80.03`	过时代码树	`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]

阅读并遵循

20-git

目录下的手册说明。若情况特殊，执行关键合理性检查。如有疑问，询问用户（Hooman）。

```
20.01
```
变基准备
```
20.02
```
变基操作

必须通过明确的
[R]
确认变基操作。

Merge Strategy

合并策略

ONLY MERGE IF EXPLICITLY REQUESTED.

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

ALWAYS CONFIRM MERGE WITH EXPLICIT

[M]

仅在明确请求时执行合并操作。

```
20.03
```
合并操作
```
20.04
```
合并后清理

必须通过明确的
[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.

规范、计划和代码需同步更新：

打开或关联一个
```
tk
```
工单。
更新相关的规范/计划。
更新代码。

添加变更日志条目：

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

在条目中关联工单和功能ID。

Codebase AGENTS.md

代码库AGENTS.md

Every top-level code folder needs an

AGENTS.md

: purpose, feature area IDs, boundaries, entry points, tests.

每个顶级代码目录都需要一个

AGENTS.md

文件：说明目录用途、功能区域ID、边界、入口点、测试内容。

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.

规范描述行为（做什么）。计划描述实现方式（怎么做）。
所有引用均为维基链接。断链表示需要同步更新。
立即通过
```
tinychange
```
更新变更日志。禁止手动编辑。
每个功能/组件对应一个规范。
决策前先调研——使用决策工具（oracles）。
AGENTS.md始终是指向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`

仅在需要时阅读这些文件。请勿预加载。

场景	阅读内容
需要Johnny Decimal规则、开放式问题格式、tk工作流、tinychange命令	`references/core-principles.md`
需要规范模板、计划模板、可靠计划规则、AGENTS.md模板、README模板	`references/templates.md`
创建维基、添加规范/计划、调研工作流、更新规范、链接格式	`references/workflows.md`
编写事后分析、事后分析模板、何时编写事后分析	`references/postmortems.md`
开放式问题系统细节和Dataview索引	`references/obsidian-open-questions-system.md`
AGENTS.md / AGENTS.md模板（精简版）	`references/claude-template.md`