From 424770d58cc06e6b7d4b6173f6cea2dc00f1312c Mon Sep 17 00:00:00 2001
From: catlog22 <catlog22@github.com>
Date: Mon, 13 Oct 2025 11:14:20 +0800
Subject: [PATCH] docs: add beginner-friendly getting started guides
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Generated comprehensive beginner guides using Gemini analysis:
- GETTING_STARTED.md (English version, 151 lines)
- GETTING_STARTED_CN.md (Chinese version, 151 lines)

Content includes:
- 5-minute quick start tutorial
- Core concepts explanation with simple language
- Common scenarios (feature development, UI design, bug fixing)
- Troubleshooting guide
- Advanced learning paths

Features:
- Emoji-enhanced readability
- Step-by-step instructions with copy-paste commands
- Real-world examples for each concept
- Progressive learning approach

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 GETTING_STARTED.md    | 151 ++++++++++++++++++++++++++++++++++++++++++
 GETTING_STARTED_CN.md | 151 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 302 insertions(+)
 create mode 100644 GETTING_STARTED.md
 create mode 100644 GETTING_STARTED_CN.md

diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md
new file mode 100644
index 00000000..fe9a0da1
--- /dev/null
+++ b/GETTING_STARTED.md
@@ -0,0 +1,151 @@
+
+# 🚀 Claude Code Workflow (CCW) - Getting Started Guide
+
+Welcome to Claude Code Workflow (CCW)! This guide will help you get up and running in 5 minutes and experience AI-driven automated software development.
+
+---
+
+## ⏱️ 5-Minute Quick Start
+
+Let's build a "Hello World" web application from scratch with a simple example.
+
+### Step 1: Install CCW
+
+First, make sure you have installed CCW according to the [Installation Guide](INSTALL.md).
+
+### Step 2: Start a Workflow Session
+
+Think of a "session" as a dedicated project folder. CCW will store all files related to your current task here.
+
+```bash
+/workflow:session:start "My First Web App"
+```
+
+You will see that the system has created a new session, for example, `WFS-my-first-web-app`.
+
+### Step 3: Create an Execution Plan
+
+Now, tell CCW what you want to do. CCW will analyze your request and automatically generate a detailed, executable task plan.
+
+```bash
+/workflow:plan "Create a simple Express API that returns Hello World at the root path"
+```
+
+This command kicks off a fully automated planning process, which includes:
+1.  **Context Gathering**: Analyzing your project environment.
+2.  **Agent Analysis**: AI agents think about the best implementation path.
+3.  **Task Generation**: Creating specific task files (in `.json` format).
+
+### Step 4: Execute the Plan
+
+Once the plan is created, you can command the AI agents to start working.
+
+```bash
+/workflow:execute
+```
+
+You will see CCW's agents (like `@code-developer`) begin to execute tasks one by one. It will automatically create files, write code, and install dependencies.
+
+### Step 5: Check the Status
+
+Want to know the progress? You can check the status of the current workflow at any time.
+
+```bash
+/workflow:status
+```
+
+This will show the completion status of tasks, the currently executing task, and the next steps.
+
+---
+
+## 🧠 Core Concepts Explained
+
+Understanding these concepts will help you use CCW more effectively:
+
+-   **Workflow Session**
+    > Like an independent sandbox or project space, used to isolate the context, files, and history of different tasks. All related files are stored in the `.workflow/WFS-<session-name>/` directory.
+
+-   **Task**
+    > An atomic unit of work, such as "create API route" or "write test case." Each task is a `.json` file that defines the goal, context, and execution steps in detail.
+
+-   **Agent**
+    > An AI assistant specialized in a specific domain. For example:
+    > -   `@code-developer`: Responsible for writing and implementing code.
+    > -   `@test-fix-agent`: Responsible for running tests and automatically fixing failures.
+    > -   `@ui-design-agent`: Responsible for UI design and prototype creation.
+
+-   **Workflow**
+    > A series of predefined, collaborative commands used to orchestrate different agents and tools to achieve a complex development goal (e.g., `plan`, `execute`, `test-gen`).
+
+---
+
+## 🛠️ Common Scenarios
+
+### Scenario 1: Developing a New Feature (as shown above)
+
+This is the most common use case, following the "start session → plan → execute" pattern.
+
+```bash
+# 1. Start a session
+/workflow:session:start "User Login Feature"
+
+# 2. Create a plan
+/workflow:plan "Implement JWT-based user login and registration"
+
+# 3. Execute
+/workflow:execute
+```
+
+### Scenario 2: UI Design
+
+CCW has powerful UI design capabilities, capable of generating complex UI prototypes from simple text descriptions.
+
+```bash
+# 1. Start a UI design workflow
+/workflow:ui-design:explore-auto --prompt "A modern, clean admin dashboard login page with username, password fields and a login button"
+
+# 2. View the generated prototype
+# After the command finishes, it will provide a path to a compare.html file. Open it in your browser to preview.
+```
+
+### Scenario 3: Fixing a Bug
+
+CCW can help you analyze and fix bugs.
+
+```bash
+# 1. Use the bug-index command to analyze the problem
+/cli:mode:bug-index "Incorrect success message even with wrong password on login"
+
+# 2. The AI will analyze the relevant code and generate a fix plan. You can then execute this plan.
+/workflow:execute
+```
+
+---
+
+## ❓ Troubleshooting
+
+-   **Problem: Prompt shows "No active session found"**
+    > **Reason**: You haven't started a workflow session, or the current session is complete.
+    > **Solution**: Use `/workflow:session:start "Your task description"` to start a new session.
+
+-   **Problem: Command execution fails or gets stuck**
+    > **Reason**: It could be a network issue, AI model limitation, or the task is too complex.
+    > **Solution**:
+    > 1.  First, try using `/workflow:status` to check the current state.
+    > 2.  Check the log files in the `.workflow/WFS-<session-name>/.chat/` directory for detailed error messages.
+    > 3.  If the task is too complex, try breaking it down into smaller tasks and then use `/workflow:plan` to create a new plan.
+
+---
+
+## 📚 Next Steps for Advanced Learning
+
+Once you've mastered the basics, you can explore CCW's more powerful features:
+
+1.  **Test-Driven Development (TDD)**: Use `/workflow:tdd-plan` to create a complete TDD workflow. The AI will first write failing tests, then write code to make them pass, and finally refactor.
+
+2.  **Multi-Agent Brainstorming**: Use `/workflow:brainstorm:auto-parallel` to have multiple AI agents with different roles (like System Architect, Product Manager, Security Expert) analyze a topic simultaneously and generate a comprehensive report.
+
+3.  **Custom Agents and Commands**: You can modify the files in the `.claude/agents/` and `.claude/commands/` directories to customize agent behavior and workflows to fit your team's specific needs.
+
+
+Hope this guide helps you get started smoothly with CCW!
diff --git a/GETTING_STARTED_CN.md b/GETTING_STARTED_CN.md
new file mode 100644
index 00000000..c58643fe
--- /dev/null
+++ b/GETTING_STARTED_CN.md
@@ -0,0 +1,151 @@
+
+# 🚀 Claude Code Workflow (CCW) - 快速上手指南
+
+欢迎来到 Claude Code Workflow (CCW)！本指南将帮助您在 5 分钟内快速入门，体验由 AI 驱动的自动化软件开发流程。
+
+---
+
+## ⏱️ 5 分钟快速入门
+
+让我们通过一个简单的例子，从零开始构建一个 "Hello World" Web 应用。
+
+### 第 1 步：安装 CCW
+
+首先，请确保您已经根据 [安装指南](INSTALL_CN.md) 完成了 CCW 的安装。
+
+### 第 2 步：启动一个工作流会话
+
+把“会话”想象成一个专门的项目文件夹。CCW 会在这里存放所有与您当前任务相关的文件。
+
+```bash
+/workflow:session:start "我的第一个 Web 应用"
+```
+
+您会看到系统创建了一个新的会话，例如 `WFS-我的第一个-web-应用`。
+
+### 第 3 步：创建执行计划
+
+现在，告诉 CCW 您想做什么。CCW 会分析您的需求，并自动生成一个详细的、可执行的任务计划。
+
+```bash
+/workflow:plan "创建一个简单的 Express API，在根路径返回 Hello World"
+```
+
+这个命令会启动一个完全自动化的规划流程，包括：
+1.  **上下文收集**：分析您的项目环境。
+2.  **智能体分析**：AI 智能体思考最佳实现路径。
+3.  **任务生成**：创建具体的任务文件（`.json` 格式）。
+
+### 第 4 步：执行计划
+
+当计划创建完毕后，您就可以命令 AI 智能体开始工作了。
+
+```bash
+/workflow:execute
+```
+
+您会看到 CCW 的智能体（如 `@code-developer`）开始逐一执行任务。它会自动创建文件、编写代码、安装依赖。
+
+### 第 5 步：查看状态
+
+想知道进展如何？随时可以查看当前工作流的状态。
+
+```bash
+/workflow:status
+```
+
+这会显示任务的完成情况、当前正在执行的任务以及下一步计划。
+
+---
+
+## 🧠 核心概念解析
+
+理解这几个概念，能帮助您更好地使用 CCW：
+
+-   **工作流会话 (Workflow Session)**
+    > 就像一个独立的沙盒或项目空间，用于隔离不同任务的上下文、文件和历史记录。所有相关文件都存放在 `.workflow/WFS-<会话名>/` 目录下。
+
+-   **任务 (Task)**
+    > 一个原子化的工作单元，例如“创建 API 路由”、“编写测试用例”。每个任务都是一个 `.json` 文件，详细定义了目标、上下文和执行步骤。
+
+-   **智能体 (Agent)**
+    > 专门负责特定领域工作的 AI 助手。例如：
+    > -   `@code-developer`: 负责编写和实现代码。
+    > -   `@test-fix-agent`: 负责运行测试并自动修复失败的用例。
+    > -   `@ui-design-agent`: 负责 UI 设计和原型创建。
+
+-   **工作流 (Workflow)**
+    > 一系列预定义的、相互协作的命令，用于编排不同的智能体和工具，以完成一个复杂的开发目标（如 `plan`、`execute`、`test-gen`）。
+
+---
+
+## 🛠️ 常见场景示例
+
+### 场景 1：开发一个新功能（如上所示）
+
+这是最常见的用法，遵循“启动会话 → 规划 → 执行”的模式。
+
+```bash
+# 1. 启动会话
+/workflow:session:start "用户登录功能"
+
+# 2. 创建计划
+/workflow:plan "实现基于 JWT 的用户登录和注册功能"
+
+# 3. 执行
+/workflow:execute
+```
+
+### 场景 2：进行 UI 设计
+
+CCW 拥有强大的 UI 设计能力，可以从简单的文本描述生成复杂的 UI 原型。
+
+```bash
+# 1. 启动一个 UI 设计工作流
+/workflow:ui-design:explore-auto --prompt "一个现代、简洁的管理后台登录页面，包含用户名、密码输入框和登录按钮"
+
+# 2. 查看生成的原型
+# 命令执行完毕后，会提供一个 compare.html 文件的路径，在浏览器中打开即可预览。
+```
+
+### 场景 3：修复一个 Bug
+
+CCW 可以帮助您分析并修复 Bug。
+
+```bash
+# 1. 使用 bug-index 命令分析问题
+/cli:mode:bug-index "用户登录时，即使密码错误也提示成功"
+
+# 2. AI 会分析相关代码，并生成一个修复计划。然后您可以执行这个计划。
+/workflow:execute
+```
+
+---
+
+## ❓ 常见问题排查 (Troubleshooting)
+
+-   **问题：提示 "No active session found" (未找到活动会话)**
+    > **原因**：您还没有启动一个工作流会话，或者当前会话已完成。
+    > **解决方法**：使用 `/workflow:session:start "您的任务描述"` 来开始一个新会话。
+
+-   **问题：命令执行失败或卡住**
+    > **原因**：可能是网络问题、AI 模型限制或任务过于复杂。
+    > **解决方法**：
+    > 1.  首先尝试使用 `/workflow:status` 检查当前状态。
+    > 2.  查看 `.workflow/WFS-<会话名>/.chat/` 目录下的日志文件，获取详细错误信息。
+    > 3.  如果任务过于复杂，尝试将其分解为更小的任务，然后使用 `/workflow:plan` 重新规划。
+
+---
+
+## 📚 进阶学习路径
+
+当您掌握了基础用法后，可以探索 CCW 更强大的功能：
+
+1.  **测试驱动开发 (TDD)**: 使用 `/workflow:tdd-plan` 来创建一个完整的 TDD 工作流，AI 会先编写失败的测试，然后编写代码让测试通过，最后进行重构。
+
+2.  **多智能体头脑风暴**: 使用 `/workflow:brainstorm:auto-parallel` 让多个不同角色的 AI 智能体（如系统架构师、产品经理、安全专家）同时对一个主题进行分析，并生成一份综合报告。
+
+3.  **自定义智能体和命令**: 您可以修改 `.claude/agents/` 和 `.claude/commands/` 目录下的文件，来定制符合您团队特定需求的智能体行为和工作流。
+
+
+希望本指南能帮助您顺利开启 CCW 之旅！