gizmoduck/docs/superpowers/specs/2026-09-06-agent-foundation-design.md

Gizmoduck Agent Foundation Design

Date: 2026-09-06
Status: Approved for planning

Purpose

Establish a small, durable set of documents that gives human and automated contributors a shared understanding of Gizmoduck before application code is written. The documents must make binding technical decisions, privacy boundaries, project scope, and agent behavior easy to discover.

Document structure

The agent foundation will use a layered structure:

• AGENTS.md is the concise, authoritative entry point for every agent.
• docs/product.md defines the product purpose, users, MVP, and exclusions.
• docs/architecture.md records binding technology choices and component boundaries.
• docs/data-policy.md governs access to and handling of real financial data.
• docs/roadmap.md orders the initial delivery milestones without becoming a task tracker.

The README remains the human-facing introduction and links to these documents once they exist. Detailed feature designs will be written separately rather than accumulated in AGENTS.md.

Binding project constraints

Until the owner explicitly approves a change, agents must treat the following as binding:

• The project is named Gizmoduck and is the clean successor to Robopato.
• The backend uses Python and Django.
• Persistent storage uses PostgreSQL with migrations from the beginning.
• Local infrastructure uses Docker Compose.
• Automated tests use pytest.
• Bank-account transactions are imported from CSV.
• Credit-card transactions are imported from Banco do Brasil/Ourocard TXT.
• OFX is not supported.
• Parsing, normalization, validation, duplicate detection, preview, and persistence remain separate stages.

Agents may identify risks or propose reconsideration, but they may not silently replace these choices while implementing unrelated work.

Robopato access and financial-data policy

Gizmoduck agents are authorized to read every file in the Robopato repository. They may copy real financial documents from Robopato for local development, parser validation, migration, and compatibility testing.

Real financial data must never be added to Git. This prohibition includes raw documents, database dumps, copied excerpts, test snapshots, logs, screenshots, generated reports, and documentation containing identifying transaction data. Real data may exist only in ignored local directories and local databases.

Committed tests must use synthetic data or data that has been irreversibly sanitized. Before every commit, agents must inspect staged paths and staged content for financial data and secrets. When uncertain whether data is safe, agents must stop and ask the owner.

Agent operating policy

Agents will:

• read AGENTS.md and its linked documents before substantive work;
• preserve user changes and avoid unrelated edits;
• clarify changes that would alter binding constraints or product scope;
• prefer small, cohesive changes with tests appropriate to their risk;
• use isolated Git worktrees for concurrent implementation that could overlap;
• report assumptions, verification performed, and unresolved risks; and
• avoid destructive operations, pushes, merges, releases, and history rewrites without explicit authorization.

Agents may create focused local commits after relevant verification succeeds. Agent-authored commits use a repository-local identity:

Codex <codex@localhost>

Human-authored commits retain the human contributor's own Git identity.

Verification

The documentation task is complete when:

• every planned document exists and links resolve;
• the README points readers to the agent and project documentation;
• constraints are consistent across all documents;
• no placeholders or unresolved policy choices remain;
• .gitignore protects the approved local-data locations and common secret and dump formats;
• sample checks confirm real-data paths are ignored while synthetic fixtures remain trackable; and
• Git reports Codex <codex@localhost> as the repository-local identity.

Deferred work

This foundation does not define the detailed financial domain model, database schema, UI, importer grammar, duplicate-detection algorithm, deployment model, or backup implementation. Each substantial subsystem will receive its own design and implementation plan before development.