Refactor AGENTS and CLAUDE for repo-agnostic guidance

AGENTS.md

@@ -1,49 +1,66 @@
 # AGENTS.md
 
-Repository-wide instructions for any autonomous or semi-autonomous coding agent.
+Repository-wide operating instructions for autonomous and semi-autonomous coding agents.
 
-## Purpose
+## Goal
 
-This repository is designed to be reused across many downstream projects. Keep behavior, docs, and naming generic by default unless you are actively working inside a specific downstream repo that requires explicit customization.
+Keep this repository reusable across many downstream projects. Favor generic defaults, portable workflows, and minimal assumptions so the same guidance works in different stacks and environments.
 
-## Startup checklist (run every session)
+## Session startup checklist
 
-1. Read this file (`AGENTS.md`).
-2. Read `CLAUDE.md` for execution conventions.
-3. Read `CONTRIBUTING.md` for commit/PR expectations.
-4. Check `KNOWN_ISSUES.md` for active blockers or workarounds.
+Run this checklist at the beginning of every session:
+
+1. Read `AGENTS.md` (this file).
+2. Read `CLAUDE.md` for execution workflow and handoff rules.
+3. Read `CONTRIBUTING.md` for commit and pull request expectations.
+4. Read `KNOWN_ISSUES.md` for active blockers and workarounds.
 5. Review `docs/agent-handoffs/README.md` and recent notes in:
    - `docs/agent-handoffs/learnings/`
    - `docs/agent-handoffs/incidents/`
 
-## Generic-first policy
+## Repo-agnostic defaults
 
-- Do not hardcode organization, product, customer, or brand-specific details.
-- Do not assume a single deployment environment unless explicitly configured.
-- Prefer neutral names such as `project`, `service`, `integration`, `consumer`, `provider`.
-- Add project-specific notes only when working in that project’s own repository, and label them clearly.
+- Do not hardcode company, product, customer, environment, or team-specific details.
+- Prefer neutral terms such as `project`, `service`, `consumer`, `provider`, `integration`, and `environment`.
+- Avoid assumptions about deployment target (local, cloud, CI, container) unless explicitly configured.
+- Add project-specific details only when required by the current repository and clearly label them as such.
 
-## Agent learning + handoff protocol
+## Decision and implementation policy
 
-Agents are expected to leave concise, reusable notes so future agents do not need to rediscover the same context.
+- Start with the smallest safe change that solves the user request.
+- Prefer explicit commands over implied behavior.
+- Keep edits focused; avoid unrelated refactors.
+- Preserve backward compatibility unless the task explicitly allows breaking changes.
+- If uncertainty remains, document assumptions in the final summary.
 
-### Which file should be updated?
+## Validation baseline
 
-- Update `KNOWN_ISSUES.md` when an issue is active/reproducible and others may hit it.
-- Add a file in `docs/agent-handoffs/learnings/` for reusable successful patterns.
-- Add a file in `docs/agent-handoffs/incidents/` for failures, root cause, and mitigations.
+- Run the most relevant checks for changed files (tests, lint, typecheck, build, or targeted scripts).
+- If a check cannot run due to environment limits, record:
+  - what was attempted,
+  - why it could not run,
+  - what fallback validation was done.
+- Never claim a check passed if it was not executed.
 
-### Naming convention
+## Agent handoff protocol
+
+Capture reusable context so future agents can continue without rediscovery.
+
+### Where to record information
+
+- `KNOWN_ISSUES.md`: active/reproducible issues, current status, impact, and workarounds.
+- `docs/agent-handoffs/learnings/`: successful patterns or repeatable fixes.
+- `docs/agent-handoffs/incidents/`: failures, root causes, and mitigations.
+
+### Note naming
 
 Use generic, descriptive filenames:
 
-- `YYYY-MM-DD-short-topic.md` (example: `2026-02-14-lock-timeout-tuning.md`)
+- `YYYY-MM-DD-short-topic.md`
 
-Avoid product, team, or person-specific prefixes.
+### Required note sections
 
-### Required note structure
-
-Each learning/incident note should include:
+Every new learning/incident note should include:
 
 - Context
 - Observation
@@ -51,29 +68,10 @@ Each learning/incident note should include:
 - Validation performed
 - Recommendation for next agents
 
-Keep each note short, actionable, and safe to share (no secrets).
+## Priority order for conflicting instructions
 
-### When to write a note
-
-Write or update a handoff note when you discover:
-
-- A non-obvious fix or command sequence that works reliably.
-- A recurring failure mode and how to prevent it.
-- A validation step that catches common mistakes early.
-
-## Safety and quality baseline
-
-- Make the smallest safe change first.
-- Prefer explicit commands over assumptions.
-- Validate with relevant tests/checks.
-- If blocked by environment limits, record the blocker and fallback.
-
-## Priority order
-
-When instructions conflict, follow this order:
-
-1. System/developer/user instructions in-session
+1. System/developer/user instructions in the active session
 2. `AGENTS.md`
 3. `CLAUDE.md`
 4. `CONTRIBUTING.md`
-5. Inline comments and prompt files
+5. Inline comments and prompt templates

CLAUDE.md

@@ -1,52 +1,66 @@
 # CLAUDE.md
 
-Operational playbook for agent execution in this repository.
+Execution playbook for agents working in this repository.
 
 ## Scope
 
-Applies to all agent tasks unless superseded by direct runtime instructions.
+Applies to all tasks unless overridden by direct session instructions.
 
-## Operating model
+## Core operating principles
 
-- Keep output and changes generic by default.
-- Prefer deterministic, auditable steps.
-- Record useful decisions so future agents can continue with minimal rediscovery.
+- Be repository-agnostic by default.
+- Keep behavior deterministic and auditable.
+- Prefer minimal, reversible changes.
+- Leave the workspace clearer for the next agent than you found it.
 
-## Execution flow (recommended)
+## Recommended execution workflow
 
-1. Read policy files listed in `AGENTS.md` startup checklist.
-2. Review current known issues and recent handoff notes.
-3. Implement the smallest safe change.
-4. Validate with relevant checks/tests.
-5. Update shared docs (`KNOWN_ISSUES.md` and/or handoff notes) when new reusable knowledge appears.
+1. Load baseline context from `AGENTS.md`, `CONTRIBUTING.md`, `KNOWN_ISSUES.md`, and handoff notes.
+2. Restate the task internally as concrete outcomes.
+3. Make the smallest safe implementation change.
+4. Validate with the most relevant automated checks available.
+5. Summarize results with clear evidence (commands, outputs, and file references).
+6. Record durable learnings/incidents if new reusable knowledge was discovered.
 
-## Handoff documentation workflow
+## Change quality checklist
 
-When you learn something that can help future agents:
+Before finishing, verify:
 
-1. Check for related notes in:
+- The change is scoped to the request.
+- Naming and docs remain generic unless project-specific behavior is explicitly required.
+- Existing workflows are not silently broken.
+- Validation matches the risk level of the change.
+
+## Handoff and documentation expectations
+
+When new reusable context appears:
+
+1. Search for an existing related note in:
    - `docs/agent-handoffs/learnings/`
    - `docs/agent-handoffs/incidents/`
-2. If the insight is new, add a short markdown note using the naming standard from `AGENTS.md`.
-3. If the issue is still active/reproducible, add or update the corresponding entry in `KNOWN_ISSUES.md`.
-4. Keep note content sanitized and reusable (no secrets, no user-identifying details).
+2. Update existing notes if they already cover the issue.
+3. Otherwise add a new note using `YYYY-MM-DD-short-topic.md`.
+4. If the issue is still active/reproducible, add or update `KNOWN_ISSUES.md`.
+
+Keep notes concise, actionable, and safe to share.
 
 ## What belongs where
 
-- `KNOWN_ISSUES.md`: active/reproducible issues, impact, workaround, and current status.
-- `docs/agent-handoffs/learnings/`: durable implementation insights and successful patterns.
-- `docs/agent-handoffs/incidents/`: failure writeups, root causes, and prevention guidance.
-- `CONTRIBUTING.md`: standards for proposing, validating, and reviewing changes.
+- `KNOWN_ISSUES.md`: active issues, impact, status, workaround, verification date.
+- `docs/agent-handoffs/learnings/`: successful implementation patterns.
+- `docs/agent-handoffs/incidents/`: failures and prevention guidance.
+- `CONTRIBUTING.md`: contribution, review, and quality standards.
 
-## Style for handoff notes
+## Writing style for handoff notes
 
 - Prefer bullets over long prose.
-- Include exact commands where useful.
-- State confidence and remaining uncertainty.
+- Include exact commands when they improve reproducibility.
+- Explicitly separate facts from assumptions.
 - End with: `Recommendation for next agents:`
 
-## Anti-patterns
+## Anti-patterns to avoid
 
-- Avoid repo-local jargon in reusable templates.
-- Avoid stale TODO dumps without context.
-- Avoid project/brand-specific terms unless explicitly required by the active downstream repo.
+- Product/brand-specific assumptions in reusable docs.
+- Broad refactors not required for the current request.
+- Status updates without validation evidence.
+- Duplicated notes that fragment context.