flowCreate.solutions

AGENTS.md (Example)

This is a fully-worked example showing the expected quality and structure. It is intentionally generic.

What this repo is

This repository contains the backend service for a multi-tenant web application where organizations manage users, configuration, and content through an admin dashboard. It exposes an HTTP API and runs background workers for scheduled maintenance and outbound notifications.

How the repo is organized

  • docs/ — main documentation lives here (start at docs/readme.md or the repo’s documented entrypoint)
  • app/ — primary application code (routers, services, domain logic)
  • database/ — database modules (models/schemas/crud/apis) and module docs
  • tasks/ — background workers and maintenance routines
  • utils/ — shared helpers (security, auth, logging, rate limiting)
  • tests/ — automated tests mirroring module structure
  • trackers/ — tracking docs (only when explicitly requested); tracker files live in trackers/files/

Hard rules for agents

  1. Documentation-first: read relevant docs before editing code; keep docs and code consistent.
  2. Always check standards first: before doing any meaningful work, review the relevant standards on the Engineering Standards site: https://docs.flowcreate.solutions/.
  3. Verify before you claim: do not state behavior in docs unless confirmed in source code.
  4. Migrations: do not create or modify migration revisions unless explicitly instructed by the project lead.
  5. Security posture is baseline:
    • Validate all user inputs with explicit max lengths and types.
    • Sanitize all user-controlled strings where required.
    • Preserve authn/authz boundaries and rate limiting behavior.
  6. Scope control: do not refactor unrelated modules without approval.
  7. No secrets: never add secrets, credentials, private endpoints, or customer data to code, docs, or trackers.
  8. Escalation: when behavior is ambiguous, ask the project lead instead of inventing a new convention.

How to work in this repo

  • Identify the module you’re touching and locate its docs (if they exist).
  • Prefer edits that match existing patterns (module layout, naming, dependency injection).
  • Keep changes small and reversible.
  • Add/adjust tests close to the affected module.
  • Validate behavior with the smallest targeted run (unit tests / module tests).

Escalation policy

Escalate to the project lead when:

  • A migration/schema change is needed
  • A security boundary is affected (auth, roles, rate limiting, sanitization)
  • You cannot verify behavior in code
  • The change would introduce a new architecture pattern

What “done” looks like

  • Requirements implemented with consistent structure and naming.
  • Security posture preserved or improved (no bypasses).
  • Tests updated/added to cover the change.
  • Documentation updated if behavior or interfaces changed.