diff --git a/AGENTS.md b/AGENTS.md index dce7742..3d6971f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,32 +4,34 @@ Repository-wide instructions for any autonomous or semi-autonomous coding agent. ## Purpose -This repository is intended to be reusable across many projects. Keep changes and documentation generic unless you are actively working inside a specific downstream repo that requires project-specific customization. +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. -## Startup checklist (every run) +## Startup checklist (run every session) 1. Read this file (`AGENTS.md`). -2. Read `CLAUDE.md` for operating conventions. -3. Read `CONTRIBUTING.md` for commit/PR quality expectations. -4. Check `KNOWN_ISSUES.md` before making changes. -5. If present, check `docs/agent-handoffs/` for recent agent learnings. +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. +5. Review `docs/agent-handoffs/README.md` and recent notes in: + - `docs/agent-handoffs/learnings/` + - `docs/agent-handoffs/incidents/` ## Generic-first policy - 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 repo and label them clearly. +- Add project-specific notes only when working in that project’s own repository, and label them clearly. ## Agent learning + handoff protocol -Agents are expected to leave concise, reusable notes for later agents. +Agents are expected to leave concise, reusable notes so future agents do not need to rediscover the same context. -### Where to write +### Which file should be updated? -- `docs/agent-handoffs/README.md` for folder usage. -- `docs/agent-handoffs/learnings/` for new practical learnings. -- `docs/agent-handoffs/incidents/` for issue/incident writeups and mitigations. +- 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. ### Naming convention @@ -37,11 +39,11 @@ Use generic, descriptive filenames: - `YYYY-MM-DD-short-topic.md` (example: `2026-02-14-lock-timeout-tuning.md`) -Avoid brand, team, or person-specific prefixes in filenames. +Avoid product, team, or person-specific prefixes. ### Required note structure -Each note should contain: +Each learning/incident note should include: - Context - Observation @@ -49,14 +51,22 @@ Each note should contain: - Validation performed - Recommendation for next agents -Keep each note short and actionable. +Keep each note short, actionable, and safe to share (no secrets). + +### 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 smallest safe change first. +- Make the smallest safe change first. - Prefer explicit commands over assumptions. -- Validate with available tests/checks. -- If blocked by environment limits, document the blocker and fallback. +- Validate with relevant tests/checks. +- If blocked by environment limits, record the blocker and fallback. ## Priority order diff --git a/CLAUDE.md b/CLAUDE.md index 289198d..78d8a8b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -10,33 +10,43 @@ Applies to all agent tasks unless superseded by direct runtime instructions. - Keep output and changes generic by default. - Prefer deterministic, auditable steps. -- Record decisions so future agents can continue with minimal rediscovery. +- Record useful decisions so future agents can continue with minimal rediscovery. + +## Execution flow (recommended) + +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. ## Handoff documentation workflow When you learn something that can help future agents: -1. Check for existing related notes in `docs/agent-handoffs/learnings/` and `docs/agent-handoffs/incidents/`. -2. If the learning is new, add a small markdown note using the naming standard in `AGENTS.md`. -3. Link related issue patterns in `KNOWN_ISSUES.md` when applicable. +1. Check for related notes 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). ## What belongs where -- `KNOWN_ISSUES.md`: currently active/reproducible issues and known workarounds. +- `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 reports, root-cause notes, and prevention guidance. -- `CONTRIBUTING.md`: process standards for proposing and reviewing changes. +- `docs/agent-handoffs/incidents/`: failure writeups, root causes, and prevention guidance. +- `CONTRIBUTING.md`: standards for proposing, validating, and reviewing changes. -## Style for agent notes +## Style for handoff notes - Prefer bullets over long prose. - Include exact commands where useful. - State confidence and remaining uncertainty. -- End with a “Next agent should …” line. +- End with: `Recommendation for next agents:` ## Anti-patterns -- Avoid repo-local jargon in shared templates. -- Avoid stale TODO dumps without context or owner. -- Avoid project/brand-specific terms unless explicitly required by the active repo. +- 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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4f73472..0681c7e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# CONTRIBUTING +# CONTRIBUTING.md Guidelines for humans and agents proposing changes. @@ -6,14 +6,15 @@ Guidelines for humans and agents proposing changes. - Keep changes focused and minimal. - Explain why a change is needed, not only what changed. -- Preserve generic behavior unless implementing explicit repo-specific requirements. +- Preserve generic behavior unless implementing explicit downstream repo requirements. ## Before opening a PR -1. Confirm instructions in `AGENTS.md` and `CLAUDE.md` were followed. -2. Run relevant checks/tests. -3. Update docs affected by behavior changes. -4. If you discovered reusable information, add/update a note under `docs/agent-handoffs/`. +1. Confirm `AGENTS.md` and `CLAUDE.md` were followed. +2. Run relevant checks/tests for the scope of change. +3. Update docs affected by behavior or workflow changes. +4. If you discovered reusable information, add/update a note in `docs/agent-handoffs/`. +5. If an issue remains active, update `KNOWN_ISSUES.md`. ## Commit guidance @@ -37,4 +38,4 @@ If no tests were run, state why. When changing workflows: - Update `KNOWN_ISSUES.md` for new known limitations/workarounds. -- Add a learning note if the change uncovered a reusable pattern. +- Add a learning or incident note if the change uncovered reusable guidance. diff --git a/KNOWN_ISSUES.md b/KNOWN_ISSUES.md index a97b6c4..1b6a63c 100644 --- a/KNOWN_ISSUES.md +++ b/KNOWN_ISSUES.md @@ -1,4 +1,4 @@ -# KNOWN ISSUES +# KNOWN_ISSUES.md Track active, reproducible issues in a generic format. @@ -6,7 +6,7 @@ Track active, reproducible issues in a generic format. - Keep entries short and factual. - Remove resolved issues quickly. -- Link to handoff/incident notes for deep details. +- Link to handoff/incident notes for deeper context. ## Entry template diff --git a/docs/agent-handoffs/README.md b/docs/agent-handoffs/README.md index a6a9cf5..7e6ced5 100644 --- a/docs/agent-handoffs/README.md +++ b/docs/agent-handoffs/README.md @@ -1,11 +1,11 @@ # Agent Handoffs -This folder stores reusable learnings that help future agents work faster and safer. +This folder stores reusable knowledge so future agents can work faster and safer. ## Folders -- `learnings/`: patterns that worked and can be reused. -- `incidents/`: failures, root causes, and prevention notes. +- `learnings/`: successful patterns and repeatable implementation guidance. +- `incidents/`: failures, root causes, and mitigation/prevention notes. ## Filename format @@ -13,7 +13,24 @@ Use: `YYYY-MM-DD-short-topic.md` Examples: -- `2026-02-14-command-ordering.md` +- `2026-02-14-validation-before-summary.md` - `2026-02-14-lock-timeout-regression.md` Keep names generic and descriptive. + +## Required note structure + +Every note should include: + +- Context +- Observation +- Action taken +- Validation performed +- Recommendation for next agents + +## Writing guidelines + +- Keep entries short and actionable. +- Include exact commands when helpful. +- Avoid secrets or user-identifying data. +- Prefer generic language unless you are in a specific downstream project repository. diff --git a/docs/agent-handoffs/incidents/2026-02-14-example-incident.md b/docs/agent-handoffs/incidents/2026-02-14-missing-baseline-context.md similarity index 66% rename from docs/agent-handoffs/incidents/2026-02-14-example-incident.md rename to docs/agent-handoffs/incidents/2026-02-14-missing-baseline-context.md index 7cebc62..16dce21 100644 --- a/docs/agent-handoffs/incidents/2026-02-14-example-incident.md +++ b/docs/agent-handoffs/incidents/2026-02-14-missing-baseline-context.md @@ -1,7 +1,7 @@ -# Example Incident: Missing Baseline Context +# Missing Baseline Context -- **Context:** Agent started editing without reviewing policy files first. -- **Observation:** Resulting patch required rework to match repo standards. -- **Action taken:** Re-read policy docs, reverted conflicting edits, reapplied changes correctly. +- **Context:** Agent started editing without reviewing baseline policy files first. +- **Observation:** Resulting patch required rework to match repository standards. +- **Action taken:** Re-read policy docs, reverted conflicting edits, and reapplied changes correctly. - **Validation performed:** Compared final output to policy docs and reran checks. - **Recommendation for next agents:** Read `AGENTS.md` and `CLAUDE.md` first on every run to avoid avoidable churn. diff --git a/docs/agent-handoffs/learnings/2026-02-14-example-learning.md b/docs/agent-handoffs/learnings/2026-02-14-validation-before-summary.md similarity index 90% rename from docs/agent-handoffs/learnings/2026-02-14-example-learning.md rename to docs/agent-handoffs/learnings/2026-02-14-validation-before-summary.md index a700458..c6e4b61 100644 --- a/docs/agent-handoffs/learnings/2026-02-14-example-learning.md +++ b/docs/agent-handoffs/learnings/2026-02-14-validation-before-summary.md @@ -1,4 +1,4 @@ -# Example Learning: Validation Before Summary +# Validation Before Summary - **Context:** Multi-file documentation update. - **Observation:** Running quick checks before writing summaries catches avoidable mistakes.