# AGENTS

This is a **flowmo** project — an OutSystems prototyping environment with a local PostgreSQL database (PGLite).

## Quick reference

| You're asked to… | Load this skill | Use these tools |
|---|---|---|
| Work on queries, SQL, aggregates, advance SQL | `outsystems-sql` | `npx flowmo db:query`, `npx flowmo db:setup`, `npx flowmo db:seed` |
| Create or edit screens, UI, prototypes, visual HTML | `outsystems-ui` + `outsystems-product-ui` | `npm run dev`, `npm test` |
| Design screen logic, actions, expressions | `outsystems-logic` | (none — OutSystems patterns only) |
| Start dev server, preview screens in browser | `dev-workflow` | `npm run dev`, `npm run dev:agent` |
| Push validated work to a real OutSystems app, write/run a Mentor prompt, run a curated Mentor task (quality/security/perf/accessibility review, test generation, demo data, demo readiness) | `outsystems-mentor` | `mentor_start` / `mentor_get_run` (requires outsystems MCP) |
| Test the live app after a push — query its Dev DB, invoke actions, verify a change landed | `outsystems-live-testing` | `test_setup_start`, `db_query`, `exec_in_app` (requires outsystems MCP) |

## Standards (read when relevant)

| Standard | When to read |
|---|---|
| `docs/flowmo-query-testing-standard.md` | Before writing or testing any SQL query |
| `docs/outsystems-apps.md` | Before using the `outsystems` MCP tools — has asset/environment keys for the apps this project pushes to, so you don't have to search for them |

## Rules

1. **Always test queries** before declaring them done. Use:
   ```bash
   npx flowmo db:query database/sql/MyQuery.advance.sql --param Foo=bar --json --limit 50
   ```

2. **Always run the dev server** after creating or editing a screen. Use `npm run dev` and visually verify in the browser.

3. **Never edit `database/schema.os.sql`** — it's auto-generated by flowmo-forge from the live OutSystems schema. Local additions go in `database/schema.local.sql`.

4. **Follow the screen folder convention**: `screens/{ticket}-{name}/index.visual.html`

5. **Queries are tested via vitest** — each query file should have a matching test in `tests/`. Follow the pattern in `docs/flowmo-query-testing-standard.md`.

6. **Keep `docs/outsystems-apps.md` reconciled.** If the `outsystems` MCP is connected
   (`mcp__outsystems__*` tools present — it's early access, not every ODC environment has it):
   before relying on `docs/outsystems-apps.md`, or the first time you read it in a session,
   reconcile it against one `app_list`/`env_list` call scoped to the portfolio — add anything
   new, fix anything renamed, flag (don't silently delete) anything listed that no longer
   resolves. If a lookup keyed off an asset key in the doc comes back not-found, treat that as a
   stale-doc signal and re-discover via `app_list`/`context_*` search rather than treating it as
   a dead end. Record stable identifiers only (asset/environment keys, URLs) — never revision,
   deploy status, or health; fetch those live every time.

## Project structure

```
screens/{ticket}-{name}/     ← screen prototypes (index.visual.html + queries.js)
components/                  ← reusable components (layouts, widgets, business)
database/
  ├── schema.os.sql          ← OutSystems schema (via flowmo-forge — DO NOT EDIT)
  ├── schema.local.sql       ← local-only additions
  │                            (db:setup concatenates both in memory — no
  │                            schema.sql file is written to disk)
  └── sql/                   ← OutSystems Advanced SQL queries (*.advance.sql)
theme/                       ← CSS (outsystems-ui.css, grid.css, theme.css)
tests/                       ← vitest test files
docs/                        ← flowmo tooling documentation
```