chore(repo): update agent guidance

[bcdonadio]

Summary

Update repository agent guidance and ignore local agent artifacts.

Changes

• refresh repository agent instructions
• ignore additional local agent files

Validation

Not run per explicit request.

[qodo-code-review]

PR Summary by Qodo

Document local agent overrides and ignore AGENTS.local.md

📝 Documentation ⚙️ Configuration changes 🕐 Less than 10 minutes

AI Description

• Add guidance for optional, locally-scoped agent instructions that override repo defaults.
• Gitignore AGENTS.local.md to prevent accidental commits of developer-specific guidance.

High-Level Assessment

The following are alternative approaches to this PR:

1. Use .git/info/exclude (no repo change)

• ➕ Avoids modifying the shared .gitignore
• ➕ Keeps local artifacts entirely out of versioned config
• ➖ Not discoverable; relies on each developer configuring it correctly
• ➖ Harder to standardize across contributors and tools

2. Store local overrides under a dedicated ignored folder (e.g., .agents/local.md)

• ➕ Scales if more local agent artifacts appear later
• ➕ Keeps agent-related files grouped
• ➖ Requires updating paths and instructions; more churn for a small need right now

Recommendation: The current approach (standardize on AGENTS.local.md, explicitly document precedence, and gitignore it) is the best tradeoff: it is discoverable, consistent across developers, and reduces risk of accidentally committing local-only guidance. The .git/info/exclude alternative is viable but too implicit for team-wide conventions.

Files changed (2) +7 / -2

Documentation (1) +4 / -2

AGENTS.mdDocument optional local agent overrides and precedence +4/-2

Document optional local agent overrides and precedence

• Updates repository instructions to reference AGENTS.local.md when present, clarifying it overrides project instructions and must remain gitignored.

AGENTS.md

Other (1) +3 / -0

.gitignoreIgnore AGENTS.local.md local agent instructions file +3/-0

Ignore AGENTS.local.md local agent instructions file

• Adds AGENTS.local.md to .gitignore under a dedicated comment, preventing local agent guidance from being committed.

.gitignore

[Copilot]

Pull request overview

Updates the repository’s agent guidance to allow optional local, gitignored overrides and ensures those local artifacts aren’t accidentally committed.

Changes:

• Refresh AGENTS.md instructions to mention optional AGENTS.local.md overrides.
• Extend .gitignore to ignore AGENTS.local.md.

Reviewed changes

Copilot reviewed 1 out of 2 changed files in this pull request and generated 1 comment.

File	Description
AGENTS.md	Updates agent guidance to reference an optional local override file and reiterate workflow docs.
.gitignore	Ignores AGENTS.local.md to prevent committing local-only guidance.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📜 Skill insights (0)

1. Local guidance overrides safety gates 🐞 Bug ⚙ Maintainability

Description

The new rule makes a user-controlled, gitignored AGENTS.local.md authoritative over all project
instructions, so agents that honor it can disregard documented coverage, testing, or
release-readiness requirements when those requirements are not independently enforced. The risk is
conditional on the consuming agent and CI/tooling, but the committed guidance now explicitly permits
those overrides.

Code

AGENTS.md[R3-5]

+- Read [AGENTS.local.md](./AGENTS.local.md) if present.
+  - Statements in this local file should override any project instruction.
+  - The file is intentionally gitignored. Keep it that way.

Relevance

●●● Strong

Same change (gitignored AGENTS.local.md overrides repo instructions) was already merged; repo
intentionally supports local overrides.

PR-#672

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The added lines establish precedence for an ignored local file, while the same file labels the
coverage and release rules as requirements. Because the local file is not tracked or reviewable, its
contents can vary per workspace and can instruct an agent to omit those checks.

AGENTS.md[3-5]
AGENTS.md[8-21]
AGENTS.md[37-46]
.gitignore[37-38]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`AGENTS.local.md` is gitignored and user-controlled, but the new guidance gives it precedence over every project instruction. This permits agents to bypass repository safety-critical requirements such as testing, coverage, and release checks when those requirements are advisory rather than independently enforced.

## Issue Context
Keep support for local developer customizations, but do not let them override mandatory project safeguards.

## Fix Focus Areas
- AGENTS.md[3-5]
- AGENTS.md[8-21]
- AGENTS.md[37-46]

State explicitly that local guidance may override only non-critical preferences and must not weaken testing, security, coverage, or release requirements; enforce those requirements independently in CI where applicable.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context

✅ Compliance rules (platform): 142 rules

Review mode: 🚀 Fast: This is a small, localized change to repository guidance and .gitignore entries, with no runtime behavior or high-risk contract changes.

Tip of the day

💡 Did you know, you can enable the Remediation agent and Qodo fixes findings in a dedicated fix PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-code-review]

1. Local guidance overrides safety gates 🐞 Bug ⚙ Maintainability

The new rule makes a user-controlled, gitignored AGENTS.local.md authoritative over all project
instructions, so agents that honor it can disregard documented coverage, testing, or
release-readiness requirements when those requirements are not independently enforced. The risk is
conditional on the consuming agent and CI/tooling, but the committed guidance now explicitly permits
those overrides.

Agent Prompt

## Issue description
`AGENTS.local.md` is gitignored and user-controlled, but the new guidance gives it precedence over every project instruction. This permits agents to bypass repository safety-critical requirements such as testing, coverage, and release checks when those requirements are advisory rather than independently enforced.

## Issue Context
Keep support for local developer customizations, but do not let them override mandatory project safeguards.

## Fix Focus Areas
- AGENTS.md[3-5]
- AGENTS.md[8-21]
- AGENTS.md[37-46]

State explicitly that local guidance may override only non-critical preferences and must not weaken testing, security, coverage, or release requirements; enforce those requirements independently in CI where applicable.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools