Start Session

Check for existing active session:

if [ -f ".agent/sessions/active-session.md" ]; then
  echo "⚠️  Active session already exists. Would you like to:"
  echo "1. Resume the existing session"
  echo "2. Archive it and start a new session"
  # Ask user what to do
fi

2. Gather Session Information

Use the AskUserQuestion tool to gather detailed information about the work:

Work Type:

• Is this a feature, bug fix, or chore?

User Story/Description:

• What is the feature/bug/chore? (Detailed description)
• What is the business value or problem being solved?

Acceptance Criteria:

• What are the specific acceptance criteria?
• How will success be measured?
• What are the edge cases to consider?

Scope & Context:

• Which components/modules will be affected?
• Are there any dependencies or prerequisites?
• Are there related features or existing code to be aware of?
• What files or areas of the codebase are relevant?

Constraints:

• Any technical constraints or requirements?
• Performance considerations?
• Security requirements?
• Breaking changes to avoid?

Testing:

• What testing is required? (unit, integration, e2e)
• Are there specific test scenarios to cover?

3. Analyze Codebase

Based on the user's input, use the Explore agent to:

• Locate relevant files and components
• Understand existing patterns in affected areas
• Identify integration points
• Find similar implementations for reference
• Assess complexity and dependencies

4. Generate Session Plan

Create a comprehensive session plan with phases optimized for context windows:

.agent/sessions/active-session.md:

# Active Session

**Created:** [Timestamp]
**Type:** [Feature/Bug/Chore]
**Status:** Phase 1 - Planning

---

## User Story

[User story or description of the work]

### Business Value
[Why this work matters]

---

## Acceptance Criteria

- [ ] [Criterion 1]
- [ ] [Criterion 2]
- [ ] [Criterion 3]

---

## Affected Components

### Primary
- [Component/Module]: [Why it's affected]

### Secondary
- [Component/Module]: [Why it's affected]

---

## Key Files

- `path/to/file.ts` - [Purpose and what will change]
- `path/to/test.spec.ts` - [Test file for above]

---

## Dependencies & Prerequisites

- [Dependency or prerequisite to be aware of]

---

## Constraints

### Technical
- [Technical constraint]

### Breaking Changes to Avoid
- [Potential breaking change to watch for]

---

## Implementation Plan

### Phase 1: [Phase Name] (Planning/Setup)

**Estimated Scope:** [Small/Medium/Large - for context estimation]

**Objectives:**
- [Objective 1]
- [Objective 2]

**Tasks:**
- [ ] [Task 1]
- [ ] [Task 2]

**Files to modify:**
- [Files for this phase]

**Success Criteria:**
- [How to know this phase is done]

---

### Phase 2: [Phase Name] (Core Implementation)

**Estimated Scope:** [Small/Medium/Large]

**Objectives:**
- [Objective 1]

**Tasks:**
- [ ] [Task 1]
- [ ] [Task 2]

**Files to modify:**
- [Files for this phase]

**Success Criteria:**
- [How to know this phase is done]

---

### Phase 3: [Phase Name] (Testing & Validation)

**Estimated Scope:** [Small/Medium/Large]

**Objectives:**
- [Objective 1]

**Tasks:**
- [ ] [Task 1]
- [ ] [Task 2]

**Success Criteria:**
- [How to know this phase is done]

---

## Testing Strategy

### Unit Tests
- [Test 1 description]
- [Test 2 description]

### Integration Tests
- [Test 1 description]

### E2E Tests (if applicable)
- [Test 1 description]

### Manual Testing
- [ ] [Manual test scenario 1]
- [ ] [Manual test scenario 2]

---

## Edge Cases & Considerations

- [Edge case 1]
- [Edge case 2]

---

## Progress Tracking

**Current Phase:** 1
**Completed Phases:** []
**Remaining Phases:** [1, 2, 3]

**Phase 1 Progress:**
- Status: Not Started
- Completed Tasks: 0/[total]

---

## Notes

[Space for additional notes during implementation]

5. Phase Breakdown Strategy

When breaking work into phases, consider:

Context Window Optimization:

• Small phase: 5-10 files, simple changes
• Medium phase: 10-20 files, moderate complexity
• Large phase: 20+ files, complex changes requiring multiple steps

Logical Grouping:

• Group related changes together
• Keep data model changes separate from business logic
• Separate core implementation from tests
• Isolate risky or breaking changes

Common Phase Patterns:

1. Setup/Infrastructure - Data models, types, interfaces, configs
2. Core Implementation - Business logic, algorithms, main features
3. Integration - Connect components, wire up dependencies
4. Testing - Unit tests, integration tests
5. Validation - E2E tests, manual testing, edge cases
6. Polish - Error handling, logging, documentation

6. Validate Session Plan

Review the generated session plan to ensure:

• All user requirements are captured
• Acceptance criteria are specific and measurable
• Phases are logically grouped and appropriately sized
• Tasks within phases are clear and actionable
• Success criteria for each phase are defined
• Edge cases are considered

7. Begin Execution

Present the session plan to the user and ask if they're ready to begin:

✅ Session plan created!

## Summary
- **Type:** [Feature/Bug/Chore]
- **Phases:** [Number] phases
- **Affected Components:** [List]

## Plan Overview
Phase 1: [Name] - [Brief description]
Phase 2: [Name] - [Brief description]
Phase 3: [Name] - [Brief description]

The detailed plan is saved in .agent/sessions/active-session.md

Ready to begin Phase 1?

If the user is ready, use the TodoWrite tool to create todos for Phase 1 and begin execution.

Resuming a Session

If resuming an existing session:

1. Read .agent/sessions/active-session.md
2. Check the Progress Tracking section for current phase and status
3. Load the todos for the current phase
4. Continue from where the session left off
5. Update progress tracking as work completes

📋 Resuming session...

**Type:** [Feature/Bug/Chore]
**Current Phase:** [N] - [Phase Name]
**Progress:** [X]/[Y] tasks completed

Continuing with remaining tasks in Phase [N].

Phase Completion

When a phase is completed:

1. Update the Progress Tracking section:

   • Mark phase as completed
   • Update completed phases list
   • Increment current phase
   • Update phase progress counters

2. Summarize phase completion:

✅ Phase [N] completed!

**Completed:**
- [Task 1]
- [Task 2]

**Next Phase:** [N+1] - [Phase Name]
[Brief description of what's next]

Ready to continue?

3. If user is ready, load Phase N+1 todos and continue

Important Notes

• One session at a time: Only one active-session.md should exist
• Resume support: Session file contains all context needed to resume
• Progress tracking: Keep progress section updated in real-time
• Context awareness: Break work into phases that fit comfortably in context
• Flexibility: Phases can be adjusted during execution if needed
• State preservation: All context needed to resume should be in the session file
• Don't over-plan: Keep plans detailed enough to execute but flexible enough to adapt