mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +08:00
d9fcdad949
Refactor workflow directory structure to improve clarity and robustness by introducing dedicated sessions/ subdirectory for active sessions. ## Directory Structure Changes ### Before (Old Structure) ``` .workflow/ ├── .active-WFS-session-1 # Marker files (fragile) ├── WFS-session-1/ # Active sessions mixed with config ├── WFS-session-2/ ├── project.json └── .archives/ # Archived sessions ``` ### After (New Structure) ``` .workflow/ ├── project.json # Project metadata ├── sessions/ # [NEW] All active sessions │ └── WFS-session-1/ └── archives/ # Archived sessions (removed dot prefix) ``` ## Key Improvements 1. **Physical Isolation**: Active sessions now in dedicated sessions/ subdirectory 2. **No Marker Files**: Removed fragile .active-* marker file mechanism 3. **Directory-Based State**: Session state determined by directory location - In sessions/ = active - In archives/ = archived 4. **Simpler Discovery**: `ls .workflow/sessions/` instead of `find .workflow/ -name ".active-*"` 5. **Cleaner Root**: .workflow/ root now only contains project.json, sessions/, archives/ ## Path Transformations | Old Pattern | New Pattern | |-------------|-------------| | `find .workflow/ -name ".active-*"` | `find .workflow/sessions/ -name "WFS-*" -type d` | | `.workflow/WFS-[slug]/` | `.workflow/sessions/WFS-[slug]/` | | `.workflow/.archives/` | `.workflow/archives/` | | `touch .workflow/.active-*` | *Removed* | | `rm .workflow/.active-*` | *Removed* | ## Modified Commands ### session/start.md - Update session creation path to .workflow/sessions/WFS-*/ - Remove .active-* marker file creation - Update session discovery to use directory listing - Updated all 3 modes: Discovery, Auto, Force New ### session/complete.md - Update session move from sessions/ to archives/ - Remove .active-* marker file deletion - Update manifest path to archives/manifest.json - Update agent prompts with new paths ### status.md - Update session discovery to find .workflow/sessions/ - Update all session file path references - Update archive query examples ### execute.md - Update session discovery logic - Update all task file paths to include sessions/ prefix - Update context package paths - Update error handling documentation ## Benefits - **Robustness**: Eliminates marker file state inconsistency risk - **Clarity**: Clear separation between active and archived sessions - **Simplicity**: Session discovery is straightforward directory listing - **Alignment**: Closer to OpenSpec's three-layer structure (specs/changes/archive) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
🚀 Claude Code Workflow (CCW)
Claude Code Workflow (CCW) transforms AI development from simple prompt chaining into a robust, context-first orchestration system. It solves execution uncertainty and error accumulation through structured planning, deterministic execution, and intelligent multi-model orchestration.
🎉 Version 5.8.1: Lite-Plan Workflow & CLI Tools Enhancement
Core Improvements:
- ✨ Lite-Plan Workflow (
/workflow:lite-plan) - Lightweight interactive planning with intelligent automation
- Three-Dimensional Multi-Select Confirmation: Task approval + Execution method + Code review tool
- Smart Code Exploration: Auto-detects when codebase context is needed (use
-eflag to force)- Parallel Task Execution: Identifies independent tasks for concurrent execution
- Flexible Execution: Choose between Agent (@code-developer) or CLI (Gemini/Qwen/Codex)
- Optional Post-Review: Built-in code quality analysis with your choice of AI tool
- ✨ CLI Tools Optimization - Simplified command syntax with auto-model-selection
- Removed
-mparameter requirement for Gemini, Qwen, and Codex (auto-selects best model)- Clearer command structure and improved documentation
- 🔄 Execution Workflow Enhancement - Streamlined phases with lazy loading strategy
- 🎨 CLI Explore Agent - Improved visibility with yellow color scheme
See CHANGELOG.md for full details.
📚 New to CCW? Check out the Getting Started Guide for a beginner-friendly 5-minute tutorial!
✨ Core Concepts
CCW is built on a set of core principles that differentiate it from traditional AI development approaches:
- Context-First Architecture: Pre-defined context gathering eliminates execution uncertainty by ensuring agents have the correct information before implementation.
- JSON-First State Management: Task states live in
.task/IMPL-*.jsonfiles as the single source of truth, enabling programmatic orchestration without state drift. - Autonomous Multi-Phase Orchestration: Commands chain specialized sub-commands and agents to automate complex workflows with zero user intervention.
- Multi-Model Strategy: Leverages the unique strengths of different AI models (Gemini for analysis, Codex for implementation) for superior results.
- Hierarchical Memory System: A 4-layer documentation system provides context at the appropriate level of abstraction, preventing information overload.
- Specialized Role-Based Agents: A suite of agents (
@code-developer,@test-fix-agent, etc.) mirrors a real software team to handle diverse tasks.
⚙️ Installation
For detailed installation instructions, please refer to the INSTALL.md guide.
🚀 Quick One-Line Installation
Windows (PowerShell):
Invoke-Expression (Invoke-WebRequest -Uri "https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1" -UseBasicParsing).Content
Linux/macOS (Bash/Zsh):
bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.sh)
✅ Verify Installation
After installation, open Claude Code and check if the workflow commands are available by running:
/workflow:session:list
If the slash commands (e.g., /workflow:*) are recognized, the installation was successful.
🛠️ Command Reference
CCW provides a rich set of commands for managing workflows, tasks, and interacting with AI tools. For a complete list and detailed descriptions of all available commands, please see the COMMAND_REFERENCE.md file.
For a detailed technical specification of every command, see the COMMAND_SPEC.md.
💡 Need Help? Use the Interactive Command Guide
CCW includes a built-in command-guide skill to help you discover and use commands effectively:
CCW-help- Get interactive help and command recommendationsCCW-issue- Report bugs or request features with guided templates
The command guide provides:
- 🔍 Smart Command Search - Find commands by keyword, category, or use-case
- 🤖 Next-Step Recommendations - Get suggestions for what to do after any command
- 📖 Detailed Documentation - View parameters, examples, and best practices
- 🎓 Beginner Onboarding - Learn the top 14 essential commands with a guided learning path
- 📝 Issue Reporting - Generate standardized bug reports and feature requests
Example Usage:
User: "CCW-help"
→ Interactive menu with command search, recommendations, and documentation
User: "What's next after /workflow:plan?"
→ Recommends /workflow:execute, /workflow:action-plan-verify, with workflow patterns
User: "CCW-issue"
→ Guided template generation for bugs, features, or questions
🚀 Getting Started
The best way to get started is to follow the 5-minute tutorial in the Getting Started Guide.
Here is a quick example of a common development workflow:
Option 1: Lite-Plan Workflow (⚡ Recommended for Quick Tasks)
Lightweight interactive workflow with in-memory planning and immediate execution:
# Basic usage with auto-detection
/workflow:lite-plan "Add JWT authentication to user login"
# Force code exploration
/workflow:lite-plan -e "Refactor logging module for better performance"
# Preset CLI tool
/workflow:lite-plan --tool codex "Add unit tests for auth service"
Interactive Flow:
- Phase 1: Automatic task analysis and smart code exploration (if needed)
- Phase 2: Answer clarification questions (if any)
- Phase 3: Review generated plan with task breakdown
- Phase 4: Three-dimensional confirmation:
- ✅ Confirm/Modify/Cancel task
- 🔧 Choose execution: Agent / Provide Plan / CLI (Gemini/Qwen/Codex)
- 🔍 Optional code review: No / Claude / Gemini / Qwen / Codex
- Phase 5: Watch real-time execution with live task tracking
Option 2: Full Workflow (Comprehensive Planning)
Traditional multi-phase workflow for complex projects:
- Create a Plan (automatically starts a session):
/workflow:plan "Implement JWT-based user login and registration" - Execute the Plan:
/workflow:execute - Check Status (optional):
/workflow:status
🤝 Contributing & Support
- Repository: GitHub - Claude-Code-Workflow
- Issues: Report bugs or request features on GitHub Issues.
- Discussions: Join the Community Forum.
📄 License
This project is licensed under the MIT License. See the LICENSE file for details.