Skip to content

SKILL.md

Latest commit

 

History

History
88 lines (62 loc) · 2.89 KB

SKILL.md

File metadata and controls

88 lines (62 loc) · 2.89 KB
name stockflow-yaml-runtime
description Use this skill when working on Stockflow's YAML-first execution model. Focus on user-authored YAML workflows, database-first setup, db:generate flow, and secure runtime behavior. Exclude temporal/ and bpm_engine/ unless explicitly requested.

Scope

This skill is for /home/shakir/projects/autobizt/supabase and focuses on stockflow/.

Primary targets:

  • stockflow/
  • root infra files related to Stockflow (docker-compose.yml, .env, config/)

Do not modify temporal/ or bpm_engine/ unless the user explicitly overrides this skill scope.

Product Context

  • Stockflow is inspired by Kestra and Supabase.
  • The core idea is YAML-driven backend execution.
  • Design intent includes tighter control for security-sensitive workflows.

Project Map

Stockflow

  • API entry: stockflow/src/index.ts
  • Runtime executor: stockflow/src/runtime/index.ts
  • Built-in runtime functions: stockflow/src/runtime/system-functions.ts
  • YAML loader/template resolver: stockflow/src/helper/yaml.loader.ts
  • Query compiler: stockflow/src/helper/query.model.ts
  • DB + schema: stockflow/src/db/index.ts, stockflow/src/db/schema.ts
  • RLS middleware: stockflow/src/middleware/withDb.ts, stockflow/src/middleware/rls.ts
  • YAML functions: stockflow/data/functions/**/*.yml
  • MCP tool bootstrap: stockflow/src/mcp/index.ts

Workflows

Standard user flow

  1. User creates/updates PostgreSQL tables.
  2. User runs npm run db:generate inside stockflow/.
  3. User writes YAML functions for business operations.
  4. Runtime executes YAML through /api/rpc.

Add or update YAML function

  1. Edit or add file in stockflow/data/functions/.
  2. Define params, steps, and return.
  3. Use supported step types only: call, map, editField, reference, query, persist, condition, loop.
  4. If function should appear as MCP tool, set:
    • skill: true
    • title: "<tool title>"
  5. Validate that called system functions exist in system-functions.ts.

Add runtime capability

  1. Add implementation in stockflow/src/runtime/system-functions.ts.
  2. Ensure function is deterministic and handles malformed inputs safely.
  3. Wire YAML calls with type: call and function: <name>.

Extend query behavior

  1. Update stockflow/src/helper/query.model.ts.
  2. Keep filter/search/having semantics backward compatible.
  3. Verify sort/populate behavior for nested tables.

Validation Checklist

After edits, run only relevant checks:

Stockflow

cd stockflow
npm run db:generate
npm run build

If DB-dependent checks cannot run (environment missing), report explicitly.

Constraints and Safety

  • Exclude temporal/ by default.
  • Exclude bpm_engine/ by default.
  • Avoid changing generated migration snapshots unless migration work is requested.
  • Preserve RLS behavior in middleware and transaction contexts.
  • Never hardcode secrets in code or docs.