Agent Instructions

Project Structure

ai_platform_engineering/   # Python backend
  mcp/                     # Per-tool MCP servers (GitHub, ArgoCD, etc.)
  dynamic_agents/          # Dynamic agents runtime (FastAPI, MongoDB, AG-UI/SSE)
  integrations/            # Slack and Webex bot integrations
  autonomous_agents/       # Scheduled and event-driven autonomous tasks
  audit_service/           # Audit-event service
  scheduler/               # Scheduler service
  cron-runner/             # Cron job runner
  knowledge_bases/rag/     # RAG server, ingestors, graphrag, ontology
  skills_middleware/       # Skill scanning / catalog middleware
  utils/                   # Shared utilities
ui/                        # Next.js frontend
docs/                      # Documentation site (Docusaurus)
docker-compose*.yaml       # Canonical Docker Compose configurations
tests/                     # Repo-level + RBAC tests
scripts/                   # Utility scripts
charts/                    # Helm charts

Find the Canonical Implementation

Start with the narrowest owning module; do not add a parallel implementation until you have checked the shared locations below.

Tests live beside their component (**/tests/, **/__tests__/) unless they exercise a cross-component contract. Repository-wide checks are in tests/; RBAC integration and browser coverage is in tests/rbac/ and ui/e2e/rbac/.

Each component has its own environment variables - see env.example in ui/ and READMEs in ai_platform_engineering/knowledge_bases/rag/.

Documentation

• Architecture & concepts - Keep updated in docs/
• Configuration & code details - Document in component READMEs
• Agent instructions - Keep this file (AGENTS.md) up-to-date

Docs & Spec Rules

• Reading is as hard as writing.
• Optimize for the next reader.
• Prefer bullets over paragraphs.
• Prefer diagrams over long explanations.
• No wall of text.
• Remove words that do not change decisions.

DCO Policy

AI agents operating in this repository must follow these rules on every commit:

1. No AI sign-off - Signed-off-by is a human DCO certification. AI agents must never invent, assume, or add this trailer on their own.
2. Use an explicit human DCO on every commit - Every commit must include the Signed-off-by trailer that the human contributor explicitly provided.
3. Do not invent identities - Use only a DCO identity explicitly provided by the human contributor.

Git Guidelines

• Conventional Commits for commits and PR titles - Format: type(scope): description
  • Types: feat, fix, docs, refactor, test, chore
  • Example: feat(rag): add userinfo caching
• Branch naming - Use prebuild/ prefix for CI to build Docker images
  • Example: prebuild/feat/rag-batch-job-status
• PR descriptions - Follow the template in .github/pull_request_template.md

Pull Requests and Review

• One logical change per PR. Aim for under 500 changed lines of hand-written code; keep refactors out of behaviour changes.
• The description states why the change exists, links the issue, and says how it was verified.
• Disclose AI assistance in the description. Never add AI co-author or assisted-by trailers - see DCO Policy.
• Never apply a review suggestion with GitHub's "Commit suggestion" button; the commit it creates names the suggestion's author as a co-author who has not signed off, which fails DCO. Apply it locally.
• Do not resolve review threads on a pull request you do not own.
• Full policy: docs/docs/repo-ops/code-review.md

Issue Tracking

This project uses GitHub Issues for issue tracking.

• Create follow-up work as GitHub Issues in caipe-io/ai-platform-engineering.
• Reference related issues in PR descriptions when applicable.
• Do not use repo-local Beads or bd issue tracking.

Quality Gates

Before committing code changes, run relevant checks:

• Python: uv run ruff check, uv run pytest (always use uv run to ensure virtual env)
• UI: nvm use first (if available), then npm run lint, npm run build

Docker Compose First Install

When changing docker-compose.yaml, docker-compose.dev.yaml, .env.example, release image tags, Compose profiles, Keycloak/OpenFGA/RAG defaults, or first-launch UX, follow .claude/skills/docker-compose-first-install/SKILL.md. The docker-compose.yaml + .env.example path must work for a first-time OSS user with the minimal profiles:

mcp-servers,caipe-ui-prod,rbac,dynamic-agents,rag,caipe-mongodb,web_ingestor

Do not add Slack/Webex bots to that default path.

Code Style

• Imports at top - All imports must be at the top of the file, unless otherwise specified
• Type hints required - Python functions should have type hints for parameters and return values
• Error handling - Use specific exceptions, log errors with context, don't silently swallow exceptions
• Comments - Explain current intent or an invariant. Do not add tool/model provenance or rely on historical spec IDs as the explanation.

Test Data and Generic Examples

• Never use real or deployment-specific names in tests, fixtures, examples, docs, seeds, screenshots, or generic source defaults.
• This includes company and product names, people, email addresses, bot identities, cluster names, environment names, customer names, and internal project names.
• Use neutral identifiers such as primary, secondary, example, test-user, and example-bot.
• Use reserved domains such as example.com, example.org, and example.test for URLs and email addresses.
• Environment-specific identities belong only in environment-owned deployment configuration, never in reusable source or tests.

Active Technologies

• TypeScript (Next.js, React) + Zustand (state management), Next.js App Router (093-fix-audit-chat-active-preserve)
• MongoDB (server-side via API), Zustand store (client-side) (093-fix-audit-chat-active-preserve)
• Python + Slack Bolt, Slack SDK, httpx (SSE streaming), Pydantic (config models), requests, loguru, PyYAML — no new dependencies (100-slack-agui-migration)
• MongoDB (LangGraph checkpointer on dynamic agents side; Slack bot is stateless beyond in-memory TTL caches) (100-slack-agui-migration)
• Service accounts: dynamic Keycloak confidential clients + OpenFGA service_account tuples + Mongo service_accounts collection; BFF (Next.js) orchestrates create/rotate/revoke/scope; caller-keyed tool authz added to the OpenFGA ext_authz bridge (2026-06-05-service-accounts)
• Python 3.13 Harness Engine supports provider adapters; the optional Python 3.14 Deep Agents integration reuses the Dynamic Agents runtime. Compatibility-service execution remains the default unless explicitly enabled.
• MongoDB harness_agents, harness_agent_versions, harness_sessions, harness_runs, and harness_events preserve execution versions, native session bindings and cursor replay. Native checkpoints stay in the application database, with a shared execution_thread_leases producer fence.

Recent Changes

• 2026-08-17-harness-engine: Added an independent AgentCore Harness Engine with detached runs, replayable sessions, and W3C trace propagation