feat(docs): add full documentation generation phase and related documentation generation phase

- Implement Phase 4: Full Documentation Generation with multi-layered strategy and tool fallback.
- Introduce Phase 5: Related Documentation Generation for incremental updates based on git changes.
- Create new utility components for displaying execution status in the terminal panel.
- Add helper functions for rendering execution status icons and formatting relative time.
- Establish a recent paths configuration for improved path resolution.
This commit is contained in:
catlog22
2026-02-13 21:46:28 +08:00
parent d750290f84
commit 25e27286b4
21 changed files with 692 additions and 498 deletions

View File

@@ -1,18 +1,18 @@
---
name: load
name: prepare
description: Delegate to universal-executor agent to analyze project via Gemini/Qwen CLI and return JSON core content package for task context
argument-hint: "[--tool gemini|qwen] \"task context description\""
allowed-tools: Task(*), Bash(*)
examples:
- /memory:load "在当前前端基础上开发用户认证功能"
- /memory:load --tool qwen "重构支付模块API"
- /memory:prepare "在当前前端基础上开发用户认证功能"
- /memory:prepare --tool qwen "重构支付模块API"
---
# Memory Load Command (/memory:load)
# Memory Prepare Command (/memory:prepare)
## 1. Overview
The `memory:load` command **delegates to a universal-executor agent** to analyze the project and return a structured "Core Content Pack". This pack is loaded into the main thread's memory, providing essential context for subsequent agent operations while minimizing token consumption.
The `memory:prepare` command **delegates to a universal-executor agent** to analyze the project and return a structured "Core Content Pack". This pack is loaded into the main thread's memory, providing essential context for subsequent agent operations while minimizing token consumption.
**Core Philosophy**:
- **Agent-Driven**: Fully delegates execution to universal-executor agent
@@ -95,11 +95,11 @@ The command fully delegates to **universal-executor agent**, which autonomously:
```javascript
Task(
subagent_type="universal-executor",
description="Load project memory: ${task_description}",
description="Prepare project memory: ${task_description}",
prompt=`
## Mission: Load Project Memory Context
## Mission: Prepare Project Memory Context
**Task**: Load project memory context for: "${task_description}"
**Task**: Prepare project memory context for: "${task_description}"
**Mode**: analysis
**Tool Preference**: ${tool || 'gemini'}
@@ -186,7 +186,7 @@ Before returning:
### Example 1: Load Context for New Feature
```bash
/memory:load "在当前前端基础上开发用户认证功能"
/memory:prepare "在当前前端基础上开发用户认证功能"
```
**Agent Execution**:
@@ -212,7 +212,7 @@ Before returning:
### Example 2: Using Qwen Tool
```bash
/memory:load --tool qwen "重构支付模块API"
/memory:prepare --tool qwen "重构支付模块API"
```
Agent uses Qwen CLI for analysis, returns same structured package.
@@ -220,7 +220,7 @@ Agent uses Qwen CLI for analysis, returns same structured package.
### Example 3: Bug Fix Context
```bash
/memory:load "修复登录验证错误"
/memory:prepare "修复登录验证错误"
```
Returns core context related to login validation, including test files and validation logic.
@@ -229,7 +229,7 @@ Returns core context related to login validation, including test files and valid
- **Session-Scoped**: Content package valid for current session
- **Subsequent Reference**: All subsequent agents/commands can access
- **Reload Required**: New sessions need to re-execute /memory:load
- **Reload Required**: New sessions need to re-execute /memory:prepare
## 8. Notes

View File

@@ -0,0 +1,229 @@
---
name: memory-manage
description: Unified memory management - CLAUDE.md updates and documentation generation with interactive routing. Triggers on "memory manage", "update claude", "update memory", "generate docs", "更新记忆", "生成文档".
allowed-tools: Task(*), Bash(*), AskUserQuestion(*), Read(*)
---
# Memory Management Skill
Unified entry point for project memory (CLAUDE.md) updates and documentation (API.md/README.md) generation. Routes to specialized sub-commands via arguments or interactive needs assessment.
## Architecture Overview
```
┌──────────────────────────────────────────────────────┐
│ Memory Manage (Router) │
│ → Parse input → Detect mode → Route to phase │
└───────────────┬──────────────────────────────────────┘
┌───────┴───────┐
↓ ↓
┌───────────┐ ┌───────────┐
│ CLAUDE.md │ │ Docs │
│ 管理 │ │ 生成 │
└─────┬─────┘ └─────┬─────┘
│ │
┌────┼────┐ ┌────┴────┐
↓ ↓ ↓ ↓ ↓
Full Related Single Full Related
全量 增量 单模块 全量 增量
```
## Execution Flow
### Step 1: Parse Input & Route
Detect execution mode from user input:
**Auto-Route Rules** (priority order):
| Signal | Route | Examples |
|--------|-------|---------|
| Explicit sub-command token | → Direct dispatch | `update-full --tool qwen` |
| Keyword: full, 全量, all, entire + update/claude | → update-full | "全量更新claude" |
| Keyword: related, changed, 增量, diff + update/claude | → update-related | "更新变更模块" |
| Keyword: single, module, 单模块 + path-like token | → update-single | "更新 src/auth 模块" |
| Keyword: docs, documentation, 文档 + full/all/全量 | → docs-full | "全量生成文档" |
| Keyword: docs, documentation, 文档 + related/changed/增量 | → docs-related | "增量生成文档" |
| Ambiguous or no arguments | → **AskUserQuestion** | `/memory-manage` |
Valid sub-command tokens: `update-full`, `update-related`, `update-single`, `docs-full`, `docs-related`
**Direct dispatch examples**:
```
input = "update-full --tool qwen"
→ subcommand = "update-full", remainingArgs = "--tool qwen"
→ Read phases/01-update-full.md, execute
input = "update-single src/auth --tool gemini"
→ subcommand = "update-single", remainingArgs = "src/auth --tool gemini"
→ Read phases/03-update-single.md, execute
```
**When ambiguous or no arguments**, proceed to Step 2.
### Step 2: Interactive Needs Assessment
**Q1 — 确定内容类别**:
```
AskUserQuestion({
questions: [{
question: "你要管理哪类内容?",
header: "类别",
multiSelect: false,
options: [
{
label: "CLAUDE.md (项目记忆)",
description: "更新模块指令文件帮助Claude理解代码库结构和约定"
},
{
label: "项目文档 (API+README)",
description: "生成API.md和README.md到.workflow/docs/目录"
}
]
}]
})
```
**Q2a — CLAUDE.md 管理范围** (用户选了 CLAUDE.md):
```
AskUserQuestion({
questions: [{
question: "CLAUDE.md 更新范围?",
header: "范围",
multiSelect: false,
options: [
{
label: "增量更新 (Recommended)",
description: "仅更新git变更模块及其父级日常开发首选"
},
{
label: "全量更新",
description: "更新所有模块3层架构bottom-up适合重大重构后"
},
{
label: "单模块更新",
description: "指定一个模块Explore深度分析后生成说明书式文档"
}
]
}]
})
```
Route mapping:
- "增量更新" → `update-related` → Ref: phases/02-update-related.md
- "全量更新" → `update-full` → Ref: phases/01-update-full.md
- "单模块更新" → `update-single` → continue to Q3
**Q2b — 文档生成范围** (用户选了项目文档):
```
AskUserQuestion({
questions: [{
question: "文档生成范围?",
header: "范围",
multiSelect: false,
options: [
{
label: "增量生成 (Recommended)",
description: "仅为git变更模块生成/更新文档,日常开发首选"
},
{
label: "全量生成",
description: "所有模块+项目级文档(ARCHITECTURE.md等),适合初始化"
}
]
}]
})
```
Route mapping:
- "增量生成" → `docs-related` → Ref: phases/05-docs-related.md
- "全量生成" → `docs-full` → Ref: phases/04-docs-full.md
**Q3 — 补充路径** (仅 update-single 需要,且无路径参数时):
```
AskUserQuestion({
questions: [{
question: "请指定要更新的模块路径:",
header: "路径",
multiSelect: false,
options: [
{
label: "src",
description: "src 目录"
},
{
label: ".",
description: "项目根目录"
}
]
}]
})
```
用户可选 "Other" 输入自定义路径。
### Step 3: Execute Selected Phase
Based on routing result, read and execute the corresponding phase:
**Phase Reference Documents** (read on-demand when phase executes):
| Mode | Document | Purpose |
|------|----------|---------|
| update-full | [phases/01-update-full.md](phases/01-update-full.md) | Full CLAUDE.md update, 3-layer architecture, batched agents |
| update-related | [phases/02-update-related.md](phases/02-update-related.md) | Git-changed CLAUDE.md update, depth-first |
| update-single | [phases/03-update-single.md](phases/03-update-single.md) | Single module CLAUDE.md, Explore + handbook style |
| docs-full | [phases/04-docs-full.md](phases/04-docs-full.md) | Full API.md + README.md generation |
| docs-related | [phases/05-docs-related.md](phases/05-docs-related.md) | Git-changed docs generation, incremental |
## Shared Configuration
### Tool Fallback Hierarchy
All sub-commands share the same fallback:
```
--tool gemini → [gemini, qwen, codex] // default
--tool qwen → [qwen, gemini, codex]
--tool codex → [codex, gemini, qwen]
```
### Common Parameters
| Parameter | Description | Default | Used By |
|-----------|-------------|---------|---------|
| `--tool <gemini\|qwen\|codex>` | Primary CLI tool | gemini | All |
| `--path <dir>` | Target directory | . | update-full, docs-full |
| `<path>` (positional) | Module path | _(required)_ | update-single |
### Batching Thresholds
| Sub-Command | Direct Execution | Agent Batch | Batch Size |
|-------------|-----------------|-------------|------------|
| update-full | <20 modules | ≥20 modules | 4/agent |
| update-related | <15 modules | ≥15 modules | 4/agent |
| update-single | always single | N/A | 1 |
| docs-full | <20 modules | ≥20 modules | 4/agent |
| docs-related | <15 modules | ≥15 modules | 4/agent |
## Core Rules
1. **Route before execute**: Determine sub-command before any execution
2. **Phase doc is truth**: All execution logic lives in phase docs, router only dispatches
3. **Read on-demand**: Only read the selected phase doc, never load all
4. **Pass arguments through**: Forward remaining args unchanged to sub-command
5. **User confirmation**: Each sub-command handles its own plan presentation and y/n confirmation
## Error Handling
| Error | Resolution |
|-------|------------|
| Unknown sub-command | Fall through to interactive flow |
| Phase doc not found | Abort with file path error |
| Missing path for update-single | Prompt via Q3 |
| Sub-command execution fails | Follow phase doc's own error handling |

View File

@@ -1,24 +1,26 @@
---
name: update-full
description: Update all CLAUDE.md files using layer-based execution (Layer 3→1) with batched agents (4 modules/agent) and gemini→qwen→codex fallback, <20 modules uses direct parallel
argument-hint: "[--tool gemini|qwen|codex] [--path <directory>]"
---
# Phase 1: Full CLAUDE.md Update (update-full)
# Full Documentation Update (/memory:update-full)
全项目 CLAUDE.md 更新,使用 3 层架构 (Layer 3→1),批量 agent 执行,自动 tool fallback。
## Overview
## Objective
Orchestrates project-wide CLAUDE.md updates using batched agent execution with automatic tool fallback and 3-layer architecture support.
- 发现所有项目模块并按深度分层
- 按 Layer 3→2→1 顺序 bottom-up 更新所有模块的 CLAUDE.md
- <20 模块直接并行≥20 模块使用 agent 批处理 (4 modules/agent)
- 自动 tool fallback (gemini→qwen→codex)
## Parameters
**Parameters**:
- `--tool <gemini|qwen|codex>`: Primary tool (default: gemini)
- `--path <directory>`: Target specific directory (default: entire project)
## Execution
**Execution Flow**: Discovery → Plan Presentation → Execution → Safety Verification
## 3-Layer Architecture & Auto-Strategy Selection
### 3-Layer Architecture & Auto-Strategy Selection
### Layer Definition & Strategy Assignment
#### Layer Definition & Strategy Assignment
| Layer | Depth | Strategy | Purpose | Context Pattern |
|-------|-------|----------|---------|----------------|
@@ -30,20 +32,17 @@ Orchestrates project-wide CLAUDE.md updates using batched agent execution with a
**Strategy Auto-Selection**: Strategies are automatically determined by directory depth - no user configuration needed.
### Strategy Details
#### Multi-Layer Strategy (Layer 3 Only)
- **Use Case**: Deepest directories with unstructured file layouts
- **Behavior**: Generates CLAUDE.md for current directory AND each subdirectory containing files
- **Context**: All files in current directory tree (`@**/*`)
#### Single-Layer Strategy (Layers 1-2)
- **Use Case**: Upper layers that aggregate from existing documentation
- **Behavior**: Generates CLAUDE.md only for current directory
- **Context**: Direct children CLAUDE.md files + current directory code files
### Example Flow
#### Example Flow
```
src/auth/handlers/ (depth 3) → MULTI-LAYER STRATEGY
CONTEXT: @**/* (all files in handlers/ and subdirs)
@@ -62,7 +61,7 @@ src/ (depth 1) → SINGLE-LAYER STRATEGY
GENERATES: ./CLAUDE.md only
```
## Core Execution Rules
### Core Execution Rules
1. **Analyze First**: Git cache + module discovery before updates
2. **Wait for Approval**: Present plan, no execution without user confirmation
@@ -74,7 +73,7 @@ src/ (depth 1) → SINGLE-LAYER STRATEGY
6. **Safety Check**: Verify only CLAUDE.md files modified
7. **Layer-based Grouping**: Group modules by LAYER (not depth) for execution
## Tool Fallback Hierarchy
### Tool Fallback Hierarchy
```javascript
--tool gemini → [gemini, qwen, codex] // default
@@ -90,9 +89,7 @@ src/ (depth 1) → SINGLE-LAYER STRATEGY
| qwen | Architecture, system design | gemini → codex |
| codex | Implementation, code quality | gemini → qwen |
## Execution Phases
### Phase 1: Discovery & Analysis
### Step 1.1: Discovery & Analysis
```javascript
// Cache git changes
@@ -109,7 +106,7 @@ Bash({command: "cd <target-path> && ccw tool exec get_modules_by_depth '{\"forma
**Smart filter**: Auto-detect and skip tests/build/config/docs based on project tech stack.
### Phase 2: Plan Presentation
### Step 1.2: Plan Presentation
**For <20 modules**:
```
@@ -168,7 +165,7 @@ Update Plan:
Confirm execution? (y/n)
```
### Phase 3A: Direct Execution (<20 modules)
### Step 1.3A: Direct Execution (<20 modules)
**Strategy**: Parallel execution within layer (max 4 concurrent), no agent overhead.
@@ -202,7 +199,7 @@ for (let layer of [3, 2, 1]) {
}
```
### Phase 3B: Agent Batch Execution (≥20 modules)
### Step 1.3B: Agent Batch Execution (≥20 modules)
**Strategy**: Batch modules into groups of 4, spawn memory-bridge agents per batch.
@@ -284,7 +281,8 @@ REPORTING FORMAT:
⚠️ path/to/module failed with {tool}, trying next...
❌ FAILED: path/to/module - all tools exhausted
```
### Phase 4: Safety Verification
### Step 1.4: Safety Verification
```javascript
// Check only CLAUDE.md files modified
@@ -308,25 +306,11 @@ Update Summary:
**Coordinator**: Invalid path abort, user decline handling, safety check with auto-revert
**Fallback Triggers**: Non-zero exit code, script timeout, unexpected output
## Usage Examples
## Output
```bash
# Full project update (auto-strategy selection)
/memory:update-full
- **Files**: Updated CLAUDE.md files across all project modules
- **Report**: Summary with success/failure counts and tool usage statistics
# Target specific directory
/memory:update-full --path .claude
/memory:update-full --path src/features/auth
## Next Phase
# Use specific tool
/memory:update-full --tool qwen
/memory:update-full --path .claude --tool qwen
```
## Key Advantages
- **Efficiency**: 30 modules → 8 agents (73% reduction from sequential)
- **Resilience**: 3-tier tool fallback per module
- **Performance**: Parallel batches, no concurrency limits
- **Observability**: Per-module tool usage, batch-level metrics
- **Automation**: Zero configuration - strategy auto-selected by directory depth
Return to [manage.md](../manage.md) router.

View File

@@ -1,22 +1,23 @@
---
name: update-related
description: Update CLAUDE.md for git-changed modules using batched agent execution (4 modules/agent) with gemini→qwen→codex fallback, <15 modules uses direct execution
argument-hint: "[--tool gemini|qwen|codex]"
---
# Phase 2: Related CLAUDE.md Update (update-related)
# Related Documentation Update (/memory:update-related)
仅更新 git 变更模块的 CLAUDE.md使用深度优先执行和自动 tool fallback。
## Overview
## Objective
Orchestrates context-aware CLAUDE.md updates for changed modules using batched agent execution with automatic tool fallback (gemini→qwen→codex).
- 检测 git 变更,识别受影响模块
- 按深度 N→0 顺序更新变更模块及其父级上下文
- <15 模块直接并行≥15 模块使用 agent 批处理
- 自动 tool fallback (gemini→qwen→codex)
## Parameters
**Parameters**:
- `--tool <gemini|qwen|codex>`: Primary tool (default: gemini)
**Execution Flow**:
1. Change Detection → 2. Plan Presentation → 3. Batched Agent Execution → 4. Safety Verification
## Execution
## Core Rules
**Execution Flow**: Change Detection → Plan Presentation → Batched Execution → Safety Verification
### Core Rules
1. **Detect Changes First**: Use git diff to identify affected modules
2. **Wait for Approval**: Present plan, no execution without user confirmation
@@ -27,7 +28,7 @@ Orchestrates context-aware CLAUDE.md updates for changed modules using batched a
5. **Depth Sequential**: Process depths N→0, parallel batches within depth (both modes)
6. **Related Mode**: Update only changed modules and their parent contexts
## Tool Fallback Hierarchy
### Tool Fallback Hierarchy
```javascript
--tool gemini → [gemini, qwen, codex] // default
@@ -37,7 +38,7 @@ Orchestrates context-aware CLAUDE.md updates for changed modules using batched a
**Trigger**: Non-zero exit code from update script
## Phase 1: Change Detection & Analysis
### Step 2.1: Change Detection & Analysis
```javascript
// Detect changed modules
@@ -53,7 +54,7 @@ Bash({command: "git add -A 2>/dev/null || true", run_in_background: false});
**Fallback**: If no changes detected, use recent modules (first 10 by depth).
## Phase 2: Plan Presentation
### Step 2.2: Plan Presentation
**Present filtered plan**:
```
@@ -87,7 +88,7 @@ Related Update Plan:
- <15 modules: Direct execution
- ≥15 modules: Agent batch execution
## Phase 3A: Direct Execution (<15 modules)
### Step 2.3A: Direct Execution (<15 modules)
**Strategy**: Parallel execution within depth (max 4 concurrent), no agent overhead.
@@ -119,11 +120,9 @@ for (let depth of sorted_depths.reverse()) { // N → 0
}
```
---
### Step 2.3B: Agent Batch Execution (≥15 modules)
## Phase 3B: Agent Batch Execution (≥15 modules)
### Batching Strategy
#### Batching Strategy
```javascript
// Batch modules into groups of 4
@@ -137,7 +136,7 @@ function batch_modules(modules, batch_size = 4) {
// Examples: 10→[4,4,2] | 8→[4,4] | 3→[3]
```
### Coordinator Orchestration
#### Coordinator Orchestration
```javascript
let modules_by_depth = group_by_depth(changed_modules);
@@ -161,7 +160,7 @@ for (let depth of sorted_depths.reverse()) { // N → 0
}
```
### Batch Worker Prompt Template
#### Batch Worker Prompt Template
```
PURPOSE: Update CLAUDE.md for assigned modules with tool fallback (related mode)
@@ -212,7 +211,7 @@ Report final summary with:
- Tool usage: {{tool_1}}:X, {{tool_2}}:Y, {{tool_3}}:Z
```
## Phase 4: Safety Verification
### Step 2.4: Safety Verification
```javascript
// Check only CLAUDE.md modified
@@ -240,16 +239,6 @@ Update Summary:
4 files changed, 82 insertions(+), 6 deletions(-)
```
## Execution Summary
**Module Count Threshold**:
- **<15 modules**: Coordinator executes Phase 3A (Direct Execution)
- **≥15 modules**: Coordinator executes Phase 3B (Agent Batch Execution)
**Agent Hierarchy** (for ≥15 modules):
- **Coordinator**: Handles batch division, spawns worker agents per depth
- **Worker Agents**: Each processes 4 modules with tool fallback (related mode)
## Error Handling
**Batch Worker**:
@@ -268,65 +257,11 @@ Update Summary:
- Script timeout
- Unexpected output
## Tool Reference
## Output
| Tool | Best For | Fallback To |
|--------|--------------------------------|----------------|
| gemini | Documentation, patterns | qwen → codex |
| qwen | Architecture, system design | gemini → codex |
| codex | Implementation, code quality | gemini → qwen |
- **Files**: Updated CLAUDE.md files for changed modules and their parents
- **Report**: Summary with success/failure counts, tool usage, and git diff statistics
## Usage Examples
## Next Phase
```bash
# Daily development update
/memory:update-related
# After feature work with specific tool
/memory:update-related --tool qwen
# Code quality review after implementation
/memory:update-related --tool codex
```
## Key Advantages
**Efficiency**: 30 modules → 8 agents (73% reduction)
**Resilience**: 3-tier fallback per module
**Performance**: Parallel batches, no concurrency limits
**Context-aware**: Updates based on actual git changes
**Fast**: Only affected modules, not entire project
## Coordinator Checklist
- Parse `--tool` (default: gemini)
- Refresh code index for accurate change detection
- Detect changed modules via detect_changed_modules.sh
- **Smart filter modules** (auto-detect tech stack, skip tests/build/config/docs)
- Cache git changes
- Apply fallback if no changes (recent 10 modules)
- Construct tool fallback order
- **Present filtered plan** with skip reasons and change types
- **Wait for y/n confirmation**
- Determine execution mode:
- **<15 modules**: Direct execution (Phase 3A)
- For each depth (N→0): Sequential module updates with tool fallback
- **≥15 modules**: Agent batch execution (Phase 3B)
- For each depth (N→0): Batch modules (4 per batch), spawn batch workers in parallel
- Wait for depth/batch completion
- Aggregate results
- Safety check (only CLAUDE.md modified)
- Display git diff statistics + summary
## Comparison with Full Update
| Aspect | Related Update | Full Update |
|--------|----------------|-------------|
| **Scope** | Changed modules only | All project modules |
| **Speed** | Fast (minutes) | Slower (10-30 min) |
| **Use case** | Daily development | Major refactoring |
| **Mode** | `"related"` | `"full"` |
| **Trigger** | After commits | After major changes |
| **Batching** | 4 modules/agent | 4 modules/agent |
| **Fallback** | gemini→qwen→codex | gemini→qwen→codex |
| **Complexity threshold** | ≤15 modules | ≤20 modules |
Return to [manage.md](../manage.md) router.

View File

@@ -1,81 +1,47 @@
---
name: update-single
description: Update single module CLAUDE.md using Explore agent for deep codebase understanding, producing manual-style documentation (handbook, not API reference)
argument-hint: "<path> [--tool gemini|qwen|codex]"
allowed-tools: Task(*), Bash(*), AskUserQuestion(*)
---
# Phase 3: Single Module CLAUDE.md Update (update-single)
# Single Module Documentation Update (/memory:update-single)
使用 Explore agent 深度分析后,为单个目标模块生成手册式 (说明书) CLAUDE.md。
## Overview
## Objective
Generates a manual-style CLAUDE.md for a single target directory using Explore agent for deep semantic codebase understanding. The output reads like a module handbook — explaining what it does, how to use it, and how it integrates — rather than dry API documentation.
**Core capabilities:**
- Explore agent for semantic codebase exploration (not just file scanning)
- Manual/handbook-style output (usage guide, not reference docs)
- Interactive confirmation with exploration summary preview
- 验证目标路径并扫描结构
- 使用 Explore agent 进行 7 维度深度探索
- 交互确认后通过 CLI tool 生成手册式 CLAUDE.md
- Tool fallback (gemini→qwen→codex)
## Usage
## Parameters
```bash
/memory:update-single <path> [--tool gemini|qwen|codex]
- `<path>`: Target directory path (required)
- `--tool <gemini|qwen|codex>`: Primary CLI tool (default: gemini)
# Arguments
<path> Target directory path (required)
# Options
--tool <gemini|qwen|codex> Primary CLI tool (default: gemini)
# Examples
/memory:update-single src/auth
/memory:update-single .claude/commands --tool qwen
/memory:update-single ccw/frontend/src/components/issue
```
## Output Artifacts
| Artifact | Description |
|----------|-------------|
| `<path>/CLAUDE.md` | Manual-style module handbook |
**CLAUDE.md Style** — "说明书" not "文档":
- What this module does (purpose & responsibility)
- How to use it (patterns, conventions, examples)
- How it integrates (dependencies, exports, data flow)
- Important constraints (gotchas, rules, limitations)
## Execution Process
## Execution
```
Phase 1: Target Validation & Scan
Step 3.1: Target Validation & Scan
├─ Parse arguments (path, --tool)
├─ Validate target directory exists
└─ Quick structure scan (file count, types, depth)
Phase 2: Deep Exploration (Explore Agent)
Step 3.2: Deep Exploration (Explore Agent)
├─ Launch Explore agent with "very thorough" level
├─ Analyze purpose, structure, patterns, exports, dependencies
└─ Build comprehensive module understanding
Phase 3: Confirmation
Step 3.3: Confirmation
├─ Display exploration summary (key findings)
└─ AskUserQuestion: Generate / Cancel
Phase 4: Generate CLAUDE.md (CLI Tool)
Step 3.4: Generate CLAUDE.md (CLI Tool)
├─ Construct manual-style prompt from exploration results
├─ Execute ccw cli with --mode write
├─ Tool fallback on failure
└─ Write to <path>/CLAUDE.md
Phase 5: Verification
Step 3.5: Verification
└─ Display generated CLAUDE.md preview + stats
```
## Implementation
### Phase 1: Target Validation & Scan
### Step 3.1: Target Validation & Scan
```javascript
// Parse arguments
@@ -86,7 +52,7 @@ const primaryTool = toolFlagIdx !== -1 ? parts[toolFlagIdx + 1] : 'gemini'
const targetPath = parts.find(p => !p.startsWith('--') && p !== primaryTool)
if (!targetPath) {
console.log('ERROR: <path> is required. Usage: /memory:update-single <path> [--tool gemini|qwen|codex]')
console.log('ERROR: <path> is required. Usage: /memory:manage update-single <path> [--tool gemini|qwen|codex]')
return
}
@@ -112,9 +78,9 @@ Launching deep exploration...
`)
```
### Phase 2: Deep Exploration (Explore Agent)
### Step 3.2: Deep Exploration (Explore Agent)
**⚠️ CRITICAL**: Use `run_in_background: false` — exploration results are REQUIRED before generation.
**CRITICAL**: Use `run_in_background: false` — exploration results are REQUIRED before generation.
```javascript
const explorationResult = Task(
@@ -173,7 +139,7 @@ Return a structured summary covering all 7 dimensions above. Include specific fi
)
```
### Phase 3: Confirmation
### Step 3.3: Confirmation
```javascript
console.log(`
@@ -203,7 +169,7 @@ AskUserQuestion({
// Cancel → abort
```
### Phase 4: Generate CLAUDE.md (CLI Tool)
### Step 3.4: Generate CLAUDE.md (CLI Tool)
**Tool fallback hierarchy**:
```javascript
@@ -285,7 +251,7 @@ CONSTRAINTS: Only write CLAUDE.md, no other files" --tool ${tool} --mode write -
}
```
### Phase 5: Verification
### Step 3.5: Verification
```javascript
// Check file was created/updated
@@ -311,8 +277,8 @@ console.log(`
The generated CLAUDE.md is a **说明书 (handbook)**, NOT a reference doc:
| Aspect | Handbook Style | Reference Doc Style |
|--------|-------------------|----------------------|
| Aspect | Handbook Style | Reference Doc Style |
|--------|---------------|---------------------|
| Purpose | "This module handles user auth" | "Authentication module" |
| Content | How to work with it | What every function does |
| Patterns | "Always use `createAuthMiddleware()`" | "List of all exports" |
@@ -330,18 +296,11 @@ The generated CLAUDE.md is a **说明书 (handbook)**, NOT a reference doc:
| Empty directory | Abort — nothing to document |
| Existing CLAUDE.md | Overwrite entirely (full regeneration) |
## Usage Examples
## Output
```bash
# Generate handbook for a module
/memory:update-single src/auth
- **File**: `<path>/CLAUDE.md` — Manual-style module handbook
- **Preview**: First 30 lines displayed after generation
# Use specific tool
/memory:update-single .claude/commands --tool qwen
## Next Phase
# Deep nested module
/memory:update-single ccw/frontend/src/components/issue
# Root-level documentation
/memory:update-single .
```
Return to [manage.md](../manage.md) router.

View File

@@ -1,24 +1,27 @@
---
name: docs-full-cli
description: Generate full project documentation using CLI execution (Layer 3→1) with batched agents (4 modules/agent) and gemini→qwen→codex fallback, <20 modules uses direct parallel
argument-hint: "[path] [--tool <gemini|qwen|codex>]"
---
# Phase 4: Full Documentation Generation (docs-full)
# Full Documentation Generation - CLI Mode (/memory:docs-full-cli)
全项目 API.md + README.md 文档生成,使用 CLI 执行、3 层架构和自动 tool fallback输出到 .workflow/docs/。
## Overview
## Objective
Orchestrates project-wide documentation generation using CLI-based execution with batched agents and automatic tool fallback.
- 发现所有项目模块并按深度分层
- 按 Layer 3→2→1 顺序生成 API.md + README.md 文档
- <20 模块直接并行≥20 模块使用 agent 批处理
- 生成项目级文档 (README.md, ARCHITECTURE.md, EXAMPLES.md)
- 自动 tool fallback (gemini→qwen→codex)
## Parameters
**Parameters**:
- `path`: Target directory (default: current directory)
- `--tool <gemini|qwen|codex>`: Primary tool (default: gemini)
**Execution Flow**: Discovery → Plan Presentation → Execution → Verification
## Execution
## 3-Layer Architecture & Auto-Strategy Selection
**Execution Flow**: Discovery → Plan Presentation → Execution → Project-Level Docs → Verification
### Layer Definition & Strategy Assignment
### 3-Layer Architecture & Auto-Strategy Selection
#### Layer Definition & Strategy Assignment
| Layer | Depth | Strategy | Purpose | Context Pattern |
|-------|-------|----------|---------|----------------|
@@ -28,24 +31,19 @@ Orchestrates project-wide documentation generation using CLI-based execution wit
**Generation Direction**: Layer 3 → Layer 2 → Layer 1 (bottom-up dependency flow)
**Strategy Auto-Selection**: Strategies are automatically determined by directory depth - no user configuration needed.
### Strategy Details
#### Full Strategy (Layer 3 Only)
- **Use Case**: Deepest directories with comprehensive file coverage
- **Behavior**: Generates API.md + README.md for current directory AND subdirectories containing code
- **Context**: All files in current directory tree (`@**/*`)
- **Output**: `.workflow/docs/{project_name}/{path}/API.md` + `README.md`
#### Single Strategy (Layers 1-2)
- **Use Case**: Upper layers that aggregate from existing documentation
- **Behavior**: Generates API.md + README.md only in current directory
- **Context**: Direct children docs + current directory code files
- **Output**: `.workflow/docs/{project_name}/{path}/API.md` + `README.md`
### Example Flow
#### Example Flow
```
src/auth/handlers/ (depth 3) → FULL STRATEGY
CONTEXT: @**/* (all files in handlers/ and subdirs)
@@ -64,7 +62,7 @@ src/ (depth 1) → SINGLE STRATEGY
GENERATES: .workflow/docs/project/{API.md,README.md} only
```
## Core Execution Rules
### Core Execution Rules
1. **Analyze First**: Module discovery + folder classification before generation
2. **Wait for Approval**: Present plan, no execution without user confirmation
@@ -76,7 +74,7 @@ src/ (depth 1) → SINGLE STRATEGY
6. **Safety Check**: Verify only docs files modified in .workflow/docs/
7. **Layer-based Grouping**: Group modules by LAYER (not depth) for execution
## Tool Fallback Hierarchy
### Tool Fallback Hierarchy
```javascript
--tool gemini → [gemini, qwen, codex] // default
@@ -84,17 +82,7 @@ src/ (depth 1) → SINGLE STRATEGY
--tool codex → [codex, gemini, qwen]
```
**Trigger**: Non-zero exit code from generation script
| Tool | Best For | Fallback To |
|--------|--------------------------------|----------------|
| gemini | Documentation, patterns | qwen → codex |
| qwen | Architecture, system design | gemini → codex |
| codex | Implementation, code quality | gemini → qwen |
## Execution Phases
### Phase 1: Discovery & Analysis
### Step 4.1: Discovery & Analysis
```javascript
// Get project metadata
@@ -111,7 +99,7 @@ Bash({command: "cd <target-path> && ccw tool exec get_modules_by_depth '{\"forma
**Smart filter**: Auto-detect and skip tests/build/config/vendor based on project tech stack.
### Phase 2: Plan Presentation
### Step 4.2: Plan Presentation
**For <20 modules**:
```
@@ -139,7 +127,6 @@ Documentation Generation Plan:
Auto-skipped: ./tests, __pycache__, node_modules (15 paths)
Execution order: Layer 2 → Layer 1
Estimated time: ~5-10 minutes
Confirm execution? (y/n)
```
@@ -176,12 +163,10 @@ Documentation Generation Plan:
- Layer 2 (15 modules, depth 1-2): 4 agents [4, 4, 4, 3]
- Layer 1 (2 modules, depth 0): 1 agent [2]
Estimated time: ~15-25 minutes
Confirm execution? (y/n)
```
### Phase 3A: Direct Execution (<20 modules)
### Step 4.3A: Direct Execution (<20 modules)
**Strategy**: Parallel execution within layer (max 4 concurrent), no agent overhead.
@@ -217,7 +202,7 @@ for (let layer of [3, 2, 1]) {
}
```
### Phase 3B: Agent Batch Execution (≥20 modules)
### Step 4.3B: Agent Batch Execution (≥20 modules)
**Strategy**: Batch modules into groups of 4, spawn memory-bridge agents per batch.
@@ -290,7 +275,6 @@ EXECUTION FLOW (for each module):
2. Handle complete failure (all tools failed):
if [ $exit_code -ne 0 ]; then
report "❌ FAILED: {{module_path}} - all tools exhausted"
# Continue to next module (do not abort batch)
fi
FOLDER TYPE HANDLING:
@@ -310,7 +294,7 @@ REPORTING FORMAT:
❌ FAILED: path/to/module - all tools exhausted
```
### Phase 4: Project-Level Documentation
### Step 4.4: Project-Level Documentation
**After all module documentation is generated, create project-level documentation files.**
@@ -370,7 +354,7 @@ Project-Level Documentation:
✅ api/README.md (HTTP API reference) [optional]
```
### Phase 5: Verification
### Step 4.5: Verification
```javascript
// Check documentation files created
@@ -398,12 +382,6 @@ Documentation Generation Summary:
└── README.md
```
## Error Handling
**Batch Worker**: Tool fallback per module, batch isolation, clear status reporting
**Coordinator**: Invalid path abort, user decline handling, verification with cleanup
**Fallback Triggers**: Non-zero exit code, script timeout, unexpected output
## Output Structure
```
@@ -426,36 +404,18 @@ Documentation Generation Summary:
│ └── core/
│ ├── API.md
│ └── README.md
├── README.md # Project root overview (auto-generated)
├── ARCHITECTURE.md # System design (auto-generated)
├── EXAMPLES.md # Usage examples (auto-generated)
└── api/ # Optional (auto-generated if HTTP API detected)
├── README.md # Project root overview (auto-generated)
├── ARCHITECTURE.md # System design (auto-generated)
├── EXAMPLES.md # Usage examples (auto-generated)
└── api/ # Optional (auto-generated if HTTP API detected)
└── README.md # HTTP API reference
```
## Usage Examples
## Error Handling
```bash
# Full project documentation generation
/memory:docs-full-cli
# Target specific directory
/memory:docs-full-cli src/features/auth
/memory:docs-full-cli .claude
# Use specific tool
/memory:docs-full-cli --tool qwen
/memory:docs-full-cli src --tool qwen
```
## Key Advantages
- **Efficiency**: 30 modules → 8 agents (73% reduction from sequential)
- **Resilience**: 3-tier tool fallback per module
- **Performance**: Parallel batches, no concurrency limits
- **Observability**: Per-module tool usage, batch-level metrics
- **Automation**: Zero configuration - strategy auto-selected by directory depth
- **Path Mirroring**: Clear 1:1 mapping between source and documentation structure
**Batch Worker**: Tool fallback per module, batch isolation, clear status reporting
**Coordinator**: Invalid path abort, user decline handling, verification with cleanup
**Fallback Triggers**: Non-zero exit code, script timeout, unexpected output
## Template Reference
@@ -464,8 +424,12 @@ Templates used from `~/.ccw/workflows/cli-templates/prompts/documentation/`:
- `module-readme.txt`: Module purpose, usage, dependencies
- `folder-navigation.txt`: Navigation README for folders with subdirectories
## Related Commands
## Output
- `/memory:docs` - Agent-based documentation planning workflow
- `/memory:docs-related-cli` - Update docs for changed modules only
- `/workflow:execute` - Execute documentation tasks (when using agent mode)
- **Directory**: `.workflow/docs/{project_name}/` — Complete documentation tree
- **Project-Level**: README.md, ARCHITECTURE.md, EXAMPLES.md, api/README.md (optional)
- **Report**: Summary with success/failure counts and tool usage statistics
## Next Phase
Return to [manage.md](../manage.md) router.

View File

@@ -1,22 +1,24 @@
---
name: docs-related-cli
description: Generate/update documentation for git-changed modules using CLI execution with batched agents (4 modules/agent) and gemini→qwen→codex fallback, <15 modules uses direct parallel
argument-hint: "[--tool <gemini|qwen|codex>]"
---
# Phase 5: Related Documentation Generation (docs-related)
# Related Documentation Generation - CLI Mode (/memory:docs-related-cli)
仅为 git 变更模块生成/更新 API.md + README.md 文档,使用增量策略和自动 tool fallback。
## Overview
## Objective
Orchestrates context-aware documentation generation/update for changed modules using CLI-based execution with batched agents and automatic tool fallback (gemini→qwen→codex).
- 检测 git 变更,识别受影响模块
- 按深度 N→0 顺序为变更模块生成/更新文档
- <15 模块直接并行≥15 模块使用 agent 批处理
- 使用 single 策略进行增量更新
- 自动 tool fallback (gemini→qwen→codex)
## Parameters
**Parameters**:
- `--tool <gemini|qwen|codex>`: Primary tool (default: gemini)
**Execution Flow**:
1. Change Detection → 2. Plan Presentation → 3. Batched Execution → 4. Verification
## Execution
## Core Rules
**Execution Flow**: Change Detection → Plan Presentation → Batched Execution → Verification
### Core Rules
1. **Detect Changes First**: Use git diff to identify affected modules
2. **Wait for Approval**: Present plan, no execution without user confirmation
@@ -28,7 +30,7 @@ Orchestrates context-aware documentation generation/update for changed modules u
6. **Related Mode**: Generate/update only changed modules and their parent contexts
7. **Single Strategy**: Always use `single` strategy (incremental update)
## Tool Fallback Hierarchy
### Tool Fallback Hierarchy
```javascript
--tool gemini → [gemini, qwen, codex] // default
@@ -36,15 +38,7 @@ Orchestrates context-aware documentation generation/update for changed modules u
--tool codex → [codex, gemini, qwen]
```
**Trigger**: Non-zero exit code from generation script
| Tool | Best For | Fallback To |
|--------|--------------------------------|----------------|
| gemini | Documentation, patterns | qwen → codex |
| qwen | Architecture, system design | gemini → codex |
| codex | Implementation, code quality | gemini → qwen |
## Phase 1: Change Detection & Analysis
### Step 5.1: Change Detection & Analysis
```javascript
// Get project metadata
@@ -63,7 +57,7 @@ Bash({command: "git add -A 2>/dev/null || true", run_in_background: false});
**Fallback**: If no changes detected, use recent modules (first 10 by depth).
## Phase 2: Plan Presentation
### Step 5.2: Plan Presentation
**Present filtered plan**:
```
@@ -95,8 +89,6 @@ Related Documentation Generation Plan:
- Depth 1 (1 module): 1 agent [1]
- Depth 0 (1 module): 1 agent [1]
Estimated time: ~5-10 minutes
Confirm execution? (y/n)
```
@@ -106,7 +98,7 @@ Related Documentation Generation Plan:
- <15 modules: Direct execution
- ≥15 modules: Agent batch execution
## Phase 3A: Direct Execution (<15 modules)
### Step 5.3A: Direct Execution (<15 modules)
**Strategy**: Parallel execution within depth (max 4 concurrent), no agent overhead.
@@ -140,9 +132,9 @@ for (let depth of sorted_depths.reverse()) { // N → 0
}
```
## Phase 3B: Agent Batch Execution (≥15 modules)
### Step 5.3B: Agent Batch Execution (≥15 modules)
### Batching Strategy
#### Batching Strategy
```javascript
// Batch modules into groups of 4
@@ -156,7 +148,7 @@ function batch_modules(modules, batch_size = 4) {
// Examples: 10→[4,4,2] | 8→[4,4] | 3→[3]
```
### Coordinator Orchestration
#### Coordinator Orchestration
```javascript
let modules_by_depth = group_by_depth(changed_modules);
@@ -181,7 +173,7 @@ for (let depth of sorted_depths.reverse()) { // N → 0
}
```
### Batch Worker Prompt Template
#### Batch Worker Prompt Template
```
PURPOSE: Generate/update documentation for assigned modules with tool fallback (related mode)
@@ -239,7 +231,7 @@ Report final summary with:
- Tool usage: {{tool_1}}:X, {{tool_2}}:Y, {{tool_3}}:Z
```
## Phase 4: Verification
### Step 5.4: Verification
```javascript
// Check documentation files created/updated
@@ -270,15 +262,23 @@ Documentation Generation Summary:
.workflow/docs/myproject/README.md (updated)
```
## Execution Summary
## Output Structure
**Module Count Threshold**:
- **<15 modules**: Coordinator executes Phase 3A (Direct Execution)
- **≥15 modules**: Coordinator executes Phase 3B (Agent Batch Execution)
**Agent Hierarchy** (for ≥15 modules):
- **Coordinator**: Handles batch division, spawns worker agents per depth
- **Worker Agents**: Each processes 4 modules with tool fallback (related mode)
```
.workflow/docs/{project_name}/
├── src/ # Mirrors source structure
│ ├── modules/
│ │ ├── README.md
│ │ ├── auth/
│ │ │ ├── API.md # Updated based on code changes
│ │ │ └── README.md # Updated based on code changes
│ │ └── api/
│ │ ├── API.md
│ │ └── README.md
│ └── utils/
│ └── README.md
└── README.md
```
## Error Handling
@@ -298,80 +298,6 @@ Documentation Generation Summary:
- Script timeout
- Unexpected output
## Output Structure
```
.workflow/docs/{project_name}/
├── src/ # Mirrors source structure
│ ├── modules/
│ │ ├── README.md
│ │ ├── auth/
│ │ │ ├── API.md # Updated based on code changes
│ │ │ └── README.md # Updated based on code changes
│ │ └── api/
│ │ ├── API.md
│ │ └── README.md
│ └── utils/
│ └── README.md
└── README.md
```
## Usage Examples
```bash
# Daily development documentation update
/memory:docs-related-cli
# After feature work with specific tool
/memory:docs-related-cli --tool qwen
# Code quality documentation review after implementation
/memory:docs-related-cli --tool codex
```
## Key Advantages
**Efficiency**: 30 modules → 8 agents (73% reduction)
**Resilience**: 3-tier fallback per module
**Performance**: Parallel batches, no concurrency limits
**Context-aware**: Updates based on actual git changes
**Fast**: Only affected modules, not entire project
**Incremental**: Single strategy for focused updates
## Coordinator Checklist
- Parse `--tool` (default: gemini)
- Get project metadata (name, root)
- Detect changed modules via detect_changed_modules.sh
- **Smart filter modules** (auto-detect tech stack, skip tests/build/config/vendor)
- Cache git changes
- Apply fallback if no changes (recent 10 modules)
- Construct tool fallback order
- **Present filtered plan** with skip reasons and change types
- **Wait for y/n confirmation**
- Determine execution mode:
- **<15 modules**: Direct execution (Phase 3A)
- For each depth (N→0): Sequential module updates with tool fallback
- **≥15 modules**: Agent batch execution (Phase 3B)
- For each depth (N→0): Batch modules (4 per batch), spawn batch workers in parallel
- Wait for depth/batch completion
- Aggregate results
- Verification check (documentation files created/updated)
- Display summary + recent changes
## Comparison with Full Documentation Generation
| Aspect | Related Generation | Full Generation |
|--------|-------------------|-----------------|
| **Scope** | Changed modules only | All project modules |
| **Speed** | Fast (minutes) | Slower (10-30 min) |
| **Use case** | Daily development | Initial setup, major refactoring |
| **Strategy** | `single` (all) | `full` (L3) + `single` (L1-2) |
| **Trigger** | After commits | After setup or major changes |
| **Batching** | 4 modules/agent | 4 modules/agent |
| **Fallback** | gemini→qwen→codex | gemini→qwen→codex |
| **Complexity threshold** | ≤15 modules | ≤20 modules |
## Template Reference
Templates used from `~/.ccw/workflows/cli-templates/prompts/documentation/`:
@@ -379,8 +305,11 @@ Templates used from `~/.ccw/workflows/cli-templates/prompts/documentation/`:
- `module-readme.txt`: Module purpose, usage, dependencies
- `folder-navigation.txt`: Navigation README for folders
## Related Commands
## Output
- `/memory:docs-full-cli` - Full project documentation generation
- `/memory:docs` - Agent-based documentation planning workflow
- `/memory:update-related` - Update CLAUDE.md for changed modules
- **Directory**: `.workflow/docs/{project_name}/` — Updated documentation for changed modules
- **Report**: Summary with success/failure counts, tool usage, and file change list
## Next Phase
Return to [manage.md](../manage.md) router.