Claude-Code-Workflow/.claude/commands/memory/workflow-skill-memory.md

name, description, argument-hint, allowed-tools

name	description	argument-hint	allowed-tools
workflow-skill-memory	Generate SKILL package from archived workflow sessions for progressive context loading	[--regenerate] [--incremental] [--filter <topic>]	SlashCommand(*), TodoWrite(*), Bash(*), Read(*), Write(*)

Workflow SKILL Memory Generator

Orchestrator Role

Pure Orchestrator: Extract and aggregate workflow session history to generate SKILL package for progressive context loading.

Auto-Continue Workflow: This command runs fully autonomously once triggered. Each phase completes and automatically triggers the next phase without user interaction.

Execution Paths:

• Full Path: All 4 phases (no existing SKILL OR --regenerate specified)
• Incremental Path: Phase 1 → Phase 2 → Phase 4 (existing SKILL found AND --incremental flag)
• Phase 4 Always Executes: SKILL.md index is never skipped, always generated or updated

Core Rules

1. Start Immediately: First action is TodoWrite initialization, second action is Phase 1 execution
2. No Task JSON: This command does not create task JSON files
3. Parse Every Output: Extract required data from each command output (session count, file paths)
4. Auto-Continue: After completing each phase, update TodoWrite and immediately execute next phase
5. Track Progress: Update TodoWrite after EVERY phase completion before starting next phase
6. Direct Generation: Phase 4 directly generates SKILL.md using Write tool
7. No Manual Steps: User should never be prompted for decisions between phases

---

4-Phase Execution

Phase 1: Read Archived Sessions

Goal: Read manifest.json and list all archived workflow sessions

Step 1.1: Check Archive Directory

bash(test -d .workflow/.archives && echo "exists" || echo "not_exists")

Step 1.2: Read Manifest

bash(test -f .workflow/.archives/manifest.json && cat .workflow/.archives/manifest.json || echo "{}")

Output:

• archive_exists: exists or not_exists
• manifest_content: JSON content or empty object
• session_count: Number of archived sessions

Step 1.3: Parse Session List

Extract from manifest:

• Session IDs
• Descriptions
• Archived dates
• Tags
• Metrics (task_count, success_rate, duration_hours)

Step 1.4: Apply Filters (if --filter specified)

If user provided --filter <topic>:

• Filter sessions by description/tags matching topic
• Update session list to only include filtered sessions

Step 1.5: Determine Execution Path

Decision Logic:

if (session_count === 0) {
  // No archived sessions
  ERROR = "No archived workflow sessions found"
  SKIP_ALL = true
} else if (existing_SKILL && incremental_flag) {
  // Incremental update: skip full aggregation
  SKIP_AGGREGATION = true
  message = "Incremental update mode, reusing existing aggregations."
} else if (regenerate_flag) {
  // Force regeneration: delete existing SKILL
  bash(rm -rf .claude/skills/workflow-progress 2>/dev/null || true)
  SKIP_AGGREGATION = false
  message = "Regenerating SKILL package from scratch."
} else {
  // No existing SKILL or full generation
  SKIP_AGGREGATION = false
  message = "Generating new SKILL package."
}

Summary Variables:

• SESSION_COUNT: Total archived sessions (or filtered count)
• SESSION_LIST: Array of session objects [{id, description, archived_at, tags, metrics}]
• FILTER_TOPIC: Filter keyword (if specified)
• INCREMENTAL: true if --incremental flag
• REGENERATE: true if --regenerate flag
• SKIP_AGGREGATION: true if incremental update
• SKIP_ALL: true if no sessions found

Completion & TodoWrite:

• If SKIP_ALL = true: Mark all phases completed (error), report error
• If SKIP_AGGREGATION = true: Mark phase 1 completed, phase 2&3 completed (skipped), phase 4 in_progress
• If SKIP_AGGREGATION = false: Mark phase 1 completed, phase 2 in_progress

Next Action:

• If error: Display error message → Exit
• If skipping aggregation: Display skip message → Jump to Phase 4
• Otherwise: Display session list → Continue to Phase 2

---

Phase 2: Extract Session Data

Skip Condition: This phase is skipped if SKIP_AGGREGATION = true (incremental mode with existing aggregations)

Goal: Traverse archived sessions and extract key data

For Each Session:

Step 2.1: Read Session Metadata

bash(cat .workflow/.archives/WFS-{session_id}/workflow-session.json)

Step 2.2: Check for Key Files

# Context package path (reference only, don't read content)
bash(test -f .workflow/.archives/WFS-{session_id}/.process/context-package.json && echo "exists" || echo "missing")

# IMPL_PLAN
bash(test -f .workflow/.archives/WFS-{session_id}/IMPL_PLAN.md && cat .workflow/.archives/WFS-{session_id}/IMPL_PLAN.md || echo "")

# TODO_LIST
bash(test -f .workflow/.archives/WFS-{session_id}/TODO_LIST.md && cat .workflow/.archives/WFS-{session_id}/TODO_LIST.md || echo "")

# Count tasks and summaries
bash(find .workflow/.archives/WFS-{session_id}/.task -name "*.json" 2>/dev/null | wc -l || echo 0)
bash(find .workflow/.archives/WFS-{session_id}/.summaries -name "*.md" 2>/dev/null | wc -l || echo 0)

Step 2.3: Extract from Manifest Entry

For each session, extract from manifest.json:

• lessons.successes - Success patterns
• lessons.challenges - Challenges encountered
• lessons.watch_patterns - Things to watch for
• tags - Functional domain tags
• metrics - Task count, success rate, duration

Aggregated Data Structure:

{
  "sessions": [
    {
      "session_id": "WFS-user-auth",
      "description": "User authentication implementation",
      "archived_at": "2025-11-03T12:00:00Z",
      "tags": ["auth", "security", "jwt"],
      "metrics": {
        "task_count": 5,
        "completed_tasks": 5,
        "success_rate": 100,
        "duration_hours": 4.5
      },
      "context_package_path": ".workflow/.archives/WFS-user-auth/.process/context-package.json",
      "impl_plan_summary": "First 200 chars of IMPL_PLAN.md...",
      "lessons": {
        "successes": ["JWT implementation worked well", "..."],
        "challenges": ["Token refresh edge cases", "..."],
        "watch_patterns": ["Concurrent token validation", "..."]
      }
    }
  ],
  "aggregated_lessons": {
    "successes_by_category": {
      "auth": ["JWT implementation", "..."],
      "testing": ["Coverage reached 90%", "..."]
    },
    "challenges_by_severity": {
      "high": ["Performance bottleneck in token validation", "..."],
      "medium": ["Edge case handling", "..."]
    },
    "watch_patterns": ["Token concurrency", "State management", "..."]
  },
  "conflict_patterns": {
    "architecture": [
      {
        "pattern": "Multiple authentication strategies conflict",
        "sessions": ["WFS-user-auth", "WFS-oauth"],
        "resolution": "Unified auth interface"
      }
    ],
    "dependencies": [
      {
        "pattern": "Version mismatch in JWT libraries",
        "sessions": ["WFS-user-auth"],
        "resolution": "Lock to compatible version"
      }
    ]
  }
}

Completion Criteria:

• All sessions traversed
• Data structure populated
• Aggregations computed (lessons by category, conflicts by type)

TodoWrite: Mark phase 2 completed, phase 3 in_progress

Next Action: Display extraction summary (sessions processed, lessons extracted) → Auto-continue to Phase 3

---

Phase 3: Classify and Organize Data

Skip Condition: This phase is skipped if SKIP_AGGREGATION = true (incremental mode)

Goal: Organize extracted data by functional domains, timeline, and patterns

Step 3.1: Group Sessions by Tags

Organize sessions into functional domains:

{
  "auth": [session_objects],
  "payment": [session_objects],
  "ui": [session_objects],
  "testing": [session_objects],
  "other": [session_objects]
}

Step 3.2: Sort by Timeline

Create chronological timeline:

• Sort sessions by archived_at (newest first)
• Group by month/quarter for large histories

Step 3.3: Identify Recurring Patterns

Lessons Analysis:

• Successes that appear in multiple sessions → "Best Practices"
• Challenges that repeat → "Known Issues"
• Watch patterns with high frequency → "High Priority Warnings"

Conflict Analysis:

• Group conflicts by type (architecture, dependencies, testing)
• Mark conflicts that occurred in multiple sessions
• Link resolutions to specific sessions

Step 3.4: Build Progressive Loading Structure

Organize data for 4 levels:

• Level 0: Top 5 recent sessions + Top 3 conflict patterns
• Level 1: Top 10 sessions + Lessons by category
• Level 2: All sessions + Full conflict analysis + IMPL_PLAN summaries
• Level 3: All sessions + Full IMPL_PLAN + TODO_LIST + Context package references

Completion Criteria:

• Sessions grouped by domain
• Timeline structure created
• Recurring patterns identified
• Progressive loading structure built

TodoWrite: Mark phase 3 completed, phase 4 in_progress

Next Action: Display organization summary → Auto-continue to Phase 4

---

Phase 4: Generate SKILL Package

Note: This phase is NEVER skipped - it always executes to generate or update the SKILL package.

Step 4.1: Create SKILL Directory

bash(mkdir -p .claude/skills/workflow-progress)

Step 4.2: Generate sessions-timeline.md

Create timeline document:

# Workflow Sessions Timeline

## Recent Sessions (Last 5)

### WFS-user-auth (2025-11-03)
**Description**: User authentication implementation
**Tags**: auth, security, jwt
**Metrics**: 5 tasks, 100% success, 4.5 hours
**Context Package**: [.workflow/.archives/WFS-user-auth/.process/context-package.json](.workflow/.archives/WFS-user-auth/.process/context-package.json)

**Key Outcomes**:
- ✅ JWT implementation with refresh tokens
- ✅ Secure password hashing
- ⚠️ Watch: Token concurrency edge cases

...

## By Functional Domain

### Authentication (3 sessions)
- WFS-user-auth (2025-11-03)
- WFS-oauth (2025-10-15)
- WFS-jwt-refresh (2025-09-20)

### Payment (2 sessions)
- WFS-stripe-integration (2025-10-28)
- WFS-payment-webhooks (2025-09-10)

...

Step 4.3: Generate lessons-learned.md

Create lessons document:

# Workflow Lessons Learned

## Best Practices (Successes)

### Authentication
- JWT implementation with refresh tokens works reliably
- Use bcrypt for password hashing (sessions: WFS-user-auth, WFS-oauth)

### Testing
- TDD approach reduced bugs by 60% (sessions: WFS-user-auth, WFS-payment)
- Mocking external APIs saves development time

...

## Known Challenges

### High Priority
- **Token refresh edge cases**: Concurrent requests can invalidate tokens prematurely
  - Affected sessions: WFS-user-auth, WFS-jwt-refresh
  - Resolution: Implement token refresh queue

### Medium Priority
- **Performance bottlenecks**: Large payload serialization
  - Affected sessions: WFS-payment-webhooks
  - Resolution: Implement streaming responses

...

## Watch Patterns

### Critical
1. **Token concurrency**: Always test concurrent token operations
2. **State management**: Redux state can become stale in async workflows
3. **Database migrations**: Always backup before schema changes

...

Step 4.4: Generate conflict-patterns.md

Create conflict patterns document:

# Workflow Conflict Patterns

## Architecture Conflicts

### Multiple Authentication Strategies
**Pattern**: Different parts of system use incompatible auth methods
**Sessions**: WFS-user-auth, WFS-oauth
**Resolution**: Unified auth interface with strategy pattern

**Code Impact**:
- Modified: src/auth/interface.ts, src/auth/jwt.ts, src/auth/oauth.ts
- Tests: src/auth/__tests__/

...

## Dependency Conflicts

### JWT Library Version Mismatch
**Pattern**: jsonwebtoken v8 vs v9 incompatibility
**Sessions**: WFS-user-auth
**Resolution**: Lock to jsonwebtoken@^9.0.0, update all imports

...

## Testing Conflicts

### Mock Data Inconsistencies
**Pattern**: Different test suites use different user fixtures
**Sessions**: WFS-user-auth, WFS-payment
**Resolution**: Centralized test fixtures in tests/fixtures/

...

Step 4.5: Generate SKILL.md

Create main SKILL index:

---
name: workflow-progress
description: Progressive workflow development history (located at {project_root}). Load this SKILL when continuing development, analyzing past implementations, or learning from workflow history, especially when no relevant context exists in memory.
version: 1.0.0
---
# Workflow Progress SKILL Package

## Documentation: `../../../.workflow/.archives/`

**Total Sessions**: {session_count}
**Functional Domains**: {domain_list}
**Date Range**: {earliest_date} - {latest_date}

## Progressive Loading

### Level 0: Quick Overview (~2K tokens)
- [Sessions Timeline](sessions-timeline.md#recent-sessions-last-5) - Recent 5 sessions
- [Top Conflict Patterns](conflict-patterns.md#top-patterns) - Top 3 recurring conflicts
- Quick reference for last completed work

**Use Case**: Quick context refresh before starting new task

### Level 1: Core History (~8K tokens)
- [Sessions Timeline](sessions-timeline.md) - Recent 10 sessions with details
- [Lessons Learned](lessons-learned.md#best-practices) - Success patterns by category
- [Conflict Patterns](conflict-patterns.md) - Known conflict types and resolutions
- Context package references (metadata only)

**Use Case**: Understanding recent development patterns and avoiding known pitfalls

### Level 2: Complete History (~25K tokens)
- All archived sessions with metadata
- Full lessons learned (successes, challenges, watch patterns)
- Complete conflict analysis with resolutions
- IMPL_PLAN summaries from all sessions
- Context package paths for on-demand loading

**Use Case**: Comprehensive review before major refactoring or architecture changes

### Level 3: Deep Dive (~40K tokens)
- Full IMPL_PLAN.md and TODO_LIST.md from all sessions
- Detailed task completion summaries
- Cross-session dependency analysis
- Direct context package file references

**Use Case**: Investigating specific implementation details or debugging historical decisions

---

## Quick Access

### Recent Sessions
{list of 5 most recent sessions with one-line descriptions}

### By Domain
- **Authentication**: {count} sessions
- **Payment**: {count} sessions
- **UI/UX**: {count} sessions
- **Testing**: {count} sessions
- **Other**: {count} sessions

### Top Watch Patterns
1. {most frequent watch pattern}
2. {second most frequent}
3. {third most frequent}

---

## Session Index

### Authentication Sessions
- [WFS-user-auth](../../../.workflow/.archives/WFS-user-auth/) - JWT authentication (2025-11-03)
  - Context: [context-package.json](../../../.workflow/.archives/WFS-user-auth/.process/context-package.json)
  - Plan: [IMPL_PLAN.md](../../../.workflow/.archives/WFS-user-auth/IMPL_PLAN.md)
  - Tags: auth, security, jwt

...

---

## Usage Examples

### Loading Quick Context
```markdown
Load Level 0 from workflow-progress SKILL for overview of recent work

Investigating Auth History

Load Level 2 from workflow-progress SKILL, filter by "auth" tag

Full Historical Analysis

Load Level 3 from workflow-progress SKILL for complete development history

**Step 4.6: Write All Files**

Use Write tool to create:
1. `.claude/skills/workflow-progress/SKILL.md`
2. `.claude/skills/workflow-progress/sessions-timeline.md`
3. `.claude/skills/workflow-progress/lessons-learned.md`
4. `.claude/skills/workflow-progress/conflict-patterns.md`

**Completion Criteria**:
- SKILL.md file created
- All support documents created
- Progressive loading structure verified
- File references use relative paths

**TodoWrite**: Mark phase 4 completed

**Final Action**: Report completion summary to user

**Return to User**:

✅ Workflow SKILL Package Generation Complete

Sessions Processed: {session_count} Functional Domains: {domain_count} SKILL Location: .claude/skills/workflow-progress/SKILL.md

Generated:

• sessions-timeline.md - {session_count} sessions organized chronologically
• lessons-learned.md - {success_count} successes, {challenge_count} challenges
• conflict-patterns.md - {conflict_count} conflict patterns documented
• SKILL.md with progressive loading (4 levels)

Usage:

• Level 0: Quick refresh (~2K tokens)
• Level 1: Recent history (~8K tokens)
• Level 2: Complete analysis (~25K tokens)
• Level 3: Deep dive (~40K tokens)

Trigger: Skill() will auto-load when continuing workflow development

---

## Implementation Details

### Critical Rules

1. **No User Prompts Between Phases**: Never ask user questions or wait for input between phases
2. **Immediate Phase Transition**: After TodoWrite update, immediately execute next phase command
3. **Status-Driven Execution**: Check TodoList status after each phase:
   - If next task is "pending" → Mark it "in_progress" and execute
   - If all tasks are "completed" → Report final summary
4. **Phase Completion Pattern**:

Phase N completes → Update TodoWrite (N=completed, N+1=in_progress) → Execute Phase N+1

### TodoWrite Patterns

#### Initialization (Before Phase 1)

**FIRST ACTION**: Create TodoList with all 4 phases
```javascript
TodoWrite({todos: [
{"content": "Read archived sessions from manifest", "status": "in_progress", "activeForm": "Reading archived sessions"},
{"content": "Extract session data and lessons", "status": "pending", "activeForm": "Extracting session data"},
{"content": "Classify and organize data by domains", "status": "pending", "activeForm": "Classifying data"},
{"content": "Generate SKILL package files", "status": "pending", "activeForm": "Generating SKILL files"}
]})

SECOND ACTION: Execute Phase 1 immediately

Full Path (SKIP_AGGREGATION = false)

After Phase 1:

TodoWrite({todos: [
  {"content": "Read archived sessions from manifest", "status": "completed", "activeForm": "Reading archived sessions"},
  {"content": "Extract session data and lessons", "status": "in_progress", "activeForm": "Extracting session data"},
  {"content": "Classify and organize data by domains", "status": "pending", "activeForm": "Classifying data"},
  {"content": "Generate SKILL package files", "status": "pending", "activeForm": "Generating SKILL files"}
]})
// Auto-continue to Phase 2

After Phase 2:

TodoWrite({todos: [
  {"content": "Read archived sessions from manifest", "status": "completed", "activeForm": "Reading archived sessions"},
  {"content": "Extract session data and lessons", "status": "completed", "activeForm": "Extracting session data"},
  {"content": "Classify and organize data by domains", "status": "in_progress", "activeForm": "Classifying data"},
  {"content": "Generate SKILL package files", "status": "pending", "activeForm": "Generating SKILL files"}
]})
// Auto-continue to Phase 3

After Phase 3:

TodoWrite({todos: [
  {"content": "Read archived sessions from manifest", "status": "completed", "activeForm": "Reading archived sessions"},
  {"content": "Extract session data and lessons", "status": "completed", "activeForm": "Extracting session data"},
  {"content": "Classify and organize data by domains", "status": "completed", "activeForm": "Classifying data"},
  {"content": "Generate SKILL package files", "status": "in_progress", "activeForm": "Generating SKILL files"}
]})
// Auto-continue to Phase 4

After Phase 4:

TodoWrite({todos: [
  {"content": "Read archived sessions from manifest", "status": "completed", "activeForm": "Reading archived sessions"},
  {"content": "Extract session data and lessons", "status": "completed", "activeForm": "Extracting session data"},
  {"content": "Classify and organize data by domains", "status": "completed", "activeForm": "Classifying data"},
  {"content": "Generate SKILL package files", "status": "completed", "activeForm": "Generating SKILL files"}
]})
// Report completion summary to user

Incremental Path (SKIP_AGGREGATION = true)

After Phase 1 (detects incremental mode, skips Phase 2 & 3):

TodoWrite({todos: [
  {"content": "Read archived sessions from manifest", "status": "completed", "activeForm": "Reading archived sessions"},
  {"content": "Extract session data and lessons", "status": "completed", "activeForm": "Extracting session data"},
  {"content": "Classify and organize data by domains", "status": "completed", "activeForm": "Classifying data"},
  {"content": "Generate SKILL package files", "status": "in_progress", "activeForm": "Generating SKILL files"}
]})
// Display skip message: "Incremental update mode, reusing existing aggregations."
// Jump directly to Phase 4

After Phase 4:

TodoWrite({todos: [
  {"content": "Read archived sessions from manifest", "status": "completed", "activeForm": "Reading archived sessions"},
  {"content": "Extract session data and lessons", "status": "completed", "activeForm": "Extracting session data"},
  {"content": "Classify and organize data by domains", "status": "completed", "activeForm": "Classifying data"},
  {"content": "Generate SKILL package files", "status": "completed", "activeForm": "Generating SKILL files"}
]})
// Report completion summary to user

Error Handling

• If no archived sessions found, mark all tasks completed and report error
• If any phase fails, mark it as "in_progress" (not completed)
• Report error details to user
• Do NOT auto-continue to next phase on failure

---

Parameters

/memory:workflow-skill-memory [--regenerate] [--incremental] [--filter <topic>]

• --regenerate: Force regenerate all SKILL files from scratch
  • When enabled: Deletes existing .claude/skills/workflow-progress/ before regeneration
  • Ensures fresh SKILL package from archived sessions
• --incremental: Incremental update mode (skip Phase 2 & 3 if existing SKILL found)
  • When enabled: Reuses existing aggregations, only updates SKILL files
  • Faster execution for adding new sessions
• --filter : Filter sessions by topic/tag
  • Example: --filter auth only processes auth-related sessions
  • Uses description and tags for matching

---

Examples

Example 1: Generate SKILL Package (Default)

/memory:workflow-skill-memory

Workflow:

1. Phase 1: Reads manifest.json, gets all archived sessions
2. Phase 2: Extracts lessons, conflicts, and summaries from all sessions
3. Phase 3: Organizes data by domain and timeline
4. Phase 4: Generates SKILL.md at .claude/skills/workflow-progress/SKILL.md

Example 2: Regenerate SKILL Package

/memory:workflow-skill-memory --regenerate

Workflow:

1. Phase 1: Deletes existing SKILL package, reads manifest
2. Phase 2-4: Full regeneration from archived sessions

Example 3: Incremental Update (Fast)

/memory:workflow-skill-memory --incremental

Workflow:

1. Phase 1: Reads manifest, detects incremental mode
2. Display: "Incremental update mode, reusing existing aggregations."
3. Phase 4: Updates SKILL.md only (~5-10x faster)

Example 4: Filter by Topic

/memory:workflow-skill-memory --filter auth

Workflow:

1. Phase 1: Reads manifest, filters sessions with "auth" in description/tags
2. Phase 2-4: Processes only auth-related sessions

---

Benefits

• ✅ Progressive Context Loading: 4 levels (2K → 8K → 25K → 40K tokens)
• ✅ Historical Wisdom: Lessons learned and conflict patterns accumulated
• ✅ Auto-Generated: Called automatically by /workflow:session:complete
• ✅ Incremental Updates: Fast updates when adding new sessions
• ✅ Intelligent Filtering: Focus on specific functional domains
• ✅ Reference-Based: Context packages referenced by path, not duplicated
• ✅ Lightweight: Only aggregates lessons/conflicts, keeps original files

Architecture

workflow-skill-memory (orchestrator)
  ├─ Phase 1: Read manifest and sessions (bash commands)
  ├─ Phase 2: Extract data (bash + Read, skippable)
  ├─ Phase 3: Organize data (in-memory, skippable)
  └─ Phase 4: Write SKILL files (Write tool, always runs)

No task JSON created by this command
Smart skip logic: 5-10x faster in incremental mode