diff --git a/src/hooks/todo-description-override/description.ts b/src/hooks/todo-description-override/description.ts
index 98129a8d2..2046889c7 100644
--- a/src/hooks/todo-description-override/description.ts
+++ b/src/hooks/todo-description-override/description.ts
@@ -1,5 +1,15 @@
 export const TODOWRITE_DESCRIPTION = `Use this tool to create and manage a structured task list for tracking progress on multi-step work.
 
+## OpenCode Schema Contract
+
+The upstream OpenCode \`todowrite\` schema expects each todo item to include:
+
+- \`content\`: string
+- \`status\`: string, one of \`pending\`, \`in_progress\`, \`completed\`, \`cancelled\`
+- \`priority\`: string, one of \`high\`, \`medium\`, \`low\`
+
+\`priority\` is a string field. Never send numeric priorities such as \`0\`, \`1\`, \`2\`, or labels such as \`P0\`, \`P1\`, \`P2\`.
+
 ## Todo Format (MANDATORY)
 
 Each todo title MUST encode four elements: WHERE, WHY, HOW, and EXPECTED RESULT.
diff --git a/src/hooks/todo-description-override/index.test.ts b/src/hooks/todo-description-override/index.test.ts
index 374b13a98..0976a229d 100644
--- a/src/hooks/todo-description-override/index.test.ts
+++ b/src/hooks/todo-description-override/index.test.ts
@@ -37,4 +37,14 @@ describe("createTodoDescriptionOverrideHook", () => {
       })
     })
   })
+
+  describe("#given todowrite description is overridden", () => {
+    describe("#when the model reads schema guidance", () => {
+      it("#then should require string priorities matching OpenCode schema", () => {
+        expect(TODOWRITE_DESCRIPTION).toContain("`priority`: string")
+        expect(TODOWRITE_DESCRIPTION).toContain("`high`, `medium`, `low`")
+        expect(TODOWRITE_DESCRIPTION).toContain("Never send numeric priorities")
+      })
+    })
+  })
 })