Manage workflow state across sessions with handoff and resume. TOON-based state persistence.
/plugin marketplace add nguyenthienthanh/aura-frog/plugin install aura-frog@aurafrogThis skill is limited to using the following tools:
Purpose: Manage workflow state across sessions with handoff and resume Priority: HIGH Version: 2.0.0
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-4 complete, starting Phase 5
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": "feature-auth-20251129-143022",
"version": "1.0.0",
"created_at": "2025-11-29T14:30:22Z",
"updated_at": "2025-11-29T16:45:30Z",
"status": "paused",
"current_phase": 5,
"current_sub_phase": "a",
"phase_name": "Write Tests (TDD RED)",
"task": {
"description": "Implement user authentication with JWT",
"ticket_id": "PROJ-1234",
"figma_url": null
},
"agents": {
"primary": "backend-nodejs",
"secondary": ["security-expert", "qa-automation"]
},
"phases_completed": {
"1": {
"name": "Requirements Analysis",
"status": "approved",
"deliverables": ["requirements.md"],
"approved_at": "2025-11-29T14:45:00Z"
},
"2": {
"name": "Technical Planning",
"status": "approved",
"deliverables": ["tech-spec.md", "architecture.md"],
"approved_at": "2025-11-29T15:10:00Z"
},
"3": {
"name": "UI Breakdown",
"status": "skipped",
"skip_reason": "Backend-only feature",
"approved_at": "2025-11-29T15:12:00Z"
},
"4": {
"name": "Test Planning",
"status": "approved",
"deliverables": ["test-plan.md"],
"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:** feature-auth-20251129-143022
📊 **Progress:**
- ✅ Phase 1: Requirements Analysis - Approved
- ✅ Phase 2: Technical Planning - Approved
- ⏭️ Phase 3: UI Breakdown - Skipped (backend-only)
- ✅ Phase 4: Test Planning - Approved
- 🔄 Phase 5a: Write Tests - In Progress
📁 **State Saved:**
`.claude/logs/workflows/feature-auth-20251129-143022/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 feature-auth-20251129-143022`
Or copy this command:
workflow:resume feature-auth-20251129-143022
═══════════════════════════════════════════════════════════
Input: "workflow:resume feature-auth-20251129-143022"
"resume feature-auth-20251129-143022"
"continue workflow feature-auth-20251129-143022"
Extract: workflow_id = "feature-auth-20251129-143022"
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:** feature-auth-20251129-143022
📝 **Task:** Implement user authentication with JWT
📊 **Restored State:**
- Current Phase: 5a - Write Tests (TDD RED)
- Primary Agent: backend-nodejs
- Tech Stack: Node.js, Express, PostgreSQL
✅ **Completed Phases:**
- Phase 1: Requirements Analysis ✓
- Phase 2: Technical Planning ✓
- Phase 3: UI Breakdown (skipped) ✓
- Phase 4: Test Planning ✓
🔑 **Key Decisions Restored:**
- Using JWT with refresh tokens
- Storing sessions in Redis
- bcrypt for password hashing
───────────────────────────────────────────────────────────
⏭️ **CONTINUING FROM:** Phase 5a - Write Tests
Ready to continue writing tests for authentication.
Type "continue" to proceed or "status" for more details.
═══════════════════════════════════════════════════════════
On "continue":
1. Resume from saved phase
2. Show agent banner
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 |
|----|------|-------|--------|--------------|
| feature-auth-20251129 | JWT Auth | 5a | paused | 2h ago |
| bugfix-login-20251128 | Login fix | 7 | waiting | 1d ago |
| refactor-api-20251127 | 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/
├── feature-auth-20251129-143022/
│ ├── workflow-state.json # Current state
│ ├── requirements.md # Phase 1 deliverable
│ ├── tech-spec.md # Phase 2 deliverable
│ └── test-plan.md # Phase 4 deliverable
├── bugfix-login-20251128-091500/
│ └── ...
└── 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: feature-auth-20251129-143022
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-feature-20251216
phase: 5
status: in_progress
phases[9]{num,name,status}:
1,Requirements,completed
2,Tech Planning,completed
3,UI Breakdown,skipped
4,Test Planning,completed
5,TDD Implementation,in_progress
6,Code Review,pending
7,QA Validation,pending
8,Documentation,pending
9,Notification,pending
agents[2]: backend-nodejs,qa-automation
Token savings: TOON uses ~160 tokens vs JSON ~600 tokens (73% reduction)
Version: 2.0.0 Last Updated: 2025-12-23
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.