diff --git a/.aider.conf.yml b/.aider.conf.yml
new file mode 100644
index 0000000..313bad9
--- /dev/null
+++ b/.aider.conf.yml
@@ -0,0 +1,7 @@
+read: AGENTS.md
+write: AGENTS.md
+ignore:
+  - .git
+  - node_modules
+  - .vscode
+  - .cursorignore
diff --git a/.gemini/settings.json b/.gemini/settings.json
new file mode 100644
index 0000000..0113f1d
--- /dev/null
+++ b/.gemini/settings.json
@@ -0,0 +1,8 @@
+{
+  "context": {
+    "fileName": "AGENTS.md"
+  },
+  "editor": {
+    "format": "markdown"
+  }
+}
diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..349b1e0
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,14 @@
+# Ensure consistent line endings and text diff behavior
+* text=auto
+*.md text
+*.sh text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+
+# Treat generated files as binary to avoid noisy diffs
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.zip binary
+*.tar.gz binary
diff --git a/.github/ai-guidance.md b/.github/ai-guidance.md
new file mode 100644
index 0000000..9bd3385
--- /dev/null
+++ b/.github/ai-guidance.md
@@ -0,0 +1,30 @@
+# AI Contributor Guidance
+
+This file complements `AGENTS.md` with quick, actionable pointers for AI-powered contributions.
+
+## Quick start for AI agents
+1. Read `AGENTS.md` first (single source of truth).
+2. Prefer small, safe edits and provide patch-style outputs.
+3. Use GitHub CLI for integration:
+   - `gh issue create --template bug`
+   - `gh issue create --template feature`
+   - `gh pr create --title "..." --body "..."`
+4. Follow branch protection:
+   - Do not push directly to `main`.
+   - Create PRs from feature branches.
+
+## Testing commands
+- `npm install`
+- `npm test`
+- `npm run lint`
+
+## Optional tools
+- For Cursor: use `.cursorignore`
+- For Aider: use `.aider.conf.yml`
+- For Gemini: use `.gemini/settings.json`
+
+## CI checks
+- `test-and-build` workflow
+- `codeql-analysis` workflow
+- `dependency-update` workflow
+- `security-scan` workflow
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..fa674aa
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,45 @@
+# AGENTS.md
+
+This repository uses AGENTS.md as the canonical agent guide according to https://agents.md/
+
+## Purpose
+- Provide project-specific agent instructions in a machine-readable human-friendly markdown.
+- Exactly one `AGENTS.md` in repo root, with optional nested AGENTS.md in subtrees (not required here).
+- Include setup, test, code style, and workflow rules.
+
+## Project context
+- Repository: `RockRunner007/template`
+- Description: secure spec-driven template for internal service projects.
+- Branch policy: direct push to `main` is blocked; all code changes must go through Pull Request and required checks. Use branch naming pattern `scarlson/{feature}` for this workflow.
+
+## Build & test
+- `npm install` (or chosen language-specific install)
+- `npm test` or `./scripts/test` (adjust for your stack)
+- CI workflows:
+  - `.github/workflows/test-and-build.yml`
+  - `.github/workflows/codeql-analysis.yml`
+  - `.github/workflows/dependency-update.yml`
+  - `.github/workflows/security-scan.yml`
+
+## Code style
+- Maintain existing repository conventions and lints.
+- Prefer small patches and explicit file path references.
+
+## Governance
+- New features require spec docs under `specs/`.
+- Create issues with `.github/ISSUE_TEMPLATE` templates.
+- Use `.github/pull_request_template.md` for PR metadata.
+
+## How agents should use these files
+- The closest `AGENTS.md` in the path wins.
+- If a subdirectory has custom guidance, that file applies to edits in that subtree.
+- Non-standard files (`agent.md`, `claude.md`, etc.) are optional helpers for custom workflows.
+
+## Cross-agent wrappers
+- `agent.md` is a generic instruction set (the one we maintain here).
+- `claude.md`, `cursor.md`, `codex.md`, `pilot.md` are model-specific entry points that refer to this file.
+
+## QA & final run
+- Run `npm test` (or equivalent) until all checks pass.
+- Open a PR with summary, testing details, and compliance to security/code policy.
+- Ensure `.github/ISSUE_TEMPLATE` and `README` badges are present.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 164e155..6a1b946 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -11,6 +11,10 @@ Thanks for considering contributions to this template. A few guidelines to keep
 - Run linters and tests locally before opening a PR
 - If you add or change workflows, prefer `workflow_dispatch` in the template and explain how to enable automation in your PR
 - Ensure documentation (README, runbooks, prompts) is updated with any behavioral changes
+- For AI-assisted contributions, add a short note in PR body with:
+  - `AI agent used:` e.g., Claude, Copilot, Gemini
+  - `Prompt summary:` high-level description of what was asked
+  - `Commands run:` e.g., `npm test`, `npm run lint`, `gh pr checks`
 
 ## Review Process
 
diff --git a/README.md b/README.md
index ac4e3d3..34df0b8 100644
--- a/README.md
+++ b/README.md
@@ -58,6 +58,17 @@ A comprehensive project template for building production-ready services with:
 - `codeowners` / `.github/CODEOWNERS` — ownership hints
 - `.github/workflows/` — CI and security workflows (template-ready)
 - `.github/dependabot.yml` — dependency automation configuration
+- `.github/ai-guidance.md` — AI contributor quick-start guidance
+
+### AI support files
+
+- `AGENTS.md` — official agent instruction file (required)
+- `claude.md`, `codex.md`, `cursor.md`, `pilot.md` — lightweight agent entrypoints
+- `.gitattributes` — consistent line endings and diffs
+- `.cursorignore` — Cursor editor ignore list
+- `.aider.conf.yml` — Aider integration config
+- `.gemini/settings.json` — Gemini CLI integration config
+
 - `docs/personas/` — stakeholder personas for guidance and communication
 
 ## Tech Stack
diff --git a/claude.md b/claude.md
new file mode 100644
index 0000000..77d334e
--- /dev/null
+++ b/claude.md
@@ -0,0 +1,10 @@
+# Claude agent entrypoint
+
+This file is a simple wrapper around `AGENTS.md` for Claude-style agents.
+
+See `AGENTS.md` for full repository guidance.
+
+## Quick instructions
+1. Use instructions from `AGENTS.md`.
+2. Prefer minimal changes and code diffs.
+3. Use `gh` for GitHub operations when needed (create PRs, check status).
diff --git a/codex.md b/codex.md
new file mode 100644
index 0000000..de6803f
--- /dev/null
+++ b/codex.md
@@ -0,0 +1,10 @@
+# Codex agent entrypoint
+
+This file is a simple wrapper around `AGENTS.md` for Codex-style agents.
+
+See `AGENTS.md` for full repository guidance.
+
+## Quick instructions
+- Follow `AGENTS.md` for requirements.
+- Provide minimal and safe code changes.
+- Mention tests and workflow commands.
diff --git a/cursor.md b/cursor.md
new file mode 100644
index 0000000..6c78d4d
--- /dev/null
+++ b/cursor.md
@@ -0,0 +1,10 @@
+# Cursor agent entrypoint
+
+This file is a simple wrapper around `AGENTS.md` for Cursor-style agents.
+
+See `AGENTS.md` for full repository guidance.
+
+## Quick instructions
+- Follow `AGENTS.md` for repository context.
+- Avoid edits to ignored files (see `.gitignore`, `.cursorignore`).
+- Provide ready-to-apply patches and commands.
diff --git a/pilot.md b/pilot.md
new file mode 100644
index 0000000..3c33fac
--- /dev/null
+++ b/pilot.md
@@ -0,0 +1,10 @@
+# Pilot agent entrypoint
+
+This file is a simple wrapper around `AGENTS.md` for Pilot-style agents.
+
+See `AGENTS.md` for full repository guidance.
+
+## Quick instructions
+- Follow `AGENTS.md` for the project rules.
+- Respect branch protection policy (PR required for main).
+- Cite changed file paths and commands.