Instruction file imported from gskinnerTeam/flutter-hatcha-app (.github/instructions/.instructions.md). Copyright stays with the author.

Global Instructions: Dual-Project Integration & Isolation

You are working on a Flutter A2UI application at the root, using Python for the custom Agent located in the /agents directory. Follow all best practices mapped out in this and other instruction files.

If no instruction is found for a filetype, use the best practices laid out by Google developers, keeping the code clean and concise. This will be open-sourced, so clean, easy-to-read code is required.

1. Directory Boundaries & Logical Separation

• Flutter Client (Root & /lib): Primary UI. Architecture and patterns are defined in architecture.instructions.md.
• Python Agent (/agents): Custom Agent logic. Architecture rules also apply via architecture.instructions.md.

2. Flutter Development Standards (Root & /lib)

• Architecture: Core patterns, service locator globals, and conventions are defined in architecture.instructions.md (auto-loaded for lib/** and agents/**).
• Catalogue Items: Use the catalogue-items skill when creating or modifying GenUI catalogue item files (5-step convention, naming, example data, widget patterns).
• GenUI Package: Use the genui skill when working with Conversation, Surface, Transport, SurfaceController, DataModel, DataContext, data binding, A2uiSchemas, CatalogItemContext API, or the A2UI message protocol.
• GenUI A2A Package: Use the genui-a2a skill when working with A2uiAgentConnector, A2AClient, A2A protocol, SSE transport, or agent cards.
• A2UI Agent SDK: Use the a2ui-agent-sdk skill when working with the Python a2ui package: A2uiSchemaManager, extension negotiation, DataPart helpers, streaming parsers, or SendA2uiToClientToolset.
• JSON Schema Builder: Use the json-schema-builder skill when building JSON schemas with S.object, S.string, S.list, etc., or working with schema validation.
• AI System: Use the ai-system skill when working with ControllerConfig, GeminiConversationConfig, Python agents, or system prompts.
• Theming: Use the theming skill when working with colors, typography, spacing, or design tokens. Access styles ONLY via context.styles and context.colors (BuildContext extensions).
• Figma Import & Implement: Use the figma-import skill when importing, implementing, or building UI from Figma designs, links, or nodes. Covers the full workflow from URL parsing through design token mapping to validation.
• Figma Use: Use the figma-use skill when creating, editing, or deleting nodes inside Figma itself via the Plugin API (use_figma tool).

3. Python Agent Standards (/agents)

• Use these rules ONLY when the active file is within the /agents directory.
• Follow the Agent Development Kit (ADK) best practices.
• Ensure all Python-generated JSON remains strictly compatible with the schemas defined in the Flutter catalogue.