Skip to content

BOOKMARKS.md

Latest commit

 

History

History
149 lines (117 loc) · 8.98 KB

BOOKMARKS.md

File metadata and controls

149 lines (117 loc) · 8.98 KB
Raw

Bookmarks

Progressive disclosure for task-specific documentation and references.

Table of Contents

Specs

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).

Workflows

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

Standards

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

Governance

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

Architecture Decisions

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

Component Guides

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

Development Environment

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

Testing

Guide Purpose
E2E Testing Guide Writing and running Cypress E2E tests
E2E README Running E2E tests, environment setup, CI integration

Observability

Guide Purpose
Overview Monitoring, metrics, and tracing architecture
Langfuse LLM tracing with privacy-preserving defaults
Operator Metrics Grafana dashboards for operator metrics

Design Documents

Document Purpose
Declarative Session Reconciliation Session lifecycle via declarative status transitions
Runner-Operator Contract Interface contract between operator and runner pods
Session Status Redesign Status field evolution and phase transitions
Session Initialization Flow How sessions are initialized and configured
Spec-Runtime Synchronization Keeping spec and runtime state in sync
Agent Runtime Registry Agent runtime registry architecture
CLI Runners CLI runner design and implementation
Status Update Comparison Comparison of status update approaches

Dependency Automation

Resource Purpose
SDK Version Bump Workflow Daily check for claude-agent-sdk + anthropic updates, auto-PR
SDK Version Bump Script PyPI version check, pyproject.toml update, changelog fetch
SDK Feature Report Generator Parse release notes into structured feature data

Amber Automation

Resource Purpose
Amber Config Automation policies and label mappings