1 files changed, 58 insertions, 0 deletions
diff --git a/claude-rules/todo-format.md b/claude-rules/todo-format.md
new file mode 100644
index 0000000..f8bc88f
--- /dev/null
+++ b/claude-rules/todo-format.md
@@ -0,0 +1,58 @@
+# Todo Entry Format
+
+Applies to: `**/*.org` (org-mode todo and inbox files)
+
+How task entries are structured in org-mode todo files (`todo.org`,
+`inbox.org`, any GTD-style org file). Same shape across every project.
+
+## The Rule
+
+A todo entry has two parts:
+
+1. **Heading** — terse subject naming just the topic. No action verbs, no
+   sentence-shape, no dates. Tags belong on the heading line.
+2. **Body** (optional) — fuller description: action verbs, context,
+   rationale, source/origin, links, deadlines. Used when the topic alone
+   isn't enough.
+
+When the topic alone is enough, skip the body entirely.
+
+## Format
+
+    ** TODO [#A] Terse topic phrase :tag1:tag2:
+    Optional body — fuller description, action verbs, context, links.
+
+    Multi-paragraph body is fine when context warrants it.
+
+## Examples
+
+Good:
+
+    ** TODO [#A] Blacken + Prettier config from Vrezh
+    Ask Jason to implement the formatter config Vrezh sends over.
+
+    ** TODO [#B] TAK-server plugin user scenarios :quick:
+    Develop with Eric, send to Nate Soule for review.
+    Out of the 2026-05-13 RTX<>DeepSat sync.
+
+Bad (sentence-shaped heading, details crammed in):
+
+    ** TODO [#B] Develop TAK-server plugin user scenarios with Eric, send to Nate :quick:
+
+## Why
+
+The org agenda view shows the heading. A short heading is scannable; a
+sentence-shaped one runs off the edge of the agenda buffer, and the
+context that mattered ends up in the truncated tail. The body is always
+reachable by visiting the entry — push everything beyond the topic there.
+
+## How to apply
+
+When adding a new task:
+
+1. Pick the smallest noun phrase that names the topic.
+2. If anything else is worth saying, put it in the body.
+3. Tags go on the heading line, not in the body.
+
+When restructuring an existing entry that's already sentence-shaped, split
+it: keep the topic as the heading, move the rest to the body.