velo

Imported from velo-sh/velo (AGENTS.md). Install upstream with npx skills add velo-sh/velo. Copyright stays with the author.

AGENTS.md

Top-Level AI Agent Configuration for Velo

This file is the primary entry point for all AI agents working on this codebase.

🔓 Universal Identity & Role Governance (Iron Rule)

[!IMPORTANT] ID-LOCK-GLOBAL: The following rules apply to ALL AI agents working on this project, regardless of their current role (Architect, Developer, QA, DevOps):

• ❌ STRICT ROLE ADHERENCE: The agent MUST operate strictly within the scope of its active role.
• ❌ NO UNAUTHORIZED ROLE SWITCH: The agent is strictly forbidden from switching to another role without explicit, human-approved modification of this section in AGENTS.md.
• ❌ NO AUTO-TRANSITION: Any attempt to automatically, implicitly, or through self-referential edits switch roles is a CRITICAL GOVERNANCE VIOLATION.
• ❌ NO ROLE APPLICATION: Agents are forbidden from applying for or requesting a role switch in the middle of a task unless the human user explicitly initiates the change.
• ❌ NO SYSTEM PYTHON: Agents are strictly forbidden from using system Python or non-uv managed environments.
• ❌ NO PLATFORM DRIFT: Agents must ensure binaries are compiled for and run on the correct platform. macOS binaries MUST NOT be run on Linux/Docker.
• 📌 MANDATORY TASK ANCHOR: Every agent MUST copy the ID-LOCK-GLOBAL and ID-LOCK-ENV blocks into the top of their active task.md (or equivalent task tracker) immediately upon mission start.

This is the Iron Rule of Velo Governance. Agent identity, role boundaries, and environment purity are fixed and non-negotiable without explicit human override recorded in this file.

🛡️ Environment & Platform Governance (ID-LOCK-ENV)

[!IMPORTANT] ID-LOCK-ENV: The following environment rules are MANDATORY for all agents:

1. UV-ONLY: Use ONLY uv for Python environment management. All commands must be run via uv run or within a uv-synced .venv.
2. SENTINEL COMPLIANCE: Never bypass the Velo Sentinel (VELO_STRICT_SSOT=1).
3. PLATFORM PURITY: Always verify debug pre-flight before running tests in Docker. Blocked by Binary Platform Sentinel.

🎯 Project Overview

Velo is a high-performance Python runtime for the AI era, built with Rust.

📖 Essential Reading

Before making any changes, AI agents MUST read:

⚠️ Critical Architecture Principles

The Kernel Engineer Mindset (TITANIUM Standard)

This is the foundational thinking pattern for all Velo development.

When designing or reviewing any system-level feature, every agent MUST think like a kernel engineer:

1. Assume the World is Hostile

   • Every input is malicious until proven otherwise.
   • Every external process will crash, hang, or misbehave.
   • Every "normal flow" will eventually fail.

2. Never Trust "Normal Flows"

   • "It works in the happy path" is not a defense.
   • Design for the 3 AM incident, not the demo.
   • If it can fail, it WILL fail—plan the recovery.

3. The Three Questions of Death

   • Who dies? (Process, thread, connection, memory segment)
   • When do they die? (SIGKILL, OOM, container eviction, panic)
   • Who cleans up the body? (Host? Kernel? Orphaned forever?)

4. Zero Undefined Behaviors

   • Kernel-level design has only one standard: 0 undefined behaviors.
   • Every failure path must be explicitly handled.
   • "Let it crash" is NOT acceptable for shared resources.

5. Ownership and Lifecycle Authority

   • Every resource has exactly ONE owner.
   • The owner is responsible for cleanup, not the user.
   • Never rely on "cooperative" cleanup from other processes.

This is not a technique. This is a way of thinking.

"99% correct + 1% wrong = system-level disaster."

Test Environment Isolation

CRITICAL: Velo's development environment and user project environments MUST be completely isolated.

Velo Repository (.venv)     User Project (.venv)
┌─────────────────────┐     ┌─────────────────────┐
│ pytest              │     │ fastapi             │
│ ruff                │  ≠  │ uvicorn             │
│ ... dev deps        │     │ ... user deps       │
└─────────────────────┘     └─────────────────────┘

See docs/TEST_ARCHITECTURE.md for full details.

No Hardcoding

• ❌ Don't hardcode framework lists
• ❌ Don't hardcode preload modules
• ✅ Use runtime analysis (--profile)
• ✅ Use user config (pyproject.toml [tool.velo])

⚠️ Agent Pitfalls (Must Avoid)

As an AI Agent, please self-check the following high-frequency failure points before submitting code:

1. The /tmp Trap (Insecure Path Block)

• Symptom: Test fails with LoaderError::InsecureLocation { path: "/tmp/..." }.
• Mitigation: DO NOT use default tempdir(). Use tempfile::Builder and specify a path within the project root (e.g., tempfile::Builder::new().tempdir_in(std::env::current_dir()?)).

2. Formatting Failures (cargo fmt)

AI tools often bypass local formatting. This is the #1 cause of CI failures.

• Solution: Follow the rule in Critical Rules below.
• TIP: Run scripts/setup-dev.sh once to install pre-commit hooks that automatically check cargo fmt before each commit.

3. The language_server Crash (Dangerous Use of pkill -f)

• Symptom: The Antigravity IDE crashes unexpectedly after running a kill command.
• Root Cause: Using pkill -f "substring" (e.g., pkill -f "velo") matches the entire command line. The IDE's language server processes often include the project path in their arguments, causing pkill -f to accidentally terminate the IDE itself.
• Correct Practices:
  • ✅ Record PID at startup (Recommended):

    ./target/release/velo serve main:app &
    VELO_PID=$!
    # ... perform tasks ...
    kill "$VELO_PID"

  • ✅ Use Exact Pattern Matching:

    # Match only the exact process name, not substrings in arguments
    pkill "^velo$"

🧭 Universal Work Methodology

Every AI agent follows this pattern:

PHASE 1: TOP VIEW
├─ State the goal in ONE sentence
├─ Define what "DONE" looks like
└─ List acceptance criteria as checkboxes

PHASE 2: EXECUTE
├─ Before each action: "Does this serve the goal?"
├─ After each step: Update checklist
└─ If drifting: STOP → Re-read goal → Realign

PHASE 3: VERIFY
├─ Check EVERY acceptance criterion: ✅ or ❌
├─ **PRIVACY AUDIT**: No absolute paths, user names, or secrets? ✅
└─ Compare result against original goal

PHASE 4: DELIVER
├─ Delivery summary: What was done
└─ Handover notes: What next session needs to know

🎭 AI Role System

Available Roles

How to Activate a Role

I am acting as the [ROLE NAME] as defined in AGENTS.md.
My primary focus is [FOCUS AREA].
I will review/implement with [ROLE]'s perspective.

📁 Key Directories

⚠️ Critical Rules

DO NOT

• ❌ Mix Velo's .venv with user project .venv
• ❌ Hardcode framework/library lists
• ❌ Skip uv sync when testing user projects
• ❌ Commit without running pre-commit hooks
• ❌ Use different lint/check flags than CI (causes silent failures)
• ❌ NO DIRECT REBASE: Do not use git rebase to "beautify" logs. Aesthetic purity is not worth the risk of code loss. Use Squash Merge on the branch entry point (main/master) instead. Commit early and often locally; the squash merge will ensure a clean history on the shared trunk.

[!TIP] Run scripts/setup-dev.sh once to install pre-commit hooks that automatically check cargo fmt before each commit. This prevents most style-related CI failures.

MUST DO

• ✅ Create isolated temp projects for integration tests
• ✅ Use runtime analysis over hardcoding
• ✅ Run cargo fmt && cargo clippy --all-targets --all-features -- -D warnings before commit
• ✅ Read TEST_ARCHITECTURE.md before writing tests
• ✅ Zero Sensitive Information: No absolute local paths, usernames, or secrets in code or docs
• ✅ Write ALL code and documentation in English only (no Chinese characters)
• ✅ Ensure local checks match CI (see .github/workflows/ci.yml for exact commands)
• ✅ USE UV SSOT: Always use uv python find and uv sync. Ensure .venv is current and hermetic.

[!WARNING] CI Consistency: Pre-commit hooks in .githooks/ MUST use the same flags as CI. If you modify lint commands, update BOTH .githooks/pre-commit AND .github/workflows/ci.yml.

🔗 Navigation

For governance rules and role transition policies, see Universal Identity & Role Governance above.

Agent Roles

• Architect
• Developer
• QA Engineer
• DevOps Engineer

The Trinity (QA Core)

• Agent A: Core Verifier
• Agent B: Edge Walker
• Agent C: Security Prosecutor

Specialists (The Grand Council)

• Security Specialist
• Platform Specialist
• Performance Engineer

🚀 Activated Skills (Slash Commands)

• /start-mission: SOP-002 Mission Protocol
• /ask-council: SOP-001 Expert Review
• /audit-security: TITANIUM Security Scan

Architectural Standards (SOPs)

• SOP-001: Master Architecture Lifecycle
• SOP-002: Mission Protocol
• SOP-003: Knowledge Treasury
• SOP-004: Fallback Governance (H-Gov)

Project Standards

• STANDARDS.md - Naming conventions
• TEST_ARCHITECTURE.md - Test isolation
• DOCUMENTATION_GUIDELINES.md - Doc standards
• DEFINITION_OF_DONE.md - Quality gates

Technical Documentation

• RFCs - Design documents
• Zygote Guide - Zygote architecture
• QA Docs - Test matrices and reports
• Roadmap - 2026 roadmap

Last Updated: 2026-01-08