feat(agents): modernize AGENTS.md for 2025-2026 agentic coding

.claude/settings.local.json

@@ -1,9 +1,7 @@
 {
   "permissions": {
-    "allow": [
-      "Bash(git init:*)"
-    ],
+    "allow": ["Bash(git init:*)"],
     "deny": [],
     "ask": []
   }
-}
+}

.github/ISSUE_TEMPLATE/agent-bug.md

@@ -0,0 +1,97 @@
+---
+name: Agent Bug Report
+about: Bug fix for AI agents (optimized for agent mode)
+title: '[BUG] '
+labels: bug, agent-task
+assignees: ''
+---
+
+## Bug Description
+
+**What's broken**:
+
+**Expected behavior**:
+
+**Actual behavior**:
+
+## Reproduction Steps
+
+1. Step 1
+2. Step 2
+3. Step 3
+4. See error
+
+## Environment
+
+- Environment (dev/staging/prod):
+- Browser (if applicable):
+- Node version (if applicable):
+- Package manager:
+
+## Error Details
+
+**Error message or logs**:
+
+```
+Paste error message here
+```
+
+**Stack trace** (if available):
+
+```
+Paste stack trace here
+```
+
+## Acceptance Criteria
+
+**Testable criteria for the fix**:
+
+- [ ] Bug is reproducible with a failing test
+- [ ] Fix resolves the issue
+- [ ] Test now passes
+- [ ] No regression (all existing tests pass)
+- [ ] `make validate` passes
+- [ ] Root cause documented in PR
+
+## Test Strategy
+
+**How to verify the fix**:
+
+- [ ] Add failing test that reproduces bug
+- [ ] Implement fix
+- [ ] Verify test now passes
+- [ ] Run full test suite (no regressions)
+- [ ] Manual verification (if applicable)
+
+## Context
+
+**Related code**:
+
+- Files affected:
+- Related issues:
+- When did this start:
+- Recent changes that might have caused it:
+
+## Root Cause Analysis
+
+**Optional - fill if known**:
+
+- Why did this bug occur:
+- What assumption was wrong:
+- How to prevent similar bugs:
+
+## Definition of Done
+
+- [ ] Failing test added that reproduces the bug
+- [ ] Fix implemented
+- [ ] Test now passes
+- [ ] No regressions (all other tests pass)
+- [ ] `make validate` passes
+- [ ] Root cause explained in PR
+- [ ] Prevention strategy documented (if applicable)
+
+---
+
+**Agent Guidelines**: Read [AGENTS.md](../../AGENTS.md) before starting. Always
+start by adding a failing test that reproduces the bug, then fix it and verify
+the test passes.

.github/ISSUE_TEMPLATE/agent-feature.md

@@ -0,0 +1,62 @@
+---
+name: Agent Feature Request
+about: Feature implementation for AI agents (optimized for agent mode)
+title: '[FEATURE] '
+labels: enhancement, agent-task
+assignees: ''
+---
+
+## Feature Description
+
+**Clear, concise description of what to build**:
+
+## Acceptance Criteria
+
+**Testable, measurable criteria** (check each when complete):
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+- [ ] All tests pass
+- [ ] `make validate` completes successfully
+- [ ] Documentation updated
+
+## Test Strategy
+
+**How to verify this works**:
+
+- Unit tests for:
+- Integration tests for:
+- Edge cases to cover:
+
+## Context
+
+**Links to related code, docs, or designs**:
+
+- Related files:
+- Similar patterns:
+- Design docs:
+- Related issues:
+
+## Implementation Hints
+
+**Optional guidance for the agent**:
+
+- Preferred approach:
+- Files to modify:
+- Patterns to follow:
+- Gotchas to avoid:
+
+## Definition of Done
+
+- [ ] Code implemented following AGENTS.md guidelines
+- [ ] Tests written and passing
+- [ ] Documentation updated
+- [ ] `make validate` passes
+- [ ] PR created with checklist complete
+- [ ] No security vulnerabilities introduced
+
+---
+
+**Agent Guidelines**: Read [AGENTS.md](../../AGENTS.md) before starting. Follow
+the agent-loop pattern: implement → test → fix → repeat until validation passes.

.github/ISSUE_TEMPLATE/agent-refactor.md

@@ -0,0 +1,111 @@
+---
+name: Agent Refactoring Task
+about: Code refactoring for AI agents (optimized for agent mode)
+title: '[REFACTOR] '
+labels: refactor, agent-task
+assignees: ''
+---
+
+## Refactoring Goal
+
+**What to improve and why**:
+
+**Current problem**:
+
+**Desired state**:
+
+## Contracts (Do NOT Break)
+
+**What must remain unchanged**:
+
+- [ ] Public API contracts (interfaces, function signatures)
+- [ ] Existing test behavior
+- [ ] External integrations
+- [ ] User-facing behavior
+
+## Acceptance Criteria
+
+- [ ] Refactoring goal achieved
+- [ ] All existing tests still pass (no regressions)
+- [ ] Golden tests unchanged (if applicable)
+- [ ] `make validate` passes
+- [ ] Code coverage maintained or improved
+- [ ] Documentation updated
+
+## Refactoring Strategy
+
+**Approach to take**:
+
+1. Step 1
+2. Step 2
+3. Step 3
+
+**Files to modify**:
+
+-
+-
+- **Tests to verify**:
+
+-
+-
+-
+
+## Safety Checks
+
+**Before making changes**:
+
+- [ ] Run full test suite (baseline)
+- [ ] Identify all consumers of code being refactored
+- [ ] Document current contracts
+- [ ] Create golden tests if none exist
+
+**After making changes**:
+
+- [ ] All tests still pass
+- [ ] No change in test coverage
+- [ ] Golden tests match (no behavior change)
+- [ ] Manual verification of affected features
+
+## Context
+
+**Related code**:
+
+- Files to refactor:
+- Tests to preserve:
+- Consumers to verify:
+- Related issues:
+
+## Benefits
+
+**What improves**:
+
+- Performance:
+- Maintainability:
+- Readability:
+- Testability:
+- Other:
+
+## Risks
+
+**Potential issues to watch for**:
+
+- Risk 1:
+- Risk 2:
+- Mitigation strategy:
+
+## Definition of Done
+
+- [ ] Refactoring complete
+- [ ] All existing tests pass (no regressions)
+- [ ] Golden tests unchanged
+- [ ] Code coverage >= baseline
+- [ ] `make validate` passes
+- [ ] Documentation updated
+- [ ] Benefits validated (performance, etc.)
+- [ ] No contracts broken
+
+---
+
+**Agent Guidelines**: Read [AGENTS.md](../../AGENTS.md) before starting.
+Refactoring MUST NOT break contracts. Run tests before and after. Golden tests
+are your regression safety net.