gizmoduck/AGENTS.md

Contributor instructions

Before substantive work, read product scope, architecture, data policy, and roadmap. This file is the authoritative agent entry point.

Binding decisions

• Gizmoduck is the clean successor to Robopato.
• Use Python, Django, PostgreSQL, migrations from the beginning, Docker Compose for local infrastructure, and pytest for automated tests.
• Import bank accounts from CSV and Banco do Brasil/Ourocard credit cards from TXT. OFX is not supported.
• Keep parsing, normalization, validation, duplicate detection, preview, and persistence separate.
• Obtain owner approval before changing these constraints or product scope.

Working rules

• Preserve user changes and avoid unrelated edits.
• Make small, cohesive changes with verification appropriate to their risk.
• Use isolated Git worktrees for concurrent implementation that could overlap.
• Design and plan substantial subsystems before implementing them.
• Report assumptions, checks performed, and unresolved risks accurately.
• Do not perform destructive operations, pushes, merges, releases, or history rewrites without explicit authorization.
• Focused local commits are allowed after verification. Inspect both staged paths and staged content for real financial data and secrets before every commit. When uncertain whether data is safe, stop and ask the owner.
• Agent-authored commits use repository-local Codex <codex@localhost>; human-authored commits retain the human contributor's identity.

Financial data

Agents may read every file in Robopato and copy real documents for local development, parser validation, migration, and compatibility testing. Store real data only in ignored local directories or local databases. Never commit raw data, identifying excerpts, snapshots, logs, screenshots, reports, or dumps. Committed fixtures must be synthetic or irreversibly sanitized. Follow the full data policy before handling source documents.