Skip to content

AGENTS.md

Latest commit

 

History

History
455 lines (345 loc) · 21.3 KB

AGENTS.md

File metadata and controls

455 lines (345 loc) · 21.3 KB
Raw

SWARM GOVERNANCE MASTER MANIFEST

ID: LORNU-GROWTH-2026

Generated by: ai-agent-agent-guides

NOTICE — AI agents extracted to lornu-ai/bullpen. The ai-agents/, ai-agent-{boots,core,crawler,procure,prompt-magic,rag}/, ai-remediation-fix/, and agents/ trees previously living in this repo have been moved wholesale to bullpen. References to those paths throughout this manifest (and in .cursorrules, the workflows under .github/, docs/, and various Cargo manifests) are stale and will be rewritten by a follow-up ai-agent-agent-guides sync. Until then, treat any ai-agents/… path mention below as bullpen/ai-agents/… in lornu-ai/bullpen.

<@all>

GROWTH WITHOUT LIMITS — SOVEREIGN ADX INSTRUCTIONS

MANDATORY: Before generating any code, read these architecture documentation files:

  • .ai/ARCHITECTURE.md - System architecture, directory structure, data flow, GitOps patterns
  • .ai/AGENT.md - Agent instructions, tech stack guidelines (Bun, Rust, dockworker), validation rules
  • .ai/CONVENTIONS.md - Code conventions for Rust and TypeScript/Bun with examples
  • .ai/TROUBLESHOOTING.md - Troubleshooting guide for common errors
  • .ai/CHECKLIST.md - Pre-commit validation checklist

Template Reference:

  • Use .ai/templates/rust-agent/ when creating new Rust agents
  • Use .ai/templates/bun-app/ when creating new Bun/TypeScript applications

Core Principle: Rust-First Architecture. All new components and performance-critical refactors must use Cargo/Rust. Legacy Python (uv) is restricted to maintenance of existing features only.

Canonical Stack

The approved technology stack for this repository. Do not introduce alternatives without an ADR.

Layer Tool
Systems / backend language Rust (compiled with Cargo)
Build / packaging Nix Flakes (flake.nix, hermetic builds)
Container images Nix OCI + dockworker.ai — never Dockerfile
Database SurrealDB (multi-model: document, graph, KV)
Frontend / scripting language TypeScript
JS runtime, package manager, bundler, test runner Bun

Implications:

  • Containers: flake.nix OCI outputs + dockworker.toml (engine = "nix"). Never add, restore, or recommend Dockerfile / docker build / docker buildx. Publish via nix build + skopeo or dockworker push.
  • New services: Rust + Cargo + a flake.nix derivation. No Go, no Java, no new Python.
  • Persistence: default to SurrealDB; do not add Postgres/Mongo/Redis without ADR justification.
  • Frontend / CLI: TypeScript run by Bun (bun run, bun test, bun install); no npm, pnpm, yarn, or node invocations.
  • Builds: prefer nix build / nix flake check over raw cargo outside Nix when reproducibility matters.

0. Handoff Protocol (MANDATORY)

Before starting any session, check for .agent-handoff.md in the root. This file contains critical context from the previous agent (Claude, Gemini, etc.) including worktree traps, in-flight PRs, and next steps.

Before ending a session, you MUST generate a handoff. Use lornu handoff generate or manually follow the .ai/HANDOFF_SPEC.md. This ensures zero context drift in our multi-agent swarm.

1. Pre-Push Validation (MANDATORY)

Run local-ci before pushing any PR. This is the canonical pre-push gate for every contributor and every coding agent that touches this repo. Configuration lives in .local-ci.toml; the binary comes from stevedores-org/local-ci.

local-ci            # run all enabled stages from .local-ci.toml
local-ci --fix      # apply auto-fixes (rustfmt, etc.) where supported
local-ci fmt clippy # run a subset of stages

Install once with go install github.com/stevedores-org/local-ci@latest (binary lands in $(go env GOPATH)/bin). Cache state in .local-ci-cache/ means repeat runs only re-execute stages whose inputs changed.

The rule: if local-ci is red, do not push. Either fix the failure or, with a documented reason, --skip the stage. Do not push a known-red PR with the expectation that GitHub CI will surface the same failure — that wastes reviewer time and burns CI minutes on issues you could have caught in seconds locally.

Why this is mandatory: the most common reason a PR sits BLOCKED on this repo is a fmt/clippy/test failure that local-ci would have caught before push. Agents that bypass this gate produce PRs that consume team review bandwidth on self-inflicted issues. This rule applies equally to humans and to coding agents (Claude, Codex, Cursor, Copilot, Jules, Antigravity).

Fallbacks (only when local-ci is unavailable)

If local-ci cannot be installed for some reason, fall back to one of these — but the gate is still the same set of checks (fmt + clippy + test + yaml validate):

just validate-all                                   # via just task runner
make test                                           # via make
cargo fmt --check && cargo clippy --all-targets --all-features -- -D warnings && cargo test --all-features

Documentation sync validation (runs separately from local-ci):

ai-agent-agent-guides validate

See also: CODING_STANDARDS.md for language standards, .cursorrules for IDE rules, .ai/CHECKLIST.md for the pre-commit checklist, .local-ci.toml for the stage definitions.

2. Python-to-Rust Migration (Strangler Fig Pattern)

Incrementally replace legacy Python with Rust while maintaining zero downtime.

Migration Workflow

  1. Profile: Identify Python bottlenecks (A2A latency, data processing)
  2. Bridge: Create Rust implementations using PyO3 + Maturin
  3. Test: Verify bit-for-bit parity in development and staging environments
  4. Swap: Update entry points to call Rust modules (keep Python wrapper initially)
  5. Validate: Run full integration tests in staging
  6. Purge: Remove legacy .py source only after production validation
  7. Document: Run ai-agent-agent-guides sync to update architecture documentation

Development Commands

# Build Rust-Python bridge
maturin develop

# Test Python compatibility
python -m pytest tests/

3. Multi-Cloud Infrastructure

Control Planes

  • Primary: GCP GKE (us-central1) — ArgoCD/Flux managing 12+ applications
  • Secondary: AWS EKS (us-east-2) — Flux-native with 24 Kustomizations
  • Tertiary: Azure AKS — Managed via GCP ArgoCD
  • Edge: Cloudflare GLB + DNS Automation (Rust-native required)

Key Services

  • Private RAG: Cloudflare R2 + Vectorize (via Rust automation-hub)
  • GLCDF: Azure Cosmos DB + Blob Storage (via glcdf-client-rs)
  • GPU Inference: NVIDIA NIM (DeepSeek-R1) via XNIMDeployment XRD

4. Git Workflow & Deployment

Branch Strategy

develop (PR target) → staging (Admin approval) → main (Production)

Immutable Deployments

Principle: "Build Once, Deploy Many"

  1. Build OCI images on develop branch
  2. Promote images through environments via Kustomize overlays
  3. Update newTag in overlays/prod/kustomization.yaml via Git PR
  4. Never rebuild images per environment

5. Repository Structure

GitHub Organizations:

Cloudflare Account:

5. Repository Structure

crossplane/hub/deploy/ # Shared infrastructure (Crossplane/Flux) crossplane/spoke/apps/ # Application manifests (ArgoCD) apps/ # Application source (Rust/Cargo, Frontend: Bun) app-agents/ # Hub Guardian Agents (SRE, Cleaner, Reviewer) ai-agent-agent-guides/ # Documentation automation (7-File Rule enforcement)


**Language Standards:**
- Backend: Rust/Cargo (required)
- Frontend: Bun (required)
- Legacy: Python/uv (maintenance only)

### 6. The 7-File Rule (AUTOMATED)

**Automation Tool:** `ai-agent-agent-guides` automatically maintains documentation consistency across all required files.

#### The 7 Mandatory Files
1. **`.cursorrules`** — IDE path/logic rules
2. **`AGENTS.md`** — Agent-to-Agent capability registry
3. **`CLAUDE.md`** — Build/test commands and workflows
4. **`README.md`** — High-level architecture overview
5. **`ARCH_PRESERVE.md`** — Documentation of retained legacy code with rationale
6. **`.github/copilot-instructions.md`** — GitHub Copilot LLM context
7. **`.github/system-instruction.md`** — Sovereign intelligence standards

#### Automated Workflow

**When Documentation Updates Are Needed:**
- Architectural changes
- New capabilities or agents added
- Significant logic modifications
- Technology stack changes
- Migration milestones (Python → Rust)

#### Commands
```bash
# Analyze codebase and update all 7 files
ai-agent-agent-guides sync

# Validate documentation consistency (pre-commit check)
ai-agent-agent-guides validate

# Review proposed changes before applying
ai-agent-agent-guides sync --dry-run

7. Security & Secrets (Zero-Trust)

Standards

  • Encryption: Mozilla SOPS + AWS KMS
  sops -e secrets.yaml > secrets.enc.yaml
  • Injection: External Secrets Operator (ESO) + Flux postBuild substitution
  • Identity: OIDC/IRSA/Workload Identity Federation
  • Prohibition: No long-lived service account keys

8. Bullpen Agent Roster (Oxidized)

🌟 The autonomous workforce is formally defined and ready for cluster-scale collaboration.

Agent Persona Role & Ecosystem Focus Maturity
AIOps SRE Sam Guardian: SLOs, automated RCA, and auto-remediation via Prometheus and KubeAPI. Phase 2
Procure AI Petra Accountant: Compute ROI, vendor lifecycles, and transaction auditing in Lone Star Ledgers. Phase 1
CISO Agent Casey Shield: Enforces Zero-Trust, Cedar Policies, and Data Fabric privacy (Client Secrets). Phase 3
AI Agent CI Quinn Stevedore: Orchestrates hermetic Nix builds and OCI packaging without Dockerfiles. Phase 2
AI Agent PM Parker Pilot: Translates business ROI into technical backlogs and monitors market signals. Phase 1

9. Quick Reference Card

Task Preferred Command Legacy Alternative
Pre-push validation (MANDATORY) local-ci just validate-all / make test
Pre-push validation with auto-fix local-ci --fix —
Run one stage local-ci clippy (or fmt, test, …) —
Rust fmt check local-ci fmt cargo fmt --check
Rust clippy local-ci clippy cargo clippy -- -D warnings
Rust tests local-ci test cargo test --all-features
Python-Rust dev maturin develop —
Frontend dev bun run dev —
YAML validation just yaml-validate make test-yaml
Force GitOps sync flux reconcile kustomization <name> --with-source —
Encrypt secrets sops -e secrets.yaml —
Sync documentation ai-agent-agent-guides sync —
Validate docs ai-agent-agent-guides validate —
Preview doc changes ai-agent-agent-guides sync --dry-run —

See also:

/@all

<@architect>

ARCHITECT GUIDANCE (Claude/Gemini)

  • Primary Goal: System integrity and long-term scalability.
  • Protocol: Generate an ADR (Architectural Decision Record) before any breaking schema change.
  • Guardrail: Reject Builder code that lacks docstrings or unit tests.
  • Leadership: You oversee the Cursor and Copilot agents. Ensure they do not deviate from the SDLC.
  • Schema Ownership: All data structure changes must be approved by an Architect agent.
  • Python Migration: Enforce the Strangler Fig pattern. Do not allow new Python features unless critical.

Architecture Principles

  1. Hub-and-Spoke: Centralized orchestration with distributed execution
  2. Data Fabric First: Schema validation before implementation
  3. Zero Trust: All agent communications must be authenticated
  4. Observability: Tracing, metrics, and logging for all operations
  5. Rust-First: Performance critical paths move to Rust immediately

/@architect

<@builder>

🛠️ BUILDER GUIDANCE (Codex/Cursor/Copilot)

  • Primary Goal: Rapid, high-quality execution.
  • Protocol: You are subordinate to the Architect. If a prompt is ambiguous, ask the Architect Agent for a spec update.
  • SDLC Gate: Implementation in src/ is forbidden without a test in tests/.
  • Code Style: Follow existing patterns. Never introduce new frameworks without ADR approval.

MANDATORY: Rust + Nix Stack

Always use:

  • Rust for all new code (with Cargo.toml)
  • Nix Flakes for builds (add default.nix to each agent)
  • Attic/R2 for binary caching (CI handles push automatically)
  • crane for incremental Rust builds in Nix

Never use:

  • Dockerfiles. NEVER create, use, or rely on a Dockerfile. This is a foundational lornu-ai/stevedores-org standard. All OCI images MUST be built natively via Nix Flakes and dockworker.ai.
  • Go, Python, or TypeScript for new agents
  • Manual dependency management outside Cargo/Nix

Implementation Rules

  1. TDD First: Write failing tests before implementation
  2. Schema Validation: Use Data Fabric types, never invent new structures
  3. Documentation: Update OpenAPI specs for any API changes
  4. Security: Never commit secrets, use ESO/OIDC for credentials
  5. Nix Integration: Every new agent needs a default.nix file
  6. Archive Reference: Search /archive before building new features to reuse existing logic
  7. Language Standards: Rust (preferred for logic), Nix (for builds), TypeScript (permitted for UI/CLI). Go/Dagger is deprecated.
  8. CI/CD Architecture: Use Nix Flakes + Attic (Cloudflare R2) for hermetic artifact management.
  9. Cache Verification: Run nix flake check before PR

Mono-Repo Structure

  • /ai-agents/ - All Rust AI agents (canonical location)
  • /app-rust/ - Production Rust services (Cloud Run)
  • /app-go/ - DEPRECATED: Legacy Go code (do not extend)
  • /app-py/ - DEPRECATED: Legacy Python experiments (maintenance only)
  • /archive/ - Historical repositories (reference only)

/@builder

<@codex>

🤖 CODEX GUIDANCE

  • Discovery: Ingest this file as the primary project personality.
  • Vibe: Technical, concise, Rust-centric, Nix-native.
  • Stack: Always use Rust + Cargo + Nix Flakes + Attic (R2).
  • Build: Use nix build and nix flake check, not raw cargo outside Nix.
  • Cache: All builds should be cached in Attic on Cloudflare R2.
  • Mono-repo: /ai-agents/ is the canonical location for all agents.

/@codex

<@cursor>

CURSOR IDE RULES

  • Language: Generate Rust code only. No Go, Python, or TypeScript.
  • Build: All agents must have Cargo.toml and default.nix.
  • Context Window: Load rules/03-data-fabric.md for every code generation request.
  • Testing: All generated code must include corresponding tests.
  • Style: Match existing Rust patterns exactly.
  • No Magic: Avoid implicit behaviors; be explicit in all implementations.
  • Nix: Include nativeBuildInputs for build deps, buildInputs for runtime deps.

/@cursor

<@copilot>

GITHUB COPILOT INSTRUCTIONS

  • Role: Tactical Builder for autocomplete and inline suggestions.
  • Language: Suggest Rust code only. Never suggest Go, Python, or TypeScript.
  • Constraint: Never invent new data structures; use the Data Fabric.
  • Reference: Check ai-agents/ai-agent-agent-guides/ for governance rules.
  • Security: Never suggest hardcoded credentials or secrets.
  • Nix: When suggesting build configs, use Nix Flakes patterns.

/@copilot

<@gemini>

GEMINI CONTEXTUAL GUARDIAN

  • Role: Data Fabric Guardian and Schema Drift Analyzer.
  • Task: Analyze all repository changes for schema drift.
  • Reference: Validate against rules/03-data-fabric.md.
  • Alert: Flag any changes that modify data structures without ADR.
  • Logic Check: Ensure python migration follows Strangler Fig pattern.

/@gemini

<@antigravity>

ANTIGRAVITY AUTONOMOUS ORCHESTRATION

  • Protocol: Autonomous project execution is permitted only if the "Execution Success Plan" is logged and approved by the Human Architect.
  • Hierarchy: Reference the Orchestration Leadership defined in <@all>.
  • Safety: All autonomous actions must be reversible or require explicit approval.

/@antigravity

<@jules>

JULES VM AUTOMATION

  • Role: Autonomous VM-based automation agent for long-running tasks.
  • Environment: Runs in isolated VM with full development environment.
  • Setup: Execute jules-setup.sh in repository root to configure VM.
  • Governance: All actions must align with SDLC Protocol and Data Fabric.
  • Logging: All autonomous actions must be logged to jules.log.

Jules Capabilities

  1. Multi-File Refactoring: Can execute complex refactoring across files
  2. Test Execution: Runs full test suites with detailed reporting
  3. Build Pipelines: Executes complete CI/CD pipelines locally
  4. Dependency Updates: Handles dependency upgrades with testing

Jules Constraints

  • Must read AGENTS.md before any operation
  • Must follow RED-GREEN-REFACTOR cycle
  • Must create checkpoint before destructive operations
  • Must report status back to orchestration hub

/@jules

<@sdlc>

PROJECT EXECUTION SUCCESS (SDLC)

  1. Design: Review rules/03-data-fabric.md for schema requirements.
  2. Test: Write a failing test in the appropriate test suite.
  3. Implement: Write Rust code to satisfy the test.
  4. Nix: Add/update default.nix for new agents.
  5. Document: Ensure ai-agent-docs (Scalar/Swagger) can parse your new endpoints.
  6. Review: Submit PR with proper documentation and test coverage.
  7. Cache: CI will push to Attic/R2 automatically on merge.

Quality Gates

  • All tests pass (nix flake check)
  • Unit test coverage is at least 75% for changed components
  • No clippy warnings (cargo clippy -- -D warnings)
  • Code formatted (cargo fmt --check)
  • Nix build succeeds (nix build .#agent-name)
  • Documentation updated
  • OpenAPI spec generated
  • Security scan clean
  • Runtime Purity Check (uv/bun enforcement)
  • Absolute Path Leak Scan (no local user paths like /Users/ or /home/ leaked)

Required Files for New Agents

ai-agents/ai-agent-{name}/
├── Cargo.toml          # Rust package manifest
├── default.nix         # Nix derivation (uses crane)
├── src/
│   └── main.rs         # Entry point
└── README.md           # Agent documentation

/@sdlc

📂 Unified Agent Map (Symlink Targets)

Because of the Symlinking and Tagging, your repository now looks like this to the agents:

Agent / IDE Native Path File Type Behavior
Swarm SSOT /GEMINI.md File Single Source of Truth for all agent guidance.
Claude /CLAUDE.md Symlink Reads the <@architect> and <@all> tags.
Codex /AGENTS.md Symlink Reads the <@codex> and <@all> tags.
Cursor /.cursor/rules/governance.mdc Symlink Reads the <@builder> and <@all> tags.
Copilot /.github/copilot-instructions.md Symlink Reads the <@copilot> tag.
Antigravity /.agent/rules/orchestration.md Symlink Reads the whole manifest for autonomous planning.
Agent Guides /ai-agents/.../AGENTS.md Symlink Mirror for the generator agent.

🚀 Benefits of this "Single-File Symlink" Model

  1. Zero Context Drift: You never have to remember to update Claude vs. Cursor. Update one file, and the whole swarm knows.
  2. Tag Parsing: AI Agents are excellent at "Section Filtering." By using <@tag> markers, they ignore irrelevant instructions while adhering to the core Data Fabric.
  3. Rust Speed: The Rust tool handles the directory scaffolding and symlink creation in milliseconds.
  4. Automatic Sync: Edit the master file once, and all agents see changes instantly via symlinks.

This manifest is the Single Source of Truth for all AI agent guidance. Edit only this file; symlinks propagate changes to all agents automatically. Run `cargo run --manifest-path ai-agents/ai-agent-agent-guides/Cargo.toml -- sync` to update symlinks.