# AGENT.md

This file defines operational guidance for contributors and coding agents in this repository.

## Scope

Default scope is `stockflow/` and root config related to it.

Work primarily in:

- `stockflow/`
- root orchestration/config files used by Stockflow

Do not edit `temporal/` or `bpm_engine/` unless explicitly requested.

## What This Repo Contains

- `stockflow`: Express + TypeScript API with YAML-driven runtime orchestration, Drizzle ORM, PostgreSQL RLS propagation, and MCP tool exposure.

## Product Intent

- Primary idea: users write YAML; Stockflow executes it.
- Database flow: users create tables, run `npm run db:generate`, then use DB operations from YAML runtime steps.
- Inspiration: Kestra + Supabase patterns.
- Security motivation: provide tighter workflow/runtime control for cases where direct Supabase usage is a concern.

## Practical Rules

- Keep changes minimal and local to requested feature/fix.
- Respect YAML runtime conventions in `stockflow/data/functions`.
- Preserve the database-first workflow in docs and examples.
- Keep query/filter semantics compatible in `stockflow/src/helper/query.model.ts`.
- Preserve RLS claim handling in `stockflow/src/middleware/rls.ts` and `withDb.ts`.
- Avoid introducing secrets in committed files.
- Prefer updating docs when behavior changes.

## Stockflow Reference

- API entry: `stockflow/src/index.ts`
- Runtime executor: `stockflow/src/runtime/index.ts`
- System functions: `stockflow/src/runtime/system-functions.ts`
- YAML loader + template resolver: `stockflow/src/helper/yaml.loader.ts`
- DB schema: `stockflow/src/db/schema.ts`
- MCP registration from YAML files where `skill: true`: `stockflow/src/mcp/index.ts`

## Recommended Verification

Run checks relevant to touched area:

```bash
# Stockflow
cd stockflow && npm run db:generate && npm run build
```

If you cannot run validations, state what was not run and why.