Session Continuation

Purpose: Manage workflow state across sessions with handoff and resume Priority: HIGH Version: 2.0.0

---

Plan State Variables

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

---

When This Skill Activates

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

---

Handoff Flow

Step 1: Detect Need for Handoff

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?"

Step 2: Save Workflow State

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": "backend-nodejs",
    "secondary": ["security-expert", "qa-automation"]
  },

  "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
  }
}

Step 3: Generate Handoff Summary

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

═══════════════════════════════════════════════════════════

---

Resume Flow

Step 1: Parse Resume Command

Input: "workflow:resume AUTH-123"
       "resume AUTH-123"
       "continue workflow AUTH-123"

Extract: workflow_id = "AUTH-123"

Step 2: Load Workflow State

Load: .claude/logs/workflows/[workflow-id]/workflow-state.json

Validate:
  - File exists
  - JSON is valid
  - Version compatible
  - Status is "paused" or "waiting_approval"

Step 3: Restore Context

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

Step 4: Show Resume Summary

═══════════════════════════════════════════════════════════
🔄 WORKFLOW RESUMED
═══════════════════════════════════════════════════════════

📋 **Workflow:** AUTH-123
📝 **Task:** Implement user authentication with JWT

📊 **Restored State:**
- Current Phase: 3 - Build GREEN
- Primary Agent: backend-nodejs
- 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.
═══════════════════════════════════════════════════════════

Step 5: Continue Execution

On "continue":
  1. Resume from saved phase
  2. Show agent banner
  3. Execute remaining phase steps
  4. Show approval gate when phase complete

---

Commands

workflow:handoff

Syntax: workflow:handoff

Action: Save current workflow state and generate resume instructions.

workflow:resume

Syntax: workflow:resume <workflow-id>

Action: Load saved workflow state and continue from last phase.

workflow:list

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>`

---

Auto-Save Behavior

When Auto-Save Triggers

Events:
  - Phase completion (before approval gate)
  - Every 5 minutes during active work
  - Token count milestones (100K, 150K, 175K)
  - Before any external system write

Auto-Save is Silent

Behavior:
  - No user notification for routine saves
  - Only notify at warning thresholds
  - State file updated in background

---

State File Management

File Location

.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

Cleanup Policy

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

---

Error Handling

State File Not Found

❌ 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>`

Corrupted State File

❌ 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)

Version Mismatch

⚠️ Workflow was created with Aura Frog v0.9.0
Current version: v1.0.0

Attempting migration...
✅ State migrated successfully

Continue? (yes/no)

---

Best Practices

DO:

• Handoff before token limit (at 150K)
• Include workflow ID in task tracking
• Resume promptly to maintain context
• Review key decisions after resume

DON'T:

• Wait until 200K tokens (may truncate)
• Delete state files manually
• Resume with different project context
• Skip the resume summary review

---

TOON State Format (Token-Efficient)

# .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]: 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