Claude-Code-Workflow/FAQ.md

❓ Frequently Asked Questions (FAQ)

This document answers common questions about Claude Code Workflow (CCW).

---

📋 Table of Contents

• General Questions
• Installation & Setup
• Usage & Workflows
• Commands & Syntax
• Sessions & Tasks
• Agents & Tools
• Memory System
• Troubleshooting
• Advanced Topics

---

🌟 General Questions

What is Claude Code Workflow (CCW)?

CCW is an advanced AI-powered development automation framework for Claude Code. It transforms AI development from simple prompt chaining into a robust, context-first orchestration system with structured planning, deterministic execution, and intelligent multi-model orchestration.

How is CCW different from using Claude Code directly?

Claude Code (Vanilla)	Claude Code with CCW
Manual task management	Automated workflow orchestration
No context preservation	Hierarchical memory system (CLAUDE.md)
Single conversation context	Session-based project isolation
Manual planning	Automated multi-phase planning
One model/approach	Multi-model strategy (Gemini, Qwen, Codex)
No quality gates	Built-in verification and review

Do I need external CLI tools (Gemini, Qwen, Codex)?

No, they're optional. CCW can work with Claude Code alone. External CLI tools enhance CCW's capabilities by:

• Providing specialized analysis (Gemini)
• Enabling autonomous development (Codex)
• Supporting architectural planning (Qwen)

But all core workflows function without them.

Is CCW suitable for beginners?

Yes! CCW provides:

• Simple commands like /workflow:plan and /workflow:execute
• Interactive command guide (CCW-help)
• Comprehensive documentation
• Built-in examples and tutorials

Start with the 5-minute Quick Start to get a feel for it.

What languages/frameworks does CCW support?

CCW is language-agnostic. It works with any programming language or framework that Claude Code supports:

• JavaScript/TypeScript (Node.js, React, Vue, etc.)
• Python (Django, Flask, FastAPI, etc.)
• Java/Kotlin (Spring Boot, etc.)
• Go, Rust, C++, C#, Ruby, PHP, etc.

Is CCW free?

Yes! CCW is open-source under the MIT License. However, you need:

• Claude Code subscription (for the base platform)
• Optional: API keys for external CLI tools (Gemini, Qwen, Codex)

---

🔧 Installation & Setup

How do I install CCW?

One-line installation:

Windows:

Invoke-Expression (Invoke-WebRequest -Uri "https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1" -UseBasicParsing).Content

Linux/macOS:

bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.sh)

See INSTALL.md for detailed instructions.

How do I verify CCW is installed correctly?

Open Claude Code and run:

/workflow:session:list

If the command is recognized, installation succeeded.

Where are CCW files installed?

CCW installs to your home directory:

~/.claude/
├── agents/       # Agent definitions
├── commands/     # Slash commands
├── skills/       # Agent skills
└── workflows/    # Workflow documentation

Can I customize CCW after installation?

Yes! All files in ~/.claude/ can be customized:

• Modify agent prompts in agents/
• Add custom commands in commands/
• Adjust workflow templates in workflows/

How do I update CCW to the latest version?

Run the installation command again. It will overwrite existing files with the latest version.

Note: Custom modifications in ~/.claude/ will be overwritten. Back up customizations first.

Do I need to install CLI tools?

Optional. To use CLI tools:

1. Gemini CLI: Follow setup instructions
2. Qwen CLI: Follow setup instructions
3. Codex CLI: Follow setup instructions

Then initialize with:

/cli:cli-init

---

🚀 Usage & Workflows

What's the simplest way to use CCW?

Two-command workflow:

/workflow:plan "Your feature description"
/workflow:execute

That's it! CCW handles planning, task generation, and implementation.

What's the difference between /workflow:plan and /workflow:lite-plan?

/workflow:plan	/workflow:lite-plan
Full 5-phase planning	Lightweight interactive planning
Creates persistent artifacts	In-memory planning
Best for complex projects	Best for quick tasks
Includes verification phase	Streamlined flow
Suitable for team collaboration	Suitable for solo development

Use /workflow:plan for: Complex features, team projects, when you need detailed documentation

Use /workflow:lite-plan for: Quick fixes, small features, rapid prototyping

When should I use brainstorming workflows?

Use /workflow:brainstorm:auto-parallel when:

• Feature requires multiple perspectives (architecture, security, UX, etc.)
• You need thorough requirements analysis
• Architecture decisions have significant impact
• Starting a complex project from scratch

Example:

/workflow:brainstorm:auto-parallel "Build real-time collaborative document editing system"
/workflow:plan
/workflow:execute

How do I check the status of my workflow?

/workflow:status

Shows:

• Current session
• Task completion status
• Currently executing task
• Next steps

Can I run multiple workflows simultaneously?

Yes! CCW supports parallel sessions:

# Session 1: Authentication
/workflow:session:start "User Authentication"
/workflow:plan "JWT-based authentication"

# Session 2: Payment
/workflow:session:start "Payment Integration"
/workflow:plan "Stripe payment integration"

# Execute each session independently
/workflow:execute --session WFS-user-authentication
/workflow:execute --session WFS-payment-integration

How do I resume a paused workflow?

/workflow:session:resume

Automatically detects and resumes the most recent paused session.

---

💬 Commands & Syntax

Where can I find all available commands?

See COMMAND_REFERENCE.md for a complete list.

Or use the interactive guide:

CCW-help

What's the difference between /cli:* and /workflow:* commands?

/cli:* commands:

• Direct access to external AI tools
• No workflow session required
• Quick one-off tasks
• Examples: /cli:analyze, /cli:chat

/workflow:* commands:

• Multi-phase orchestration
• Session-based
• Complex development workflows
• Examples: /workflow:plan, /workflow:execute

How do I use command flags?

Most commands support flags for customization:

# Basic usage
/workflow:plan "Feature description"

# With CLI execution flag
/workflow:plan --cli-execute "Feature description"

# With tool selection
/cli:analyze --tool gemini "Code analysis"

# With multiple flags
/workflow:ui-design:explore-auto --prompt "Login page" --style-variants 3 --layout-variants 2

Can I use natural language instead of commands?

Yes! Claude understands semantic invocation:

Instead of:

/cli:analyze --tool gemini "Authentication module"

You can say:

"Use Gemini to analyze the authentication module architecture"

Claude will automatically execute the appropriate command.

What does the -e or --enhance flag do?

The -e flag triggers the prompt-enhancer skill in natural conversation:

User: "Analyze authentication module -e"

Claude will expand and enhance your request for better results.

Note: --enhance in CLI commands (e.g., /cli:analyze --enhance) is a different feature built into CLI tools.

---

📦 Sessions & Tasks

What is a workflow session?

A workflow session is an isolated workspace for a specific feature or project. It contains:

• Task definitions (JSON files)
• Brainstorming artifacts
• Generated plans
• Chat logs
• Session state

Location: .workflow/active/WFS-<session-name>/

How are sessions created?

Sessions are created automatically when you run:

/workflow:session:start "Feature name"
/workflow:plan "Feature description"
/workflow:brainstorm:auto-parallel "Topic"

How do I list all sessions?

/workflow:session:list

Shows all sessions with their status (active, paused, completed).

What happens when I complete a session?

/workflow:session:complete

CCW will:

1. Archive session to .workflow/archives/
2. Remove active flag
3. Generate lessons learned
4. Update session manifest

What are tasks in CCW?

Tasks are atomic units of work stored as JSON files in .task/ directory:

.workflow/active/WFS-feature/.task/
├── IMPL-1.json       # Main task
├── IMPL-1.1.json     # Subtask
└── IMPL-2.json       # Another task

Each task contains:

• Title and description
• Requirements and acceptance criteria
• Context and focus paths
• Implementation approach
• Status (pending, in_progress, completed)

How deep can task hierarchies go?

Maximum 2 levels:

• IMPL-1 - Main task
• IMPL-1.1, IMPL-1.2 - Subtasks
• No further nesting (no IMPL-1.1.1)

Can I manually edit task JSON files?

Yes, but:

• ⚠️ JSON files are the source of truth
• ⚠️ Markdown documents are read-only views
• ✅ Edit JSON directly for fine-grained control
• ✅ Validate JSON syntax after editing
• ✅ Use /workflow:status to regenerate views

---

🤖 Agents & Tools

What agents are available in CCW?

Agent	Purpose
@code-developer	Code implementation
@test-fix-agent	Test generation and fixing
@ui-design-agent	UI design and prototyping
@action-planning-agent	Task planning and decomposition
@cli-execution-agent	Autonomous CLI task handling
@cli-explore-agent	Codebase exploration
@context-search-agent	Context gathering
@doc-generator	Documentation generation
@memory-bridge	Memory system updates

See ARCHITECTURE.md for details.

How do agents get selected for tasks?

Automatic selection based on task type defined in JSON:

{
  "meta": {
    "agent": "code-developer"
  }
}

CCW automatically invokes the appropriate agent during /workflow:execute.

What's the difference between Gemini, Qwen, and Codex?

Tool	Strengths	Best For
Gemini	Deep analysis, pattern recognition	Code exploration, architecture analysis
Qwen	System design, planning	Architectural planning, system design
Codex	Autonomous implementation	Feature development, bug fixes

CCW auto-selects the best tool for each task, but you can override with --tool flag.

Can I create custom agents?

Yes! Create a new file in .claude/agents/:

# My Custom Agent

## Role
Agent description

## Tools Available
- Tool 1
- Tool 2

## Prompt
Agent instructions...

Then reference it in task JSON:

{
  "meta": {
    "agent": "my-custom-agent"
  }
}

---

💾 Memory System

What is the CLAUDE.md memory system?

A hierarchical documentation system that maintains project knowledge across 4 layers:

CLAUDE.md (Project root)
└── src/CLAUDE.md (Source layer)
    └── auth/CLAUDE.md (Module layer)
        └── jwt/CLAUDE.md (Component layer)

Each layer provides context at the appropriate abstraction level.

When should I update memory?

Update memory when:

• After completing a feature
• After refactoring modules
• After changing architecture
• Before starting complex tasks
• Weekly maintenance

What's the difference between memory update commands?

Command	Scope	When to Use
/memory:update-full	Entire project	Major changes, first-time setup, monthly maintenance
/memory:update-related	Changed modules only	Daily development, after feature completion
/memory:load	Task-specific, no files	Quick context for immediate task

How long does memory update take?

• /memory:update-full: 5-20 minutes (depends on project size)
• /memory:update-related: 1-5 minutes (only changed modules)
• /memory:load: <1 minute (no file updates)

Do I need to update memory manually?

Recommended but not required. Benefits of regular updates:

• ✅ Higher quality AI outputs
• ✅ Accurate pattern recognition
• ✅ Better context understanding
• ✅ Reduced hallucinations

Without updates:

• ⚠️ AI may reference outdated code
• ⚠️ Incorrect architectural assumptions
• ⚠️ Lower output quality

Can I exclude files from memory?

Yes! Use ignore files:

• .geminiignore - For Gemini CLI
• .qwenignore - For Qwen CLI
• .gitignore - Automatically respected

Example .geminiignore:

node_modules/
dist/
*.log
*.test.js

---

🔧 Troubleshooting

"No active session found" error

Cause: No workflow session is currently active.

Solution:

# Option 1: Start new session
/workflow:session:start "Feature name"

# Option 2: Resume existing session
/workflow:session:resume

Command execution fails or hangs

Troubleshooting steps:

1. Check status:

   /workflow:status
   

2. Review logs:

   # Session logs location
   .workflow/active/WFS-<session>/.chat/
   

3. Simplify task: Break complex requests into smaller tasks

4. Check CLI tools: Ensure external tools (if used) are properly configured

Task execution produces errors

Common causes:

1. Outdated memory: Run /memory:update-related
2. Insufficient context: Add more details to task requirements
3. Tool misconfiguration: Check CLI tool setup with /cli:cli-init

Memory update fails

Solutions:

1. Check file permissions: Ensure write access to project
2. Try different tool:

   /memory:update-full --tool qwen
   

3. Update incrementally:

   /memory:update-related
   

Workflow gets stuck in a phase

Steps:

1. Check current phase:

   /workflow:status
   

2. Review session JSON:

   cat .workflow/active/WFS-<session>/workflow-session.json
   

3. Manually advance (if needed): Edit session JSON to update phase

4. Restart session:

   /workflow:session:complete
   /workflow:session:start "New attempt"
   

CLI tools not working

Checklist:

1. ✅ Tools installed correctly?
2. ✅ API keys configured?
3. ✅ .gemini/ or .qwen/ directories exist?
4. ✅ Configuration files valid?

Re-initialize:

/cli:cli-init --tool gemini

Performance is slow

Optimization tips:

1. Use incremental updates:

   /memory:update-related  # Instead of update-full
   

2. Exclude unnecessary files: Add to .geminiignore or .qwenignore

3. Break down large tasks: Smaller tasks = faster execution

4. Use lite workflows:

   /workflow:lite-plan  # Instead of full workflow:plan
   

---

🚀 Advanced Topics

How does CCW handle dependencies between tasks?

Tasks can reference dependencies in their JSON:

{
  "id": "IMPL-2",
  "dependencies": ["IMPL-1"],
  "context": {
    "inherited_from": "IMPL-1"
  }
}

CCW ensures dependencies are completed before dependent tasks execute.

Can I integrate CCW with CI/CD pipelines?

Yes! CCW can be used in automated workflows:

1. Generate tests:

   /workflow:test-gen WFS-feature
   /workflow:execute
   

2. Run verification:

   /workflow:action-plan-verify
   

3. Automated reviews:

   /workflow:review --type security
   

How do I create custom workflows?

Combine existing commands:

# Custom TDD workflow
/workflow:tdd-plan "Feature"
/workflow:execute
/workflow:tdd-verify
/workflow:review --type quality

Or create custom command in .claude/commands/.

What's the JSON-first architecture?

Principle: JSON files are the single source of truth for all task state.

• ✅ JSON files contain actual state
• ❌ Markdown documents are read-only generated views
• ✅ Edit JSON to change state
• ❌ Never edit markdown documents

Benefits:

• No synchronization complexity
• Programmatic access
• Clear data model
• Deterministic state

How does context flow between agents?

Agents share context through:

1. Session JSON: Shared session state
2. Task JSON: Task-specific context
3. CLAUDE.md: Project knowledge base
4. Flow Control: Pre-analysis and implementation approach

Can I use CCW for non-code projects?

Yes! CCW can manage any structured project:

• Documentation writing
• Content creation
• Data analysis
• Research projects
• Process automation

How do I migrate from one CCW version to another?

1. Backup customizations: Save .claude/ modifications
2. Run installation: Install new version
3. Restore customizations: Reapply your changes
4. Check changelog: Review breaking changes in CHANGELOG.md
5. Test workflows: Verify existing workflows work

Where can I get more help?

• 📖 Documentation: README.md, GETTING_STARTED.md
• 💬 Discussions: GitHub Discussions
• 🐛 Issues: GitHub Issues
• 🤖 Command Guide: CCW-help within Claude Code
• 📚 Examples: EXAMPLES.md

---

📚 Additional Resources

• Getting Started Guide - 5-minute tutorial
• Architecture Overview - System design
• Command Reference - All commands
• Contributing Guide - How to contribute
• Examples - Real-world use cases
• Changelog - Version history

---

Last Updated: 2025-11-20 Version: 5.8.1

Didn't find your question? Ask in GitHub Discussions!