ai_ops/AGENTS.md

Agent Instructions

Goals

• Keep runtime behavior explicit and predictable.
• Keep integration points documented when features are added.
• Enforce a consistent quality gate before merging changes.

Project Organization

• src/agents: session lifecycle, limits, resource provisioning, and schema-driven orchestration.
• src/mcp: MCP config types, conversion, and handler policy resolution.
• src/examples: provider-specific execution entrypoints.
• tests: focused unit tests for orchestration and config behavior.

Engineering Standards

• TypeScript strict mode stays enabled.
• Exported interfaces should be typed explicitly and validated at boundaries.
• New behavior should include at least one test if it changes control flow or config parsing.
• Avoid provider-specific policy in shared modules unless there is a clear extension point.
• When adding new runtime limits or resource constraints, ensure they are added to .env.example.

Runtime Environment Variables

• Agent manager limits:
  • AGENT_MAX_CONCURRENT
  • AGENT_MAX_SESSION
  • AGENT_MAX_RECURSIVE_DEPTH
• Orchestration/context limits:
  • AGENT_STATE_ROOT
  • AGENT_PROJECT_CONTEXT_PATH
  • AGENT_TOPOLOGY_MAX_DEPTH
  • AGENT_TOPOLOGY_MAX_RETRIES
  • AGENT_RELATIONSHIP_MAX_CHILDREN
  • AGENT_MERGE_CONFLICT_MAX_ATTEMPTS
• Provisioning/resource controls:
  • AGENT_WORKTREE_ROOT
  • AGENT_WORKTREE_BASE_REF
  • AGENT_WORKTREE_TARGET_PATH
  • AGENT_PORT_BASE
  • AGENT_PORT_BLOCK_SIZE
  • AGENT_PORT_BLOCK_COUNT
  • AGENT_PORT_PRIMARY_OFFSET
  • AGENT_PORT_LOCK_DIR
  • AGENT_DISCOVERY_FILE_RELATIVE_PATH
• Security middleware controls:
  • AGENT_SECURITY_VIOLATION_MODE
  • AGENT_SECURITY_ALLOWED_BINARIES
  • AGENT_SECURITY_COMMAND_TIMEOUT_MS
  • AGENT_SECURITY_AUDIT_LOG_PATH
  • AGENT_SECURITY_ENV_INHERIT
  • AGENT_SECURITY_ENV_SCRUB
  • AGENT_SECURITY_DROP_UID
  • AGENT_SECURITY_DROP_GID
• Runtime-injected resource context (provided by provisioning; do not set in .env):
  • AGENT_REPO_ROOT
  • AGENT_WORKTREE_PATH
  • AGENT_WORKTREE_BASE_REF
  • AGENT_PORT_RANGE_START
  • AGENT_PORT_RANGE_END
  • AGENT_PORT_PRIMARY
  • AGENT_DISCOVERY_FILE

Documentation Standards

• Update README.md for user-facing behavior.
• Update this file for any new environment variables related to agent context or limits.
• Add design/maintenance notes in docs/ for non-trivial architecture decisions.

Quality Gate

Run this before opening a PR:

npm run verify

Equivalent individual commands:

npm run check
npm run check:tests
npm run test
npm run build