Enables seamless resumption in fresh session with full context restoration. </objective>
<context> @.planning/STATE.md </context> <process> <step name="detect"> Find current phase directory using universal discovery:# Get current phase from STATE.md
CURRENT_PHASE=$(grep -oP 'Phase: \K[0-9]+' .planning/STATE.md 2>/dev/null | head -1)
PADDED=$(printf "%02d" "$CURRENT_PHASE" 2>/dev/null || echo "$CURRENT_PHASE")
PHASE_DIR=""
for state in active pending completed; do
PHASE_DIR=$(find .planning/phases/${state} -maxdepth 1 -type d -name "${PADDED}-*" 2>/dev/null | head -1)
[ -z "$PHASE_DIR" ] && PHASE_DIR=$(find .planning/phases/${state} -maxdepth 1 -type d -name "${CURRENT_PHASE}-*" 2>/dev/null | head -1)
[ -n "$PHASE_DIR" ] && break
done
# Fallback: flat directory (backward compatibility)
if [ -z "$PHASE_DIR" ]; then
PHASE_DIR=$(find .planning/phases -maxdepth 1 -type d -name "${PADDED}-*" 2>/dev/null | head -1)
[ -z "$PHASE_DIR" ] && PHASE_DIR=$(find .planning/phases -maxdepth 1 -type d -name "${CURRENT_PHASE}-*" 2>/dev/null | head -1)
fi
If universal discovery fails, fall back to most recently modified files. </step>
<step name="gather"> **Collect complete state for handoff:**- Current position: Which phase, which plan, which task
- Work completed: What got done this session
- Work remaining: What's left in current plan/phase
- Decisions made: Key decisions and rationale
- Blockers/issues: Anything stuck
- Mental context: The approach, next steps, "vibe"
- Files modified: What's changed but not committed
Ask user for clarifications if needed. </step>
<step name="write"> **Write handoff to `${PHASE_DIR}/.continue-here.md`:**---
phase: XX-name
task: 3
total_tasks: 7
status: in_progress
last_updated: [timestamp]
---
<current_state>
[Where exactly are we? Immediate context]
</current_state>
<completed_work>
- Task 1: [name] - Done
- Task 2: [name] - Done
- Task 3: [name] - In progress, [what's done]
</completed_work>
<remaining_work>
- Task 3: [what's left]
- Task 4: Not started
- Task 5: Not started
</remaining_work>
<decisions_made>
- Decided to use [X] because [reason]
- Chose [approach] over [alternative] because [reason]
</decisions_made>
<blockers>
- [Blocker 1]: [status/workaround]
</blockers>
<context>
[Mental state, what were you thinking, the plan]
</context>
<next_action>
Start with: [specific first action when resuming]
</next_action>
Be specific enough for a fresh Claude to understand immediately. </step>
<step name="commit"> **Check planning config:**COMMIT_PLANNING_DOCS=$(node scripts/kata-lib.cjs read-config "commit_docs" "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
If COMMIT_PLANNING_DOCS=false: Skip git operations
If COMMIT_PLANNING_DOCS=true (default):
git add ${PHASE_DIR}/.continue-here.md
git commit -m "wip: [phase-name] paused at task [X]/[Y]"
Current state:
- Phase: [XX-name]
- Task: [X] of [Y]
- Status: [in_progress/blocked]
- Committed as WIP
To resume: /kata-resume-work
</step>
</process>
<success_criteria>
- [ ] .continue-here.md created in correct phase directory
- [ ] All sections filled with specific content
- [ ] Committed as WIP
- [ ] User knows location and how to resume
</success_criteria>