AGENTS.md (Template)

Copy this file into the project root as AGENTS.md and customize the placeholders.

---

What this repo is

<One paragraph describing what the repository is and the service(s) it contains.>

How the repo is organized

High-level module map:

• <dir>/ —
• <dir>/ —
• docs/ — main documentation lives here (required). Start at: <docs entrypoint file> (e.g. docs/readme.md or docs/index.md)
• docs/playbooks/git/workflow.md — Git/GitHub workflow (branches, worktrees, push/PR semantics, monorepo ↔ split repo sync)
• tests/ —
• trackers/ — tracking docs (only when explicitly requested)

Hard rules for agents

• Documentation-first: read the relevant docs before editing code.
• Always check standards first: before doing any meaningful work, review the relevant standards on the Engineering Standards site: https://docs.flowcreate.solutions/.
• Verify: confirm behavior against source code; don’t document guesses.
• Migrations: do not create/modify migration revisions unless explicitly instructed by the project lead.
• Security: follow validation/sanitization/authz/rate limiting standards; do not introduce bypasses.
• Scope: do not edit outside agreed directories without approval.
• Escalation: if ambiguous, ask the project lead rather than inventing a pattern.
• No secrets: never add secrets, credentials, or private URLs to code or docs.

How to work in this repo

• Start by locating the relevant module docs.
• Make the smallest safe change that satisfies requirements.
• Keep structure consistent with existing module patterns.
• Update or add tests that mirror module boundaries.
• Run the smallest targeted verification you can (unit tests, module tests).

Escalation policy

Escalate to the project lead when:

• behavior is ambiguous or undocumented
• a change touches security boundaries
• a migration/schema change is required
• the change would introduce a new pattern

What “done” looks like

• Code matches conventions and module structure.
• Security posture preserved (validation/sanitization/authz).
• Tests updated/added appropriately.
• Documentation updated if behavior changed.