Refactor documentation for code commands and workflows

- Updated command syntax formatting to use code blocks for clarity in `prep.md`, `review.md`, and `spec.md`. - Enhanced architectural diagrams in `ch01-what-is-claude-dms3.md` and core concepts in `ch03-core-concepts.md` using mermaid syntax for better visualization. - Improved workflow diagrams in `ch04-workflow-basics.md` and `4-level.md` to provide clearer representations of processes. - Added troubleshooting section in `installation.md` to address common installation issues and provide quick start examples. - Revised skill documentation in `claude-meta.md` and `claude-workflow.md` to standardize command triggers and output structures. - Updated best practices and workflow index documentation to enhance readability and understanding of workflow levels and practices.
2026-03-01 15:03:57 +08:00 · 2026-02-28 19:53:24 +08:00
parent b0bfdb907a
commit 4a89f626fc
51 changed files with 741 additions and 619 deletions
--- a/docs/commands/claude/cli.md
+++ b/docs/commands/claude/cli.md
@@ -26,7 +26,7 @@
 **Function**: Generate `.gemini/` and `.qwen/` configuration directories based on workspace tech detection, including settings.json and ignore files.

 **Syntax**:
-```
+```bash
 /cli:cli-init [--tool gemini|qwen|all] [--output path] [--preview]
 ```

@@ -36,7 +36,7 @@
 - `--preview`: Preview mode (don't actually create)

 **Generated File Structure**:
-```
+```plaintext
 .gemini/
 ├── settings.json      # Gemini configuration
 └── ignore            # Ignore patterns
@@ -75,7 +75,7 @@
 **Function**: Interactive code review using Codex CLI via ccw endpoint, supporting configurable review targets, models, and custom instructions.

 **Syntax**:
-```
+```bash
 /cli:codex-review [--uncommitted|--base <branch>|--commit <sha>] [--model <model>] [--title <title>] [prompt]
 ```

--- a/docs/commands/claude/core-orchestration.md
+++ b/docs/commands/claude/core-orchestration.md
@@ -18,7 +18,7 @@
 **Function**: Main workflow orchestrator - intent analysis -> workflow selection -> command chain execution

 **Syntax**:
-```
+```bash
 /ccw "task description"
 ```

@@ -80,7 +80,7 @@ graph TD
 **Function**: Command orchestration tool - analyze tasks, recommend command chains, sequential execution, state persistence

 **Syntax**:
-```
+```bash
 /ccw-coordinator "task description"
 ```

--- a/docs/commands/claude/index.md
+++ b/docs/commands/claude/index.md
@@ -11,7 +11,7 @@
 | **Core Orchestration** | 2 | Main workflow orchestrators (ccw, ccw-coordinator) |
 | **Workflow** | 20+ | Planning, execution, review, TDD, testing workflows |
 | **Session Management** | 6 | Session creation, listing, resuming, completion |
-| **Issue Workflow** | 7 | Issue discovery, planning, queue, execution |
+| **Issue Workflow** | 8 | Issue discovery, planning, queue, execution |
 | **Memory** | 8 | Memory capture, update, document generation |
 | **CLI Tools** | 2 | CLI initialization, Codex review |
 | **UI Design** | 10 | UI design prototype generation, style extraction |
@@ -52,6 +52,7 @@
 | [`/workflow:session:start`](./session.md#start) | Discover existing sessions or start new workflow session | Intermediate |
 | [`/workflow:session:list`](./session.md#list) | List all workflow sessions | Beginner |
 | [`/workflow:session:resume`](./session.md#resume) | Resume most recently paused workflow session | Intermediate |
+| [`/workflow:session:sync`](./session.md#sync) | Quick-sync session work to specs and project-tech | Intermediate |
 | [`/workflow:session:complete`](./session.md#complete) | Mark active workflow session as completed | Intermediate |
 | [`/workflow:session:solidify`](./session.md#solidify) | Crystallize session learnings into project guidelines | Intermediate |

@@ -62,6 +63,7 @@
 | [`/issue:new`](./issue.md#new) | Create structured issue from GitHub URL or text description | Intermediate |
 | [`/issue:discover`](./issue.md#discover) | Discover potential issues from multiple perspectives | Intermediate |
 | [`/issue:discover-by-prompt`](./issue.md#discover-by-prompt) | Discover issues via user prompt | Intermediate |
+| [`/issue:from-brainstorm`](./issue.md#from-brainstorm) | Convert brainstorm session ideas into issue with executable solution | Intermediate |
 | [`/issue:plan`](./issue.md#plan) | Batch plan issue solutions | Intermediate |
 | [`/issue:queue`](./issue.md#queue) | Form execution queue | Intermediate |
 | [`/issue:execute`](./issue.md#execute) | Execute queue | Intermediate |
@@ -73,7 +75,7 @@
 |---------|----------|------------|
 | [`/memory:compact`](./memory.md#compact) | Compress current session memory to structured text | Intermediate |
 | [`/memory:tips`](./memory.md#tips) | Quick note-taking | Beginner |
-| [`/memory:load`](./memory.md#load) | Load task context via CLI project analysis | Intermediate |
+| [`/memory:prepare`](./memory.md#prepare) | Load task context via CLI project analysis | Intermediate |
 | [`/memory:update-full`](./memory.md#update-full) | Update all CLAUDE.md files | Intermediate |
 | [`/memory:update-related`](./memory.md#update-related) | Update CLAUDE.md for git-changed modules | Intermediate |
 | [`/memory:docs-full-cli`](./memory.md#docs-full-cli) | Generate full project documentation using CLI | Intermediate |
--- a/docs/commands/claude/issue.md
+++ b/docs/commands/claude/issue.md
@@ -32,7 +32,7 @@
 **Function**: Create structured issue from GitHub URL or text description, supporting requirement clarity detection.

 **Syntax**:
-```
+```bash
 /issue:new [-y|--yes] <github-url | text description> [--priority 1-5]
 ```

@@ -92,7 +92,7 @@ interface Issue {
 **Function**: Discover potential issues from multiple perspectives (Bug, UX, Test, Quality, Security, Performance, Maintainability, Best Practices).

 **Syntax**:
-```
+```bash
 /issue:discover [-y|--yes] <path pattern> [--perspectives=bug,ux,...] [--external]
 ```

@@ -125,7 +125,7 @@ interface Issue {
 **Function**: Discover issues via user prompt, using Gemini-planned iterative multi-agent exploration, supporting cross-module comparison.

 **Syntax**:
-```
+```bash
 /issue:discover-by-prompt [-y|--yes] <prompt> [--scope=src/**] [--depth=standard|deep] [--max-iterations=5]
 ```

@@ -151,7 +151,7 @@ interface Issue {
 **Function**: Batch plan issue solutions, using issue-plan-agent (explore + plan closed loop).

 **Syntax**:
-```
+```bash
 /issue:plan [-y|--yes] --all-pending <issue-id>[,<issue-id>,...] [--batch-size 3]
 ```

@@ -176,7 +176,7 @@ interface Issue {
 **Function**: Form execution queue from bound solutions, using issue-queue-agent (solution level).

 **Syntax**:
-```
+```bash
 /issue:queue [-y|--yes] [--queues <n>] [--issue <id>]
 ```

@@ -201,7 +201,7 @@ interface Issue {
 **Function**: Execute queue, using DAG parallel orchestration (one commit per solution).

 **Syntax**:
-```
+```bash
 /issue:execute [-y|--yes] --queue <queue-id> [--worktree [<existing-path>]]
 ```

@@ -223,7 +223,7 @@ interface Issue {
 **Function**: Convert planning artifact (lite-plan, workflow session, markdown) to issue solution.

 **Syntax**:
-```
+```bash
 /issue:convert-to-plan [-y|--yes] [--issue <id>] [--supplement] <source>
 ```

@@ -253,7 +253,7 @@ interface Issue {
 **Function**: Convert brainstorm session ideas to issues and generate executable solutions.

 **Syntax**:
-```
+```bash
 /issue:from-brainstorm SESSION="session-id" [--idea=<index>] [--auto] [-y|--yes]
 ```

--- a/docs/commands/claude/memory.md
+++ b/docs/commands/claude/memory.md
@@ -19,7 +19,7 @@
 |---------|----------|--------|
 | [`compact`](#compact) | Compress current session memory to structured text | `/memory:compact [optional: session description]` |
 | [`tips`](#tips) | Quick note-taking | `/memory:tips <note content> [--tag tags] [--context context]` |
-| [`load`](#load) | Load task context via CLI project analysis | `/memory:load [--tool gemini\|qwen] "task context description"` |
+| [`prepare`](#prepare) | Load task context via CLI project analysis | `/memory:prepare [--tool gemini\|qwen] "task context description"` |
 | [`update-full`](#update-full) | Update all CLAUDE.md files | `/memory:update-full [--tool gemini\|qwen\|codex] [--path directory]` |
 | [`update-related`](#update-related) | Update CLAUDE.md for git-changed modules | `/memory:update-related [--tool gemini\|qwen\|codex]` |
 | [`docs-full-cli`](#docs-full-cli) | Generate full project documentation using CLI | `/memory:docs-full-cli [path] [--tool tool]` |
@@ -33,7 +33,7 @@
 **Function**: Compress current session memory to structured text, extracting objectives, plans, files, decisions, constraints, and state, saving via MCP core_memory tool.

 **Syntax**:
-```
+```bash
 /memory:compact [optional: session description]
 ```

@@ -59,7 +59,7 @@
 **Function**: Quick note-taking command, capturing thoughts, snippets, reminders, and insights for future reference.

 **Syntax**:
-```
+```bash
 /memory:tips <note content> [--tag <tag1,tag2>] [--context <context>]
 ```

@@ -79,13 +79,13 @@
 /memory:tips "use Redis to cache user sessions" --context "login optimization"
 ```

-### load
+### prepare

 **Function**: Delegate to universal-executor agent, analyzing project via Gemini/Qwen CLI and returning JSON core content package for task context.

 **Syntax**:
-```
-/memory:load [--tool gemini|qwen] "task context description"
+```bash
+/memory:prepare [--tool gemini|qwen] "task context description"
 ```

 **Options**:
@@ -96,10 +96,10 @@
 **Examples**:
 ```bash
 # Use default tool
-/memory:load "user authentication module"
+/memory:prepare "user authentication module"

 # Specify tool
-/memory:load --tool gemini "payment system architecture"
+/memory:prepare --tool gemini "payment system architecture"
 ```

 ### update-full
@@ -107,7 +107,7 @@
 **Function**: Update all CLAUDE.md files, using layer-based execution (Layer 3->1), batch agent processing (4 modules/agent), and gemini->qwen->codex fallback.

 **Syntax**:
-```
+```bash
 /memory:update-full [--tool gemini|qwen|codex] [--path <directory>]
 ```

@@ -137,7 +137,7 @@
 **Function**: Update CLAUDE.md files for git-changed modules, using batch agent execution (4 modules/agent) and gemini->qwen->codex fallback.

 **Syntax**:
-```
+```bash
 /memory:update-related [--tool gemini|qwen|codex]
 ```

@@ -158,7 +158,7 @@
 **Function**: Generate full project documentation using CLI (Layer 3->1), batch agent processing (4 modules/agent), gemini->qwen->codex fallback, direct parallel for <20 modules.

 **Syntax**:
-```
+```bash
 /memory:docs-full-cli [path] [--tool <gemini|qwen|codex>]
 ```

@@ -179,7 +179,7 @@
 **Function**: Generate documentation for git-changed modules using CLI, batch agent processing (4 modules/agent), gemini->qwen->codex fallback, direct execution for <15 modules.

 **Syntax**:
-```
+```bash
 /memory:docs-related-cli [--tool <gemini|qwen|codex>]
 ```

@@ -197,7 +197,7 @@
 **Function**: Generate SKILL memory package from style reference, facilitating loading and consistent design system usage.

 **Syntax**:
-```
+```bash
 /memory:style-skill-memory [package-name] [--regenerate]
 ```

--- a/docs/commands/claude/session.md
+++ b/docs/commands/claude/session.md
@@ -20,6 +20,7 @@
 | [`start`](#start) | Discover existing sessions or start new workflow session | `/workflow:session:start [--type type] [--auto\|--new] [description]` |
 | [`list`](#list) | List all workflow sessions | `/workflow:session:list` |
 | [`resume`](#resume) | Resume most recently paused workflow session | `/workflow:session:resume` |
+| [`sync`](#sync) | Quick-sync session work to specs and project-tech | `/workflow:session:sync [-y] ["what was done"]` |
 | [`complete`](#complete) | Mark active workflow session as completed | `/workflow:session:complete [-y] [--detailed]` |
 | [`solidify`](#solidify) | Crystallize session learnings into project guidelines | `/workflow:session:solidify [-y] [--type type] [--category category] "rule"` |

@@ -30,7 +31,7 @@
 **Function**: Discover existing sessions or start new workflow session, supporting intelligent session management and conflict detection.

 **Syntax**:
-```
+```bash
 /workflow:session:start [--type <workflow|review|tdd|test|docs>] [--auto|--new] [optional: task description]
 ```

@@ -99,7 +100,7 @@ graph TD
 **Function**: List all workflow sessions, supporting state filtering, displaying session metadata and progress information.

 **Syntax**:
-```
+```bash
 /workflow:session:list
 ```

@@ -122,7 +123,7 @@ graph TD
 **Function**: Resume most recently paused workflow session, supporting automatic session discovery and state update.

 **Syntax**:
-```
+```bash
 /workflow:session:resume
 ```

@@ -144,12 +145,50 @@ graph TD
 /workflow:session:resume
 ```

+### sync
+
+**Function**: Quick-sync session work to specs and project-tech, extracting guidelines and tech entries from recent changes.
+
+**Syntax**:
+```bash
+/workflow:session:sync [-y|--yes] ["what was done"]
+```
+
+**Options**:
+- `--yes` or `-y`: Skip confirmation, auto-write both files
+
+**Workflow**:
+
+```mermaid
+graph TD
+    A[Start] --> B[Gather Context]
+    B --> C[Extract Updates]
+    C --> D{Auto Mode?}
+    D -->|Yes| E[Write Files]
+    D -->|No| F[Preview & Confirm]
+    F -->|Confirmed| E
+    E --> G[Update specs and project-tech.json]
+    G --> H[Confirm Synced]
+```
+
+**Examples**:
+```bash
+# Sync with confirmation prompt
+/workflow:session:sync "implemented user authentication"
+
+# Auto-sync without confirmation
+/workflow:session:sync --yes "fixed login bug"
+
+# Quick sync with auto-yes
+/workflow:session:sync -y
+```
+
 ### complete

 **Function**: Mark active workflow session as completed, archive and learn from experience, update checklist and remove active flag.

 **Syntax**:
-```
+```bash
 /workflow:session:complete [-y|--yes] [--detailed]
 ```

@@ -189,8 +228,8 @@ graph TD
 **Function**: Crystallize session learnings and user-defined constraints into permanent project guidelines.

 **Syntax**:
-```
-/workflow:session:solidify [-y|--yes] [--type <convention|constraint|learning>] [--category <category>] "rule or insight"
+```bash
+/workflow:session:solidify [-y|--yes] [--type <convention|constraint|learning|compress>] [--category <category>] "rule or insight"
 ```

 **Options**:
@@ -198,12 +237,14 @@ graph TD
  - `convention`: Code convention
  - `constraint`: Constraint condition
  - `learning`: Experience learning
+  - `compress`: Consolidate multiple memories into core memory
 - `--category=category`: Category name (e.g., `authentication`, `testing`)

 **Output Locations**:
 - Conventions: `.workflow/specs/conventions/<category>.md`
 - Constraints: `.workflow/specs/constraints/<category>.md`
 - Learnings: `.workflow/specs/learnings/<category>.md`
+- Compress: Core memory (MEMORY.md)

 **Examples**:
 ```bash
@@ -215,6 +256,9 @@ graph TD

 # Add learning
 /workflow:session:solidify --type=learning --category=api "REST API design lessons learned"
+
+# Consolidate memories into core memory
+/workflow:session:solidify --type=compress --category=workflow "session learnings summary"
 ```

 ## Session Directory Structure
--- a/docs/commands/claude/ui-design.md
+++ b/docs/commands/claude/ui-design.md
@@ -47,7 +47,7 @@
 **Function**: Interactive exploratory UI design workflow, style-centric batch generation, creating design variants from prompts/images, supporting parallel execution and user selection.

 **Syntax**:
-```
+```bash
 /workflow:ui-design:explore-auto [--input "<value>"] [--targets "<list>"] [--target-type "page|component"] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
 ```

@@ -76,7 +76,7 @@
 **Function**: UI design workflow supporting direct code/image input for design token extraction and prototype generation.

 **Syntax**:
-```
+```bash
 /workflow:ui-design:imitate-auto [--input "<value>"] [--session <id>]
 ```

@@ -98,7 +98,7 @@
 **Function**: Extract design styles using Claude analysis from reference images or text prompts, supporting variant generation or refine mode.

 **Syntax**:
-```
+```bash
 /workflow:ui-design:style-extract [-y|--yes] [--design-id <id>] [--session <id>] [--images "<glob>"] [--prompt "<description>"] [--variants <count>] [--interactive] [--refine]
 ```

@@ -126,7 +126,7 @@
 **Function**: Extract structural layout information using Claude analysis from reference images or text prompts, supporting variant generation or refine mode.

 **Syntax**:
-```
+```bash
 /workflow:ui-design:layout-extract [-y|--yes] [--design-id <id>] [--session <id>] [--images "<glob>"] [--prompt "<description>"] [--targets "<list>"] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>] [--interactive] [--refine]
 ```

@@ -151,7 +151,7 @@
 **Function**: Extract animation and transition patterns from prompts inference and image references for design system documentation.

 **Syntax**:
-```
+```bash
 /workflow:ui-design:animation-extract [-y|--yes] [--design-id <id>] [--session <id>] [--images "<glob>"] [--focus "<type>"] [--interactive] [--refine]
 ```

@@ -172,7 +172,7 @@
 **Function**: Import design system from code files (CSS/JS/HTML/SCSS), using automatic file discovery and parallel agent analysis.

 **Syntax**:
-```
+```bash
 /workflow:ui-design:import-from-code [--design-id <id>] [--session <id>] [--source <path>]
 ```

@@ -193,7 +193,7 @@
 **Function**: Orchestrator extracts styles from code and generates shareable reference package, supporting preview (automatic file discovery).

 **Syntax**:
-```
+```bash
 /workflow:ui-design:codify-style <path> [--package-name <name>] [--output-dir <path>] [--overwrite]
 ```

@@ -216,7 +216,7 @@
 **Function**: Extract and generate multi-component reference pages and documentation from design run.

 **Syntax**:
-```
+```bash
 /workflow:ui-design:reference-page-generator [--design-run <path>] [--package-name <name>] [--output-dir <path>]
 ```

@@ -234,7 +234,7 @@
 **Function**: Assemble UI prototypes, combining layout templates with design tokens (default animation support), pure assembler with no new content generation.

 **Syntax**:
-```
+```bash
 /workflow:ui-design:generate [--design-id <id>] [--session <id>]
 ```

@@ -252,7 +252,7 @@
 **Function**: Sync final design system reference to brainstorm artifacts, preparing for consumption by `/workflow:plan`.

 **Syntax**:
-```
+```bash
 /workflow:ui-design:design-sync --session <session_id> [--selected-prototypes "<list>"]
 ```

@@ -286,7 +286,7 @@ graph TD

 ## Design Run Structure

-```
+```plaintext
 .workflow/ui-design-runs/<run-id>/
 ├── design-tokens.json       # Design tokens
 ├── layouts/                 # Layout templates
--- a/docs/commands/claude/workflow.md
+++ b/docs/commands/claude/workflow.md
@@ -72,7 +72,7 @@
 **Function**: Ultra-lightweight multi-tool analysis and direct execution. Simple tasks have no artifacts, complex tasks automatically create planning documents in `.workflow/.scratchpad/`.

 **Syntax**:
-```
+```bash
 /workflow:lite-lite-lite [-y|--yes] <task description>
 ```

@@ -95,7 +95,7 @@
 **Function**: Lightweight interactive planning workflow, supporting in-memory planning, code exploration, and execution to lite-execute.

 **Syntax**:
-```
+```bash
 /workflow:lite-plan [-y|--yes] [-e|--explore] "task description" | file.md
 ```

@@ -116,7 +116,7 @@
 **Function**: Execute tasks based on in-memory plan, prompt description, or file content.

 **Syntax**:
-```
+```bash
 /workflow:lite-execute [-y|--yes] [--in-memory] ["task description" | file-path]
 ```

@@ -137,7 +137,7 @@
 **Function**: Lightweight bug diagnosis and fix workflow, supporting intelligent severity assessment and optional hotfix mode.

 **Syntax**:
-```
+```bash
 /workflow:lite-fix [-y|--yes] [--hotfix] "bug description or issue reference"
 ```

@@ -158,7 +158,7 @@
 **Function**: 5-phase planning workflow, outputting IMPL_PLAN.md and task JSON.

 **Syntax**:
-```
+```bash
 /workflow:plan [-y|--yes] "text description" | file.md
 ```

@@ -183,7 +183,7 @@
 **Function**: Coordinate agent execution of workflow tasks, supporting automatic session discovery, parallel task processing, and state tracking.

 **Syntax**:
-```
+```bash
 /workflow:execute [-y|--yes] [--resume-session="session-id"]
 ```

@@ -201,7 +201,7 @@
 **Function**: Interactive workflow replanning, supporting session-level artifact updates and scope clarification.

 **Syntax**:
-```
+```bash
 /workflow:replan [-y|--yes] [--session session-id] [task-id] "requirement" | file.md [--interactive]
 ```

@@ -219,7 +219,7 @@
 **Function**: Multi-CLI collaborative planning workflow, using ACE context collection and iterative cross-validation.

 **Syntax**:
-```
+```bash
 /workflow:multi-cli-plan [-y|--yes] <task description> [--max-rounds=3] [--tools=gemini,codex] [--mode=parallel|serial]
 ```

@@ -242,7 +242,7 @@
 **Function**: Interactive brainstorming, multi-CLI collaboration, idea expansion, and documented thinking evolution.

 **Syntax**:
-```
+```bash
 /workflow:brainstorm-with-file [-y|--yes] [-c|--continue] [-m|--mode creative|structured] "idea or topic"
 ```

@@ -264,7 +264,7 @@
 **Function**: Interactive collaborative analysis with documented discussion, CLI-assisted exploration, and evolving understanding.

 **Syntax**:
-```
+```bash
 /workflow:analyze-with-file [-y|--yes] [-c|--continue] "topic or question"
 ```

@@ -282,7 +282,7 @@
 **Function**: Interactive hypothesis-driven debugging with documented exploration, understanding evolution, and Gemini-assisted correction.

 **Syntax**:
-```
+```bash
 /workflow:debug-with-file [-y|--yes] "bug description or error message"
 ```

@@ -300,7 +300,7 @@
 **Function**: Universal execution engine consuming any planning/brainstorming/analysis output, supporting minimal progress tracking, multi-agent coordination, and incremental execution.

 **Syntax**:
-```
+```bash
 /workflow:unified-execute-with-file [-y|--yes] [-p|--plan <path>] [-m|--mode sequential|parallel] ["execution context"]
 ```

--- a/docs/commands/codex/prep.md
+++ b/docs/commands/codex/prep.md
@@ -38,7 +38,7 @@
 **Function**: Delegate to universal-executor agent, analyzing project via Gemini/Qwen CLI and returning JSON core content package for task context.

 **Syntax**:
-```
+```bash
 /memory:prepare [--tool gemini|qwen] "task context description"
 ```

--- a/docs/commands/codex/review.md
+++ b/docs/commands/codex/review.md
@@ -19,7 +19,7 @@
 **Function**: Interactive code review using Codex CLI via ccw endpoint, supporting configurable review targets, models, and custom instructions.

 **Syntax**:
-```
+```bash
 /cli:codex-review [--uncommitted|--base <branch>|--commit <sha>] [--model <model>] [--title <title>] [prompt]
 ```