Refactor agent docs to be fully repo-agnostic

AGENTS.md

@@ -4,69 +4,88 @@ Repository-wide operating instructions for autonomous and semi-autonomous coding
 
 ## Goal
 
-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.
+Make this repository portable across many downstream projects. Default to generic guidance, minimal assumptions, and workflows that work in different languages, runtimes, and deployment environments.
 
-## Session startup checklist
+## Session startup checklist (run every session)
-
-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.
+2. Read `CLAUDE.md` for execution workflow and handoff protocol details.
-3. Read `CONTRIBUTING.md` for commit and pull request expectations.
+3. Read `CONTRIBUTING.md` for commit/PR expectations.
 4. Read `KNOWN_ISSUES.md` for active blockers and workarounds.
-5. Review `docs/agent-handoffs/README.md` and recent notes in:
+5. Read `docs/agent-handoffs/README.md`.
+6. Review recent notes in:
    - `docs/agent-handoffs/learnings/`
    - `docs/agent-handoffs/incidents/`
 
 ## Repo-agnostic defaults
 
-- Do not hardcode company, product, customer, environment, or team-specific details.
+- Do not hardcode company, product, team, customer, or environment-specific assumptions.
-- Prefer neutral terms such as `project`, `service`, `consumer`, `provider`, `integration`, and `environment`.
+- Prefer neutral terms such as `project`, `service`, `integration`, `consumer`, `provider`, and `environment`.
-- Avoid assumptions about deployment target (local, cloud, CI, container) unless explicitly configured.
+- Do not assume a specific infrastructure model (local machine, container, CI, cloud VM, etc.) unless explicitly configured in repo files.
-- Add project-specific details only when required by the current repository and clearly label them as such.
+- Add project-specific details only when required by the current repository and clearly label them as repository-specific.
 
 ## Decision and implementation policy
 
-- Start with the smallest safe change that solves the user request.
+- Start with the smallest safe change that satisfies the request.
-- Prefer explicit commands over implied behavior.
 - Keep edits focused; avoid unrelated refactors.
-- Preserve backward compatibility unless the task explicitly allows breaking changes.
+- Prefer explicit commands and documented behavior over implicit assumptions.
-- If uncertainty remains, document assumptions in the final summary.
+- Preserve backward compatibility unless the task explicitly permits a breaking change.
+- If assumptions are necessary, record them in the final summary.
 
 ## Validation baseline
 
 - 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:
+- If a check cannot run, record:
-  - what was attempted,
+  - command attempted,
-  - why it could not run,
+  - reason it could not complete,
-  - what fallback validation was done.
+  - fallback validation performed.
-- Never claim a check passed if it was not executed.
+- Never claim a check passed unless it was actually executed.
 
-## Agent handoff protocol
+## Agent knowledge-sharing protocol
 
 Capture reusable context so future agents can continue without rediscovery.
 
-### Where to record information
+### What belongs where
 
-- `KNOWN_ISSUES.md`: active/reproducible issues, current status, impact, and workarounds.
+- `KNOWN_ISSUES.md`
-- `docs/agent-handoffs/learnings/`: successful patterns or repeatable fixes.
+  - Active and reproducible issues only.
-- `docs/agent-handoffs/incidents/`: failures, root causes, and mitigations.
+  - Include status, impact, workaround, and last verification date.
+- `docs/agent-handoffs/learnings/`
+  - Proven patterns, repeatable fixes, and successful implementation guidance.
+- `docs/agent-handoffs/incidents/`
+  - Failures, root causes, mitigations, and prevention guidance.
 
-### Note naming
+### File naming standard (generic)
 
-Use generic, descriptive filenames:
+Use descriptive, repository-agnostic note names:
 
 - `YYYY-MM-DD-short-topic.md`
 
+Good examples:
+
+- `2026-02-14-validation-before-summary.md`
+- `2026-02-14-missing-baseline-context.md`
+
+Avoid tool, product, customer, or team names in filenames unless absolutely required for clarity.
+
 ### Required note sections
 
-Every new learning/incident note should include:
+Every learning or incident note should include these headings:
 
-- Context
+1. Context
-- Observation
+2. Observation
-- Action taken
+3. Action taken
-- Validation performed
+4. Validation performed
-- Recommendation for next agents
+5. Recommendation for next agents
+
+### Update decision tree
+
+When you discover new reusable context:
+
+1. Check if an existing note already covers it.
+2. If yes, update the existing note.
+3. If no, add a new note in `learnings/` or `incidents/` using the naming standard above.
+4. If the issue is still active/reproducible, add or update an entry in `KNOWN_ISSUES.md`.
 
 ## Priority order for conflicting instructions
 
@@ -74,4 +93,4 @@ Every new learning/incident note should include:
 2. `AGENTS.md`
 3. `CLAUDE.md`
 4. `CONTRIBUTING.md`
-5. Inline comments and prompt templates
+5. Inline code comments and prompt templates

CLAUDE.md

@@ -4,63 +4,83 @@ Execution playbook for agents working in this repository.
 
 ## Scope
 
-Applies to all tasks unless overridden by direct session instructions.
+Applies to all tasks unless direct session instructions override it.
 
-## Core operating principles
+## Operating principles
 
 - Be repository-agnostic by default.
-- Keep behavior deterministic and auditable.
+- Make deterministic, auditable decisions.
 - Prefer minimal, reversible changes.
-- Leave the workspace clearer for the next agent than you found it.
+- Leave clearer context for the next agent.
 
-## Recommended execution workflow
+## Standard execution workflow
 
-1. Load baseline context from `AGENTS.md`, `CONTRIBUTING.md`, `KNOWN_ISSUES.md`, and handoff notes.
+1. Load baseline context:
-2. Restate the task internally as concrete outcomes.
+   - `AGENTS.md`
-3. Make the smallest safe implementation change.
+   - `CONTRIBUTING.md`
-4. Validate with the most relevant automated checks available.
+   - `KNOWN_ISSUES.md`
-5. Summarize results with clear evidence (commands, outputs, and file references).
+   - `docs/agent-handoffs/README.md`
-6. Record durable learnings/incidents if new reusable knowledge was discovered.
+   - recent notes in `docs/agent-handoffs/learnings/` and `docs/agent-handoffs/incidents/`
+2. Translate the request into concrete outcomes.
+3. Implement the smallest safe change.
+4. Run relevant validation.
+5. Summarize evidence clearly (commands, outputs, and changed files).
+6. Record durable learnings/incidents when new reusable knowledge appears.
 
-## Change quality checklist
+## Quality checklist before finishing
 
-Before finishing, verify:
+- Scope matches the user request.
+- Language and guidance remain generic unless project-specific detail is required.
+- Existing workflows were not unintentionally broken.
+- Validation coverage is appropriate for risk/impact.
 
-- The change is scoped to the request.
+## Knowledge-sharing and handoff protocol
-- 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
+### 1) Search first
 
-When new reusable context appears:
+Before writing a new note, check for an existing related note and update it if applicable.
 
-1. Search for an existing related note in:
+### 2) Write in the right place
-   - `docs/agent-handoffs/learnings/`
-   - `docs/agent-handoffs/incidents/`
-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.
+- `docs/agent-handoffs/learnings/` for successful patterns.
+- `docs/agent-handoffs/incidents/` for failures and mitigations.
+
+### 3) Use generic, consistent names
+
+- Format: `YYYY-MM-DD-short-topic.md`
+- Keep names descriptive and repository-agnostic.
+
+### 4) Use the required structure
+
+Each note should include:
+
+- Context
+- Observation
+- Action taken
+- Validation performed
+- Recommendation for next agents
+
+### 5) Promote active problems to `KNOWN_ISSUES.md`
+
+If the problem is still reproducible or unresolved, add/update a `KNOWN_ISSUES.md` entry with status, impact, workaround, and last verified date.
 
 ## What belongs where
 
-- `KNOWN_ISSUES.md`: active issues, impact, status, workaround, verification date.
+- `KNOWN_ISSUES.md`: currently active issues and workarounds.
-- `docs/agent-handoffs/learnings/`: successful implementation patterns.
+- `docs/agent-handoffs/learnings/`: reusable successes.
-- `docs/agent-handoffs/incidents/`: failures and prevention guidance.
+- `docs/agent-handoffs/incidents/`: reusable failure analysis.
-- `CONTRIBUTING.md`: contribution, review, and quality standards.
+- `CONTRIBUTING.md`: expectations for commits, PRs, and validation.
 
-## Writing style for handoff notes
+## Writing style for agent notes
 
-- Prefer bullets over long prose.
+- Prefer concise bullets over long prose.
 - Include exact commands when they improve reproducibility.
-- Explicitly separate facts from assumptions.
+- Clearly separate facts from assumptions.
-- End with: `Recommendation for next agents:`
+- End with a practical recommendation for the next agent.
 
-## Anti-patterns to avoid
+## Anti-patterns
 
-- Product/brand-specific assumptions in reusable docs.
+- Project/brand-specific assumptions in reusable docs.
-- Broad refactors not required for the current request.
+- Unnecessary broad refactors.
-- Status updates without validation evidence.
+- Claims of validation without executed checks.
-- Duplicated notes that fragment context.
+- Duplicate notes that fragment context across many files.

CONTRIBUTING.md

@@ -5,37 +5,46 @@ Guidelines for humans and agents proposing changes.
 ## Change principles
 
 - Keep changes focused and minimal.
-- Explain why a change is needed, not only what changed.
+- Explain why the change is needed, not only what changed.
-- Preserve generic behavior unless implementing explicit downstream repo requirements.
+- Preserve generic behavior unless explicit repository-specific behavior is required.
 
 ## Before opening a PR
 
 1. Confirm `AGENTS.md` and `CLAUDE.md` were followed.
-2. Run relevant checks/tests for the scope of change.
+2. Run relevant checks/tests for the changed scope.
-3. Update docs affected by behavior or workflow changes.
+3. Update documentation impacted by behavior or workflow changes.
-4. If you discovered reusable information, add/update a note in `docs/agent-handoffs/`.
+4. If reusable knowledge was discovered, update/add a note in `docs/agent-handoffs/`.
 5. If an issue remains active, update `KNOWN_ISSUES.md`.
 
 ## Commit guidance
 
 - Use clear, descriptive commit messages.
 - Keep unrelated edits in separate commits.
-- Avoid committing temporary debug code or local-only artifacts.
+- Do not commit temporary debug code, generated noise, or local-only artifacts.
 
 ## PR guidance
 
 Include:
 
-- Summary of what changed
+- What changed
 - Why it changed
 - Validation performed
-- Any known follow-ups
+- Follow-up items or risks
 
-If no tests were run, state why.
+If no tests/checks were run, explicitly state why.
+
+## Agent handoff expectations
+
+When your work creates reusable context:
+
+- Prefer updating an existing handoff note over creating duplicates.
+- If creating a new note, use `YYYY-MM-DD-short-topic.md`.
+- Keep notes generic and actionable.
+- Use the required sections from `docs/agent-handoffs/README.md`.
 
 ## Documentation maintenance
 
-When changing workflows:
+When workflows change:
 
-- Update `KNOWN_ISSUES.md` for new known limitations/workarounds.
+- Update `KNOWN_ISSUES.md` for newly discovered active limitations/workarounds.
-- Add a learning or incident note if the change uncovered reusable guidance.
+- Add/update a learning or incident note for durable guidance.

KNOWN_ISSUES.md

@@ -1,19 +1,20 @@
 # KNOWN_ISSUES.md
 
-Track active, reproducible issues in a generic format.
+Track active, reproducible issues in a reusable format.
 
 ## How to use this file
 
-- Keep entries short and factual.
+- Keep entries short, factual, and current.
-- Remove resolved issues quickly.
+- List active issues only; remove resolved items promptly.
-- Link to handoff/incident notes for deeper context.
+- Link to related incident/handoff notes for deeper details.
+- Prefer one entry per distinct issue.
 
 ## Entry template
 
 ### [ISSUE-YYYYMMDD-brief-name]
 
 - **Status:** Open | Monitoring | Mitigated
-- **Area:** Scheduler | Locking | Dashboard | Docs | Other
+- **Area:** Build | Test | Tooling | Runtime | Docs | Other
 - **Symptom:**
 - **Trigger/Conditions:**
 - **Workaround:**

docs/agent-handoffs/README.md

@@ -1,36 +1,62 @@
 # Agent Handoffs
 
-This folder stores reusable knowledge so future agents can work faster and safer.
+This directory stores reusable context so future agents can work faster without repeating discovery.
 
-## Folders
+## Directory purpose
 
-- `learnings/`: successful patterns and repeatable implementation guidance.
+- `learnings/`: successful patterns, proven fixes, and repeatable implementation guidance.
-- `incidents/`: failures, root causes, and mitigation/prevention notes.
+- `incidents/`: failures, root causes, mitigations, and prevention guidance.
 
-## Filename format
+## When to write a note
 
-Use: `YYYY-MM-DD-short-topic.md`
+Create or update a note when your work reveals knowledge that is likely useful in future sessions.
+
+Examples:
+
+- A reliable fix pattern that could be reused.
+- A recurring failure mode and its mitigation.
+- A non-obvious validation approach that prevented regressions.
+
+If the issue is still active/reproducible, also update `KNOWN_ISSUES.md`.
+
+## Naming convention (generic)
+
+Use:
+
+- `YYYY-MM-DD-short-topic.md`
 
 Examples:
 
 - `2026-02-14-validation-before-summary.md`
-- `2026-02-14-lock-timeout-regression.md`
+- `2026-02-14-missing-baseline-context.md`
 
-Keep names generic and descriptive.
+Naming tips:
+
+- Keep names descriptive and concise.
+- Avoid product, team, customer, and environment names unless essential.
+- Prefer neutral technical terms.
 
 ## Required note structure
 
-Every note should include:
+Every learning/incident note should include the following headings:
 
-- Context
+1. Context
-- Observation
+2. Observation
-- Action taken
+3. Action taken
-- Validation performed
+4. Validation performed
-- Recommendation for next agents
+5. Recommendation for next agents
 
 ## Writing guidelines
 
 - Keep entries short and actionable.
-- Include exact commands when helpful.
+- Prefer bullets over long narrative.
-- Avoid secrets or user-identifying data.
+- Include exact commands when useful for reproduction.
-- Prefer generic language unless you are in a specific downstream project repository.
+- Avoid secrets, credentials, and user-identifying details.
+- Distinguish facts from assumptions.
+
+## Maintenance workflow
+
+1. Search for an existing related note.
+2. Update it if it already covers your case.
+3. Otherwise, add a new note using the naming convention.
+4. Cross-link related notes when helpful.