planning-with-files

## Help Us Test Session Management Features!

I've implemented session management patterns from Anthropic's article ["Effective harnesses for long-running agents"](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) in the **`feature/anthropic-patterns`** branch.

These features need testing before merging to main. **Your feedback is critical!**

---

## What's New

### 1. Session Initialization Script
Run at the start of every session:
```bash
bash scripts/init-session.sh
```

**What it does:**
- ✅ Verifies planning files exist
- ✅ Shows current phase and git status
- ✅ Displays last commit
- ✅ Logs session start to progress.md
- ✅ Creates missing files if needed

### 2. Pass/Fail Status Tracking
Enhanced `task_plan.md` template with:
- Status icons: ⏸️ Pending | 🔄 In Progress | ✅ Pass | ❌ Fail | ⏭️ Skipped
- Test Results table for each phase
- Git Checkpoints table to log commits
- Phase Summary table for quick overview

### 3. Git Checkpoint Workflow
New documentation: `docs/git-checkpoints.md`
- "One phase, one commit" pattern
- Use git commits as rollback points
- Integrates with task_plan.md

### 4. Session-Start Verification
Automated checklist that verifies:
- Planning files present
- Git working tree clean
- Current branch status
- Last commit information

---

## How to Test

### 1. Checkout the Branch
```bash
cd your-planning-with-files-repo
git fetch origin
git checkout feature/anthropic-patterns
```

### 2. Try It In a Test Project
```bash
cd ~/your-test-project
bash /path/to/planning-with-files/scripts/init-session.sh
```

### 3. Work Through a Multi-Phase Task
- Let the script create planning files
- Define some phases in task_plan.md
- Complete a phase and test it
- Mark it as ✅ Pass with test results
- Commit: `git commit -m "feat(Phase 1): description"`
- Log the commit hash in Git Checkpoints table
- Start a new session and run init-session.sh again

### 4. Read the Implementation Summary
See `IMPLEMENTATION_SUMMARY.md` in the branch for full details.

---

## What We Need Feedback On

1. **Does init-session.sh work on your system?**
   - Unix/Mac: Does the bash script run smoothly?
   - Windows: Does the PowerShell version work?

2. **Is the new task_plan.md template helpful?**
   - Are the status icons clear?
   - Is the Test Results table useful?
   - Does the Git Checkpoints table make sense?

3. **Does the workflow feel natural?**
   - Plan → Implement → Verify → Commit
   - Does session recovery work when you restart?

4. **Any bugs or issues?**
   - Errors when running scripts?
   - Confusing documentation?
   - Missing features?

5. **Suggestions for improvement?**
   - What would make this better?
   - Any patterns from the Anthropic article we missed?

---

## Related Issue

This work resolves [Issue #19](https://github.com/OthmanAdi/planning-with-files/issues/19) requested by @wqh17101.

---

## Documentation

- [Git Checkpoint Workflow](https://github.com/OthmanAdi/planning-with-files/blob/feature/anthropic-patterns/docs/git-checkpoints.md)
- [Implementation Summary](https://github.com/OthmanAdi/planning-with-files/blob/feature/anthropic-patterns/IMPLEMENTATION_SUMMARY.md)
- [Anthropic Article](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) (inspiration)

---

**Please test and share your experience!** Once we have enough feedback and approval, I'll merge this to main.

Thank you!

Ahmad