Global Agent Instructions

Universal rules for AI coding agents. CLAUDE.md symlinks here.

Before Work

• Read root PROGRESS.md at session start.

• Use context7, or the agent's equivalent docs MCP, for code generation, setup/configuration, and library/API docs. Resolve and fetch docs without waiting for an explicit ask.

• Adaptive docs. Read the matching file BEFORE relevant work and announce 📖 Loading context: <path>.md.

  • Per-project: if the project has docs/ai/, treat it as source of truth.
  • Global (~/dotfiles/docs/ai/):

  Task	Doc
  Git operations, committing, rebasing, merging	git.md
  Editing AGENTS.md, .agents/skills/, docs/ai/	writing-docs.md

• Re-read the hard rules before implementation.

Session Tools

• MANDATORY: invoke task-observer BEFORE your first tool call in any task-oriented session where tools produce deliverables. Non-negotiable. No rationalizing ("quick task", "I'll invoke later", "doesn't count"). Skipping it loses observations across dozens of future sessions; the cost is ~50 tokens. The SessionStart hook reinforces this. Subagents skip — Task-dispatched sessions have no user-feedback signal; the parent agent owns observation logging for delegated work.
• Store task-observer files centrally:

<project-slug> is the git toplevel basename, or _meta outside git. The repo is auto-committed by launchd and reviewed M/W/F on divad12/agent-observations.

Superpowers Paths

Never write Superpowers artifacts under docs/superpowers/. Use:

Keep the feature folder together: design.md, plan.md, checklist.md, deferred.md, and reviews/.

Writing

• Comment the why, not the what.
• When tightening docs, remove redundancy without softening corrective guardrails.

Surfacing to the User

For any recommendation, decision, deferred item, review finding, blocker, or question, use plain English and include the user-facing ramification.

Why: without the ramification, findings read like engineering todos and I cannot weigh them against product priorities. With it, they become decisions I can make.

• Lead with what the user sees, loses, feels, or risks.
• Translate jargon into product framing: "unsafe cast" becomes "custom field edits could crash on save."
• File:line citations are references, not the explanation.
• If there is no product impact, say: "No user-facing impact - this is internal."
• If you cannot state the impact, re-read before surfacing.

Code Hard Rules

These rules prevent the common agent failure mode: making a small, plausible shortcut under context pressure and leaving the user with a hidden regression.

• Preserve existing working behavior unless the user approves the change. Self-check: if reverting the feature would change anything else, ask first.
• Search before writing any function, helper, utility, or computation. Reuse existing code instead of recreating it. Stop signals: "I need a helper", "simplest approach", "let me add a utility", or "I'll compute this by".
• Trace callers before changing a function. Most regressions happen when a caller two levels up depended on behavior that looked local.
• Keep one source of truth. No duplicate logic, duplicate data, copy-pasted components, parallel parameters, or lighter duplicate functions. They will diverge, so extend the existing mechanism instead.
• Make contracts unbreakable. Shared shapes, values, cleanup, sequences, and coupled operations belong in shared helpers, wrappers, builders, types, or tests. A new call site should not be able to silently get the contract wrong.
• Fix visible violations in the touched area: duplication, hardcoded values, missing boundary tests, and bypassed guardrails are part of the task. Leaving them in place means the next change starts from a known broken pattern.
• Prefer fixing weak infrastructure over working around it. Hard fixes usually mean the abstraction is missing or the data flow needs simplifying.
• Ask before assuming deployment context, geography, scale, or user base. Scope guesses become product decisions if they land in code.
• Correctness over laziness. Most bugs come from taking the easy path under context pressure, not from missing requirements. If a scope/correctness tradeoff is needed, ask the user so they can choose deliberately.
• No silent shortcuts. If correctness cannot fit right now, only two options are allowed: break the work into smaller PROGRESS.md subtasks and tell the user, or mark the incomplete spot with FIXME: explaining what is wrong and what the correct fix is. Unmarked shortcuts are bugs.
• Stop immediately if you think: "for now", "MVP", "only one user", "I'll come back", "this is fine", or "let me just". Do it correctly, ask the user, or write the FIXME:.

Testing

• TDD always: write the failing test first, run it, then implement without changing that test. No rationalizing. If code comes first, stop immediately, back it out, and write the test.
• For user-reported bugs, first write a test that reproduces the report from the user's perspective.
• If a project legitimately does not warrant TDD, its AGENTS.md must override this with rationale.