forked from eva/focus-flow
151 lines
5.1 KiB
Markdown
151 lines
5.1 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
Human Documentation/
|
|
```
|
|
|
|
Codex execution planning belongs in:
|
|
|
|
```text
|
|
Codex Documentation/
|
|
```
|
|
|
|
Current, active implementation plans belong in:
|
|
|
|
```text
|
|
Codex Documentation/Current Software Plan/
|
|
```
|
|
|
|
Completed plans must be moved to:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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.
|