From a6a10ab195947c9c040cf7687b449720562657fc Mon Sep 17 00:00:00 2001 From: Darren Cheng Date: Tue, 18 Aug 2026 15:25:16 -0700 Subject: [PATCH 1/2] docs(agents): document global CLAUDE.md sync convention, add Linear priority rule Establishes agents/AGENTS.md as the mirrored source of truth for the user's global ~/.claude/CLAUDE.md and records the never-Urgent-priority Linear rule in both copies. --- AGENTS.md | 14 +++++++++++++- agents/AGENTS.md | 4 ++++ 2 files changed, 17 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index b3f20cd2..2cd9b065 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -124,7 +124,7 @@ tooling) into CI. The quality gate is and stays the **Pre-Completion Checklist** | hammerspoon | Window management | | tools | Devbox, Claude Code, Codex | | osx | macOS defaults | -| agents | Agent skills, custom agents, hooks, and status line (symlinks agents/skills → ~/.claude/skills + ~/.agents/skills, agents/custom → ~/.claude/agents, registers hooks and status line in ~/.claude/settings.json) | +| agents | Agent skills, custom agents, hooks, and status line (symlinks agents/skills → ~/.claude/skills + ~/.agents/skills, agents/custom → ~/.claude/agents, agents/AGENTS.md → ~/.claude/CLAUDE.md, registers hooks and status line in ~/.claude/settings.json) | | pi | pi.dev coding agent CLI + config (installs pi via curl pi.dev/install.sh, symlinks pi/agent/models.json → ~/.pi/agent/models.json, and seeds defaultProvider/defaultModel for Ollama qwen3:32b in ~/.pi/agent/settings.json; auth.json and sessions/ stay local) | ## Writing Skills / Slash Commands @@ -232,6 +232,18 @@ Put personal or org-specific knowledge in private project-local CLAUDE.md files, When receiving a handoff for `~/.dots` skill changes, apply them to this workspace under `agents/skills/`. This repo is the source of truth for skills — `~/.claude/skills/` is a symlink to `agents/skills/` via `dots install agents`. +## Global CLAUDE.md Sync + +This repo controls the user's global Claude Code instructions: `agents/AGENTS.md` is the source of +truth, symlinked to `~/.claude/CLAUDE.md` via `dots install agents` (see +`cli/commands/install/agents.go`). Whenever the user asks to update their global CLAUDE.md, make the +same edit to `agents/AGENTS.md` here so the repo copy stays in sync — don't only edit the live +`~/.claude/CLAUDE.md`. + +Apply the Public Repo Policy below when syncing: only mirror generic, reusable instructions into +`agents/AGENTS.md`. If an instruction is personal or org-specific, leave it in the user's local +`~/.claude/CLAUDE.md` only. + ## README Maintenance When making changes that affect user-facing features — adding/removing skills, custom agents, CLI commands, components, or utilities — always update `README.md` to reflect those changes. Keep counts, tables, and the project structure tree accurate. diff --git a/agents/AGENTS.md b/agents/AGENTS.md index 94cc7783..0d3ab5bf 100644 --- a/agents/AGENTS.md +++ b/agents/AGENTS.md @@ -8,6 +8,10 @@ - **Third-party code review**: Invoke `Skill("security-review")` before an ad-hoc grep-based review — it has no local SKILL.md file, so it's easy to forget. - **General rule**: If a task matches an available skill, invoke `Skill("")` before attempting any other approach. +## Linear + +- Never create a Linear ticket with Urgent priority — it triggers a PagerDuty alert. Use a lower priority unless the user explicitly confirms they want the page. + ## TTS Notifications **ALWAYS speak aloud when completing ANY task or waiting for user input.** From 128f3ac3a3597fe7c3dd2417e54e4f5a8315fe7d Mon Sep 17 00:00:00 2001 From: Darren Cheng Date: Tue, 18 Aug 2026 15:26:43 -0700 Subject: [PATCH 2/2] docs(agents): fix section-reference direction in CLAUDE.md sync note Review caught that the new Global CLAUDE.md Sync section pointed "below" at the Public Repo Policy section, which actually sits above it. --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 2cd9b065..0d603d1f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -240,7 +240,7 @@ truth, symlinked to `~/.claude/CLAUDE.md` via `dots install agents` (see same edit to `agents/AGENTS.md` here so the repo copy stays in sync — don't only edit the live `~/.claude/CLAUDE.md`. -Apply the Public Repo Policy below when syncing: only mirror generic, reusable instructions into +Apply the Public Repo Policy above when syncing: only mirror generic, reusable instructions into `agents/AGENTS.md`. If an instruction is personal or org-specific, leave it in the user's local `~/.claude/CLAUDE.md` only.