Add AGENTS.md file

Author: mheadd

AGENTS.md

@@ -0,0 +1,172 @@
+# AGENTS.md
+
+## Project Overview
+
+This is a secure-by-design template for building LLM-powered agents in Node.js + TypeScript. The template enforces security patterns to resist prompt injection, privilege escalation, and unsafe tool use through:
+
+- **Dual LLM isolation** - separating untrusted text processing from tool execution
+- **Quarantined Readers** - convert raw text to strict JSON schemas without tool access
+- **Orchestrator/Reducers** - process sanitized data and handle tool execution
+- **Context minimization** - strips prompts/raw data before tool use
+- **Sandboxed execution** - tests run in network-isolated Docker containers
+
+## Setup Commands
+
+- Install dependencies: `npm ci`
+- Type checking: `npm run typecheck`
+- Linting: `npm run lint`
+- Format code: `npm run format`
+- Run tests: `npm test`
+- Watch tests: `npm run test:watch`
+
+## Security Validation Commands
+
+- Validate schemas: `npm run secure:schemas`
+- Validate file paths: `npm run secure:paths`
+- Run full CI locally: Use VS Code task "Secure Agents: Run CI Test (local container)"
+
+## Code Style Guidelines
+
+- **TypeScript strict mode** - all code must pass strict type checking
+- **ESLint rules** - enforced via `eslint.config.js` with TypeScript ESLint plugin
+- **Prettier formatting** - consistent code formatting
+- **No explicit `any` types** - use proper typing (warns on `any`)
+- **ES modules** - use `import/export` syntax (type: "module" in package.json)
+
+## Architecture Patterns
+
+### Required Security Patterns
+
+1. **Plan → Patch workflow**:
+   - Always create a PLAN (YAML) in `plans/` directory first
+   - Then implement matching code changes
+   - Plans must specify trust boundaries and tool scope
+
+2. **Agent Structure**:
+
+   ```
+   agents/<agent-name>/
+   ├── reader/
+   │   └── index.ts      # Quarantined reader (no tools, outputs JSON schema)
+   └── orchestrator/
+       └── reducer.ts    # Orchestrator/reducer (can use tools)
+   ```
+
+3. **Trust Boundaries**:
+   - Readers: see raw untrusted text, output only structured JSON
+   - Orchestrators: consume sanitized JSON, may call tools
+   - No free text pass-through between layers
+
+## Testing Instructions
+
+- **Test structure**: `tests/<agent-name>/<agent-name>.test.ts`
+- **Required tests**:
+  - Reader always produces valid schema (never leaks raw text)
+  - Orchestrator handles sanitized inputs correctly
+  - Adversarial prompts don't break the pipeline
+- **Test runner**: Vitest with TypeScript support
+- **Network isolation**: All CI tests run in Docker with `--network=none`
+
+## File Organization
+
+```
+/
+├── agents/           # Agent implementations
+├── plans/           # YAML plan definitions
+├── schemas/         # JSON schemas for validation
+├── tests/           # Test files matching agent structure
+├── scripts/         # Validation and CI scripts
+└── .github/         # CI/CD workflows and Docker configs
+```
+
+## Security Considerations
+
+### Path Restrictions
+
+The following paths require `security-approved` label on PRs:
+
+- `.github/workflows/`
+- `.github/actions/`
+- `.github/docker/`
+- `infra/`
+- `deploy/`
+- `scripts/prod/`
+- Lock files (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`)
+
+### Allowed Development Paths
+
+- `agents/` - agent implementations
+- `tests/` - test files
+- `plans/` - agent plans
+- `schemas/` - validation schemas
+- `scripts/` - development scripts (non-production)
+
+## CI/CD Pipeline
+
+### GitHub Actions Workflow
+
+1. **Path validation** - ensures only approved paths are modified
+2. **Schema validation** - validates YAML plans and JSON schemas
+3. **Isolated testing** - runs in Docker with no network access
+
+### Local Development
+
+- Use VS Code tasks for validation
+- Pre-commit hooks validate schemas and paths
+- Docker-based CI can be run locally
+
+## Adding New Agents
+
+1. **Create plan**: `plans/<agent-name>.yml` with security patterns defined
+2. **Validate plan**: `npm run secure:schemas`
+3. **Implement reader**: `agents/<agent-name>/reader/index.ts` (no tools)
+4. **Implement orchestrator**: `agents/<agent-name>/orchestrator/reducer.ts` (tools allowed)
+5. **Add tests**: `tests/<agent-name>/<agent-name>.test.ts`
+6. **Validate paths**: `npm run secure:paths`
+7. **Run full test suite**: `npm test`
+
+## Common Patterns
+
+### Reader Implementation
+
+```typescript
+// Convert untrusted text to bounded schema - NO TOOLS
+export function processRawText(input: string): StructuredOutput {
+  // Parse and validate against strict schema
+  // Never pass through free text
+  return {
+    /* structured data only */
+  };
+}
+```
+
+### Orchestrator Implementation
+
+```typescript
+// Process sanitized inputs - TOOLS ALLOWED
+export function orchestrate(sanitizedInputs: StructuredOutput[]): Result {
+  // Can call external APIs, file system, etc.
+  // Context has been minimized and sanitized
+  return processWithTools(sanitizedInputs);
+}
+```
+
+## Troubleshooting
+
+### Docker Build Issues
+
+- Check Node.js/npm compatibility in `.github/docker/ci.Dockerfile`
+- Ensure ESLint version compatibility with TypeScript ESLint plugins
+- Python packages may need `--break-system-packages` flag
+
+### Schema Validation Failures
+
+- Ensure YAML plans follow `schemas/plan.schema.json`
+- Check that all required fields are present
+- Validate JSON syntax and structure
+
+### Path Validation Failures
+
+- Check if modified files are in restricted paths
+- Add `security-approved` label for infrastructure changes
+- Ensure new files follow approved directory structure