Back to Details

project-session-management

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Project Session Management Skill

项目会话管理Skill

Track progress across work sessions using SESSION.md with git checkpoints and concrete next actions.
使用SESSION.md结合git检查点和明确的后续操作，跨工作会话跟踪进度。

When to Use

适用场景

  • Starting projects after 
    project-planning
    generates IMPLEMENTATION_PHASES.md
  • Resuming work after context clears
  • Mid-phase checkpoints when context is full
  • Phase transitions
  • Tracking Implementation → Verification → Debugging cycle
  • 在
    project-planning
    生成IMPLEMENTATION_PHASES.md后启动项目
  • 上下文重置后恢复工作
  • 上下文饱和时的阶段中期检查点
  • 阶段转换时
  • 跟踪实施→验证→调试周期

Phases vs Sessions

阶段 vs 会话

Phases (IMPLEMENTATION_PHASES.md): Units of WORK (e.g., "Database Schema", "Auth API"). Have verification/exit criteria. May span multiple sessions.
Sessions (SESSION.md): Units of CONTEXT. Complete before clearing/compacting context. Can complete a phase, part of a phase, or multiple small phases.
Example: Phase 3 (Tasks API) → Session 1 (GET/POST) → Session 2 (PATCH/DELETE) → Session 3 (verify) ✅
阶段（IMPLEMENTATION_PHASES.md）：工作单元（例如：“数据库架构”、“认证API”）。具备验证/退出标准，可能跨越多个会话。
会话（SESSION.md）：上下文单元。在清除/压缩上下文前完成。可以完成一个阶段、一个阶段的部分内容，或多个小型阶段。
示例：阶段3（任务API）→ 会话1（GET/POST）→ 会话2（PATCH/DELETE）→ 会话3（验证） ✅

Workflow

工作流程

Starting New Project:
  1. After 
    project-planning
    creates IMPLEMENTATION_PHASES.md, offer: "Create SESSION.md to track progress?"
  2. Generate SESSION.md from phases, set Phase 1 as 🔄 (in progress), set concrete "Next Action"
Ending Session:
  • Automated: 
    /wrap-session
    (updates SESSION.md, creates checkpoint commit, outputs summary)
  • Manual: Update SESSION.md → git checkpoint → set concrete "Next Action"
Resuming:
  • Automated: 
    /continue-session
    (loads context, shows summary, continues from "Next Action")
  • Manual: Read SESSION.md → check "Next Action" → continue
启动新项目:
  1. 在
    project-planning
    创建IMPLEMENTATION_PHASES.md后，询问：“是否创建SESSION.md来跟踪进度？”
  2. 根据阶段生成SESSION.md，将阶段1设置为🔄（进行中），并设置明确的“后续操作”
结束会话:
  • 自动化方式：
    /wrap-session
    （更新SESSION.md、创建检查点提交、输出摘要）
  • 手动方式：更新SESSION.md → 创建git检查点 → 设置明确的“后续操作”
恢复工作:
  • 自动化方式：
    /continue-session
    （加载上下文、显示摘要、从“后续操作”处继续）
  • 手动方式：阅读SESSION.md → 查看“后续操作” → 继续工作

Automation Commands

自动化命令

/wrap-session
: Analyzes state → updates SESSION.md → updates related docs → creates checkpoint commit → outputs summary → optionally pushes
/continue-session
: Loads SESSION.md + planning docs → shows git history + summary → displays verification criteria (if in Verification stage) → opens "Next Action" file → asks permission to continue
/wrap-session
：分析状态 → 更新SESSION.md → 更新相关文档 → 创建检查点提交 → 输出摘要 → 可选择推送
/continue-session
：加载SESSION.md + 规划文档 → 显示git历史 + 摘要 → 显示验证标准（如果处于验证阶段） → 打开“后续操作”对应的文件 → 请求继续权限

SESSION.md Structure

SESSION.md结构

Purpose: Navigation hub referencing planning docs, tracking current progress Target: <200 lines in project root Update: After significant progress (not every change)
用途：作为参考规划文档、跟踪当前进度的导航中心 目标：项目根目录下不超过200行 更新时机：取得重大进展后（无需每次变更都更新）

Template

模板

markdown
undefined
markdown
undefined

Session State

Session State

Current Phase: Phase 3 Current Stage: Implementation (or Verification/Debugging) Last Checkpoint: abc1234 (2025-10-23) Planning Docs: 
docs/IMPLEMENTATION_PHASES.md
, 
docs/ARCHITECTURE.md
Current Phase: Phase 3 Current Stage: Implementation (or Verification/Debugging) Last Checkpoint: abc1234 (2025-10-23) Planning Docs: 
docs/IMPLEMENTATION_PHASES.md
, 
docs/ARCHITECTURE.md

Phase 1: Setup ✅

Phase 1: Setup ✅

Completed: 2025-10-15 | Checkpoint: abc1234 Summary: Vite + React + Tailwind v4 + D1 binding
Completed: 2025-10-15 | Checkpoint: abc1234 Summary: Vite + React + Tailwind v4 + D1 binding

Phase 2: Database ✅

Phase 2: Database ✅

Completed: 2025-10-18 | Checkpoint: def5678 Summary: D1 schema + migrations + seed data
Completed: 2025-10-18 | Checkpoint: def5678 Summary: D1 schema + migrations + seed data

Phase 3: Tasks API 🔄

Phase 3: Tasks API 🔄

Type: API | Started: 2025-10-23 Spec: 
docs/IMPLEMENTATION_PHASES.md#phase-3
Progress:
  • GET /api/tasks endpoint (commit: ghi9012)
  • POST /api/tasks endpoint (commit: jkl3456)
  • PATCH /api/tasks/:id ← CURRENT
  • DELETE /api/tasks/:id
  • Verify all endpoints (see IMPLEMENTATION_PHASES.md for criteria)
Next Action: Implement PATCH /api/tasks/:id in src/routes/tasks.ts:47, handle validation and ownership check
Key Files:
  • src/routes/tasks.ts
  • src/lib/schemas.ts
Known Issues: None
Type: API | Started: 2025-10-23 Spec: 
docs/IMPLEMENTATION_PHASES.md#phase-3
Progress:
  • GET /api/tasks endpoint (commit: ghi9012)
  • POST /api/tasks endpoint (commit: jkl3456)
  • PATCH /api/tasks/:id ← CURRENT
  • DELETE /api/tasks/:id
  • Verify all endpoints (see IMPLEMENTATION_PHASES.md for criteria)
Next Action: Implement PATCH /api/tasks/:id in src/routes/tasks.ts:47, handle validation and ownership check
Key Files:
  • src/routes/tasks.ts
  • src/lib/schemas.ts
Known Issues: None

Phase 4: Task UI ⏸️

Phase 4: Task UI ⏸️

Spec: 
docs/IMPLEMENTATION_PHASES.md#phase-4

---
Spec: 
docs/IMPLEMENTATION_PHASES.md#phase-4

---

Status Icons

状态图标

Use these emoji status icons consistently:
  • ⏸️ = Not started (pending)
  • 🔄 = In progress
  • ✅ = Complete
  • 🚫 = Blocked
请统一使用以下表情状态图标：
  • ⏸️ = 未开始（待启动）
  • 🔄 = 进行中
  • ✅ = 已完成
  • 🚫 = 已阻塞

Stages Within a Phase

阶段内的子阶段

  1. Implementation → Writing code
  2. Verification → Testing against criteria
  3. Debugging → Fixing issues
Update SESSION.md with current stage and progress. Example:
markdown
**Current Stage**: Verification

**Verification Progress**:
- [x] GET /api/tasks returns 200 ✅
- [x] POST /api/tasks creates task ✅
- [ ] POST with invalid data returns 400 ❌ (returns 500)

**Current Issue**: Invalid data returning 500. Check src/middleware/validate.ts
  1. 实施 → 编写代码
  2. 验证 → 根据标准测试
  3. 调试 → 修复问题
更新SESSION.md以记录当前子阶段和进度。示例：
markdown
**Current Stage**: Verification

**Verification Progress**:
- [x] GET /api/tasks returns 200 ✅
- [x] POST /api/tasks creates task ✅
- [ ] POST with invalid data returns 400 ❌ (returns 500)

**Current Issue**: Invalid data returning 500. Check src/middleware/validate.ts

SESSION.md Guidelines

SESSION.md编写指南

✅ Collapse completed phases (2-3 lines), concrete "Next Action" (file+line+task), reference planning docs, checkpoint at phase end or when context full
❌ No code copying, no duplicating IMPLEMENTATION_PHASES.md, no vague actions, keep <200 lines
✅ 折叠已完成的阶段（2-3行）、明确的“后续操作”（文件+行号+任务）、参考规划文档、在阶段结束或上下文饱和时创建检查点
❌ 不要复制代码、不要重复IMPLEMENTATION_PHASES.md的内容、不要使用模糊的操作描述、保持内容不超过200行

Git Checkpoint Format

Git检查点格式

checkpoint: Phase [N] [Status] - [Brief Description]

Phase: [N] - [Name]
Status: [Complete/In Progress/Paused]
Session: [What was accomplished this session]

Files Changed:
- path/to/file.ts (what changed)

Next: [Concrete next action]
Example (Phase Complete):
checkpoint: Phase 3 Complete - Tasks API

Phase: 3 - Tasks API
Status: Complete
Session: Completed all CRUD endpoints and verified functionality

Files Changed:
- src/routes/tasks.ts (all CRUD operations)
- src/lib/schemas.ts (task validation)

Next: Phase 4 - Start building Task List UI component
checkpoint: Phase [N] [Status] - [Brief Description]

Phase: [N] - [Name]
Status: [Complete/In Progress/Paused]
Session: [What was accomplished this session]

Files Changed:
- path/to/file.ts (what changed)

Next: [Concrete next action]
示例（阶段完成）:
checkpoint: Phase 3 Complete - Tasks API

Phase: 3 - Tasks API
Status: Complete
Session: Completed all CRUD endpoints and verified functionality

Files Changed:
- src/routes/tasks.ts (all CRUD operations)
- src/lib/schemas.ts (task validation)

Next: Phase 4 - Start building Task List UI component

Expected Uncommitted Files (CRITICAL)

预期的未提交文件（关键）

Checkpoint Cycle: 
/wrap-session
creates commit → gets hash → updates SESSION.md with hash. Therefore SESSION.md is always uncommitted when resuming (BY DESIGN).
Expected uncommitted files (no warning):
  • SESSION.md - Checkpoint hash updated post-commit, always uncommitted between sessions (NORMAL)
  • CLAUDE.md - Often updated during dev, may be uncommitted (NORMAL)
  • .roomodes - Editor/IDE state, not relevant to session handoff (SAFE TO IGNORE)
Warning triggers (unexpected):
  • Source files (.ts, .tsx, .js)
  • Config files (vite.config.ts, wrangler.jsonc)
  • Planning docs (IMPLEMENTATION_PHASES.md, ARCHITECTURE.md)
  • New untracked files
/continue-session
behavior:
  • ℹ️ Info message when only SESSION.md/CLAUDE.md/.roomodes uncommitted
  • ⚠️ Warning when code/doc changes uncommitted (shows filtered list excluding expected files)
检查点周期：
/wrap-session
创建提交 → 获取哈希值 → 使用哈希值更新SESSION.md。因此恢复工作时SESSION.md始终处于未提交状态（设计如此）。
预期的未提交文件（无警告）:
  • SESSION.md - 提交后更新检查点哈希值，会话间始终未提交（正常状态）
  • CLAUDE.md - 开发过程中经常更新，可能处于未提交状态（正常状态）
  • .roomodes - 编辑器/IDE状态，与会话交接无关（可安全忽略）
警告触发条件（意外情况）:
  • 源码文件（.ts、.tsx、.js）
  • 配置文件（vite.config.ts、wrangler.jsonc）
  • 规划文档（IMPLEMENTATION_PHASES.md、ARCHITECTURE.md）
  • 新的未跟踪文件
/continue-session
的行为:
  • ℹ️ 当只有SESSION.md/CLAUDE.md/.roomodes未提交时，显示信息提示
  • ⚠️ 当代码/文档变更未提交时，显示警告（显示过滤后的列表，排除预期文件）

Context Management

上下文管理

Context full mid-phase: Update SESSION.md → checkpoint → clear context → read SESSION.md + planning docs → continue from "Next Action"
Phase complete: Check verification criteria → mark 🔄→✅ → checkpoint → move next phase ⏸️→🔄
Troubleshooting: Update to "Debugging" stage → document "Current Issue" → when fixed, return to "Verification" or "Implementation"
阶段中期上下文饱和：更新SESSION.md → 创建检查点 → 清除上下文 → 阅读SESSION.md + 规划文档 → 从“后续操作”处继续
阶段完成：检查验证标准 → 将状态从🔄标记为✅ → 创建检查点 → 将下一阶段从⏸️标记为🔄
问题排查：更新为“调试”子阶段 → 记录“当前问题” → 修复后，返回“验证”或“实施”子阶段

Integration with project-planning

与project-planning的集成

project-planning
generates IMPLEMENTATION_PHASES.md (the plan) → 
project-session-management
creates SESSION.md (the tracker) → work through phases → git checkpoints → resume from SESSION.md
Planning docs (/docs): Reference material, rarely change SESSION.md (root): Living document, updates constantly
project-planning
生成IMPLEMENTATION_PHASES.md（规划）→ 
project-session-management
创建SESSION.md（跟踪器）→ 完成各阶段工作 → 创建git检查点 → 从SESSION.md恢复工作
规划文档（/docs目录）：参考资料，很少变更 SESSION.md（根目录）：动态文档，持续更新

Creating SESSION.md for New Project

为新项目创建SESSION.md

After 
project-planning
runs:
  1. Read IMPLEMENTATION_PHASES.md
  2. Create SESSION.md in root: Phase 1 as 🔄, others as ⏸️
  3. Expand Phase 1 with task checklist
  4. Set concrete "Next Action"
  5. Output for review
Offer: "Would you like me to create SESSION.md to track progress through these phases? (clear current phase, progress tracking, easy resume, git checkpoint format)"
project-planning
运行后：
  1. 读取IMPLEMENTATION_PHASES.md
  2. 在根目录创建SESSION.md：将阶段1设置为🔄，其他阶段设置为⏸️
  3. 为阶段1扩展任务清单
  4. 设置明确的“后续操作”
  5. 输出供审核
询问：“是否需要我创建SESSION.md来跟踪这些阶段的进度？（包含当前阶段明确化、进度跟踪、轻松恢复、git检查点格式等功能）”

Bundled Resources

附带资源

Templates: SESSION.md.template, checkpoint-commit-format.md, CLAUDE-session-snippet.md
Scripts: resume.sh (show current state)
References: session-handoff-protocol.md, best-practices.md
模板：SESSION.md.template、checkpoint-commit-format.md、CLAUDE-session-snippet.md
脚本：resume.sh（显示当前状态）
参考文档：session-handoff-protocol.md、best-practices.md