Stats
Actions
Tags
From aura-frog
Persists and resumes multi-phase workflows across Claude Code sessions via handoff triggers, JSON state files, and auto-save on high token usage or session end.
How this skill is triggered — by the user, by Claude, or both
Slash command
/aura-frog:session-continuationhaikuThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
**Purpose:** Manage workflow state across sessions with handoff and resume
Purpose: Manage workflow state across sessions with handoff and resume Priority: HIGH
state_vars[4]{var,purpose,persistence}:
AF_ACTIVE_PLAN,Current active plan path,Session temp file
AF_SUGGESTED_PLAN,Branch-matched plan hint,Inferred from git branch
AF_COMPLEXITY,Auto-detected task complexity,Session memory
AF_ACTIVE_AGENTS,Currently active agents,Session memory
triggers[5]{trigger,action}:
Token 150K (75%),Suggest handoff
User says handoff/save,Execute handoff
User says resume + ID,Execute resume
Session ending,Auto-save state
Incomplete workflow,Prompt to resume
Triggers:
- Token count: >= 150,000 (75% of 200K limit)
- User request: "handoff", "save", "pause"
- Long workflow: Phases 1-2 complete, starting Phase 3
Auto-prompt:
"⚠️ Token usage is at 75%. Would you like to save workflow state for continuation in a new session?"
State File Location: .claude/logs/workflows/[workflow-id]/workflow-state.json
State Content:
{
"workflow_id": "AUTH-123",
"version": "1.0.0",
"created_at": "2025-11-29T14:30:22Z",
"updated_at": "2025-11-29T16:45:30Z",
"status": "paused",
"current_phase": 3,
"current_sub_phase": null,
"phase_name": "Build GREEN",
"task": {
"description": "Implement user authentication with JWT",
"ticket_id": "PROJ-1234",
"figma_url": null
},
"agents": {
"primary": "architect",
"secondary": ["security", "tester"]
},
"phases_completed": {
"1": {
"name": "Understand + Design",
"status": "approved",
"deliverables": ["requirements.md", "tech-spec.md", "architecture.md"],
"approved_at": "2025-11-29T14:45:00Z"
},
"2": {
"name": "Test RED",
"status": "approved",
"deliverables": ["test-plan.md", "failing-tests"],
"approved_at": "2025-11-29T15:30:00Z"
}
},
"context": {
"project_name": "my-api",
"tech_stack": "Node.js, Express, PostgreSQL",
"test_framework": "Jest",
"key_decisions": [
"Using JWT with refresh tokens",
"Storing sessions in Redis",
"bcrypt for password hashing"
],
"blockers": [],
"notes": "User prefers functional approach over classes"
},
"token_usage": {
"at_handoff": 152340,
"estimated_remaining": 47660
}
}
Output to User:
═══════════════════════════════════════════════════════════
🔄 WORKFLOW HANDOFF COMPLETE
═══════════════════════════════════════════════════════════
📋 **Workflow ID:** AUTH-123
📊 **Progress:**
- ✅ Phase 1: Understand + Design - Approved
- ✅ Phase 2: Test RED - Approved
- 🔄 Phase 3: Build GREEN - In Progress
📁 **State Saved:**
`.claude/logs/workflows/AUTH-123/workflow-state.json`
📦 **Deliverables Created:**
- requirements.md
- tech-spec.md
- architecture.md
- test-plan.md
🔑 **Key Decisions:**
- Using JWT with refresh tokens
- Storing sessions in Redis
- bcrypt for password hashing
───────────────────────────────────────────────────────────
📥 **TO RESUME IN NEW SESSION:**
Type: `workflow:resume AUTH-123`
Or copy this command:
workflow:resume AUTH-123
═══════════════════════════════════════════════════════════
Input: "workflow:resume AUTH-123"
"resume AUTH-123"
"continue workflow AUTH-123"
Extract: workflow_id = "AUTH-123"
Load: .claude/logs/workflows/[workflow-id]/workflow-state.json
Validate:
- File exists
- JSON is valid
- Version compatible
- Status is "paused" or "waiting_approval"
Actions:
1. Load project context (project-contexts/[project]/)
2. Activate saved agents
3. Load phase-specific rules
4. Restore key decisions
5. Load deliverables created so far
═══════════════════════════════════════════════════════════
🔄 WORKFLOW RESUMED
═══════════════════════════════════════════════════════════
📋 **Workflow:** AUTH-123
📝 **Task:** Implement user authentication with JWT
📊 **Restored State:**
- Current Phase: 3 - Build GREEN
- Primary Agent: architect
- Tech Stack: Node.js, Express, PostgreSQL
✅ **Completed Phases:**
- Phase 1: Understand + Design ✓
- Phase 2: Test RED ✓
🔑 **Key Decisions Restored:**
- Using JWT with refresh tokens
- Storing sessions in Redis
- bcrypt for password hashing
───────────────────────────────────────────────────────────
⏭️ **CONTINUING FROM:** Phase 3 - Build GREEN
Ready to continue implementing authentication.
Type "continue" to proceed or "status" for more details.
═══════════════════════════════════════════════════════════
On "continue":
1. Resume from saved phase
3. Execute remaining phase steps
4. Show approval gate when phase complete
Syntax: workflow:handoff
Action: Save current workflow state and generate resume instructions.
Syntax: workflow:resume <workflow-id>
Action: Load saved workflow state and continue from last phase.
Syntax: workflow:list
Action: Show all saved workflows with status.
Output:
📋 Saved Workflows:
| ID | Task | Phase | Status | Last Updated |
|----|------|-------|--------|--------------|
| AUTH-123 | JWT Auth | 5a | paused | 2h ago |
| fix-login-0128 | Login fix | 7 | waiting | 1d ago |
| REFACTOR-789 | API refactor | complete | done | 3d ago |
To resume: `workflow:resume <id>`
Events:
- Phase completion (before approval gate)
- Every 5 minutes during active work
- Token count milestones (100K, 150K, 175K)
- Before any external system write
Behavior:
- No user notification for routine saves
- Only notify at warning thresholds
- State file updated in background
.claude/logs/workflows/
├── AUTH-123/
│ ├── workflow-state.json # Current state
│ ├── requirements.md # Phase 1 deliverable
│ ├── tech-spec.md # Phase 1 deliverable
│ └── test-plan.md # Phase 2 deliverable
├── fix-login-0128/
│ └── ...
└── README.md # Index of workflows
Auto-cleanup:
- Completed workflows: Keep 30 days
- Cancelled workflows: Keep 7 days
- Paused workflows: Keep indefinitely
Manual cleanup:
- Command: workflow:cleanup
- Removes old completed/cancelled workflows
❌ Workflow not found: AUTH-123
Possible reasons:
- Workflow ID is incorrect
- State file was deleted
- Workflow was never saved
Available workflows:
[list recent workflows]
To start a new workflow: `workflow:start <task>`
❌ Cannot load workflow state: Invalid JSON
Attempting recovery...
- Found backup: workflow-state.backup.json
- Restored from backup (15 minutes old)
⚠️ Some recent progress may be lost.
Continue with restored state? (yes/no)
⚠️ Workflow was created with Aura Frog v0.9.0
Current version: v1.0.0
Attempting migration...
✅ State migrated successfully
Continue? (yes/no)
# .claude/workflow-state.toon
workflow:
id: AUTH-1234
phase: 5
status: in_progress
phases[5]{num,name,status}:
1,Understand + Design,completed
2,Test RED,completed
3,Build GREEN,in_progress
4,Refactor + Review,pending
5,Finalize,pending
agents[2]: architect,tester
Token savings: TOON uses ~160 tokens vs JSON ~600 tokens (73% reduction)
npx claudepluginhub nguyenthienthanh/aura-frog --plugin aura-frogSaves and restores workflow state (task details, worktree locations, PR URLs, review status) across sessions via /checkpoint and /rehydrate commands.
Captures current workflow state into a handoff document so a fresh session can resume exactly where the previous one left off. Useful when context is running low or work needs to continue in a new session.
Saves session state at end of session and resumes it at start of next session. Useful when context is running out, wrapping up, or continuing previous work.