Dev Phase Manager

Professional phase and checkpoint management system for Claude Code

Dev Phase Manager is a non-invasive workflow enhancement plugin for Claude Code that enables context-aware, multi-phase development workflows with intelligent checkpoint management.

🎯 Key Features

📍 Checkpoint System

State Persistence: Save plan execution state across /clear operations
Automatic Progress Detection: Parse completed tasks from git history
Seamless Recovery: Resume execution from saved checkpoints without context loss

🔄 Phase Stack Management

Multi-Phase Parallel: Suspend current phase to start urgent work
Phase Hierarchy: Manage active and suspended phases with stack-based approach
Smart Recovery: Resume suspended phases with full context restoration

🤝 Superpowers Integration

Non-Invasive Design: Works alongside superpowers without modifications
Enhanced Workflow: Integrates with brainstorming, writing-plans, subagent-driven-development
File-Based State: Uses filesystem for state transfer, maintaining clean separation

🛡️ Idempotency & Safety

Duplicate Prevention: Prevents accidental repeated operations
Graceful Degradation: Works even when files are missing
Smart Prompts: Intelligent confirmations and suggestions

📦 Installation

Method 1: From GitHub (Recommended)

# Add GitHub repository as marketplace
claude plugin marketplace add uukuguy/dev-phase-manager

# Install the plugin
claude plugin install dev-phase-manager

Method 2: Local Development

# Clone the repository
git clone https://github.com/uukuguy/dev-phase-manager.git

# Add local directory as marketplace
claude plugin marketplace add /path/to/dev-phase-manager

# Install the plugin
claude plugin install dev-phase-manager

🚀 Quick Start

Basic Workflow

# 1. Start a new phase
/start-phase "Phase 1 - Feature Implementation"

# 2. Design and plan
/brainstorming
/writing-plans

# 3. Save checkpoint before clearing context
/checkpoint-plan
/clear

# 4. Resume execution
/resume-plan
/subagent-driven-development

# 5. Complete phase
/end-phase

Multi-Phase Workflow

# Start Phase 1
/start-phase "Phase 1 - Core Features"
# ... work on Phase 1 ...

# Urgent: Start Phase 2 (suspends Phase 1)
/start-phase "Phase 2 - Critical Bugfix"
# → Prompts: Suspend Phase 1? (y)
# ... complete Phase 2 ...
/end-phase

# Resume Phase 1
/start-phase --resume phase1
# ... complete Phase 1 ...
/end-phase

🏛️ Architecture: Commands + Skills

Dev Phase Manager follows the dual-layer architecture pattern (same as superpowers):

dev-phase-manager/
├── commands/                    ← User entry points (thin wrappers)
│   ├── start-phase.md           ← One-line: invoke skill
│   ├── end-phase.md
│   ├── list-plan.md
│   ├── checkpoint-plan.md
│   ├── checkpoint-progress.md
│   ├── resume-plan.md
│   ├── mem-save.md              ← NEW in v1.1.0
│   └── mem-search.md            ← NEW in v1.1.0
└── skills/                      ← Full skill logic
    ├── start-phase/SKILL.md
    ├── end-phase/SKILL.md
    ├── list-plan/SKILL.md
    ├── checkpoint-plan/SKILL.md
    ├── checkpoint-progress/SKILL.md
    ├── resume-plan/SKILL.md
    ├── mem-save/SKILL.md         ← NEW in v1.1.0
    └── mem-search/SKILL.md       ← NEW in v1.1.0

commands/*.md are thin wrappers that invoke the corresponding skill:

---
description: "Start new phase or resume suspended phase"
disable-model-invocation: true
---
Invoke the dev-phase-manager:start-phase skill and follow it exactly as presented to you

skills/*/SKILL.md contain the complete behavior definition with all execution steps.

📚 Commands Reference

Core Commands

`/checkpoint-plan`

Save current plan execution state to filesystem.

Usage:

/checkpoint-plan

What it does:

Locates latest plan file in docs/plans/
Collects execution state (phase, completed tasks, current task)
Saves to docs/plans/.checkpoint.json
Enables recovery after /clear

Output:

✅ Checkpoint saved

Plan: Phase 5 - MCP Server
File: docs/plans/2026-02-22-mcp-server.md
Phase: design
Status: Design completed, ready for execution

Next steps:
1. /clear - Clear context
2. /resume-plan - Resume execution

`/resume-plan`

Resume plan execution from saved checkpoint.

Usage:

/resume-plan

What it does:

Loads checkpoint from docs/plans/.checkpoint.json
Displays progress summary
Prompts for execution mode selection
Loads plan content into context

Output:

📋 Resume Plan Execution

Phase: Phase 5 - MCP Server
Plan: docs/plans/2026-02-22-mcp-server.md
Status: design → execution
Progress: 0/10 tasks completed
Next: Task 1 - Setup MCP server structure

Choose execution mode:
1. subagent-driven-development
2. executing-plans

Please execute: /subagent-driven-development

`/checkpoint-progress`

Update execution progress during implementation.

Usage:

/checkpoint-progress

What it does:

Auto-detects completed tasks from git log
Updates checkpoint with current progress
Supports manual input if auto-detection fails

Output:

✅ Progress saved

Completed: 3/10 tasks (30%)
  - Task 1: Setup MCP server structure
  - Task 2: Define tool interfaces
  - Task 3: Implement basic handlers

Current: Task 4 - Implement tool handlers
Mode: subagent-driven-development

Next steps:
1. Continue current task
2. /clear - Clear context (if needed)
3. /resume-plan - Resume after clear

`/start-phase`

Start a new phase or resume a suspended phase.

Usage:

# Start new phase
/start-phase "Phase 5 - MCP Server"

# Resume suspended phase
/start-phase --resume phase4

# Continue current phase
/start-phase

Arguments:

phase_name (optional): Name of the new phase
--resume <phase_id> (optional): Resume suspended phase

What it does:

Reads phase stack from docs/dev/.phase_stack.json
Detects conflicts with active phases
Manages phase suspension and resumption
Loads memory and session guide

Output:

✅ Phase started: Phase 5 - MCP Server

Start time: 2026-02-22 15:00
Phase stack: 1 active, 1 suspended

⏸️  Suspended phases:
  Phase 4 - Cognitive Layer (60% complete)

Next steps:
1. /brainstorming - Discuss design
2. /writing-plans - Create implementation plan
3. /list-plan - View complete plan

`/end-phase`

Complete current phase with proper cleanup.

Usage:

/end-phase

What it does:

Idempotency check (prevents duplicate operations)
Saves memory to claude-mem and memory MCP
Updates docs/dev/WORK_LOG.md
Updates docs/dev/NEXT_SESSION_GUIDE.md
Commits documentation changes to git
Cleans up phase stack
Prompts to resume suspended phases

Output:

✅ Phase 5 completed

Memory saved
Documentation updated
Git committed

⏸️  Suspended phases detected:
  Phase 4 - Cognitive Layer
  Suspended: 2026-02-22 15:00
  Progress: 60%

Suggested actions:
1. /start-phase --resume phase4 - Resume
2. /clear - Clear context first
3. /list-plan - View all phases

Resume phase4 now? (y/n)

`/list-plan`

Display comprehensive project status.

Usage:

/list-plan

What it does:

Reads phase stack status
Reads checkpoint progress
Searches recent memories
Displays comprehensive status view

Output:

📋 Project Status

🟢 Active Phase:
  Phase 5 - MCP Server Implementation
  Started: 2026-02-22 15:00
  Plan: docs/plans/2026-02-22-mcp-server.md
  Progress: 3/10 tasks (30%)
  Current: Task 4 - Implement tool handlers
  Mode: subagent-driven-development

⏸️  Suspended Phases:
  Phase 4 - Cognitive Layer
  Started: 2026-02-22 10:00
  Suspended: 2026-02-22 15:00
  Reason: Starting urgent Phase 5
  Progress: 6/10 tasks (60%)

📝 Recent Memory:
  1. [2026-02-22 15:00] Phase 5 started
  2. [2026-02-22 14:30] Phase 4 suspended
  3. [2026-02-22 12:00] Phase 4 progress - FSM design

💡 Suggested Actions:
  1. Continue Phase 5: Execute Task 4
  2. If needed: /checkpoint-progress + /clear
  3. When done: /end-phase
  4. Resume Phase 4: /start-phase --resume phase4

📂 Key Files:
  - Active plan: docs/plans/2026-02-22-mcp-server.md
  - Session guide: docs/dev/NEXT_SESSION_GUIDE.md
  - Work log: docs/dev/WORK_LOG.md
  - Phase stack: docs/dev/.phase_stack.json

`/mem-save`

Save current work memory to multiple backends with local index tracking.

Usage:

/mem-save

What it does:

Summarizes current progress (2-3 sentences)
Saves to claude-mem and knowledge graph
Appends entry to docs/dev/MEMORY_INDEX.md
Does NOT create git commits

Output:

Memory saved

Saved to:
- claude-mem: "[Project] Memory Save - [Achievement]"
- knowledge graph: Updated observations
- MEMORY_INDEX.md: Added entry to [Active Work]

Summary:
- Completed: Feature X implementation
- In progress: Integration testing
- Next steps: Run full test suite

`/mem-search`

Search and browse work memories with local index priority.

Usage:

# Browse recent memories
/mem-search

# Search specific topic
/mem-search architecture

What it does:

Reads docs/dev/MEMORY_INDEX.md first (local, fast, browsable)
Searches claude-mem and knowledge graph as supplement
Merges and displays results with local index first

Output:

Memory Search Results

Local Index (MEMORY_INDEX.md):
  [Active Work]
  - 15:30 | Completed MCP server integration
  - 14:00 | Architecture decision: FastMCP

  claude-mem:
  - [2026-02-22] Phase 4 completed

  Knowledge Graph:
  - Ouroboros: bilingual architecture (Python + TypeScript)

🏗️ Architecture

File Structure

docs/
├── dev/
│   ├── .phase_stack.json              # Phase stack (active/suspended)
│   ├── MEMORY_INDEX.md                # Local memory index (NEW in v1.1.0)
│   ├── NEXT_SESSION_GUIDE.md          # Active phase guide
│   ├── NEXT_SESSION_GUIDE-phase4.md   # Suspended phase guide
│   └── WORK_LOG.md                    # Work log
└── plans/
    ├── .checkpoint.json               # Active phase checkpoint
    ├── .checkpoint-phase4.json        # Suspended phase checkpoint
    ├── .checkpoint.archive.json       # Archived checkpoint
    └── 2026-02-22-feature.md          # Plan file

Phase Stack Format

{
  "active_phases": [
    {
      "name": "Phase 5 - MCP Server",
      "started_at": "2026-02-22T15:00:00+08:00",
      "checkpoint": "docs/plans/.checkpoint.json",
      "guide": "docs/dev/NEXT_SESSION_GUIDE.md",
      "progress": "30%"
    }
  ],
  "suspended_phases": [
    {
      "name": "Phase 4 - Cognitive Layer",
      "started_at": "2026-02-22T10:00:00+08:00",
      "suspended_at": "2026-02-22T15:00:00+08:00",
      "checkpoint": "docs/plans/.checkpoint-phase4.json",
      "guide": "docs/dev/NEXT_SESSION_GUIDE-phase4.md",
      "progress": "60%",
      "reason": "Starting urgent Phase 5"
    }
  ]
}

Checkpoint Format

{
  "plan_file": "docs/plans/2026-02-22-mcp-server.md",
  "phase": "execution",
  "created_at": "2026-02-22T17:30:00+08:00",
  "updated_at": "2026-02-22T18:15:00+08:00",
  "completed_tasks": ["Task 1", "Task 2", "Task 3"],
  "current_task": "Task 4",
  "execution_mode": "subagent-driven",
  "phase_name": "Phase 5 - MCP Server",
  "notes": "Completed 3/10 tasks, continuing with Task 4"
}

🔗 Integration with Superpowers

Phase Manager is designed to work seamlessly with the superpowers plugin:

Enhanced Workflow

start-phase (Phase Manager)
  ↓
brainstorming (Superpowers)
  ↓
writing-plans (Superpowers)
  ↓
checkpoint-plan (Phase Manager)
  ↓
clear
  ↓
resume-plan (Phase Manager)
  ↓
subagent-driven-development (Superpowers)
  OR
executing-plans (Superpowers)
  ↓
checkpoint-progress (Phase Manager)
  ↓
end-phase (Phase Manager)

Non-Invasive Design

No Modifications: Superpowers skills remain unchanged
File-Based State: Uses filesystem for state transfer
Clean Separation: Clear responsibility boundaries
User Control: Manual skill composition for flexibility

📖 Use Cases

Use Case 1: Long-Running Feature Development

Scenario: Implementing a complex feature that requires multiple sessions.

# Session 1: Design
/start-phase "Feature X Implementation"
/brainstorming
/writing-plans
/checkpoint-plan
/clear

# Session 2: Implementation (Part 1)
/resume-plan
/subagent-driven-development
# ... complete 5/10 tasks ...
/checkpoint-progress
/clear

# Session 3: Implementation (Part 2)
/resume-plan
/subagent-driven-development
# ... complete remaining tasks ...
/end-phase

Benefits:

Context preserved across sessions
Progress tracked automatically
No manual state management

Use Case 2: Urgent Interruption Handling

Scenario: Working on Feature A when critical bug requires immediate attention.

# Working on Feature A
/start-phase "Feature A"
# ... 60% complete ...

# Critical bug discovered
/start-phase "Hotfix - Critical Bug"
# → Suspend Feature A? (y)
# ... fix bug ...
/end-phase

# Resume Feature A
/start-phase --resume featurea
/resume-plan
# ... complete Feature A ...
/end-phase

Benefits:

No context loss when switching
Clear phase hierarchy
Easy resumption

Use Case 3: Context Management

Scenario: Context approaching limit during implementation.

/resume-plan
/subagent-driven-development
# ... context at 85% ...

# Save and clear
/checkpoint-progress
/clear

# Resume with fresh context
/resume-plan
/subagent-driven-development
# ... continue seamlessly ...

Benefits:

Prevents context overflow
Seamless continuation
No manual state tracking

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

# Clone repository
git clone https://github.com/uukuguy/dev-phase-manager.git
cd phase-manager

# Link to Claude Code plugins directory
ln -s $(pwd) ~/.claude/plugins/phase-manager

# Test commands
/list-plan

Guidelines

Follow existing code style
Add tests for new features
Update documentation
Keep commands idempotent
Maintain backward compatibility

❓ FAQ

How is this different from superpowers?

Complementary, not competing:

Superpowers: Core development skills (TDD, debugging, planning, code review)
Dev Phase Manager: Phase and checkpoint management for long-running workflows

Dev Phase Manager is designed to enhance superpowers workflows by adding state persistence across /clear operations.

Do I need superpowers to use this plugin?

No, but recommended. Dev Phase Manager works standalone, but it's designed to integrate seamlessly with superpowers workflows like:

/brainstorming → /writing-plans → /checkpoint-plan → /clear → /resume-plan → /subagent-driven-development

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Claude Code - The amazing CLI tool
Superpowers - Inspiration for workflow enhancement
Community contributors and testers

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: Wiki

🗺️ Roadmap

v1.1: Memory enhancement + commands/ restoration
v1.2: Progress visualization with progress bars
v1.3: Phase dependency management
v1.4: Timeline view for phase history
v2.0: Web UI for phase management

Made with ❤️ for the Claude Code community

Name		Name	Last commit message	Last commit date
Latest commit History 23 Commits
.claude-plugin		.claude-plugin
.github/workflows		.github/workflows
commands		commands
docs		docs
skills		skills
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
GITHUB_SETUP.md		GITHUB_SETUP.md
INSTALLATION.md		INSTALLATION.md
LICENSE		LICENSE
PITCH.md		PITCH.md
PROJECT_SUMMARY.md		PROJECT_SUMMARY.md
PROMOTION_PLAN.md		PROMOTION_PLAN.md
README.md		README.md
RELEASE_CHECKLIST.md		RELEASE_CHECKLIST.md
SOCIAL_MEDIA_TEMPLATES.md		SOCIAL_MEDIA_TEMPLATES.md
test-installation.sh		test-installation.sh
verify-skills.sh		verify-skills.sh

License

uukuguy/dev-phase-manager

Folders and files

Latest commit

History

Repository files navigation

Dev Phase Manager

🎯 Key Features

📍 Checkpoint System

🔄 Phase Stack Management

🤝 Superpowers Integration

🛡️ Idempotency & Safety

📦 Installation

Method 1: From GitHub (Recommended)

Method 2: Local Development

🚀 Quick Start

Basic Workflow

Multi-Phase Workflow

🏛️ Architecture: Commands + Skills

📚 Commands Reference

Core Commands

/checkpoint-plan

/resume-plan

/checkpoint-progress

/start-phase

/end-phase

/list-plan

/mem-save

/mem-search

🏗️ Architecture

File Structure

Phase Stack Format

Checkpoint Format

🔗 Integration with Superpowers

Enhanced Workflow

Non-Invasive Design

📖 Use Cases

Use Case 1: Long-Running Feature Development

Use Case 2: Urgent Interruption Handling

Use Case 3: Context Management

🤝 Contributing

Development Setup

Guidelines

❓ FAQ

How is this different from superpowers?

Do I need superpowers to use this plugin?

📄 License

🙏 Acknowledgments

📞 Support

🗺️ Roadmap

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

`/checkpoint-plan`

`/resume-plan`

`/checkpoint-progress`

`/start-phase`

`/end-phase`

`/list-plan`

`/mem-save`

`/mem-search`

Packages