docs: require Linear sync in agent instructions

AGENTS.md

@@ -104,6 +104,16 @@ Coding agents MUST verify every implementation end-to-end before considering it
 
 Do NOT rely solely on unit tests passing. If you cannot run it and see it work, it is not done. Hand over PR links, merge commits, deployment links, and live test results.
 
+## Linear Sync (Mandatory)
+
+Linear is the source of truth for work tracking. For TemperPaw work, agents must keep Linear synchronized at discovery, start, and completion.
+
+- Discovering an issue -> search Linear first. If a matching issue exists, update or append to it; do not create a duplicate. If none exists, create one in the right project with clear title, priority, labels, and context.
+- Starting work -> find the relevant Linear issue before implementation, add a start/progress comment, assign it to yourself when appropriate, and move it to In Progress. If no issue exists, create one only after a dedup search.
+- Completing work -> move the issue to Done only after attaching every artifact of the work: commits, PRs, proof reports, deployment links, and relevant verification notes. Record residual risks and follow-ups as linked issues.
+
+All updates must be additive: append comments, links, and findings without overwriting prior context. If Linear tools are unavailable, say so explicitly and do not claim sync happened.
+
 ## Root Cause & Operations
 
 - When something "keeps happening" or "didn't use to happen": find **what changed** (read the code, read Datadog), fix the root cause, and explain the causal story — why it started, what the fix is, how you verified. Never stack fixes on fixes.

CLAUDE.md

@@ -104,6 +104,16 @@ Coding agents MUST verify every implementation end-to-end before considering it
 
 Do NOT rely solely on unit tests passing. If you cannot run it and see it work, it is not done. Hand over PR links, merge commits, deployment links, and live test results.
 
+## Linear Sync (Mandatory)
+
+Linear is the source of truth for work tracking. For TemperPaw work, agents must keep Linear synchronized at discovery, start, and completion.
+
+- Discovering an issue -> search Linear first. If a matching issue exists, update or append to it; do not create a duplicate. If none exists, create one in the right project with clear title, priority, labels, and context.
+- Starting work -> find the relevant Linear issue before implementation, add a start/progress comment, assign it to yourself when appropriate, and move it to In Progress. If no issue exists, create one only after a dedup search.
+- Completing work -> move the issue to Done only after attaching every artifact of the work: commits, PRs, proof reports, deployment links, and relevant verification notes. Record residual risks and follow-ups as linked issues.
+
+All updates must be additive: append comments, links, and findings without overwriting prior context. If Linear tools are unavailable, say so explicitly and do not claim sync happened.
+
 ## Root Cause & Operations
 
 - When something "keeps happening" or "didn't use to happen": find **what changed** (read the code, read Datadog), fix the root cause, and explain the causal story — why it started, what the fix is, how you verified. Never stack fixes on fixes.

INSTRUCTIONS.md

@@ -17,6 +17,14 @@ git clone https://github.com/nerdsane/temperpaw.git
 cd temperpaw
 ```
 
+Before setup or implementation work, sync with Linear:
+
+- Search Linear for an existing matching issue before creating anything new.
+- If an issue exists, append progress there instead of creating a duplicate.
+- When starting work, move the issue to In Progress and add a start comment.
+- When completing work, attach commits, PRs, proof reports, deployment links, and verification notes before moving the issue to Done.
+- If Linear tools are unavailable, say so explicitly and do not claim sync happened.
+
 ### 2. Configure
 
 Write a `.env` file with the human's API key. The key goes in `ANTHROPIC_API_KEY` regardless of provider — the platform detects the provider from the key prefix.