focus-flow/AGENTS.md

AGENTS.md — Codex Project Rules

This file is persistent project guidance. Codex must treat it as standing instructions for this repository.

User and product context

The product owner is a software engineer building a personal scheduling app for difficult ADHD/executive-dysfunction scheduling problems. The app must reduce planning friction, preserve task order, prevent forgotten tasks, and recover gracefully when the user misses work, burns out, or cannot manually reorganize a plan.

Design priorities:

1. Low-friction interactions.
2. Reliable scheduling behavior.
3. No shame, guilt, punishment, or productivity-slogan framing.
4. Preserve flexible task order unless the user explicitly chooses otherwise.
5. Never move locked or inflexible time during automatic rescheduling.
6. Keep hidden locked time hidden by default.
7. Make every scheduling rule testable.
8. Prefer explicit state transitions over vague magic behavior.
9. Do not add non-MVP features unless the active plan asks for them.
10. Update documentation when behavior changes.

The user prefers practical, concrete implementation work. Avoid broad redesigns unless the active plan calls for them.

Documentation structure rules

Human-facing design/product documentation belongs in:

Human Documentation/

Codex execution planning belongs in:

Codex Documentation/

Current, active implementation plans belong in:

Codex Documentation/Current Software Plan/

Completed plans must be moved to:

Codex Documentation/Archived plans/

This is firm. New plans may be uploaded, generated, or pointed at from elsewhere, but once Codex completes a plan, it must move the completed plan document into Codex Documentation/Archived plans/. Do not leave completed plans in Current Software Plan/.

Planning document execution rules

Planning documents are organized into blocks, chunks, and optional stages.

• Blocks are groups of related work.
• Chunks are actionable pieces of work inside a block.
• Stages may be used inside larger chunks when helpful.
• Blocks do not receive a Codex thinking-level classification.
• Chunks and stages must include one of these classifications:
  • low
  • medium
  • high
  • extra high

Codex should rely on the planning documents as much as possible to avoid excess token use. Before doing exploratory work, check whether the current plan already answers the question.

Break point rules

Planning documents may contain BREAKPOINT markers.

When the user says to do the next chunk:

1. Execute only the next permitted chunk or stage.
2. Do not proceed past a BREAKPOINT.
3. If the next chunk or stage has a different recommended thinking level, stop and tell the user the next required level.
4. Wait for user confirmation that the mode has been switched before continuing.

A breakpoint is a hard stop. Do not skip it because the next task seems small.

Commit rules

When finishing a work block or a clearly bounded chunk that leaves the project in a working state:

1. Run relevant formatting/analyze/tests when possible.
2. Commit the work.
3. Use a descriptive conventional commit message.

Examples:

feat(scheduling): add flexible task push behavior
fix(backlog): preserve stale age marker after task update
test(engine): cover locked block overlap rules
docs(plan): archive completed foundation block

Do not make vague commits such as update files, changes, or work.

Engineering rules

• Keep scheduling/domain logic separate from UI.
• Start with pure Dart domain logic and tests.
• Add Flutter UI only when the plan calls for it.
• Avoid network/sync/background behavior unless explicitly planned.
• Prefer immutable models or copy/update patterns.
• Avoid hidden side effects in scheduling functions.
• Every rule that changes task placement should have tests.
• Use clear names over clever abstractions.
• If a rule is ambiguous, add a TODO comment and a small safe default rather than inventing broad behavior.

MVP boundaries

MVP includes:

• Today view data model.
• Backlog/wishlist model.
• Quick capture to backlog.
• Optional quick-capture scheduling into next available flexible slot.
• Flexible/inflexible/critical/locked/surprise task types.
• Recurring locked blocks, hidden by default.
• One-day overrides for locked blocks.
• Flexible task push behavior.
• Push options: next available slot, tomorrow/top of queue, backlog.
• End-of-day rollover notice.
• Manual compact mode state.
• Task actions: done, push, backlog, break up.
• Child task ownership and parent auto-completion logic.
• Internal statistics needed for future reporting.

MVP excludes unless explicitly added:

• Week view.
• Month view.
• Weekly reports.
• Overwhelm shield.
• Drag-and-drop reordering.
• Per-task history panel.
• Task dependencies.
• Context tags.
• Full sync.
• Long-running task auto-extension behavior.

UX language rules

Use calm, non-punitive terminology:

• Prefer: missed, pushed, moved to backlog, no longer relevant, cancelled.
• Avoid: failed, late again, bad, unproductive, overdue pile, punishment.

The app should treat disruption as expected, not exceptional.