Session-Based Development Workflow

CRITICAL: Developer MUST follow this session workflow to maintain continuity across conversations.

Session Tracker File

The file docs/session/.current_session is the entry point for every session.

• It contains the filename (relative to project root) of the active development plan.
• If the file is empty or does not exist, there is no active session — ask the user what to work on.
• If the file contains a plan filename, read that plan first before doing any work.

Session Protocol

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-simplification-plan.md). Understand the current sprint, completed tasks, and next tasks.
3. If no plan exists: Ask the user what they'd like 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.

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 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. Create a new plan file in docs/session/ with naming convention: YYYY-MM-DD-HHMM_short-description.md.
2. Write the plan with: problem statement, scope, sprint breakdown with task checklists.
3. Add corresponding tasks to TASK.md.
4. Write the plan filename into docs/session/.current_session.

Session File Structure

docs/session/
├── .current_session                              # Contains filename of active plan (or empty)
├── 2026-02-13-1350_mock-simplification-plan.md   # Example: active plan
└── ...                                           # Completed plans stay as historical records

Example .current_session content

docs/session/2026-02-13-1350_mock-simplification-plan.md

When all tasks in that plan are done, the file becomes empty (no content).

Task Tracking

IMPORTANT: TASK.md is the source of truth for overall project progress. Session plans in docs/session/ provide detailed sprint-level tracking for active initiatives.

Developer Instructions

1. Before starting work: Read docs/session/.current_session first, then check TASK.md
2. When completing sprint tasks: Update session plan to mark items as [x]. Add suggestion, note or finding if needed.
3. When completing main tasks: Update both the session plan file AND TASK.md to mark items as [x]. At summary and finding to session plan
4. When starting tasks: Mark items as [/] in progress in TASK.md
5. Keep both in sync: Session plan and TASK.md should always reflect actual project state