From d98cc41e62611b553bde833342c04c4cd6c0a302 Mon Sep 17 00:00:00 2001 From: rita-aga Date: Wed, 17 Jun 2026 22:34:41 -0400 Subject: [PATCH] docs: require Linear sync in agent instructions --- AGENTS.md | 10 ++++++++++ CLAUDE.md | 10 ++++++++++ INSTRUCTIONS.md | 8 ++++++++ 3 files changed, 28 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index bbcd82c82..8910dd581 100644 --- a/AGENTS.md +++ b/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. diff --git a/CLAUDE.md b/CLAUDE.md index 5422fc985..ef5251462 100644 --- a/CLAUDE.md +++ b/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. diff --git a/INSTRUCTIONS.md b/INSTRUCTIONS.md index bf92f257f..5a42ef093 100644 --- a/INSTRUCTIONS.md +++ b/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.