# 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`
- Provisioning/resource controls:
  - `AGENT_WORKTREE_ROOT`
  - `AGENT_WORKTREE_BASE_REF`
  - `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`

## 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:

```bash
npm run verify
```

Equivalent individual commands:

```bash
npm run check
npm run check:tests
npm run test
npm run build
```