Guide for developers working with session management

AGENTS.md

< PROJECT NAME >

Guide for developers working on the ... project.

Project Overview

...

Code Style & Architecture

General Principles

• Prefer simplicity over complexity
• Prefer modular structure over monolithic files. Keep files under 300 lines when possible.
• Security-first: encryption, audit logs, role-based access
• Maintain phased approach (MVP → full features)
• Keep documentation as source of truth

File Organization

• Break large files into smaller, focused modules
• Separate concerns: business logic, data access, UI components
• Use clear, descriptive names

Documentation

Central Documentation

• README.md - Setup and API examples
• RELEASE.md - Release notes and fixes (update regularly)
• docs/sessions/ - Development session logs
• docs/changes/ - Changes log entries for each release
• TASK.md (Overall task checklist and Task tracking)

Session Management

At the START of every session:

1. Read docs/session/.current_session to check for an active development plan.
2. If a plan exists: Read the referenced plan file (e.g., docs/session/2026-02-13-1350_mock-plan.md). Understand the current sprint, completed tasks, and next tasks.
3. If no plan exists: Process the user request to work on. If the work is non-trivial, create a plan in docs/session/ first.
4. Check TASK.md for overall project status and find the matching task section.

DURING a session:

1. Work on tasks from the active plan, following the sprint order.
2. Update TASK.md: Mark tasks as [/] in progress or [x] completed as you go.
3. Update the plan file: Check off completed items in the plan's task lists.

When receiving feedback or corrections on the current plan

Revise the current plan in-place — do NOT create a new one.

1. If the user gives feedback, points out a wrong approach, or requests changes:
   • Edit the existing plan file — update the affected tasks to reflect the corrected approach.
   • Add a dated note in the Findings/Progress section explaining what changed and why.
   • Keep all unaffected remaining tasks intact.
2. Only create a new plan if the scope has fundamentally changed (e.g., user requests an entirely different feature). Even then:
   • Properly close the old plan: mark remaining items as [-] deferred or → moved to <new plan>.
   • List all carried-forward items in the new plan with a reference to the old plan.
   • Never silently abandon unchecked items — every remaining task must be explicitly accounted for.
3. Changing the approach to one task does not affect unrelated tasks — only modify the tasks that the feedback applies to. All other remaining work in the plan stays as-is.

At the END of every session (every assistant turn):

1. Summarize: Brief requirement, findings, work done (with suggested git commit message), recommendations, and next steps.
2. Update the plan file: Check off completed items in the plan's task lists. Add short summaries or findings or recommendations to current sprint section to help remind future sessions. Remove outdated items (excluding completed tasks).
3. Update TASK.md to reflect current state.

When ALL tasks in a plan are complete:

1. Mark all tasks as [x] in both the plan file and TASK.md.
2. Clear docs/session/.current_session — remove the filename so it is empty.
3. The completed plan file stays in docs/session/ as a historical record.

When starting a NEW development initiative:

1. Check the current plan first — if .current_session points to an active plan with remaining tasks, you must handle those tasks before starting a new plan (revise in-place, carry forward, or explicitly defer). Never silently replace an active plan.
2. Create plan file: docs/session/YYYY-MM-DD-HHMM_short-description.md
3. Include: problem statement, scope, sprint breakdown with task checklists.
4. If replacing an old plan, include a "Carried from" section listing deferred items and a reference to the old plan file.
5. Add corresponding tasks to TASK.md (concise entries only).
6. Write the plan filename into docs/session/.current_session.

---

Remember: Always check current date/time with date command before writing date-related information