diff --git a/AGENTS.md b/AGENTS.md index bc24a0c..1cd6ba4 100644 --- a/AGENTS.md +++ b/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 - -Run this checklist at the beginning of every session: +## Session startup checklist (run 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. +2. Read `CLAUDE.md` for execution workflow and handoff protocol details. +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. -- 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. +- Do not hardcode company, product, team, customer, or environment-specific assumptions. +- Prefer neutral terms such as `project`, `service`, `integration`, `consumer`, `provider`, and `environment`. +- 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 repository-specific. ## Decision and implementation policy -- Start with the smallest safe change that solves the user request. -- Prefer explicit commands over implied behavior. +- Start with the smallest safe change that satisfies the request. - 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. +- Prefer explicit commands and documented behavior over implicit assumptions. +- 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: - - what was attempted, - - why it could not run, - - what fallback validation was done. -- Never claim a check passed if it was not executed. +- If a check cannot run, record: + - command attempted, + - reason it could not complete, + - fallback validation performed. +- 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. -- `docs/agent-handoffs/learnings/`: successful patterns or repeatable fixes. -- `docs/agent-handoffs/incidents/`: failures, root causes, and mitigations. +- `KNOWN_ISSUES.md` + - Active and reproducible issues only. + - 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 -- Observation -- Action taken -- Validation performed -- Recommendation for next agents +1. Context +2. Observation +3. Action taken +4. Validation performed +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 diff --git a/CLAUDE.md b/CLAUDE.md index 6e9087e..7772d11 100644 --- a/CLAUDE.md +++ b/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. -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. +1. Load baseline context: + - `AGENTS.md` + - `CONTRIBUTING.md` + - `KNOWN_ISSUES.md` + - `docs/agent-handoffs/README.md` + - 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. -- 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. +## Knowledge-sharing and handoff protocol -## 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: - - `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`. +### 2) Write in the right place -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. -- `docs/agent-handoffs/learnings/`: successful implementation patterns. -- `docs/agent-handoffs/incidents/`: failures and prevention guidance. -- `CONTRIBUTING.md`: contribution, review, and quality standards. +- `KNOWN_ISSUES.md`: currently active issues and workarounds. +- `docs/agent-handoffs/learnings/`: reusable successes. +- `docs/agent-handoffs/incidents/`: reusable failure analysis. +- `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. -- End with: `Recommendation for next agents:` +- Clearly separate facts from assumptions. +- End with a practical recommendation for the next agent. -## Anti-patterns to avoid +## Anti-patterns -- 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. +- Project/brand-specific assumptions in reusable docs. +- Unnecessary broad refactors. +- Claims of validation without executed checks. +- Duplicate notes that fragment context across many files. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0681c7e..cf38a6c 100644 --- a/CONTRIBUTING.md +++ b/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. -- Preserve generic behavior unless implementing explicit downstream repo requirements. +- Explain why the change is needed, not only what changed. +- 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. -3. Update docs affected by behavior or workflow changes. -4. If you discovered reusable information, add/update a note in `docs/agent-handoffs/`. +2. Run relevant checks/tests for the changed scope. +3. Update documentation impacted by behavior or workflow changes. +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. -- Add a learning or incident note if the change uncovered reusable guidance. +- Update `KNOWN_ISSUES.md` for newly discovered active limitations/workarounds. +- Add/update a learning or incident note for durable guidance. diff --git a/KNOWN_ISSUES.md b/KNOWN_ISSUES.md index 1b6a63c..fcf5d72 100644 --- a/KNOWN_ISSUES.md +++ b/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. -- Remove resolved issues quickly. -- Link to handoff/incident notes for deeper context. +- Keep entries short, factual, and current. +- List active issues only; remove resolved items promptly. +- 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:** diff --git a/docs/agent-handoffs/README.md b/docs/agent-handoffs/README.md index 7e6ced5..35ffa71 100644 --- a/docs/agent-handoffs/README.md +++ b/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. -- `incidents/`: failures, root causes, and mitigation/prevention notes. +- `learnings/`: successful patterns, proven fixes, and repeatable implementation guidance. +- `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 -- Observation -- Action taken -- Validation performed -- Recommendation for next agents +1. Context +2. Observation +3. Action taken +4. Validation performed +5. 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. +- Prefer bullets over long narrative. +- Include exact commands when useful for reproduction. +- 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.