Planning

Ship a lean machine-targeted instruction file at the repo root that states build/test/run commands, conventions, and what is out of scope.

Characterize the computational profile of each candidate scope group by identifying dominant algorithms, data structures, and complexity characteristics.

Characterize how components communicate within the application — delegation, pub/sub, shared state, and other in-process coordination patterns.

Use MVVM with [CommunityToolkit.Mvvm](https://learn.microsoft.com/en-us/dotnet/communitytoolkit/mvvm/) — source-gener...

Pick a .NET target framework from the documented support cadence: LTS for apps, multi-target libraries, pin the SDK.

Decide a Windows UI framework and deployment model deliberately and early; package identity is mandatory for notifications and background tasks.

Distinguish concerns that span all scope groups (cross-cutting — do not isolate) from shared infrastructure that is itself a coherent group.

Identify scope groups by measuring internal coupling density versus external coupling — files that import each other heavily belong together.

Separate the irreducible complexity of the problem from incidental complexity, then spend agents on the incidental and design review on the essential.

Identify the architectural patterns imposed by the chosen framework and use those conventional units as primary scope group candidates.

Group files by their shared public API surface — types, protocols, and exported symbols that define a coherent contract.

Share domain and data logic broadly across platforms with KMP; choose shared vs native UI per platform maturity.

Identify scope group boundaries by finding groups of objects that are created, owned, and destroyed together as a unit.

Identify scope group candidates by locating explicit build targets, package manifests, and declared module boundaries.

Classify every file by its primary reason for existing, and verify that each candidate scope group has a single coherent purpose.

Identify permissions, entitlements, environment checks, and configuration prerequisites that constrain when and where code can execute.

Only modify what was requested. State the goal before starting. Note but do not fix adjacent issues.

Before writing new code, check the platform, your existing dependencies, your own codebases, and proven open source — and verify any candidate dependency is real.

For non-trivial agent work, write a self-contained spec before code, separating planning from execution and ending with a verification step.

Characterize which external libraries, OS frameworks, and system services the code reaches for, and what that implies about scope boundaries.

Characterize how the code communicates with the operating system — IPC, lifecycle callbacks, background execution, and OS-level integration points.

Rules for analyzing query access patterns to drive schema and index decisions, covering read-heavy vs write-heavy tradeoffs, designing for WHERE/JOIN/ORDER BY, identifying missing indexes, and sync-specific batch sizing and transaction patterns.

Pick SwiftData or Core Data for Apple persistence by OS-version floor, model complexity, and migration needs — not by novelty.

Default to a relational database for a server backend; adopt a specialist store only for a concrete, measured requirement.

How to choose the right clock system for distributed sync: physical clocks, Lamport timestamps, vector clocks, Hybrid Logical Clocks, and server-assigned monotonic versions.

How to choose and implement a conflict resolution strategy for sync: LWW, server-wins, field-level merge, CRDTs, Operational Transformation, and manual conflict queues.

Adopt CQRS or event sourcing ONLY when audit/replay or independent read/write scaling justifies their substantial complexity cost.

Use SQLite with WAL mode for concurrent read access. No ORM — use direct SQL via the `sqlite3` standard library module.

Rules for creating effective indexes in SQLite and PostgreSQL, covering B-tree fundamentals, composite ordering, covering indexes, partial and expression indexes, sync metadata indexes, and when not to index.

JSON storage and extraction in SQLite, json_each for array iteration, generated columns for indexing JSON fields, and when JSON is a schema design smell.

Start normalized (3NF), denormalize only measured hotspots. SQLite-specific tradeoffs and sync-safe denormalization guidance.

Design rules for offline-first apps: WAL as the foundation, operation queues, optimistic UI updates, rollback on rejection, offline schema migrations, data expiry, and connectivity-aware sync scheduling.

Choosing between INTEGER PRIMARY KEY, AUTOINCREMENT, UUID, and WITHOUT ROWID — including sync compatibility and cross-database PK design.

One-to-many, many-to-many, polymorphic FKs, self-referential tables, and tree hierarchy patterns with tradeoffs and SQLite-specific guidance.

Comparison and selection guide for SQLite sync tools: Session Extension, cr-sqlite, Litestream, ElectricSQL, PowerSync, Turso/libSQL, and sqlite-sync — with a decision matrix and selection criteria.

How to design a client-side sync engine: layered architecture, entity-agnostic Syncable interface, the six-step sync cycle, scheduling strategies, snapshot rebuilding, and error handling with circuit breakers.

Rules for designing the sync protocol between client and server: push/pull direction, full vs incremental sync, change tracking, batching, idempotency, the outbox pattern, and retry with backoff.

Schema design rules for databases that sync across devices: UUID primary keys, timestamp columns, soft deletes, dirty tracking, version columns, and sync metadata tables.

Rules for transaction management and concurrency in SQLite, covering WAL mode, journal mode selection, BEGIN IMMEDIATE vs DEFERRED, connection strategies, busy_timeout, PRAGMA tuning, and WAL benefits for sync workloads.

Plan RAG retrieval on pgvector with an HNSW index and hybrid dense+lexical+rerank scoring before reaching for a dedicated vector DB.

Plan for feature flag architecture from the start: define a FeatureFlagProvider interface, choose storage backend, and identify which features need gating.

Never mutate running servers in place; build a versioned image artifact and replace instances to deploy or roll back.

Define infrastructure declaratively in version control and apply it through a reviewed plan, never by hand.

Use REST with consistent conventions. Follow the platform API guidelines (Microsoft, Google,

Evolve APIs additively; when versioning is unavoidable pick one scheme and run a header-driven deprecation lifecycle.

Use HTTP caching headers. The server controls cache policy; the client honors it.

Select an API style from consumer needs and traffic shape: REST for resource CRUD, gRPC for internal RPC, GraphQL for client-driven aggregation.

Author the OpenAPI document before implementing endpoints and treat it as the linted, machine-readable contract.

For apps that must work offline, design for local-first with background sync.

Prefer **cursor pagination** for most APIs — stable under concurrent mutations, consistent

Choose the simplest technique that meets your needs.

Use OAuth 2.0 / OpenID Connect with PKCE for all public clients. The Implicit flow is

Identify the privacy regimes that apply and confirm a lawful basis before collecting any personal data.

Collect only what is needed. Prefer on-device processing.

Map personal-data flows, minimize collection, default to the most private setting, and run a DPIA before building high-risk processing.

Model trust boundaries and ask the four Manifesto questions before building so point security controls trace to a why.

Projects SHOULD follow the Google SWE Book ratio: **80% unit / 15% integration / 5% E2E**.

Pick a rendering strategy per route to minimize how much JavaScript reaches the client and when, treating it as an architecture decision not a framework mandate.

The dashboard service is a generic API and UI layer. It has no knowledge of git, files, or roadmap structure. Agents ...

Choose the right pattern for the content type and user task.

Express UI design decisions once as named, tiered design tokens in one platform-agnostic source; reference semantic tokens, never raw values.

Defer to these canonical sources before applying the defaults in this file:

Keep remote server state in a query/cache layer and UI client state in lightweight local state; never hand-cache server data in a global store.