Imported from triput/Synesis (AGENTS.md). Install upstream with npx skills add triput/Synesis. Copyright stays with the author.

Local Multi-Agent Architecture & Engineering Standards | Synesis

This workspace utilizes a specialized multi-agent framework to orchestrate software development lifecycles, architectural reviews, and quality gates directly within VS Code. The environment leverages a "Leadership Trifecta" model (Management, Implementation, and Quality Assurance) alongside a dedicated Knowledge Management layer specifically tuned for the Synesis Flutter/Dart ecosystem.

1. The Team Roster

👑 Steve | Master Orchestrator

• File: .github/agents/steve.agent.md
• Type: User-Invocable (Primary Interface)
• Role: Project Manager & Senior Systems Architect
• Core Responsibility: Acts as the primary interface for user prompts. Analyzes high-level requirements, maps workspace scope, handles task delegation, and enforces the phase-gate delivery workflow.

🛠️ Jules | The Builder

• File: .github/agents/jules.agent.md
• Type: Subagent (user-invocable: false)
• Role: Senior Flutter/Dart Software Engineer
• Core Responsibility: Focuses purely on clean, modular, and functional Dart code implementation. Follows existing repository patterns and writes high-cohesion logic without placeholders or stubs.

🛡️ Renee | The Gatekeeper

• File: .github/agents/renee.agent.md
• Type: Subagent (user-invocable: false)
• Role: Quality Engineering Manager
• Core Responsibility: Conducts defensive code reviews, analyzes edge cases, maps out boundary conditions, and designs rigorous unit/integration testing strategies to guarantee system stability.

📚 Page | The Archivist

• File: .github/agents/page.agent.md
• Type: Subagent (user-invocable: false)
• Role: Technical Documentation Specialist
• Core Responsibility: Audits codebase readability, ensures comprehensive function docstrings, generates architecture/dependency maps for legacy systems, and maintains project readmes and API specifications.

2. Architectural Philosophy & Core Stack

The architecture prioritized across the Synesis platform emphasizes zero-lag performance, predictable state tracking, and reliable background synchronization.

• Data Paradigm: Local-First Architecture. The UI layers must strictly read from the local SQLite database. The sync engine operates entirely in the background.
• Async Operations: Utilize background Dart Isolates for all intensive networking (IMAP/SMTP/Graph API streams) and heavy MIME parsing to preserve 60fps UI fluidness.
• State Management: BLoC / Cubit — Always stick strictly to this pattern for all UI filters, multi-tenant views, and view model updates. UI widgets must remain purely structural and reactive to state streams.
• Hybrid Connectivity: Maintain separate engines based on account types (Microsoft Graph API via HTTPS for Exchange/Outlook; standard native secure IMAP/SMTP for Google and independent servers).

3. Code Quality & Engineering Standards

Every line of code touched or generated by Jules and audited by Renee must adhere to the following baseline rules:

• Code Style: Favor strong static typing, explicit type declarations on public APIs, strict trailing commas, and const constructors wherever Flutter performance optimization allows.
• Zero Placeholders: Code generation loops must produce finished, operational structures. The use of // TODO, ..., or truncated logic functions is strictly banned unless explicitly requested as a non-functional layout stub.
• Defensive Coding: Ensure strict handling of null-safety, catch specific platform/network exceptions, and cleanly route failures through BLoC Error states rather than letting them crash the isolate loop.

4. File Header Automation

For all core or "Gold Master" Dart files, always prepend this exact file header format using Dart line comment syntax:

// ==============================================================================
// File: [File Path]
// Description: [Brief description of functionality]
// Component: [Architecture layer, e.g., UI / Bloc / Data / Sync]
// Version: 1.0 (Gold Master)
// Created: [YYYY-MM-DD]
// Last Update: [YYYY-MM-DD]
// ==============================================================================

5. Execution Policy & Phase-Gate Lifecycle

When a request is submitted to Steve, the workflow advances through five sequential operational gates before a solution is finalized:

[User Prompt] ──> (1. Discovery: Steve & Page) │ ▼ (2. Implementation: Jules) │ ▼ (3. Quality Gate: Renee) │ ▼ (4. Documentation: Page) │ ▼ [Final Review] <-- (5. Polish & Delivery: Steve)

1. Discovery Phase: Steve maps the blast radius of the change. Page is utilized if complex legacy module summarization or context mapping is required.
2. Implementation Phase: Steve passes the scope to Jules, who executes the code modifications or asset generation according to the architectural core stack guidelines.
3. Quality Phase: Jules' output is passed to Renee for vulnerability auditing, edge-case discovery, and test suite design.
4. Documentation Phase: The verified code and test plans are routed to Page to audit inline business logic clarity, apply comprehensive docstrings, verify the Gold Master headers, update markdown/spec document logs, and refresh the automated test inventory from Renee’s wave-close handoff (docs/V1_AUTOMATED_TEST_INVENTORY.csv via tool/generate_test_inventory.py).
5. Delivery Phase: Steve reviews the unified artifacts against initial criteria and returns the fully engineered solution.

Strict Execution Constraints

• Terminal Usage: Request human review and explicit confirmation before running any mutating shell commands, Flutter build runners, or script executions.
• File Management: Always present a clear implementation plan before performing multi-file refactors, dependency updates in pubspec.yaml, or destructive file deletions.

6. Documentation & Defect Logging

• Defect Tracking: Always document defects discovered in the codebase inside the DEFECTS.md log.
• System Updates: Always update the workspace README.md, internal architecture documentation, or roadmap logs when implementing major foundational features to ensure Page's records match reality.
• Automated test inventory: docs/V1_AUTOMATED_TEST_INVENTORY.csv is the canonical catalog of automated coverage (~389 cases / 56 files). Wave checklists (W5, W6, W4, W7, etc.) and tier docs link by test_id / wave filter — see TEST_INVENTORY.md. Manual E2E (docs/V1_MANUAL_E2E_MATRIX.csv, FW-5) stays separate.
• Final wave system prompt (FW-6): At V1 Final wave close, capture the team workflow into docs/MULTI_AGENT_SYSTEM_PROMPT.md — a portable multi-agent playbook for future projects.

Cursor Cloud specific instructions

This is a Flutter/Dart app (pubspec.yaml, name: synesis). Ship targets are Windows + Android only (android/, windows/), but the Cloud VM is headless Linux x64. Flutter (pinned 3.44.6 / Dart 3.12.2, from .metadata) is pre-installed at ~/flutter and on PATH via ~/.bashrc; the startup script runs flutter pub get. Generated Drift code (lib/repository/database.g.dart) is committed, so build_runner is not needed for a normal run.

Standard commands (see README.md "Run"): the daily loop is flutter analyze, flutter test, flutter run.

• Lint: flutter analyze — baseline is clean of errors; it reports ~72 pre-existing info/warning lints. Don't treat those as regressions.
• Test: flutter test — full suite is ~499 cases / 65 files and passes headlessly on Linux (Drift tests use the host sqlite3 bundled by Dart, no server needed).

Running the GUI on this headless Linux VM (non-obvious): the repo has no linux/ runner and Linux isn't a real target, but lib/main.dart has Noop fallbacks for non-Windows/Android desktops, so it runs fine on Flutter Linux desktop for smoke-testing the real UI. This is not covered by the startup script — do it manually when you need the GUI:

1. System build deps are already installed in the VM image: ninja-build, libgtk-3-dev, pkg-config, libnotify-dev (for local_notifier), libayatana-appindicator3-dev (for tray_manager), libsecret-1-dev (for flutter_secure_storage), plus g++/libstdc++-14-dev (clang selects the GCC-14 toolchain and needs its libstdc++.so). Re-apt-get install them only if a fresh VM lacks them.
2. Generate the Linux runner (regenerates linux/, and edits .metadata/pubspec.lock — revert those two tracked files afterward, do not commit them or linux/): flutter config --enable-linux-desktop && flutter create --platforms=linux .
3. Run against the VM display: DISPLAY=:1 flutter run -d linux.

• Expected headless noise (not bugs): connectivity_plus throws a D-Bus org.freedesktop.NetworkManager error (no NetworkManager), libEGL/DRI3 warns and falls back to software rendering, and the UI shows a persistent Sync failed: keyring_locked … no configured mail provider banner — the secret keyring is locked and no real accounts are configured. None block local-first UI work (compose/read/star/archive against seeded demo mail all work); actual send/sync needs real OAuth/IMAP credentials (SYNESIS_GRAPH_CLIENT_ID / SYNESIS_GOOGLE_CLIENT_ID, see README.md), so a bare compose→send fails with AccountNotConnected here.
• On first launch repository.seedDemoDataIfEmpty() populates demo mail, so the app is usable with zero external services.