eva/focus-flow
6
0
Fork 1
Code Issues 14 Pull requests 1 Projects Releases Packages Wiki Activity Actions 1
focus-flow/AGENTS.md

5.1 KiB
Raw Blame History

AGENTS.md — Codex Project Rules (SQLite‑First, July 2026)

This document supersedes all previous agent rule files. Treat it as the single source of truth.

0. Quick‑start for Codex

  • Blocks live in Codex Documentation/Current Software Plan/.
  • Work strictly in numerical order unless the active plan explicitly says otherwise.
  • Treat each block or named plan as the primary work unit.
  • New or updated plan documents must use blocks of work, implementation steps, tasks, or acceptance checks.
  • Stop at any explicit BREAKPOINT in the active block or plan; wait for confirmation before continuing.
  • Before coding, run scripts/bootstrap_dev.sh to set up the local dev DB.

1. Persistence

Element Rule
Local storage SQLite via Drift, schemaVersion 1
Abstraction Domain-only repository interfaces (scheduler_persistence)
Swappable New adapters must pass repository conformance tests
Backup AES-256-GCM encrypted SQLite file (Backup library, Block 24)
Migrations Drift migrations with tests (Block 20, Block 26)

SQLite is the selected V1 implementation database. Keep Drift and database details inside the SQLite persistence adapter; core/domain code must not import database libraries or depend on row shapes.

2. Repository & Adapter Rules

  1. Interfaces expose domain objects only.
  2. Optimistic revision on every mutable save.
  3. Owner scope parameter now for future multi-user.
  4. Adapters implement compare-and-set; core never overwrites stale revision.

3. Notification Rules

  • Use NotificationAdapter (Block 21).
  • Desktop implementation (Block 22), fake adapter for tests.
  • Core never imports platform APIs directly.

4. Backup / Export Rules

  • Backup: encrypted SQLite (.sqlite.aes) via Backup library.
  • Readable exports: JSON + CSV via ExportController (Block 23).

5. Testing Hierarchy

Layer Folder Purpose
Unit test/unit pure domain logic
Contract test/contract repository conformance
Migration test/migration Drift schema upgrades
Integration test/integration full stack InMemory + SQLite + fake notifications

CI fails below 80% line coverage.

6. Dev Scripts (Block 27)

Script Description
bootstrap_dev.sh install deps, create dev DB
dev.sh hot-reload desktop run
test.sh all tests + coverage
package_release.sh build OS binaries

Flutter UI work starts in Block 29 under apps/focus_flow_flutter/. Keep it out of the root Dart workspace until the Flutter toolchain gate is fully integrated.

6.1 Code Documentation & File Hygiene

All future project files must include the relevant SPDX metadata for their file format.

All new and modified code must be commented or documented in detail while the work is being done. Update existing comments and docs whenever functionality, contracts, invariants, side effects, persistence mappings, scheduling rules, or error behavior change. Stale comments are treated as incorrect code.

New Dart files must include file-level Dartdoc library docs and Dartdoc comments for every class, enum, enum value, constructor, method, field, and top-level declaration. Existing Dart declarations touched by a change must have their Dartdoc added or updated as part of that same change.

Keep files small and focused. If a file grows to cover multiple responsibilities, split it into smaller files with clear names rather than expanding a broad catch-all file. Use increasingly specific folder scopes, ordered from broad package/feature ownership down to concrete responsibility. Prefer descriptive folder names that explain the domain area or adapter boundary.

Aim for fewer than 10 files per folder. This is a guideline, not a hard rule: do not create artificial one-file folders merely to satisfy the count, and do split crowded folders when the files naturally form smaller responsibility groups.

7. Branch, Commit & CI

  • Start each new block or plan from main on a dedicated branch named for the work, such as block-20-sqlite-adapter or plan-backlog-tab.
  • Keep all work for the active block or plan on its dedicated branch.
  • Commit completed work after it is implemented, documented, and locally validated.
  • Do not leave completed work only in the working tree.
  • Use conventional commits (feat, fix, docs, test, refactor, chore, ci).
  • When a full plan is complete and no work remains for that plan, rerun the required validation. If tests still pass, merge the plan branch back into main.
  • CI matrix: ubuntu-latest, windows-latest, macos-latest.
  • dart analyze and dart test must pass.

8. MVP Boundaries

  • Today + Backlog only.
  • Task types: flexible, inflexible, critical, locked, surprise, free slot.
  • No week/month views, sync, or shield in V1.

9. UX Language

  • Use calm terms: missed, pushed, backlog, archived.
  • Avoid blame language.

Last updated: 2026-07-07