cross-session-execution-framework

🪷 跨 Session 執行框架

問題

Hermes Agent 每次 Session 有 token/context 限制，跨 Session 開發有以下痛點：

問題	症狀
Context 遺失	新 Session 唔記得上次做咗乜
任務偏差	開始做 A，做到一半改做 B，最後 A 未完成
進度遺失	用戶唔知做到邊一步
決定遺失	之前用戶確認嘅決定，新 Session 要再問一次

解決方案：檔案系統實體化

喺 project root 建立 3 個追蹤檔案：

project/
├── ROADMAP.md    ← 用戶睇進度
├── STATE.md      ← Agent 記錄狀態
└── boot.sh       ← 自動行，開工匯報

---

1. ROADMAP.md — 總路線圖

格式

# 🪷 專案名 — 優化路線圖

> 整體執行進度。✅ = 完成，⬜ = 未開始

## 階段一：XXX
- [x] 1.1 已完成任務（簡短說明）
- [ ] 1.2 未完成任務

## 階段二：XXX
- [ ] 2.1 ...

規則

• 任務用 checkbox 格式 - [ ] / - [x]
• 分階段（P0/P1/P2 或 基建/功能/優化）
• 每個 checkbox 對應一個可獨立完成嘅 task
• 唔好放太細粒度（唔好一個 task 就係「改一行 code」）

---

2. STATE.md — 當前執行狀態

格式

# 🪷 當前執行狀態

## 基本資訊
- **最後更新**：YYYY-MM-DD（Session N）
- **當前階段**：階段一 — ✅ 完成 / 🔄 進行中
- **當前 Task**：XXX

## 已完成
重點 list 已完成嘅 task，每個 task 下面有具體改動 summary

## 已修改／新增檔案
| 檔案 | 狀態 | 說明 |

## 下一個要做
清晰描述下一個 task 係乜

## 待確認事項
1. **問題描述** — 需要用戶決定嘅事
   - 選項 A
   - 選項 B
   
## Git 狀態
（如有）

更新規則

• 每次 Session 完結前必須 update
• 「已修改／新增檔案」記錄 exact path，方便下個 Session 快速定位
• 「待確認事項」係最關鍵嘅 section——確保用戶決定唔會 lost

---

3. boot.sh — 開機腳本

範例

#!/bin/bash
PROJECT_DIR="/path/to/project"

echo "=== 🪷 Boot Sequence ==="

# Check ROADMAP
if [ -f "$PROJECT_DIR/ROADMAP.md" ]; then
    echo "✅ ROADMAP.md 存在"
    grep -n "\[ \]" "$PROJECT_DIR/ROADMAP.md" | head -10
fi

# Check STATE
if [ -f "$PROJECT_DIR/STATE.md" ]; then
    echo "✅ STATE.md 存在"
    grep -A 2 "當前階段\|當前 Task\|下一個\|待確認" "$PROJECT_DIR/STATE.md"
fi

# Git status
if [ -d "$PROJECT_DIR/.git" ]; then
    git -C "$PROJECT_DIR" status --short
fi

執行時機

• 每次用戶講「開工」時自動執行
• 如果 boot.sh 唔存在，要手動 read_file ROADMAP.md + STATE.md

---

每次 Session 標準流程

用戶講「開工」
  ↓
行 boot.sh（或手動檢查 ROADMAP + STATE）
  ↓
讀 STATE.md → 知道上次進度 + 未確認事項
  ↓
如果有「待確認事項」→ 先問用戶決定
  ↓
開始做當前 Task（一個 task 一個 Session）
  ↓
完成後：
  1. 更新 ROADMAP.md（check box）
  2. 更新 STATE.md（完成記錄 + 修改檔案 + 下個 task + 新待確認）
  ↓
匯報完成 + 列出待確認事項
  ↓
（Session end — 下次重複）