- Clear side-by-side comparison of current vs proposed structure
- Safety indicators (safe vs dangerous operations)
- Command output examples showing the improvements
- User experience improvements with concrete examples
- Performance impact analysis
- Timeline and decision framework
- Complements OUTPUT_DIRECTORY_REORGANIZATION.md with visual summary
Major improvements to workflow understanding and guidance:
1. New Document: WORKFLOW_DECISION_GUIDE.md
- Comprehensive decision flowchart for full software lifecycle
- Interactive Mermaid diagram with 40+ decision points
- Clear guidance on when to use each command
- Real-world scenarios for all workflow types
- Quick reference tables by knowledge level, project stage, and mode
- Expert tips and common pitfalls
2. Clarified Brainstorm vs Plan Relationship
Core concept correction:
- Brainstorm: Use when you know WHAT to build, NOT HOW
- Plan: Use when you know both WHAT and HOW
- Plan can accept user input OR brainstorm output
3. Updated Documentation Files
- GETTING_STARTED.md: Added clear distinction and decision criteria
- GETTING_STARTED_CN.md: Chinese version with same clarifications
- FAQ.md: Enhanced brainstorm usage explanation with workflow comparison table
- README.md: Added Workflow Decision Guide link
- README_CN.md: Added Chinese link to decision guide
4. Key Improvements
When to Use Brainstorming:
- Unclear solution approach (multiple ways to solve)
- Architectural exploration needed
- Requirements clarification (high-level clear, details not)
- Multiple trade-offs to analyze
- Unfamiliar domain
When to Skip Brainstorming:
- Clear implementation approach
- Similar to existing code patterns
- Well-defined requirements
- Simple features
5. Decision Flowchart Covers:
- Ideation phase (know what to build?)
- Design phase (know how to build?)
- UI design phase (need UI design?)
- Planning phase (complexity level?)
- Testing phase (TDD, post-test, test-fix?)
- Review phase (security, architecture, quality?)
- Completion
Benefits:
- Eliminates confusion about brainstorm usage
- Provides clear decision criteria for all commands
- Visual flowchart helps users navigate workflows
- Comprehensive coverage of all development stages
- Reduces trial-and-error in workflow selection
Files modified: 5
Files added: 1 (WORKFLOW_DECISION_GUIDE.md)
Add four new comprehensive documentation files and update READMEs:
New Documentation:
- ARCHITECTURE.md: High-level system architecture overview
* Design philosophy and core principles
* System components and data flow
* Multi-agent system details
* CLI tool integration strategy
* Session and memory management
* Performance optimizations and best practices
- CONTRIBUTING.md: Contributor guidelines
* Code of conduct
* Development setup instructions
* Coding standards and best practices
* Testing guidelines
* Documentation requirements
* Pull request process
* Release process
- FAQ.md: Frequently asked questions
* General questions about CCW
* Installation and setup
* Usage and workflows
* Commands and syntax
* Sessions and tasks
* Agents and tools
* Memory system
* Troubleshooting
* Advanced topics
- EXAMPLES.md: Real-world use cases
* Quick start examples
* Web development (Express, React, e-commerce)
* API development (REST, GraphQL)
* Testing & quality assurance (TDD, test generation)
* Refactoring (monolith to microservices)
* UI/UX design (design systems, landing pages)
* Bug fixes (simple and complex)
* Documentation generation
* DevOps & automation (CI/CD, Docker)
* Complex projects (chat app, analytics dashboard)
Updated Documentation:
- README.md: Added comprehensive documentation section
* Organized docs into categories
* Links to all new documentation files
* Improved navigation structure
- README_CN.md: Added documentation section (Chinese)
* Same organization as English version
* Links to all documentation resources
Benefits:
- Provides clear entry points for new users
- Comprehensive reference for all features
- Real-world examples for practical learning
- Complete contributor onboarding
- Better project discoverability
Remove unnecessary Core Principles sections that reference task-core.md
and workflow-architecture.md from both workflow:replan and task:replan
documentation to align with execute.md style and maintain simplicity.
Removed 104 lines of version history and enhancement documentation (lines 420-523):
- TDD Workflow Enhancements section
- Key Improvements (adopted features from test-gen and plan workflows)
- Workflow Comparison table (Previous vs Current)
- Migration Notes and backward compatibility info
- Configuration examples
This content represented ~19% of the file and was historical/evolutionary
information rather than core command functionality. Focuses the documentation
on what the command does, not how it evolved.
Improves task focus and documentation clarity as identified in audit report.
- Simplify Phase 1-3: Use unified principles (Detect→Classify→Store) to avoid string concatenation and escaping
- Reduce Phase 1-3 from 70+ lines to 30 lines with clear priority chains
- Remove Phase 11 (preview generation): Delegated to generate.md command to eliminate duplication
- Update workflow from 11 phases to 10 phases
- Convert all content to English for internationalization
- Update TodoWrite pattern from 5 tasks to 4 tasks (remove preview generation task)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Updated output paths in various command files to reflect the new structure: `.workflow/sessions/{session_id}/` instead of `.workflow/{session_id}/`.
- Adjusted documentation and code comments to ensure consistency across all agents and commands.
- Ensured that all references to session-related files are correctly pointing to the new directory format.
Issue:
- In Bash version, new_install_manifest creates file immediately
- save_install_manifest calls remove_old_manifests_for_path
- This deletes ALL manifests for the path, including the new one
- Result: "WARNING: Failed to save installation manifest"
Solution:
- Add current_manifest_file parameter to remove_old_manifests_for_path
- Skip deletion if file matches current manifest
- Pass manifest_file to exclude it from deletion
Note: PowerShell version does not have this issue because it creates
the manifest file AFTER deleting old ones (hashtable → file conversion)
- Add Remove-OldManifestsForPath function to automatically clean old manifests
- Modify Save-InstallManifest to remove old manifests before saving new one
- Update Get-AllInstallManifests to return only latest manifest per installation path
- Apply same strategy to both Install-Claude.ps1 (PowerShell) and Install-Claude.sh (Bash)
Benefits:
- Each installation location registers only once
- Only latest version manifest is retained
- Uninstall UI shows only latest version per location
- Prevents manifest file accumulation
Restructure lite-plan.md (844→668 lines, -176) and lite-execute.md (597→569 lines, -28) following agent document patterns. Move Data Structures sections to end as reference, simplify repeated content, improve hierarchical organization. All original content preserved.
Key changes:
- Data Structures moved to end (from beginning)
- Simplified Execution Process to avoid duplication
- Improved section hierarchy and flow
- Consistent structure across both documents
Restructure cli-lite-planning-agent.md and cli-planning-agent.md following action-planning-agent.md's clear hierarchical pattern. Merge duplicate content, consolidate sections, and improve readability while preserving all original information.
Issue found by Gemini analysis:
- executionContext.planObject.tasks was incorrectly documented as string[]
- Actual runtime structure is array of structured task objects (7 fields)
- This caused documentation mismatch between lite-plan and lite-execute
Fix:
- Update executionContext definition to show full task object structure
- Add comment clarifying it's an array of structured objects (7 fields each)
- Aligns with actual implementation and lite-execute consumption logic
Impact: Documentation only (no code changes, runtime behavior was already correct)
Major changes:
- Add cli-lite-planning-agent.md for generating structured task objects
- Upgrade planObject.tasks from string[] to structured objects with 7 fields:
- title, file, action, description (what to do)
- implementation (3-7 steps on how to do it)
- reference (pattern, files, examples to follow)
- acceptance (verification criteria)
- Update lite-execute.md to format structured tasks for Agent/Codex execution
- Clean up agent files: remove "how to call me" sections (cli-planning-agent, cli-explore-agent)
- Update lite-plan.md to use cli-lite-planning-agent for Medium/High complexity tasks
Benefits:
- Execution agents receive complete "how to do" guidance instead of vague descriptions
- Each task includes specific file paths, implementation steps, and verification criteria
- Clear separation of concerns: agents only describe what they do, not how they are called
- Architecture validated by Gemini: 100% consistency, no responsibility leakage
Breaking changes: None (backward compatible via task.title || task fallback in lite-execute)
Changes:
1. Initialize previousExecutionResults array in Step 5.1
2. Add id field to executionCalls objects (format: [Method-Index])
3. Add execution loop structure in Step 5.2 showing sequential processing
4. Clarify executionId comes from executionCalls[currentIndex].id
5. Add comments explaining ID storage for result collection
Benefits:
- Clear definition of where executionId comes from
- Explicit initialization of tracking variables
- Better understanding of execution flow and result collection
- Proper context continuity across multiple execution calls
Improvements:
1. Add plan summary in confirmation question for quick review
2. Add previousExecutionResults tracking for multi-execution flows
3. Include execution result collection mechanism after each call
4. Update both Agent and Codex execution prompts with context continuity
Benefits:
- Subsequent executions can see what previous calls completed
- Avoid duplicate work across multiple execution calls
- Better dependency management and task flow
- Clear context propagation: executionId, status, tasks, outputs, notes
Change Phase 4 confirmation flow from single-step to two-step process:
- Step 4.1: Display complete plan as readable text output
- Step 4.2: Collect three-dimensional input via AskUserQuestion
Benefits:
- Clearer plan presentation (not embedded in question)
- Simpler question interface focused on user decisions
- Better user experience with logical separation
