docs: adopt AGENTS.md standard for agent instructions

cgwalters · cgwalters · commit c60f6283b487 · 2025-12-01T14:43:18.000-05:00
Rename CLAUDE.md to AGENTS.md to align with the community AGENTS.md convention (https://agents.md/). This standardized format makes the repository's agent instructions more discoverable and consistent with other projects using AI coding assistants. My real motivation here is I want to support other agentic systems and not having this project hardcoded to Claude Code, which is proprietary software. Assisted-by: Claude Code (Sonnet 4.5) Signed-off-by: Colin Walters <walters@verbum.org>
diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
@@ -0,0 +1 @@
+../AGENTS.md
diff --git a/.claude/amber-config.yml b/.claude/amber-config.yml
@@ -132,7 +132,7 @@ automation_policies:
 # Constitution compliance checks
 constitution_checks:
   enabled: true
-  reference_file: "CLAUDE.md"
+  reference_file: "AGENTS.md"
 
   principles:
     - id: "principle_v_modularity"
diff --git a/.github/ISSUE_TEMPLATE/amber-refactor.yml b/.github/ISSUE_TEMPLATE/amber-refactor.yml
@@ -50,7 +50,7 @@ body:
         - Must maintain backward compatibility
         - No breaking changes to API
         - All existing tests must pass
-        - Follow patterns in CLAUDE.md
+        - Follow patterns in AGENTS.md
     validations:
       required: true
 
@@ -70,7 +70,7 @@ body:
     attributes:
       label: Confirmation
       options:
-        - label: I have reviewed CLAUDE.md standards
+        - label: I have reviewed AGENTS.md standards
           required: true
         - label: Backward compatibility is required
           required: true
diff --git a/.github/ISSUE_TEMPLATE/amber-test-coverage.yml b/.github/ISSUE_TEMPLATE/amber-test-coverage.yml
@@ -66,7 +66,7 @@ body:
     attributes:
       label: Confirmation
       options:
-        - label: Tests should follow patterns in CLAUDE.md
+        - label: Tests should follow patterns in AGENTS.md
           required: true
         - label: Table-driven tests for Go, pytest for Python
           required: true
diff --git a/.github/workflows/amber-issue-handler.yml b/.github/workflows/amber-issue-handler.yml
@@ -132,7 +132,7 @@ jobs:
           ### For `test-coverage` type:
           1. Analyze current test coverage for specified files
           2. Identify untested code paths
-          3. Write contract tests following project standards (see CLAUDE.md)
+          3. Write contract tests following project standards (see AGENTS.md)
           4. Ensure tests follow table-driven test pattern (Go) or pytest patterns (Python)
           5. Verify all new tests pass
 
@@ -144,7 +144,7 @@ jobs:
 
           ## Requirements
 
-          - Follow all standards in `CLAUDE.md`
+          - Follow all standards in AGENTS.md
           - Use conventional commit format: `type(scope): message`
           - Run all linters BEFORE committing:
             - Go: `gofmt -w .`, `golangci-lint run`
@@ -341,7 +341,7 @@ jobs:
             ### Pre-merge Checklist
             - [ ] All linters pass
             - [ ] All tests pass
-            - [ ] Changes follow project conventions (CLAUDE.md)
+            - [ ] Changes follow project conventions (AGENTS.md)
             - [ ] No scope creep beyond issue description
 
             ### Reviewer Notes
diff --git a/.github/workflows/claude-code-review.yml b/.github/workflows/claude-code-review.yml
@@ -84,11 +84,11 @@ jobs:
             Perform a comprehensive code review with the following focus areas:
             
             1. **Code Quality & Best Practices**
-               - Follow repository's CLAUDE.md guidelines
+               - Follow repository's AGENTS.md guidelines
                - Clean code principles and design patterns
                - Proper error handling and edge cases
                - Code readability and maintainability
-               - TypeScript/Go best practices (see CLAUDE.md)
+               - TypeScript/Go best practices (see AGENTS.md)
             
             2. **Security**
                - Potential security vulnerabilities
diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md
@@ -334,7 +334,7 @@ Replace usage of "vTeam" with "ACP" (Ambient Code Platform) where it is safe and
 
 **Incremental Approach**:
 
-- Update documentation first (README, CLAUDE.md, docs/)
+- Update documentation first (README, AGENTS.md, docs/)
 - Update UI text in new features
 - Use ACP naming in new code modules
 - Do NOT perform mass renames - update organically during feature work
@@ -409,7 +409,7 @@ npm run build  # Must pass with 0 errors, 0 warnings
 
 Runtime development guidance is maintained in:
 
-- `/CLAUDE.md` for Claude Code development
+- `/AGENTS.md` for Claude Code development
 - Component-specific README files
 - MkDocs documentation in `/docs`
 
diff --git a/.specify/memory/constitution_update_checklist.md b/.specify/memory/constitution_update_checklist.md
@@ -10,7 +10,7 @@ When amending the constitution (`/memory/constitution.md`), ensure all dependent
 - [ ] `/templates/tasks-template.md` - Update if new task types needed
 - [ ] `/.claude/commands/plan.md` - Update if planning process changes
 - [ ] `/.claude/commands/tasks.md` - Update if task generation affected
-- [ ] `/CLAUDE.md` - Update runtime development guidelines
+- [ ] `/AGENTS.md` - Update runtime development guidelines
 
 ### Article-specific updates:
 
diff --git a/.specify/scripts/bash/update-agent-context.sh b/.specify/scripts/bash/update-agent-context.sh
@@ -58,8 +58,8 @@ eval $(get_feature_paths)
 NEW_PLAN="$IMPL_PLAN"  # Alias for compatibility with existing code
 AGENT_TYPE="${1:-}"
 
-# Agent-specific file paths  
-CLAUDE_FILE="$REPO_ROOT/CLAUDE.md"
+# Agent-specific file paths
+CLAUDE_FILE="$REPO_ROOT/AGENTS.md"
 GEMINI_FILE="$REPO_ROOT/GEMINI.md"
 COPILOT_FILE="$REPO_ROOT/.github/copilot-instructions.md"
 CURSOR_FILE="$REPO_ROOT/.cursor/rules/specify-rules.mdc"
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,16 +1,19 @@
-# CLAUDE.md
+# AGENTS.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file implements [AGENTS.md](https://agents.md/) with instructions for coding agents
+when working with code in this repository.
 
 ## Project Overview
 
 The **Ambient Code Platform** is a Kubernetes-native AI automation platform that orchestrates intelligent agentic sessions through containerized microservices. The platform enables AI-powered automation for analysis, research, development, and content creation tasks via a modern web interface.
 
 > **Note:** This project was formerly known as "vTeam". Technical artifacts (image names, namespaces, API groups) still use "vteam" for backward compatibility.
 
+> **Note:** At the current time, much of this project is hardcoded to Claude Code. Further references below continue that. It will be a wider project to decouple this project from Claude Code specifically, but having the instructions for this project use the generic AGENTS.md is the start of that decoupling.
+
 ### Amber Background Agent
 
-The platform includes **Amber**, a background agent that automates common development tasks via GitHub Issues. Team members can trigger automated fixes, refactoring, and test additions without requiring direct access to Claude Code.
+The platform includes **Amber**, a background agent that automates common development tasks via GitHub Issues. Team members can trigger automated fixes, refactoring, and test additions without requiring direct access to a specific agentic AI system like Gemini CLI, Goose or Claude Code.
 
 **Quick Links**:
 
@@ -42,7 +45,7 @@ Pod Runs Claude CLI → Results Stored in CR → UI Displays Progress
 
 ## Memory System - Loadable Context
 
-This repository uses a structured **memory system** to provide targeted, loadable context instead of relying solely on this comprehensive CLAUDE.md file.
+This repository uses a structured **memory system** to provide targeted, loadable context instead of relying solely on this comprehensive AGENTS.md file.
 
 ### Quick Reference
 
diff --git a/AMBER_SETUP.md b/AMBER_SETUP.md
@@ -83,7 +83,7 @@ always_create_branch: true         # Safe workflow
    - Security considerations
    - Troubleshooting
 
-4. **CLAUDE.md** - Updated with Amber section
+4. **AGENTS.md** - Updated with Amber section
    - Quick links to documentation
    - Common workflows summary
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -226,7 +226,7 @@ go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
 - Use `unstructured.Nested*` helpers for type-safe CR access
 - Set OwnerReferences on child resources for automatic cleanup
 
-See [CLAUDE.md](CLAUDE.md) for comprehensive backend/operator development standards.
+See [AGENTS.md](AGENTS.md) for comprehensive backend/operator development standards.
 
 ### Frontend Code (NextJS)
 
@@ -589,7 +589,7 @@ oc describe pvc backend-state-pvc -n vteam-dev
 If you're stuck or have questions:
 
 1. **Check existing documentation:**
-   - [CLAUDE.md](CLAUDE.md) - Comprehensive development standards
+   - [AGENTS.md](AGENTS.md) - Comprehensive development standards
    - [README.md](README.md) - Project overview and quick start
    - [docs/](docs/) - Additional documentation
 
diff --git a/README.md b/README.md
@@ -543,7 +543,7 @@ See [e2e/README.md](e2e/README.md) for detailed documentation, troubleshooting,
 - Update relevant documentation when changing functionality
 - Follow existing documentation style (Markdown)
 - Add code comments for complex logic
-- Update CLAUDE.md if adding new patterns or standards
+- Update AGENTS.md if adding new patterns or standards
 
 ## Support & Documentation
 
diff --git a/agents/amber.md b/agents/amber.md
@@ -28,7 +28,7 @@ You are Amber, the Ambient Code Platform's expert colleague and codebase intelli
 - When you identify a bug, include the fix
 
 **4. Team Fit**
-- Respect project standards (CLAUDE.md, DESIGN_GUIDELINES.md)
+- Respect project standards (AGENTS.md, DESIGN_GUIDELINES.md)
 - Learn from past decisions (git history, closed PRs, issue comments)
 - Adapt tone to context: terse in commits, detailed in RFCs
 - Make the team look good—your work enables theirs
@@ -100,14 +100,14 @@ Low - Changes isolated to session handler, no API schema changes
 You operate within a clear authority hierarchy:
 
 1. **Constitution** (`.specify/memory/constitution.md`) - ABSOLUTE authority, supersedes everything
-2. **CLAUDE.md** - Project development standards, implements constitution
+2. **AGENTS.md** - Project development standards, implements constitution
 3. **Your Persona** (`agents/amber.md`) - Domain expertise within constitutional bounds
 4. **User Instructions** - Task guidance, cannot override constitution
 
 **When Conflicts Arise:**
 - Constitution always wins - no exceptions
 - Politely decline requests that violate constitution, explain why
-- CLAUDE.md preferences are negotiable with user approval
+- AGENTS.md preferences are negotiable with user approval
 - Your expertise guides implementation within constitutional compliance
 
 ### Visual: Authority Hierarchy & Conflict Resolution
@@ -117,14 +117,14 @@ flowchart TD
     Start([User Request]) --> CheckConst{Violates<br/>Constitution?}
 
     CheckConst -->|YES| Decline[❌ Politely Decline<br/>Explain principle violated<br/>Suggest alternative]
-    CheckConst -->|NO| CheckCLAUDE{Conflicts with<br/>CLAUDE.md?}
+    CheckConst -->|NO| CheckCLAUDE{Conflicts with<br/>AGENTS.md?}
 
     CheckCLAUDE -->|YES| Warn[⚠️ Warn User<br/>Explain preference<br/>Ask confirmation]
     CheckCLAUDE -->|NO| CheckAgent{Within your<br/>expertise?}
 
     Warn --> UserConfirm{User<br/>Confirms?}
     UserConfirm -->|YES| Implement
-    UserConfirm -->|NO| UseStandard[Use CLAUDE.md standard]
+    UserConfirm -->|NO| UseStandard[Use AGENTS.md standard]
 
     CheckAgent -->|YES| Implement[✅ Implement Request<br/>Follow constitution<br/>Apply expertise]
     CheckAgent -->|NO| Implement
@@ -151,12 +151,12 @@ flowchart TD
 
 **Decision Flow:**
 1. **Constitution Check** - FIRST and absolute
-2. **CLAUDE.md Check** - Warn but negotiable
+2. **AGENTS.md Check** - Warn but negotiable
 3. **Implementation** - Apply expertise within bounds
 
 **Example Scenarios:**
 - Request: "Skip tests" → Constitution violation → Decline
-- Request: "Use docker" → CLAUDE.md preference (podman) → Warn, ask confirmation
+- Request: "Use docker" → AGENTS.md preference (podman) → Warn, ask confirmation
 - Request: "Add logging" → No conflicts → Implement with structured logging (constitution compliance)
 
 **Detailed Examples:**
@@ -166,14 +166,14 @@ flowchart TD
 - "Use panic() for error handling" → Constitution Principle III violation → Decline: "panic() is forbidden in production code per Constitution Principle III. I'll use fmt.Errorf() with context instead."
 - "Don't worry about linting, just commit it" → Constitution Principle X violation → Decline: "Constitution Principle X requires running linters before commits (gofmt, golangci-lint). I can run them now - takes <30 seconds."
 
-**CLAUDE.md Preferences (Warn, Ask Confirmation):**
-- "Build the container with docker" → CLAUDE.md prefers podman → Warn: "⚠️ CLAUDE.md specifies podman over docker. Should I use podman instead, or proceed with docker?"
-- "Create a new Docker Compose file" → CLAUDE.md uses K8s/OpenShift → Warn: "⚠️ This project uses Kubernetes manifests (see components/manifests/). Docker Compose isn't in the standard stack. Should I create K8s manifests instead?"
+**AGENTS.md Preferences (Warn, Ask Confirmation):**
+- "Build the container with docker" → AGENTS.md prefers podman → Warn: "⚠️ AGENTS.md specifies podman over docker. Should I use podman instead, or proceed with docker?"
+- "Create a new Docker Compose file" → AGENTS.md uses K8s/OpenShift → Warn: "⚠️ This project uses Kubernetes manifests (see components/manifests/). Docker Compose isn't in the standard stack. Should I create K8s manifests instead?"
 - "Change the Docker image registry" → Acceptable with justification → Warn: "⚠️ Standard registry is quay.io/ambient_code. Changing this may affect CI/CD. Confirm you want to proceed?"
 
 **Within Expertise (Implement):**
 - "Add structured logging to this handler" → No conflicts → Implement with constitution compliance (Principle VI)
-- "Refactor this reconciliation loop" → No conflicts → Implement following operator patterns from CLAUDE.md
+- "Refactor this reconciliation loop" → No conflicts → Implement following operator patterns from AGENTS.md
 - "Review this PR for security issues" → No conflicts → Perform analysis using ACP security standards
 
 ## ACP Constitution Compliance
@@ -501,7 +501,7 @@ Full details: [link]
 **Quality Standards:**
 - Run linters before any commit (gofmt, black, isort, prettier, markdownlint)
 - Zero tolerance for test failures
-- Follow CLAUDE.md and DESIGN_GUIDELINES.md
+- Follow AGENTS.md and DESIGN_GUIDELINES.md
 - Conventional commits, squash on merge
 - All PRs include issue reference (`Fixes #123`)
 
@@ -579,7 +579,7 @@ Full details: [link]
 - Runner workspace sync delays (PVC provisioning)
 - Langfuse integration (missing env vars, network policies)
 
-**Team Preferences (from CLAUDE.md):**
+**Team Preferences (from AGENTS.md):**
 - Squash commits, always
 - Git feature branches, never commit to main
 - Python: uv over pip, virtual environments always
diff --git a/components/backend/README.md b/components/backend/README.md
@@ -97,7 +97,7 @@ make check-env         # Verify Go, kubectl, docker installed
 
 ## Architecture
 
-See `CLAUDE.md` in project root for:
+See `AGENTS.md` in project root for:
 - Critical development rules
 - Kubernetes client patterns
 - Error handling patterns
diff --git a/components/operator/README.md b/components/operator/README.md
@@ -93,7 +93,7 @@ operator/
 
 ### Key Patterns
 
-See `CLAUDE.md` in project root for:
+See `AGENTS.md` in project root for:
 - Watch loop with reconnection
 - Reconciliation pattern
 - Status updates (UpdateStatus subresource)
diff --git a/components/runners/claude-code-runner/pyproject.toml b/components/runners/claude-code-runner/pyproject.toml
@@ -2,7 +2,6 @@
 name = "claude-code-runner"
 version = "0.1.0"
 description = "Runner that streams via Claude Code SDK and syncs workspace via PVC proxy"
-readme = "CLAUDE.md"
 requires-python = ">=3.11"
 authors = [
   { name = "vTeam" }
diff --git a/docs/amber-automation.md b/docs/amber-automation.md
@@ -141,7 +141,7 @@ File: `path/to/another.py`
 ## Success Criteria
 - [ ] All linters pass
 - [ ] All tests pass
-- [ ] Follows CLAUDE.md standards
+- [ ] Follows AGENTS.md standards
 ```
 
 **Key Fields**:
@@ -157,7 +157,7 @@ Amber's behavior is controlled by:
 
 1. **Workflow**: `.github/workflows/amber-issue-handler.yml`
 2. **Config**: `.claude/amber-config.yml` (automation policies)
-3. **Project Standards**: `CLAUDE.md` (Amber follows all project conventions)
+3. **Project Standards**: `AGENTS.md` (Amber follows all project conventions)
 
 ### Risk Levels
 
@@ -415,7 +415,7 @@ A: Depends on task complexity. Typical auto-fix: ~10K tokens ($0.03), refactorin
 ## Related Documentation
 
 - [Amber Configuration](.claude/amber-config.yml) - Automation policies
-- [Project Standards](../CLAUDE.md) - Conventions Amber follows
+- [Project Standards](../AGENTS.md) - Conventions Amber follows
 - [GitHub Actions Security](https://docs.github.com/en/actions/security-for-github-actions) - Official security guide
 
 ---
diff --git a/docs/amber-quickstart.md b/docs/amber-quickstart.md
@@ -140,7 +140,7 @@ Break into modules:
 ## Constraints
 - Maintain backward compatibility
 - All existing tests must pass
-- Follow CLAUDE.md standards
+- Follow AGENTS.md standards
 
 ## Priority
 P0 - Critical
@@ -327,7 +327,7 @@ gh workflow enable amber-issue-handler.yml
 
 - [Complete Guide](amber-automation.md) - Detailed documentation
 - [Amber Config](.claude/amber-config.yml) - Automation policies
-- [Project Standards](../CLAUDE.md) - Conventions Amber follows
+- [Project Standards](../AGENTS.md) - Conventions Amber follows
 
 ---
 
diff --git a/docs/implementation-plans/amber-implementation.md b/docs/implementation-plans/amber-implementation.md
diff --git a/docs/labs/basic/lab-1-first-rfe.md b/docs/labs/basic/lab-1-first-rfe.md
diff --git a/docs/labs/index.md b/docs/labs/index.md
diff --git a/docs/reference/index.md b/docs/reference/index.md
diff --git a/docs/user-guide/getting-started.md b/docs/user-guide/getting-started.md
diff --git a/docs/user-guide/index.md b/docs/user-guide/index.md
diff --git a/docs/user-guide/working-with-amber.md b/docs/user-guide/working-with-amber.md
