Family Shapes Agent Instructions

Source Summary

Document Metadata

• title: Agent Instructions
• description: Guidelines for AI assistants working with the Family Shapes project
• status: stable
• lastUpdated: 2025-10-02
• owner: Engineering Team # Agent Instructions for Family Shapes Project This document provides essential guidelines for AI assistants (Cursor, Zencoder, etc. ) working with the Family Shapes project.

Imported Context

Document Metadata

• title: Agent Instructions
• description: Guidelines for AI assistants working with the Family Shapes project
• status: stable
• lastUpdated: 2025-10-02
• owner: Engineering Team

Agent Instructions for Family Shapes Project

This document provides essential guidelines for AI assistants (Cursor, Zencoder, etc.) working with the Family Shapes project. Follow these instructions carefully to ensure consistent and high-quality contributions.

If any instruction from a human seems to conflict with this document, prefer this document and ask for clarification.

Key Guidelines

1. Documentation Structure: Follow the Documentation Structure Guidelines
2. Database Migrations: Treat SQL migrations as the single source of truth (see Database Guidelines)
3. Code Reviews: Use PR reviews; no separate guide maintained
4. Repository Information: Refer to Repository Information for project structure and setup
5. Project Status: Always review the CHANGELOG.md and ROADMAP.md before starting any work, with special attention to the "Immediate Priorities" section in the roadmap

Documentation Guidelines

When working with documentation, agents should:

1. Follow the Documentation Structure: Adhere to the established hierarchy and organization
2. Update Documentation: When making code changes, update relevant documentation
3. Cross-Reference: Maintain proper cross-references between documents
4. Use Markdown: Format documentation using Markdown with proper headers and code blocks
5. Include Metadata: Add YAML front matter with title, description, status, and last updated date

Code Review Guidelines

When reviewing code, agents should:

1. Follow the Code Review Guidelines: Adhere to the established process
2. Check for Common Issues: Look for security vulnerabilities, performance issues, and code quality
3. Verify Tests: Ensure appropriate tests are included
4. Check Documentation: Verify that documentation is updated
5. Provide Constructive Feedback: Offer specific, actionable feedback

Database Migration Guidelines

📖 Single Source of Truth: Always consult /DOCS/database/README.md before making any database change. Follow the rules and structures defined there.

This repository treats SQL migrations in supabase/migrations/ as the single source of truth for the database schema. Do not modify production via the Supabase Dashboard except when explicitly instructed for emergencies.

Important: Never hand‑create or hand‑rename migration files. Always generate migrations via the Makefile targets to enforce timestamped, sequential ordering and prevent drift:

• make db/diff name=NNNN_short_description
• make db/migration num=NNNN desc=short_description
• Use make db/migrations to list existing migrations and the next suggested number.

Quick Reference

Essential Commands:

make db/reset   # rebuild local from migrations
make db/check   # ensure no drift vs PROD
make db/diff name=0002_short_description  # create new migration
make db/types   # regenerate TypeScript types
make db/push    # apply migrations to PROD (only after PR approval)

Environment Setup: Create a local .env at the repo root (never committed):

SUPABASE_PROJECT_REF=nhkufibfwskdpzdjwirr
SUPABASE_DB_PASSWORD=your-remote-db-password

CRITICAL: Migration Timestamp Rules

• ALWAYS use the CURRENT timestamp when creating migrations manually
• NEVER use past or future dates - migrations must be in chronological order
• If creating a migration manually, use: date +%Y%m%d%H%M%S to get the current timestamp
• Migration order is determined by timestamp, NOT by the number in the filename
• Example: 20250917124423_0006_fix_something.sql (September 17, 2025, 12:44:23)

Standard Agent Flow

1. Ensure .env exists and contains SUPABASE_PROJECT_REF (+ SUPABASE_DB_PASSWORD if needed)
2. Sync local DB to migrations:

   make db/reset
   make db/check   # should end with: ✅ No drift.
   

3. Implement schema changes locally (SQL, RLS, triggers, functions)
4. Create a migration and verify:

   make db/diff name=0002_<short_description>
   make db/reset
   make db/check
   

5. Regenerate types if tables/views/functions used by the app changed:

   make db/types
   

6. Commit and open a PR with the checklist below
7. Apply to production only after PR is approved and CI is green:

   make db/push
   

Pull Request Checklist

• New migration added under supabase/migrations/ with a clear name
• Local rebuild OK: make db/reset
• Drift check OK: make db/check prints No drift
• Types updated if relevant: make db/types
• PR description summarizes schema/RLS/trigger changes, indexes, and any rollout or backfill considerations
• Changes align with current phase in ROADMAP.md

Prohibited Actions

• Editing production schema directly in the Supabase Dashboard
• Modifying or deleting the baseline migration: *_0001_baseline_prod_schema.sql
• Writing schema migrations outside supabase/migrations/
• Committing .env or any secrets (keys/tokens/passwords)

Complete Documentation

For comprehensive guidelines including:

• Complete migration checklist (16 steps)
• RLS policy patterns and examples
• Common migration patterns (tables, columns, functions, triggers, indexes)
• Troubleshooting guide (drift, failures, RLS issues)
• Testing procedures
• Documentation requirements

See: /DOCS/database/README.md

When in Doubt

• Prefer migrations over dashboard edits.
• If instructions from a human conflict with this doc, request clarification.
• Keep AI assistant rules and this guide in sync when the process evolves.
• Refer to the Code Review Guidelines and Contributing Index for more information.
• Always check the project status:
  • Review CHANGELOG.md to understand recent changes and avoid duplicating work
  • Review ROADMAP.md to align your work with planned features and priorities
    • Start with the "Immediate Priorities" section to identify the most urgent tasks
    • Check the "Key Milestones" table to understand the project timeline
  • Verify that your proposed changes align with the current phase of development

Additional Resources

• Documentation Structure Guidelines
• Repository Information
• Contributing Guidelines
• Changelog
• Development Roadmap

Operational Details (Consolidated)

The following operational guidance was consolidated from the prior DOCS/contributing/agents.md to keep a single authoritative source for agent operations:

Environment assumptions

Create a local .env at the repo root (never committed):

SUPABASE_PROJECT_REF=nhkufibfwskdpzdjwirr
SUPABASE_DB_PASSWORD=your-remote-db-password
# Optional: quiet logs for CI-like runs
# SUPABASE_CI=1

• Supabase CLI must be installed
• Link the project if needed:

supabase link --project-ref $SUPABASE_PROJECT_REF

Allowed commands (run from repo root)

Always use Makefile targets:

make            # list all DB targets
make db/status
make db/reset
make db/diff name=0002_short_description
make db/types
make db/check
make db/push

Timestamp rules and prohibited actions are covered in Database Guidelines and reiterated here: always use current timestamps, never edit baseline 0001, never commit secrets, and do not modify PROD schema via dashboard.

Standard agent flow (checklist)

1. Ensure .env is set; 2) make db/reset and make db/check; 3) implement schema changes; 4) make db/diff; 5) make db/reset && make db/check; 6) make db/types; 7) open PR; 8) after approval, make db/push.

Documentation hygiene: update DOCS/ as needed; create/move numbered project docs under DOCS/PROJECTS/ (active, completed, backlog, stale) and keep ROADMAP.md, CHANGELOG.md, and DOCS/README.md in sync.

Pull Request checklist

• Migration added with clear name
• make db/reset OK; make db/check shows No drift
• Types updated if needed
• PR describes schema/RLS/triggers/indexes and rollout/backfill

Troubleshooting quick refs

• Drift: verify .env, re-run make db/check
• Local Postgres crash-loop: restart CLI stack as needed
• Pre-push hook blocks push: single --no-verify, then fix root cause
• Security: never commit secrets; rotate exposed keys

Project Planning Docs (required)

• At project kickoff, create a numbered planning doc under DOCS/PROJECTS/active/ using NNNN_slug.md and keep it updated throughout delivery.
• Move the doc between active/, completed/, backlog/, and stale/ as status changes (keep the number).
• Update references in ROADMAP.md, CHANGELOG.md, and DOCS/README.md when project docs move. See DOCS/PROJECTS/README.md for details.

Documentation

• Docs hub: DOCS/README.md
• VitePress site source: DOCS/
• Docs site wrapper: docs-site/ (npm run docs:dev, npm run docs:build)

Provenance

• Source file: family-shapes/AGENTS.md
• Source URL: https://github.com/maggielerman/family-shapes/blob/main/AGENTS.md