Progressive disclosure for task-specific documentation and references.
Desired state of the system, organized by capability domain.
| Spec | Domain | Purpose |
|---|
| Ambient Data Model | api | Platform-wide data model: projects, agents, sessions, credentials, RBAC |
| Control Plane | control-plane | CP architecture, runner structure, K8s provisioning |
| Runner | agents | Runner subprocess lifecycle, bridges, gRPC/HTTP endpoints |
| MCP Server | integrations | MCP tool definitions, sidecar and public endpoint modes |
| Security | security | Identity boundaries, credential authorization, per-session isolation, design decisions |
Feature specs remain in numbered directories under specs/ (e.g., specs/001-*/spec.md).
Agent-consumable procedures — step-by-step implementation workflows.
| Workflow | Domain | Purpose |
|---|
| Ambient Model | sessions | Spec-driven implementation pipeline for data model changes |
| Control Plane | control-plane | CP + Runner implementation workflow |
| MCP Server | integrations | MCP server implementation workflow |
Component-specific conventions loaded by review agents on demand.
| Standard | Domain | Scope |
|---|
| Backend Conventions | backend | Go patterns, K8s integration, handler conventions, user-scoped clients |
| Backend Error Handling | backend | Consistent error patterns across backend and operator |
| Backend K8s Client | backend | User token vs. service account — critical for RBAC compliance |
| Frontend Conventions | frontend | NextJS patterns, Shadcn, React Query, component guidelines |
| Frontend React Query | frontend | Data fetching hooks, mutations, cache invalidation |
| Operator Conventions | control-plane | OwnerReferences, reconciliation patterns, SecurityContext, resource limits |
| Security Standards | security | Auth flows, RBAC, token handling, container security |
| Cross-Cutting Conventions | platform | Image consistency, reconciliation, error propagation, namespace-scoped keys |
| Document | Purpose |
|---|
| ACP Constitution | 10 core principles: K8s-native, security, type safety, TDD, modularity, observability, lifecycle, context engineering, data access, commit discipline |
| Runner Constitution | Version pinning, automated freshness, image discipline, schema sync, bridge modularity |
| SDD Preflight | CI workflow enforcing constitution compliance on PRs |
| ADR | Decision |
|---|
| ADR-0001 | CRDs, operators, and Job-based execution over traditional API |
| ADR-0002 | User tokens for API ops instead of service accounts |
| ADR-0003 | Multi-repository support in a single session |
| ADR-0004 | Go for backend/operator, Python for runner |
| ADR-0005 | NextJS + Shadcn + React Query frontend stack |
| ADR-0006 | Runner SDK design and architecture |
| ADR-0007 | Unleash with workspace-scoped overrides |
| ADR-0008 | Automated inner-loop code review |
| ADR-0009 | REST API + PostgreSQL via rh-trex-ai |
| Guide | Purpose |
|---|
| Backend README | Go API development, testing, handler structure |
| Backend Test Guide | Testing strategies, test utilities, integration test setup |
| Frontend README | NextJS development, local setup, environment config |
| Frontend Design Guidelines | Component patterns, Shadcn usage, type conventions |
| Frontend Component Patterns | Architecture patterns for React components |
| Operator README | Operator development, watch patterns, reconciliation loop |
| Runner README | Python runner, Claude Code SDK integration |
| Public API README | Stateless gateway, token forwarding, input validation |
| API Server Guide | rh-trex-ai REST API, plugin system, code generation |
| SDK Guide | Go + Python client libraries for the public API |
| CLI README | acpctl CLI for managing agentic sessions |
| CodeRabbit Integration | Setup, review gate, session credentials, .coderabbit.yaml config |
| Guide | Purpose |
|---|
| Kind | Recommended local dev setup (Kubernetes in Docker) |
| OpenShift | OpenShift Local (CRC) setup for OCP-specific features |
| Hybrid | Run components locally with breakpoint debugging |
| Manifests | Kustomize overlay structure, deploy.sh usage |
| Guide | Purpose |
|---|
| Overview | Monitoring, metrics, and tracing architecture |
| Langfuse | LLM tracing with privacy-preserving defaults |
| Operator Metrics | Grafana dashboards for operator metrics |
| Resource | Purpose |
|---|
| Amber Config | Automation policies and label mappings |