From 5e35da32e8095cdbdd681fde1a7138b3bffdb2c1 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Sat, 28 Feb 2026 17:20:37 +0800 Subject: [PATCH] docs: enhance documentation with examples and fix package names - Fix incorrect package names (@ccw/cli, @anthropic/claude-code-workflow) to claude-code-workflow - Add workflow examples page with 8 practical artifact samples - Optimize sidebar navigation with emoji icons and second-level grouping - Add usage examples to commands and skills documentation - Update qa/issues.md with current status - Sync Chinese documentation changes --- docs/.vitepress/config.ts | 1 + docs/.vitepress/theme/index.ts | 2 + docs/commands/claude/index.md | 104 +++++++++ docs/guide/installation.md | 45 ++++ docs/index.md | 4 - docs/skills/index.md | 90 ++++++++ docs/workflows/examples.md | 391 +++++++++++++++++++++++++++++++++ docs/zh/index.md | 4 - 8 files changed, 633 insertions(+), 8 deletions(-) create mode 100644 docs/workflows/examples.md diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 49258fb6..d98bcd94 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -207,6 +207,7 @@ export default defineConfig({ items: [ { text: 'Overview', link: '/workflows/' }, { text: '4-Level System', link: '/workflows/4-level' }, + { text: 'Examples', link: '/workflows/examples' }, { text: 'Best Practices', link: '/workflows/best-practices' }, { text: 'Teams', link: '/workflows/teams' } ] diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts index 1f739937..9941ff3a 100644 --- a/docs/.vitepress/theme/index.ts +++ b/docs/.vitepress/theme/index.ts @@ -5,6 +5,7 @@ import DarkModeToggle from './components/DarkModeToggle.vue' import CopyCodeButton from './components/CopyCodeButton.vue' import Breadcrumb from './components/Breadcrumb.vue' import PageToc from './components/PageToc.vue' +import ProfessionalHome from './components/ProfessionalHome.vue' import Layout from './layouts/Layout.vue' import './styles/variables.css' import './styles/custom.css' @@ -21,5 +22,6 @@ export default { app.component('CopyCodeButton', CopyCodeButton) app.component('Breadcrumb', Breadcrumb) app.component('PageToc', PageToc) + app.component('ProfessionalHome', ProfessionalHome) } } diff --git a/docs/commands/claude/index.md b/docs/commands/claude/index.md index 350d25ee..78b1bf23 100644 --- a/docs/commands/claude/index.md +++ b/docs/commands/claude/index.md @@ -111,6 +111,110 @@ Most commands support the `--yes` or `-y` flag to enable auto mode and skip conf /ccw "implement user authentication" --yes ``` +## Usage Examples + +### Quick Analysis + +```bash +# Analyze codebase structure +/ccw "Analyze the authentication module architecture" + +# Quick bug diagnosis +/ccw "Diagnose why the login timeout issue occurs" +``` + +### Planning & Implementation + +```bash +# Create implementation plan +/workflow:plan "Add OAuth2 authentication with Google and GitHub providers" + +# Execute with auto mode +/workflow:execute --yes +``` + +### Code Review + +```bash +# Review current changes +/cli:codex-review + +# Focus on specific area +/cli:codex-review "Focus on security vulnerabilities in auth module" +``` + +### Session Management + +```bash +# List all sessions +/workflow:session:list + +# Resume a paused session +/workflow:session:resume "WFS-001" + +# Mark session as complete +/workflow:session:complete "WFS-001" +``` + +### Issue Workflow + +```bash +# Discover issues from codebase +/issue:discover + +# Create plan for specific issue +/issue:plan "ISSUE-001" + +# Execute the fix +/issue:execute --commit +``` + +### Memory Management + +```bash +# Capture current session learnings +/memory:capture "Key insights from authentication refactoring" + +# List all memories +/memory:list + +# Search memories +/memory:search "authentication patterns" +``` + +### CLI Tool Invocation + +```bash +# Initialize CLI configuration +/cli:cli-init + +# Run Gemini analysis +ccw cli -p "Analyze code patterns in src/auth" --tool gemini --mode analysis + +# Run with specific rule template +ccw cli -p "Review code quality" --tool gemini --mode analysis --rule analysis-review-code-quality +``` + +### UI Design Workflow + +```bash +# Extract styles from reference image +/workflow:ui-design:style-extract --input "path/to/reference.png" + +# Generate prototype +/workflow:ui-design:generate --layout "dashboard" --tokens "design-tokens.json" +``` + +## Tips + +1. **Use Auto Mode Sparingly**: Only use `--yes` or `-y` for routine tasks. Keep manual confirmation for complex decisions. + +2. **Session Persistence**: Always complete sessions with `/workflow:session:complete` to preserve learnings. + +3. **Memory Capture**: Regularly capture important insights with `/memory:capture` to build project knowledge. + +4. **CLI Tool Selection**: Let `/ccw` auto-select the appropriate tool, or explicitly specify with `--tool gemini|qwen|codex`. + ## Related Documentation - [Skills Reference](../skills/) diff --git a/docs/guide/installation.md b/docs/guide/installation.md index cbc84c66..ff25e93d 100644 --- a/docs/guide/installation.md +++ b/docs/guide/installation.md @@ -144,3 +144,48 @@ echo 'set -gx PATH (npm config get prefix)/bin $PATH' >> ~/.config/fish/config.f ::: info Next Steps After installation, check out the [First Workflow](./first-workflow.md) guide. ::: + +## Quick Start Example + +After installation, try these commands to verify everything works: + +```bash +# 1. Initialize in your project +cd your-project +ccw init + +# 2. Try a simple analysis +ccw cli -p "Analyze the project structure" --tool gemini --mode analysis + +# 3. Run the main orchestrator +/ccw "Summarize the codebase architecture" + +# 4. Check available commands +ccw --help +``` + +### Expected Output + +``` +$ ccw --version +CCW v7.0.5 + +$ ccw init +✔ Created .claude/CLAUDE.md +✔ Created .ccw/workflows/ +✔ Configuration complete + +$ ccw cli -p "Analyze project" --tool gemini --mode analysis +Analyzing with Gemini... +✔ Analysis complete +``` + +### Common First-Time Issues + +| Issue | Solution | +|-------|----------| +| `ccw: command not found` | Add npm global bin to PATH, or reinstall | +| `Permission denied` | Use `sudo` or fix npm permissions | +| `API key not found` | Configure API keys in `~/.claude/cli-tools.json` | +| `Node version mismatch` | Update to Node.js >= 18.0.0 | + diff --git a/docs/index.md b/docs/index.md index 947b40c7..57ac1b1a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,8 +4,4 @@ title: CCW Documentation titleTemplate: Claude Code Workspace --- - - diff --git a/docs/skills/index.md b/docs/skills/index.md index 26f13292..cd8e010b 100644 --- a/docs/skills/index.md +++ b/docs/skills/index.md @@ -165,6 +165,96 @@ Skill(skill="my-custom-skill", args="input") 4. **Compact Recovery**: Use TodoWrite for progress tracking 5. **Documentation**: Include usage examples and expected outputs +## Practical Examples + +### Example 1: Feature Development + +**Scenario**: Implement a new user dashboard feature + +```bash +# Step 1: Brainstorm the feature +ccw brainstorm +# Follow prompts to define: +# - Dashboard widgets (stats, charts, recent activity) +# - Layout preferences +# - Data refresh intervals + +# Step 2: Plan implementation +ccw workflow:plan "Build user dashboard with configurable widgets" +# Outputs: IMPL-001.json with task breakdown + +# Step 3: Execute with team +ccw team lifecycle +# Or use quick iteration: +ccw workflow:lite-plan && ccw workflow:execute + +# Step 4: Review and refine +ccw review-code +# Fix any issues found +``` + +### Example 2: Bug Investigation + +**Scenario**: Debug performance issue in API endpoint + +```bash +# Step 1: Quick analysis +ccw cli -p "Analyze /api/users endpoint for N+1 query issues" --tool gemini --mode analysis + +# Step 2: Deep dive if needed +ccw workflow:debug-with-file +# Creates hypothesis, instruments code, analyzes logs + +# Step 3: Apply fix +ccw workflow:execute --task "Fix N+1 query in user endpoint" +``` + +### Example 3: Code Migration + +**Scenario**: Migrate from JavaScript to TypeScript + +```bash +# Step 1: Analyze codebase +ccw workflow:refactor-cycle +# Identifies tech debt and creates migration plan + +# Step 2: Execute migration in phases +ccw team roadmap-dev --epic "ts-migration" +# Progressively migrates modules with tests +``` + +### Example 4: Documentation Generation + +**Scenario**: Generate API documentation + +```bash +# Step 1: Capture existing patterns +ccw memory:capture "API patterns: REST, versioning, error handling" + +# Step 2: Generate docs +ccw software-manual --output ./docs/api/ +``` + +### Example 5: Code Review Pipeline + +**Scenario**: Review PR changes + +```bash +# Comprehensive review +ccw review-code --focus security,performance + +# Or use cycle for auto-fix +ccw review-cycle --max-iterations 3 +``` + +### Tips for Best Results + +1. **Start Small**: Begin with `workflow:lite-plan` for simple tasks +2. **Use Memory**: Capture insights with `memory:capture` for future reference +3. **Verify Plans**: Always review generated plans before execution +4. **Iterate**: Use `review-cycle` for continuous improvement +5. **Check Sessions**: Use `workflow:session:list` to track progress + ## Design Patterns Skills use these proven patterns: diff --git a/docs/workflows/examples.md b/docs/workflows/examples.md new file mode 100644 index 00000000..5164ff0b --- /dev/null +++ b/docs/workflows/examples.md @@ -0,0 +1,391 @@ +# Workflow Examples + +This page provides practical examples of CCW workflow artifacts with sensitive information redacted. + +## Example 1: Lite Plan Output + +### plan.json +This is an output from `workflow:lite-plan` command. + +```json +{ + "title": "Add user authentication with OAuth2", + "description": "Implement OAuth2 authentication with GitHub provider", + "entryPoint": "/api/auth/oauth2/callback", + "outputPath": "src/auth/oauth2/callback.ts", + "tasks": [ + { + "id": "TASK-001", + "title": "Define OAuth2 types", + "description": "Create TypeScript interfaces", + "type": "new file", + "file_path": "src/types/oauth2.ts", + "priority": 1, + "dependencies": [] + }, + { + "id": "TASK-002", + "title": "Implement GitHub provider", + "description": "Implement GitHubProvider class", + "type": "new file", + "file_path": "src/providers/github.ts", + "priority": 2, + "dependencies": ["TASK-001"] + }, + { + "id": "TASK-003", + "title": "Create auth routes", + "description": "Set up Express routes", + "type": "new file", + "file_path": "src/routes/auth.ts", + "priority": 3, + "dependencies": ["TASK-001", "TASK-002"] + } + ], + "generatedAt": "2026-02-28T10:30:00", + "version": "1.0.0" +} +``` + +### Execution Steps + +```bash +# Execute the plan +ccw workflow:execute --session WFS-001 +``` + +--- + +## Example 2: Team Session Output + +### team-session.json +This is an output from `team-coordinate` with a team of specialists. + +```json +{ + "session_id": "TLS-frontend-team-2026-02-27", + "team_name": "creative-spark", + "mode": "full-lifecycle-fe", + "scope": "Build React dashboard with real-time visualization", + "requirements": { + "location": "~/projects/dashboard", + "features": [ + "Responsive grid layout", + "Interactive charts with D3.js", + "Real-time data via WebSocket", + "Dark mode support", + "Accessibility compliance" + ] + }, + "status": "completed", + "created_at": "2026-02-27", + "completed_at": "2026-02-28", + "tasks_total": 12, + "tasks_completed": 12, + "members": [ + { + "name": "architect", + "type": "team-worker", + "role_spec": ".claude/skills/team-lifecycle-v5/role-specs/architect.md" + }, + { + "name": "frontend-dev", + "type": "team-worker", + "role_spec": ".claude/skills/team-lifecycle-v5/role-specs/frontend-dev.md" + }, + { + "name": "backend-dev", + "type": "team-worker", + "role_spec": ".claude/skills/team-lifecycle-v5/role-specs/backend-dev.md" + }, + { + "name": "qa-engineer", + "type": "team-worker", + "role_spec": ".claude/skills/team-lifecycle-v5/role-specs/qa.md" + } + ], + "deliverables": [ + { + "type": "code", + "path": "~/projects/dashboard/src/", + "description": "Complete dashboard implementation" + }, + { + "type": "documentation", + "path": "~/projects/dashboard/README.md", + "description": "Setup and usage guide" + } + ] +} +``` + +--- + +## Example 3: Memory Capture Output + +### memory.json +This is an output from `memory:capture` command. + +```json +{ + "id": "CMEM-20260228-001", + "type": "core_memory", + "source_type": "workflow", + "source_id": "WFS-dashboard-001", + "content": "Dashboard Implementation Insights", + "key_learnings": [ + { + "topic": "WebSocket Integration", + "challenge": "Connection drops during high traffic", + "solution": "Implemented exponential backoff with reconnection", + "benefit": "99.9% uptime achieved" + }, + { + "topic": "D3.js Performance", + "challenge": "5000+ data points caused lag", + "solution": "Switched to SVG rendering with virtual scrolling", + "benefit": "60% performance improvement" + } + ], + "code_pattern": "useWebSocket hook for real-time data" +} +``` + +--- + +## Example 4: CLI Analysis Output + +### analysis-result.json +This is an output from `ccw cli` with `--tool gemini`. + +```json +{ + "summary": "Code quality analysis for authentication module", + "tool": "gemini", + "timestamp": "2026-02-27T14:30:00", + "findings": [ + { + "severity": "high", + "category": "security", + "title": "Missing CSRF token validation", + "file": "src/routes/auth.ts", + "line": 45, + "description": "OAuth2 callback missing CSRF token validation", + "recommendation": "Add CSRF token validation in validateCSRFToken method" + }, + { + "severity": "medium", + "category": "performance", + "title": "Inefficient user profile query", + "file": "src/models/user.ts", + "line": 78, + "description": "Query fetches all fields including unused ones", + "recommendation": "Select only necessary fields" + }, + { + "severity": "low", + "category": "style", + "title": "Inconsistent error handling", + "file": "src/providers/github.ts", + "line": 89, + "description": "Error messages vary in format", + "recommendation": "Standardize error codes" + } + ], + "recommendations": [ + "Immediate: Add CSRF token validation", + "Short-term: Optimize database queries", + "Optional: Standardize error handling" + ] +} +``` + +--- + +## Example 5: Issue Solution Output + +### issue-solution.json +This is an output from `issue:execute` command. + +```json +{ + "issue_id": "ISSUE-001", + "title": "Memory leak in WebSocket connection handler", + "status": "resolved", + "priority": "high", + "created_at": "2026-02-26", + "resolved_at": "2026-02-26", + "resolution": "Fixed by adding proper cleanup in onClose handler", + "affected_files": ["src/services/websocket.ts"], + "root_cause": "Event listeners not removed when connections close", + "fix_steps": [ + { + "step": 1, + "description": "Add cleanup logic to onClose handler", + "changes": [ + "Add connection.removeListener call", + "Add connection.on close handler", + "Add cleanup interval in constructor" + ] + }, + { + "step": 2, + "description": "Add unit test for cleanup logic", + "changes": ["Add test case for event listener removal"] + }, + { + "step": 3, + "description": "Update documentation", + "changes": ["Add note about proper connection cleanup"] + } + ], + "verifications": [ + { + "type": "unit_test", + "status": "passed", + "details": "All listeners properly removed on close" + }, + { + "type": "integration_test", + "status": "passed", + "details": "No memory leaks after 1000 connections" + } + ] +} +``` + +--- + +## Example 6: Code Review Output + +### review-report.md +This is an output from `review-code` skill. + +```markdown +## Code Review Report + +### Summary +- **Review Type**: 6-Dimensional code review +- **Scope**: All files changed in PR #42 +- **Timestamp**: 2026-02-28 + +### 1. Correctness +| Aspect | Score | Issues | +|--------|-------|--------| +| Logic correctness | 9/10 | No issues | +| Edge case handling | 8/10 | 1 issue | + +### 2. Security +| Aspect | Score | Issues | +|--------|-------|--------| +| Input validation | 10/10 | No issues | +| XSS prevention | 10/10 | No issues | +| CSRF protection | 10/10 | No issues | + +### 3. Performance +| Aspect | Score | Issues | +|--------|-------|--------| +| Bundle size | 7/10 | 1 issue | +| Database queries | 6/10 | 2 issues | + +### Overall Score: 8.4/10 + +### Recommendations +1. **Performance**: Review bundle size +2. **Performance**: Optimize database queries +3. **Maintainability**: Add JSDoc comments +``` + +--- + +## Example 7: Spec Document Output + +### spec-section.md +This is an output from `spec-generator` skill. + +```markdown +## API: User Authentication + +### Endpoint: POST /api/auth/login +- **Description**: Authenticate user with email and password +- **Request**: { "email": "string", "password": "string" } +- **Response**: { "success": true, "token": "jwt_token", "user": {...} } + +### Endpoint: POST /api/auth/oauth2/callback +- **Description**: Handle OAuth2 provider callback +- **Request**: { "code": "string", "provider": "string", "state": "string" } +- **Response**: { "success": true, "token": "jwt_token", "user": {...} } + +### Endpoint: POST /api/auth/logout +- **Description**: Logout user and invalidate token +- **Headers**: Authorization: Bearer token +- **Response**: { "success": true, "message": "Logged out" } + +### Error Codes +| Code | Description | +|------|-------------| +| 400 | Bad Request | +| 401 | Unauthorized | +| 403 | Forbidden | +| 429 | Rate Limited | +| 500 | Server Error | +``` + +--- + +## Example 8: Skill Definition Output + +### skill-definition.yaml +This is a skill file for creating new custom skills. + +```yaml +name: api-documentation-generator +description: Generate API documentation from code annotations +version: 1.0.0 +triggers: + - generate api docs + - create documentation + - document api + +phases: + - name: Analyze Code + description: Scan codebase for API endpoints + tools: + - glob + - read_file + - grep + + - name: Generate Documentation + description: Create markdown files + tools: + - write_file + + - name: Review Output + description: Validate documentation + tools: + - read_file + - edit_file + +output: + format: markdown + template: docs/api-template.md + +examples: + - input: "Generate docs for /api/auth endpoints" + output: "Created auth-api.md with 5 endpoints" +``` + +--- + +## Using These Examples + +To use these examples in your own projects: + +1. **Copy the structure** that matches your needs +2. **Modify fields** to fit your requirements +3. **Remove sensitive information** +4. **Test the output** with `ccw workflow:execute` + +::: tip +These examples are generated by CCW workflow tools. Run relevant commands to generate similar outputs for your projects. +::: diff --git a/docs/zh/index.md b/docs/zh/index.md index e07ca576..ac79e042 100644 --- a/docs/zh/index.md +++ b/docs/zh/index.md @@ -4,8 +4,4 @@ title: CCW 文档 titleTemplate: Claude Code Workspace --- - -