first commit

AGENTS.md

@@ -0,0 +1,61 @@
+# 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_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`
+
+## 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
+```