mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +08:00
feat: enhance documentation generation process with improved structure and quality guidelines
This commit is contained in:
catlog22
@@ -26,6 +26,81 @@ You are an expert technical documentation specialist. Your responsibility is to
|
||||
- **Template-Based**: You apply specified templates to generate consistent and high-quality documentation.
|
||||
- **Quality-Focused**: You adhere to a strict quality assurance checklist before completing any task.
|
||||
|
||||
## Documentation Quality Principles
|
||||
|
||||
### 1. Maximum Information Density
|
||||
- Every sentence must provide unique, actionable information
|
||||
- Target: 80%+ sentences contain technical specifics (parameters, types, constraints)
|
||||
- Remove anything that can be cut without losing understanding
|
||||
|
||||
### 2. Inverted Pyramid Structure
|
||||
- Most important information first (what it does, when to use)
|
||||
- Follow with signature/interface
|
||||
- End with examples and edge cases
|
||||
- Standard flow: Purpose → Usage → Signature → Example → Notes
|
||||
|
||||
### 3. Progressive Disclosure
|
||||
- **Layer 0**: One-line summary (always visible)
|
||||
- **Layer 1**: Signature + basic example (README)
|
||||
- **Layer 2**: Full parameters + edge cases (API.md)
|
||||
- **Layer 3**: Implementation + architecture (ARCHITECTURE.md)
|
||||
- Use cross-references instead of duplicating content
|
||||
|
||||
### 4. Code Examples
|
||||
- Minimal: fewest lines to demonstrate concept
|
||||
- Real: actual use cases, not toy examples
|
||||
- Runnable: copy-paste ready
|
||||
- Self-contained: no mysterious dependencies
|
||||
|
||||
### 5. Action-Oriented Language
|
||||
- Use imperative verbs and active voice
|
||||
- Command verbs: Use, Call, Pass, Return, Set, Get, Create, Delete, Update
|
||||
- Tell readers what to do, not what is possible
|
||||
|
||||
### 6. Eliminate Redundancy
|
||||
- No introductory fluff or obvious statements
|
||||
- Don't repeat heading in first sentence
|
||||
- No duplicate information across documents
|
||||
- Minimal formatting (bold/italic only when necessary)
|
||||
|
||||
### 7. Document-Specific Guidelines
|
||||
|
||||
**API.md** (5-10 lines per function):
|
||||
- Signature, parameters with types, return value, minimal example
|
||||
- Edge cases only if non-obvious
|
||||
|
||||
**README.md** (30-100 lines):
|
||||
- Purpose (1-2 sentences), when to use, quick start, link to API.md
|
||||
- No architecture details (link to ARCHITECTURE.md)
|
||||
|
||||
**ARCHITECTURE.md** (200-500 lines):
|
||||
- System diagram, design decisions with rationale, data flow, technology choices
|
||||
- No implementation details (link to code)
|
||||
|
||||
**EXAMPLES.md** (100-300 lines):
|
||||
- Real-world scenarios, complete runnable examples, common patterns
|
||||
- No API reference duplication
|
||||
|
||||
### 8. Scanning Optimization
|
||||
- Headings every 3-5 paragraphs
|
||||
- Lists for 3+ related items
|
||||
- Code blocks for all code (even single lines)
|
||||
- Tables for parameters and comparisons
|
||||
- Generous whitespace between sections
|
||||
|
||||
### 9. Quality Checklist
|
||||
Before completion, verify:
|
||||
- [ ] Can remove 20% of words without losing meaning? (If yes, do it)
|
||||
- [ ] 80%+ sentences are technically specific?
|
||||
- [ ] First paragraph answers "what" and "when"?
|
||||
- [ ] Reader can find any info in <10 seconds?
|
||||
- [ ] Most important info in first screen?
|
||||
- [ ] Examples runnable without modification?
|
||||
- [ ] No duplicate information across files?
|
||||
- [ ] No empty or obvious statements?
|
||||
- [ ] Headings alone convey the flow?
|
||||
- [ ] All code blocks syntactically highlighted?
|
||||
|
||||
## Optimized Execution Model
|
||||
|
||||
**Key Principle**: Lightweight metadata loading + targeted content analysis
|
||||
|
||||
@@ -65,62 +65,42 @@ Lightweight planner that analyzes project structure, decomposes documentation wo
|
||||
|
||||
### Phase 1: Initialize Session
|
||||
|
||||
#### Step 1: Create Session and Generate Config
|
||||
#### Step 1: Get Target Path and Project Name
|
||||
```bash
|
||||
# Create session structure and initialize config in one step
|
||||
bash(
|
||||
# Parse arguments
|
||||
path="${1:-.}"
|
||||
tool="gemini"
|
||||
mode="full"
|
||||
cli_generate=false
|
||||
shift
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case "$1" in
|
||||
--tool) tool="$2"; shift 2 ;;
|
||||
--mode) mode="$2"; shift 2 ;;
|
||||
--cli-generate) cli_generate=true; shift ;;
|
||||
*) shift ;;
|
||||
esac
|
||||
done
|
||||
# Get current directory as target path
|
||||
bash(pwd)
|
||||
|
||||
# Detect paths
|
||||
project_root=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
|
||||
if [[ "$path" == /* ]] || [[ "$path" == [A-Z]:* ]]; then
|
||||
target_path="$path"
|
||||
else
|
||||
target_path=$(cd "$path" 2>/dev/null && pwd || echo "$PWD/$path")
|
||||
fi
|
||||
# Get project name from current directory
|
||||
bash(basename "$(pwd)")
|
||||
|
||||
# Extract project name from target_path
|
||||
project_name=$(basename "$target_path")
|
||||
# Get project root from git
|
||||
bash(git rev-parse --show-toplevel 2>/dev/null || pwd)
|
||||
|
||||
# Create session
|
||||
timestamp=$(date +%Y%m%d-%H%M%S)
|
||||
session="WFS-docs-${timestamp}"
|
||||
mkdir -p ".workflow/${session}"/{.task,.process,.summaries}
|
||||
touch ".workflow/.active-${session}"
|
||||
# Generate timestamp for session ID
|
||||
bash(date +%Y%m%d-%H%M%S)
|
||||
```
|
||||
|
||||
# Generate single config file with all info
|
||||
cat > ".workflow/${session}/.process/config.json" <<EOF
|
||||
{
|
||||
"session_id": "${session}",
|
||||
"timestamp": "$(date -Iseconds)",
|
||||
"path": "${path}",
|
||||
"target_path": "${target_path}",
|
||||
"project_root": "${project_root}",
|
||||
"project_name": "${project_name}",
|
||||
"mode": "${mode}",
|
||||
"tool": "${tool}",
|
||||
"cli_generate": ${cli_generate}
|
||||
}
|
||||
EOF
|
||||
**Output**:
|
||||
- `target_path`: `/d/Claude_dms3`
|
||||
- `project_name`: `Claude_dms3`
|
||||
- `project_root`: `/d/Claude_dms3`
|
||||
- `timestamp`: `20240120-143022`
|
||||
|
||||
echo "✓ Session initialized: ${session}"
|
||||
echo "✓ Target: ${target_path}"
|
||||
echo "✓ Mode: ${mode}"
|
||||
echo "✓ Tool: ${tool}, CLI generate: ${cli_generate}"
|
||||
)
|
||||
#### Step 2: Create Session Structure
|
||||
```bash
|
||||
# Create session directories (replace timestamp with actual value)
|
||||
bash(mkdir -p .workflow/WFS-docs-20240120-143022/.task)
|
||||
bash(mkdir -p .workflow/WFS-docs-20240120-143022/.process)
|
||||
bash(mkdir -p .workflow/WFS-docs-20240120-143022/.summaries)
|
||||
|
||||
# Mark session as active
|
||||
bash(touch .workflow/.active-WFS-docs-20240120-143022)
|
||||
```
|
||||
|
||||
#### Step 3: Create Config File
|
||||
```bash
|
||||
# Create config.json with session info (replace values with actual data)
|
||||
bash(echo '{"session_id":"WFS-docs-20240120-143022","timestamp":"2024-01-20T14:30:22+08:00","path":".","target_path":"/d/Claude_dms3","project_root":"/d/Claude_dms3","project_name":"Claude_dms3","mode":"full","tool":"gemini","cli_generate":false}' | jq '.' > .workflow/WFS-docs-20240120-143022/.process/config.json)
|
||||
```
|
||||
|
||||
**Output**:
|
||||
@@ -195,69 +175,57 @@ bash(jq '. + {analysis: {total: "15", code: "8", navigation: "7", top_level: "3"
|
||||
|
||||
### Phase 3: Detect Update Mode
|
||||
|
||||
#### Step 1: Count Existing Documentation in .workflow/docs/{project_name}/
|
||||
#### Step 1: Get Project Name from Config
|
||||
```bash
|
||||
# Check .workflow/docs/{project_name}/ directory and count existing files
|
||||
bash(
|
||||
project_name=$(jq -r '.project_name' .workflow/WFS-docs-20240120/.process/config.json)
|
||||
if [[ -d ".workflow/docs/${project_name}" ]]; then
|
||||
find .workflow/docs/${project_name} -name "*.md" 2>/dev/null | wc -l
|
||||
else
|
||||
echo "0"
|
||||
fi
|
||||
)
|
||||
# Read project name from config
|
||||
bash(jq -r '.project_name' .workflow/WFS-docs-20240120-143022/.process/config.json)
|
||||
```
|
||||
|
||||
**Output**: `5` (existing docs in .workflow/docs/{project_name}/)
|
||||
**Output**: `Claude_dms3`
|
||||
|
||||
#### Step 2: List Existing Documentation
|
||||
#### Step 2: Count Existing Documentation
|
||||
```bash
|
||||
# List existing files in .workflow/docs/{project_name}/ (for task context)
|
||||
bash(
|
||||
project_name=$(jq -r '.project_name' .workflow/WFS-docs-20240120/.process/config.json)
|
||||
if [[ -d ".workflow/docs/${project_name}" ]]; then
|
||||
find .workflow/docs/${project_name} -name "*.md" 2>/dev/null > .workflow/WFS-docs-20240120/.process/existing-docs.txt
|
||||
else
|
||||
touch .workflow/WFS-docs-20240120/.process/existing-docs.txt
|
||||
fi
|
||||
)
|
||||
# Count existing docs (replace project_name with actual value)
|
||||
bash(find .workflow/docs/Claude_dms3 -name "*.md" 2>/dev/null | wc -l || echo 0)
|
||||
```
|
||||
|
||||
**Output**: `5` (existing docs) or `0` (no docs)
|
||||
|
||||
#### Step 3: List Existing Documentation Files
|
||||
```bash
|
||||
# List existing docs to file (replace project_name and session)
|
||||
bash(find .workflow/docs/Claude_dms3 -name "*.md" 2>/dev/null > .workflow/WFS-docs-20240120-143022/.process/existing-docs.txt || touch .workflow/WFS-docs-20240120-143022/.process/existing-docs.txt)
|
||||
|
||||
# Display existing docs
|
||||
bash(cat .workflow/WFS-docs-20240120-143022/.process/existing-docs.txt)
|
||||
```
|
||||
|
||||
**Output** (existing-docs.txt):
|
||||
```
|
||||
.workflow/docs/my_app/src/modules/auth/API.md
|
||||
.workflow/docs/my_app/src/modules/auth/README.md
|
||||
.workflow/docs/my_app/lib/core/README.md
|
||||
.workflow/docs/my_app/README.md
|
||||
.workflow/docs/Claude_dms3/src/modules/auth/API.md
|
||||
.workflow/docs/Claude_dms3/src/modules/auth/README.md
|
||||
.workflow/docs/Claude_dms3/lib/core/README.md
|
||||
.workflow/docs/Claude_dms3/README.md
|
||||
```
|
||||
|
||||
#### Step 3: Update Config with Update Status
|
||||
#### Step 4: Update Config with Update Status
|
||||
```bash
|
||||
# Determine update status (create or update) and update config
|
||||
bash(
|
||||
project_name=$(jq -r '.project_name' .workflow/WFS-docs-20240120/.process/config.json)
|
||||
existing_count=$(find .workflow/docs/${project_name} -name "*.md" 2>/dev/null | wc -l)
|
||||
if [[ $existing_count -gt 0 ]]; then
|
||||
jq ". + {update_mode: \"update\", existing_docs: $existing_count}" .workflow/WFS-docs-20240120/.process/config.json > .workflow/WFS-docs-20240120/.process/config.json.tmp && mv .workflow/WFS-docs-20240120/.process/config.json.tmp .workflow/WFS-docs-20240120/.process/config.json
|
||||
else
|
||||
jq '. + {update_mode: "create", existing_docs: 0}' .workflow/WFS-docs-20240120/.process/config.json > .workflow/WFS-docs-20240120/.process/config.json.tmp && mv .workflow/WFS-docs-20240120/.process/config.json.tmp .workflow/WFS-docs-20240120/.process/config.json
|
||||
fi
|
||||
)
|
||||
# If existing_count > 0, update config with "update" mode (replace session and count)
|
||||
bash(jq '. + {update_mode: "update", existing_docs: 5}' .workflow/WFS-docs-20240120-143022/.process/config.json > .workflow/WFS-docs-20240120-143022/.process/config.json.tmp && mv .workflow/WFS-docs-20240120-143022/.process/config.json.tmp .workflow/WFS-docs-20240120-143022/.process/config.json)
|
||||
|
||||
# Display strategy summary
|
||||
bash(
|
||||
mode=$(jq -r '.mode' .workflow/WFS-docs-20240120/.process/config.json)
|
||||
update_mode=$(jq -r '.update_mode' .workflow/WFS-docs-20240120/.process/config.json)
|
||||
existing=$(jq -r '.existing_docs' .workflow/WFS-docs-20240120/.process/config.json)
|
||||
tool=$(jq -r '.tool' .workflow/WFS-docs-20240120/.process/config.json)
|
||||
cli_gen=$(jq -r '.cli_generate' .workflow/WFS-docs-20240120/.process/config.json)
|
||||
# Or if existing_count = 0, use "create" mode
|
||||
bash(jq '. + {update_mode: "create", existing_docs: 0}' .workflow/WFS-docs-20240120-143022/.process/config.json > .workflow/WFS-docs-20240120-143022/.process/config.json.tmp && mv .workflow/WFS-docs-20240120-143022/.process/config.json.tmp .workflow/WFS-docs-20240120-143022/.process/config.json)
|
||||
```
|
||||
|
||||
echo "📋 Documentation Strategy:"
|
||||
echo " - Path: $(jq -r '.target_path' .workflow/WFS-docs-20240120/.process/config.json)"
|
||||
echo " - Mode: $mode ($([ "$mode" = "full" ] && echo "complete docs" || echo "modules only"))"
|
||||
echo " - Update: $update_mode ($existing existing files)"
|
||||
echo " - Tool: $tool, CLI generate: $cli_gen"
|
||||
)
|
||||
#### Step 5: Display Strategy Summary
|
||||
```bash
|
||||
# Read config values
|
||||
bash(jq -r '.mode' .workflow/WFS-docs-20240120-143022/.process/config.json)
|
||||
bash(jq -r '.update_mode' .workflow/WFS-docs-20240120-143022/.process/config.json)
|
||||
bash(jq -r '.existing_docs' .workflow/WFS-docs-20240120-143022/.process/config.json)
|
||||
bash(jq -r '.tool' .workflow/WFS-docs-20240120-143022/.process/config.json)
|
||||
bash(jq -r '.cli_generate' .workflow/WFS-docs-20240120-143022/.process/config.json)
|
||||
bash(jq -r '.target_path' .workflow/WFS-docs-20240120-143022/.process/config.json)
|
||||
```
|
||||
|
||||
### Phase 4: Decompose Tasks
|
||||
@@ -277,98 +245,92 @@ Level 3: Architecture & Examples (mode=full only, depends on Level 2)
|
||||
└─ IMPL-006: Generate HTTP API (optional)
|
||||
```
|
||||
|
||||
#### Step 1: Generate Level 1 Tasks (Module Trees)
|
||||
#### Step 1: Read Top-Level Directories
|
||||
```bash
|
||||
# Read top-level directories and create tasks
|
||||
bash(
|
||||
task_count=0
|
||||
while read -r top_dir; do
|
||||
task_count=$((task_count + 1))
|
||||
task_id=$(printf "IMPL-%03d" $task_count)
|
||||
echo "Creating $task_id for '$top_dir'"
|
||||
# Generate task JSON (see Task Templates section)
|
||||
done < .workflow/WFS-docs-20240120/.process/top-level-dirs.txt
|
||||
)
|
||||
# Read top-level directories list
|
||||
bash(cat .workflow/WFS-docs-20240120-143022/.process/top-level-dirs.txt)
|
||||
```
|
||||
|
||||
**Output**:
|
||||
```
|
||||
Creating IMPL-001 for 'src/modules'
|
||||
Creating IMPL-002 for 'src/utils'
|
||||
Creating IMPL-003 for 'lib'
|
||||
src/modules
|
||||
src/utils
|
||||
lib
|
||||
```
|
||||
|
||||
#### Step 2: Generate Level 2-3 Tasks (Full Mode Only)
|
||||
#### Step 2: Count Directories for Task Generation
|
||||
```bash
|
||||
# Check documentation mode
|
||||
bash(jq -r '.mode' .workflow/WFS-docs-20240120/.process/config.json)
|
||||
|
||||
# If full mode, create project-level tasks
|
||||
bash(
|
||||
mode=$(jq -r '.mode' .workflow/WFS-docs-20240120/.process/config.json)
|
||||
if [[ "$mode" == "full" ]]; then
|
||||
echo "Creating IMPL-004: Project README"
|
||||
echo "Creating IMPL-005: ARCHITECTURE.md + EXAMPLES.md"
|
||||
# Optional: Check for HTTP API endpoints
|
||||
if grep -r "router\.|@Get\|@Post" src/ >/dev/null 2>&1; then
|
||||
echo "Creating IMPL-006: HTTP API docs"
|
||||
fi
|
||||
else
|
||||
echo "Partial mode: Skipping project-level tasks"
|
||||
fi
|
||||
)
|
||||
# Count how many tasks to create
|
||||
bash(wc -l < .workflow/WFS-docs-20240120-143022/.process/top-level-dirs.txt)
|
||||
```
|
||||
|
||||
**Output**: `3` (will generate IMPL-001, IMPL-002, IMPL-003)
|
||||
|
||||
#### Step 3: Check Documentation Mode
|
||||
```bash
|
||||
# Check if full or partial mode
|
||||
bash(jq -r '.mode' .workflow/WFS-docs-20240120-143022/.process/config.json)
|
||||
```
|
||||
|
||||
**Output**: `full` or `partial`
|
||||
|
||||
#### Step 4: Check for HTTP API Endpoints (Optional)
|
||||
```bash
|
||||
# Search for API endpoint patterns
|
||||
bash(grep -r "router\.|@Get\|@Post" src/ 2>/dev/null && echo "API_FOUND" || echo "NO_API")
|
||||
```
|
||||
|
||||
**Output**: `API_FOUND` or `NO_API`
|
||||
|
||||
**Task Generation Summary**:
|
||||
- **Partial mode**: Generate only IMPL-001, IMPL-002, IMPL-003 (module trees)
|
||||
- **Full mode without API**: Generate IMPL-001 to IMPL-005
|
||||
- **Full mode with API**: Generate IMPL-001 to IMPL-006
|
||||
|
||||
### Phase 5: Generate Task JSONs
|
||||
|
||||
#### Step 1: Extract Configuration
|
||||
#### Step 1: Read Configuration Values
|
||||
```bash
|
||||
# Read config values from JSON
|
||||
bash(jq -r '.tool' .workflow/WFS-docs-20240120/.process/config.json)
|
||||
bash(jq -r '.cli_generate' .workflow/WFS-docs-20240120/.process/config.json)
|
||||
```
|
||||
# Read tool selection
|
||||
bash(jq -r '.tool' .workflow/WFS-docs-20240120-143022/.process/config.json)
|
||||
|
||||
**Output**: `tool=gemini`, `cli_generate=false`
|
||||
# Read cli_generate flag
|
||||
bash(jq -r '.cli_generate' .workflow/WFS-docs-20240120-143022/.process/config.json)
|
||||
|
||||
#### Step 2: Determine CLI Command Strategy
|
||||
```bash
|
||||
# Determine MODE and placement based on cli_generate flag
|
||||
bash(
|
||||
cli_generate=$(jq -r '.cli_generate' .workflow/WFS-docs-20240120/.process/config.json)
|
||||
|
||||
if [[ "$cli_generate" == "true" ]]; then
|
||||
echo "mode=write"
|
||||
echo "placement=implementation_approach"
|
||||
echo "approval_flag=--approval-mode yolo"
|
||||
else
|
||||
echo "mode=analysis"
|
||||
echo "placement=pre_analysis"
|
||||
echo "approval_flag="
|
||||
fi
|
||||
)
|
||||
# Read mode
|
||||
bash(jq -r '.mode' .workflow/WFS-docs-20240120-143022/.process/config.json)
|
||||
```
|
||||
|
||||
**Output**:
|
||||
```
|
||||
mode=analysis
|
||||
placement=pre_analysis
|
||||
approval_flag=
|
||||
```
|
||||
- `tool`: `gemini`
|
||||
- `cli_generate`: `false`
|
||||
- `mode`: `full`
|
||||
|
||||
#### Step 3: Build Tool-Specific Commands
|
||||
```bash
|
||||
# Generate command templates based on tool selection
|
||||
bash(
|
||||
tool=$(jq -r '.tool' .workflow/WFS-docs-20240120/.process/config.json)
|
||||
#### Step 2: Determine CLI Strategy
|
||||
|
||||
if [[ "$tool" == "codex" ]]; then
|
||||
echo "codex -C \${dir} --full-auto exec \"...\" --skip-git-repo-check -s danger-full-access"
|
||||
else
|
||||
echo "bash(cd \${dir} && ${tool} ${approval_flag} -p \"...\")"
|
||||
# Direct CLI commands for gemini/qwen
|
||||
fi
|
||||
)
|
||||
```
|
||||
**If cli_generate = false**:
|
||||
- MODE: `analysis`
|
||||
- Placement: `pre_analysis`
|
||||
- Approval flag: (none)
|
||||
- Command pattern: `cd dir && gemini -p "..."`
|
||||
|
||||
**If cli_generate = true**:
|
||||
- MODE: `write`
|
||||
- Placement: `implementation_approach`
|
||||
- Approval flag: `--approval-mode yolo`
|
||||
- Command pattern: `cd dir && gemini --approval-mode yolo -p "..."`
|
||||
|
||||
**If tool = codex**:
|
||||
- Command pattern: `codex -C dir --full-auto exec "..." --skip-git-repo-check -s danger-full-access`
|
||||
|
||||
#### Step 3: Generate Task JSON Files
|
||||
|
||||
Tasks are generated based on:
|
||||
- Top-level directories from Phase 4
|
||||
- Configuration from config.json
|
||||
- Task templates (see Task Templates section below)
|
||||
|
||||
Each task JSON is written to `.workflow/WFS-docs-20240120-143022/.task/IMPL-XXX.json`
|
||||
|
||||
## Task Templates
|
||||
|
||||
@@ -782,38 +744,48 @@ bash(
|
||||
|
||||
### Session Management
|
||||
```bash
|
||||
# Create session and initialize config (all in one)
|
||||
bash(
|
||||
session="WFS-docs-$(date +%Y%m%d-%H%M%S)"
|
||||
mkdir -p ".workflow/${session}"/{.task,.process,.summaries}
|
||||
touch ".workflow/.active-${session}"
|
||||
cat > ".workflow/${session}/.process/config.json" <<EOF
|
||||
{"session_id":"${session}","timestamp":"$(date -Iseconds)","path":".","mode":"full","tool":"gemini","cli_generate":false}
|
||||
EOF
|
||||
echo "Session: ${session}"
|
||||
)
|
||||
# Generate timestamp
|
||||
bash(date +%Y%m%d-%H%M%S)
|
||||
|
||||
# Create session directories (replace timestamp)
|
||||
bash(mkdir -p .workflow/WFS-docs-20240120-143022/.task)
|
||||
bash(mkdir -p .workflow/WFS-docs-20240120-143022/.process)
|
||||
bash(mkdir -p .workflow/WFS-docs-20240120-143022/.summaries)
|
||||
|
||||
# Mark as active
|
||||
bash(touch .workflow/.active-WFS-docs-20240120-143022)
|
||||
|
||||
# Get project name
|
||||
bash(basename "$(pwd)")
|
||||
|
||||
# Create config (replace values)
|
||||
bash(echo '{"session_id":"WFS-docs-20240120-143022","timestamp":"2024-01-20T14:30:22+08:00","path":".","target_path":"/d/project","project_name":"project","mode":"full","tool":"gemini","cli_generate":false}' | jq '.' > .workflow/WFS-docs-20240120-143022/.process/config.json)
|
||||
|
||||
# Read session config
|
||||
bash(cat .workflow/WFS-docs-20240120/.process/config.json)
|
||||
bash(cat .workflow/WFS-docs-20240120-143022/.process/config.json)
|
||||
|
||||
# Extract config values
|
||||
bash(jq -r '.tool' .workflow/WFS-docs-20240120/.process/config.json)
|
||||
bash(jq -r '.mode' .workflow/WFS-docs-20240120/.process/config.json)
|
||||
bash(jq -r '.tool' .workflow/WFS-docs-20240120-143022/.process/config.json)
|
||||
bash(jq -r '.mode' .workflow/WFS-docs-20240120-143022/.process/config.json)
|
||||
bash(jq -r '.project_name' .workflow/WFS-docs-20240120-143022/.process/config.json)
|
||||
|
||||
# List session tasks
|
||||
bash(ls .workflow/WFS-docs-20240120/.task/*.json)
|
||||
bash(ls .workflow/WFS-docs-20240120-143022/.task/*.json)
|
||||
```
|
||||
|
||||
### Analysis Commands
|
||||
```bash
|
||||
# Discover and classify folders (scans project source)
|
||||
bash(~/.claude/scripts/get_modules_by_depth.sh | ~/.claude/scripts/classify-folders.sh)
|
||||
# Discover and classify folders
|
||||
bash(~/.claude/scripts/get_modules_by_depth.sh | ~/.claude/scripts/classify-folders.sh > .workflow/WFS-docs-20240120-143022/.process/folder-analysis.txt)
|
||||
|
||||
# Count existing docs (in .workflow/docs/{project_name}/ directory)
|
||||
bash(if [[ -d ".workflow/docs/${project_name}" ]]; then find .workflow/docs/${project_name} -name "*.md" 2>/dev/null | wc -l; else echo "0"; fi)
|
||||
# Count existing docs (replace project_name)
|
||||
bash(find .workflow/docs/my_project -name "*.md" 2>/dev/null | wc -l || echo 0)
|
||||
|
||||
# List existing documentation (in .workflow/docs/{project_name}/ directory)
|
||||
bash(if [[ -d ".workflow/docs/${project_name}" ]]; then find .workflow/docs/${project_name} -name "*.md" 2>/dev/null; fi)
|
||||
# List existing documentation (replace project_name)
|
||||
bash(find .workflow/docs/my_project -name "*.md" 2>/dev/null || echo "No docs found")
|
||||
|
||||
# Check if docs directory exists
|
||||
bash(test -d .workflow/docs/my_project && echo "exists" || echo "not exists")
|
||||
```
|
||||
|
||||
## Template Reference
|
||||
|
||||
@@ -40,77 +40,61 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Bash(*), Read(*), Write(*)
|
||||
|
||||
**Goal**: Parse command arguments and check existing documentation
|
||||
|
||||
**Actions**:
|
||||
**Step 1: Get Target Path and Project Name**
|
||||
```bash
|
||||
# Parse arguments
|
||||
bash(
|
||||
path="${1:-.}"
|
||||
tool="gemini"
|
||||
regenerate=""
|
||||
mode="full"
|
||||
shift
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case "$1" in
|
||||
--tool) tool="$2"; shift 2 ;;
|
||||
--regenerate) regenerate="--regenerate"; shift ;;
|
||||
--mode) mode="$2"; shift 2 ;;
|
||||
*) shift ;;
|
||||
esac
|
||||
done
|
||||
# Get current directory (or use provided path)
|
||||
bash(pwd)
|
||||
|
||||
# Detect paths
|
||||
project_root=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
|
||||
if [[ "$path" == /* ]] || [[ "$path" == [A-Z]:* ]]; then
|
||||
target_path="$path"
|
||||
else
|
||||
target_path=$(cd "$path" 2>/dev/null && pwd || echo "$PWD/$path")
|
||||
fi
|
||||
# Get project name from directory
|
||||
bash(basename "$(pwd)")
|
||||
|
||||
project_name=$(basename "$target_path")
|
||||
docs_path=".workflow/docs/${project_name}"
|
||||
|
||||
echo "PROJECT_NAME: ${project_name}"
|
||||
echo "TARGET_PATH: ${target_path}"
|
||||
echo "DOCS_PATH: ${docs_path}"
|
||||
echo "TOOL: ${tool}"
|
||||
echo "MODE: ${mode}"
|
||||
echo "REGENERATE: ${regenerate}"
|
||||
)
|
||||
|
||||
# Check existing documentation
|
||||
bash(
|
||||
project_name="[from previous output]"
|
||||
docs_path=".workflow/docs/${project_name}"
|
||||
regenerate="[from previous output]"
|
||||
|
||||
if [[ -d "$docs_path" ]]; then
|
||||
doc_count=$(find "$docs_path" -name "*.md" 2>/dev/null | wc -l)
|
||||
echo "EXISTING_DOCS: $doc_count"
|
||||
|
||||
# Handle --regenerate flag: delete existing docs
|
||||
if [[ -n "$regenerate" ]]; then
|
||||
echo "REGENERATE: Deleting existing docs at ${docs_path}"
|
||||
rm -rf "$docs_path"
|
||||
echo "EXISTING_DOCS: 0 (after regenerate)"
|
||||
fi
|
||||
else
|
||||
echo "EXISTING_DOCS: 0"
|
||||
fi
|
||||
)
|
||||
# Get project root
|
||||
bash(git rev-parse --show-toplevel 2>/dev/null || pwd)
|
||||
```
|
||||
|
||||
**Parse Output**:
|
||||
- `PROJECT_NAME`: Project name (store as `projectName`)
|
||||
- `TARGET_PATH`: Full target path (store as `targetPath`)
|
||||
- `DOCS_PATH`: Documentation path (store as `docsPath`)
|
||||
- `TOOL`: CLI tool selection (store as `tool`)
|
||||
- `MODE`: Documentation mode (store as `mode`)
|
||||
- `REGENERATE`: Regenerate flag (store as `regenerateFlag`)
|
||||
- `EXISTING_DOCS`: Existing doc count (store as `existingDocs`)
|
||||
**Output**:
|
||||
- `target_path`: `/d/my_project`
|
||||
- `project_name`: `my_project`
|
||||
- `project_root`: `/d/my_project`
|
||||
|
||||
**Validation**:
|
||||
- Target path exists
|
||||
- Project name extracted
|
||||
**Step 2: Set Default Parameters**
|
||||
```bash
|
||||
# Default values (use these unless user specifies otherwise):
|
||||
# - tool: "gemini"
|
||||
# - mode: "full"
|
||||
# - regenerate: false (no --regenerate flag)
|
||||
```
|
||||
|
||||
**Step 3: Check Existing Documentation**
|
||||
```bash
|
||||
# Check if docs directory exists (replace project_name with actual value)
|
||||
bash(test -d .workflow/docs/my_project && echo "exists" || echo "not_exists")
|
||||
|
||||
# Count existing documentation files
|
||||
bash(find .workflow/docs/my_project -name "*.md" 2>/dev/null | wc -l || echo 0)
|
||||
```
|
||||
|
||||
**Output**:
|
||||
- `docs_exists`: `exists` or `not_exists`
|
||||
- `existing_docs`: `5` (or `0` if no docs)
|
||||
|
||||
**Step 4: Handle --regenerate Flag (If Specified)**
|
||||
```bash
|
||||
# If user specified --regenerate, delete existing docs directory
|
||||
bash(rm -rf .workflow/docs/my_project 2>/dev/null || true)
|
||||
|
||||
# Verify deletion
|
||||
bash(test -d .workflow/docs/my_project && echo "still_exists" || echo "deleted")
|
||||
```
|
||||
|
||||
**Summary**:
|
||||
- `PROJECT_NAME`: `my_project`
|
||||
- `TARGET_PATH`: `/d/my_project`
|
||||
- `DOCS_PATH`: `.workflow/docs/my_project`
|
||||
- `TOOL`: `gemini` (default) or user-specified
|
||||
- `MODE`: `full` (default) or user-specified
|
||||
- `REGENERATE`: `false` (default) or `true` if --regenerate flag
|
||||
- `EXISTING_DOCS`: `0` (after regenerate) or actual count
|
||||
|
||||
**TodoWrite**: Mark phase 1 completed, phase 2 in_progress
|
||||
|
||||
@@ -178,38 +162,69 @@ SlashCommand(command="/workflow:execute")
|
||||
|
||||
**Goal**: Create SKILL.md at `.claude/skills/{project_name}/SKILL.md`
|
||||
|
||||
**Actions**:
|
||||
|
||||
1. **Load project README for description**:
|
||||
**Step 1: Load Project README**
|
||||
```bash
|
||||
bash(
|
||||
project_name="[from Phase 1]"
|
||||
cat .workflow/docs/${project_name}/README.md 2>/dev/null | head -50 || echo "No README found"
|
||||
)
|
||||
# Read README for project description (replace project_name)
|
||||
bash(cat .workflow/docs/my_project/README.md 2>/dev/null | head -50 || echo "No README found")
|
||||
```
|
||||
|
||||
2. **Discover documentation structure**:
|
||||
**Step 2: Discover All Documentation Files**
|
||||
```bash
|
||||
bash(
|
||||
project_name="[from Phase 1]"
|
||||
find .workflow/docs/${project_name} -name "*.md" 2>/dev/null | sort
|
||||
)
|
||||
# List all documentation files (replace project_name)
|
||||
bash(find .workflow/docs/my_project -name "*.md" 2>/dev/null | sort)
|
||||
```
|
||||
|
||||
3. **Extract module directories**:
|
||||
```bash
|
||||
bash(
|
||||
project_name="[from Phase 1]"
|
||||
find .workflow/docs/${project_name} -mindepth 1 -maxdepth 2 -type d 2>/dev/null | sed "s|.workflow/docs/${project_name}/||" | sort -u
|
||||
)
|
||||
**Output**:
|
||||
```
|
||||
.workflow/docs/my_project/README.md
|
||||
.workflow/docs/my_project/ARCHITECTURE.md
|
||||
.workflow/docs/my_project/src/modules/auth/API.md
|
||||
.workflow/docs/my_project/src/modules/auth/README.md
|
||||
```
|
||||
|
||||
4. **Generate SKILL.md**:
|
||||
**Step 3: Count Documentation Files**
|
||||
```bash
|
||||
# Count total docs (replace project_name)
|
||||
bash(find .workflow/docs/my_project -name "*.md" 2>/dev/null | wc -l)
|
||||
```
|
||||
|
||||
Use the `Write` tool to create `.claude/skills/{project_name}/SKILL.md` with:
|
||||
**Output**: `12` files
|
||||
|
||||
**Step 4: Extract Module Directories**
|
||||
```bash
|
||||
# Find module directories (1-2 levels deep, replace project_name)
|
||||
bash(find .workflow/docs/my_project -mindepth 1 -maxdepth 2 -type d 2>/dev/null | sed 's|.workflow/docs/my_project/||' | sort -u)
|
||||
```
|
||||
|
||||
**Output**:
|
||||
```
|
||||
src
|
||||
src/modules
|
||||
src/utils
|
||||
lib
|
||||
lib/core
|
||||
```
|
||||
|
||||
**Step 5: Count Module Directories**
|
||||
```bash
|
||||
# Count modules (replace project_name)
|
||||
bash(find .workflow/docs/my_project -mindepth 1 -maxdepth 2 -type d 2>/dev/null | wc -l)
|
||||
```
|
||||
|
||||
**Output**: `5` modules
|
||||
|
||||
**Step 6: Create Skills Directory**
|
||||
```bash
|
||||
# Create directory for SKILL.md (replace project_name)
|
||||
bash(mkdir -p .claude/skills/my_project)
|
||||
```
|
||||
|
||||
**Step 7: Generate SKILL.md**
|
||||
|
||||
Use the `Write` tool to create `.claude/skills/my_project/SKILL.md` with:
|
||||
- YAML frontmatter (name, description from README)
|
||||
- Progressive loading guide (Level 0-3)
|
||||
- Module index with relative paths to `../../.workflow/docs/{project_name}/`
|
||||
- Module index with relative paths to `../../.workflow/docs/my_project/`
|
||||
|
||||
**SKILL.md Structure**:
|
||||
```markdown
|
||||
|
||||
Reference in New Issue
Block a user