Imported from a-uror/AgentBridge (.bob/rules-advanced/AGENTS.md). Install upstream with npx skills add a-uror/AgentBridge --skill rules-advanced. Copyright stays with the author.

AGENTS.md

This file provides guidance to agents when working with code in this repository.

Advanced Mode Capabilities

• Full access to MCP and Browser tools (unlike Code mode)

Critical Non-Obvious Patterns

Port Configuration

• agent-service runs on 8081 (NOT 8080) - changed due to Apache httpd conflict on Windows
• Update vite.config.ts proxy if port changes

Maven Build Gotchas

• XML comments cannot contain --- (three dashes) - Maven parser fails
• scanner module MUST build before mcp-server (hidden dependency)
• Child POMs inherit BOM from parent - DO NOT duplicate <dependencyManagement> sections
• enterprise-service uses Quarkus 3.9.5, agent-service uses 3.15.2 (intentional version mismatch)

Quarkus 3.x Specifics

• Use quarkus-rest-jackson NOT quarkus-resteasy-reactive-jackson (naming changed in 3.9+)
• LangChain4j 0.26.1 uses max-tokens NOT max-new-tokens (API breaking change)
• Hot reload works for Java code, NOT for application.properties changes
• Default watsonx timeout (10s) too aggressive - set to 60s for cold-start completions

Database Patterns

• H2 table name is Orders not Order (SQL reserved word workaround)
• @Version field REQUIRED on Order entity (optimistic locking for cancel endpoint)
• Panache uses static finders on entity classes (NOT separate repositories)

Testing

• Integration tests require -Dintegration.tests=true flag (see @EnabledIfSystemProperty)
• Unit tests use reflection to inject mocks (see OrderToolsTest.inject())
• Run single test: mvn test -pl agent-service -Dtest=OrderToolsTest#listOrdersCallsMcpServer

Liberty WAR Deployment

• MUST have beans.xml in WEB-INF/ or deployment fails with "headRegion must not be null"
• Liberty takes ~30 seconds to start (vs Quarkus ~5 seconds)

Bob Sandbox Security

• Bob validates action BEFORE calling API (see BobSandbox.validateAction())
• Allowed actions: create, update, remove, fix, test, refactor (case-insensitive)
• Sandbox root defaults to enterprise-service/src (configurable via PROJECT_ROOT env var)

Service-to-Service Auth

• MCP server expects Authorization: Bearer <token> header from agent-service
• enterprise-service expects X-Service-Token header from mcp-server
• Both default to demo-service-token for dev (override with MCP_SERVICE_TOKEN env var)

Frontend Specifics

• Vite proxy at vite.config.ts:22 routes /api to 8081, /mcp to 9080
• Chat history persists in localStorage via useChat hook
• Session ID generated per-tab in useSessionId for agent memory isolation