From 6d1e0ae4afbb95305e10d414ae90fcf3d74b9c4e Mon Sep 17 00:00:00 2001 From: Luong NGUYEN Date: Thu, 2 Apr 2026 02:20:45 +0200 Subject: [PATCH] refactor(ci): shift quality checks to pre-commit, CI as 2nd pass (#34) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * refactor(ci): shift quality checks to pre-commit, CI as 2nd pass - Remove ci.yml (lint, security, pytest were only for EPUB scripts) - Move EPUB build to pre-commit local hook (runs on .md changes) - Add check_cross_references.py, check_mermaid.py, check_links.py scripts - Add markdown-lint, cross-references, mermaid-syntax, link-check as pre-commit hooks — mirrors all 4 CI doc-check jobs locally - Remove spell check job from docs-check.yml (breaks on translations) - Refactor docs-check.yml to reuse scripts/ instead of inline Python - Add .markdownlint.json config shared by pre-commit and CI - Update CONTRIBUTING.md with required dependencies and hook table * fix(ci): resolve all CI check failures in docs-check workflow - fix(check_cross_references): skip code blocks and inline code spans to avoid false positives from documentation examples; fix emoji heading anchor generation (rstrip not strip); add blog-posts, openspec, prompts, .agents to IGNORE_DIRS; ignore README.backup.md - fix(check_links): strip trailing Markdown punctuation from captured URLs; add wikipedia, api.github.com to SKIP_DOMAINS; add placeholder URL patterns to SKIP_URL_PATTERNS; add .agents/.claude to IGNORE_DIRS - fix(check_mermaid): add --no-sandbox puppeteer config support via MERMAID_PUPPETEER_NO_SANDBOX env var for GitHub Actions Linux runners - fix(docs-check.yml): pass MERMAID_PUPPETEER_NO_SANDBOX=true to mermaid job - fix(content): repair broken anchors in README.md, 09-advanced-features; fix #plugins -> #claude-code-plugins in claude_concepts_guide.md; remove non-existent ./docs/performance.md placeholder links; fix dependabot alerts URL in SECURITY_REPORTING.md; update auto-mode URL in resources.md; use placeholder pattern for 07-plugins example URL - remove README.backup.md (stale file) * fix(check-scripts): fix strip_code_blocks regex and URL fragment handling - fix regex in strip_code_blocks to avoid conflicting MULTILINE+DOTALL flags that could fail to strip indented code fences; use DOTALL only - strip URL fragments (#section) before dispatching link checks to avoid false-positive 404s on valid URLs with anchor fragments * fix(check-scripts): fix anchor stripping, cross-ref enforcement, and mermaid temp file cleanup - heading_to_anchor: use .strip("-") instead of .rstrip("-") to also strip leading hyphens produced by emoji-prefixed headings, preventing false-positive anchor errors - check_cross_references: always exit with main()'s return code — filesystem checks should block pre-commit unconditionally, not silently pass on errors - check_mermaid: wrap file-processing loop in try/finally so the puppeteer config temp file is cleaned up even if an unexpected exception (e.g. UnicodeDecodeError) occurs - docs-check.yml: remove now-unused CROSS_REF_STRICT env var * fix(scripts): fix anchor stripping and mermaid output path - Replace .strip('-') with .rstrip('-') in heading_to_anchor() so leading hyphens from emoji-prefixed headings are preserved, matching GitHub's anchor generation behaviour. - Use Path.with_suffix('.svg') in check_mermaid.py instead of str.replace('.mmd', '.svg') to avoid replacing all occurrences of .mmd in the full temp path. --- .github/SECURITY_REPORTING.md | 2 +- .github/workflows/ci.yml | 130 --- .github/workflows/docs-check.yml | 301 +----- .markdownlint.json | 13 + .pre-commit-config.yaml | 45 +- .../code-review/templates/finding-template.md | 1 - 07-plugins/README.md | 2 +- 09-advanced-features/README.md | 2 +- CONTRIBUTING.md | 44 +- README.backup.md | 945 ------------------ README.md | 12 +- claude_concepts_guide.md | 3 +- docs/ROADMAP-20260401.md | 153 +++ docs/TASKS-20260401.md | 291 ++++++ resources.md | 2 +- resources/INDEX.txt | 1 - scripts/check_cross_references.py | 96 ++ scripts/check_links.py | 125 +++ scripts/check_mermaid.py | 86 ++ 19 files changed, 887 insertions(+), 1367 deletions(-) delete mode 100644 .github/workflows/ci.yml create mode 100644 .markdownlint.json delete mode 100644 README.backup.md create mode 100644 docs/ROADMAP-20260401.md create mode 100644 docs/TASKS-20260401.md create mode 100644 scripts/check_cross_references.py create mode 100644 scripts/check_links.py create mode 100644 scripts/check_mermaid.py diff --git a/.github/SECURITY_REPORTING.md b/.github/SECURITY_REPORTING.md index 2be9463..69721a8 100644 --- a/.github/SECURITY_REPORTING.md +++ b/.github/SECURITY_REPORTING.md @@ -30,7 +30,7 @@ This is the preferred method for reporting security vulnerabilities. If you discover a vulnerability in a dependency: -1. Go to: https://github.com/luongnv89/claude-howto/security/dependabot/alerts +1. Go to: https://github.com/luongnv89/claude-howto/security/advisories 2. Review the alert 3. Create a pull request with the fix 4. Tag with `security` label diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml deleted file mode 100644 index cd712a9..0000000 --- a/.github/workflows/ci.yml +++ /dev/null @@ -1,130 +0,0 @@ -name: CI - -on: - push: - branches: [main] - pull_request: - branches: [main] - -# Cancel in-progress runs for the same branch -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true - -jobs: - lint: - name: Lint & Format - runs-on: ubuntu-latest - steps: - - name: Checkout code - uses: actions/checkout@v4 - - - name: Install uv - uses: astral-sh/setup-uv@v4 - - - name: Set up Python - run: uv python install 3.11 - - - name: Create venv and install Ruff - run: | - uv venv - uv pip install ruff - - - name: Ruff Format Check - run: uv run ruff format --check scripts/ - - - name: Ruff Lint Check - run: uv run ruff check scripts/ - - security: - name: Security Scan - runs-on: ubuntu-latest - steps: - - name: Checkout code - uses: actions/checkout@v4 - - - name: Install uv - uses: astral-sh/setup-uv@v4 - - - name: Set up Python - run: uv python install 3.11 - - - name: Create venv and install Bandit - run: | - uv venv - uv pip install "bandit[toml]" - - - name: Run Bandit Security Scan - run: uv run bandit -c scripts/pyproject.toml -r scripts/ --exclude scripts/tests/ - - test: - name: Unit Tests (Python ${{ matrix.python-version }}) - runs-on: ubuntu-latest - strategy: - fail-fast: false - matrix: - python-version: ['3.10', '3.11', '3.12'] - steps: - - name: Checkout code - uses: actions/checkout@v4 - - - name: Install uv - uses: astral-sh/setup-uv@v4 - - - name: Set up Python ${{ matrix.python-version }} - run: uv python install ${{ matrix.python-version }} - - - name: Create venv and install dependencies - run: | - uv venv - uv pip install -r scripts/requirements-dev.txt - - - name: Run pytest with coverage - run: uv run pytest scripts/tests/ -v --tb=short --cov=scripts --cov-report=xml --cov-report=term-missing - - - name: Upload coverage to Codecov - uses: codecov/codecov-action@v3 - with: - files: ./coverage.xml - flags: unittests - name: codecov-python-${{ matrix.python-version }} - fail_ci_if_error: false - - build: - name: Build EPUB - runs-on: ubuntu-latest - needs: [lint, security, test] - steps: - - name: Checkout code - uses: actions/checkout@v4 - - - name: Install uv - uses: astral-sh/setup-uv@v4 - - - name: Set up Python - run: uv python install 3.11 - - - name: Create venv and install dependencies - run: | - uv venv - uv pip install -r scripts/requirements-dev.txt - - - name: Build EPUB - run: uv run scripts/build_epub.py - - - name: Verify EPUB Created - run: | - if [ -f claude-howto-guide.epub ]; then - echo "EPUB built successfully" - ls -lh claude-howto-guide.epub - else - echo "EPUB file not found!" - exit 1 - fi - - - name: Upload EPUB Artifact - uses: actions/upload-artifact@v4 - with: - name: claude-howto-guide-epub - path: claude-howto-guide.epub - retention-days: 7 diff --git a/.github/workflows/docs-check.yml b/.github/workflows/docs-check.yml index 9216066..29738eb 100644 --- a/.github/workflows/docs-check.yml +++ b/.github/workflows/docs-check.yml @@ -6,16 +6,18 @@ on: paths: - '**.md' - '.github/workflows/docs-check.yml' - - '.cspell.json' - '.github/markdown-link-check-config.json' + - '.markdownlint.json' + - 'scripts/check_*.py' pull_request: branches: [main] paths: - '**.md' - 'CONTRIBUTING.md' - 'LICENSE' - - '.cspell.json' - '.github/markdown-link-check-config.json' + - '.markdownlint.json' + - 'scripts/check_*.py' # Cancel in-progress runs for the same branch concurrency: @@ -39,8 +41,7 @@ jobs: run: npm install -g markdownlint-cli - name: Run Markdown Linter - run: markdownlint '**/*.md' --ignore node_modules --ignore .venv - continue-on-error: true + run: markdownlint '**/*.md' --ignore node_modules --ignore .venv --config .markdownlint.json link-check: name: Check Links @@ -49,33 +50,43 @@ jobs: - name: Checkout code uses: actions/checkout@v4 - - name: Check markdown links - uses: gaurav-nelson/github-action-markdown-link-check@v1 + - name: Setup Python + uses: actions/setup-python@v4 with: - use-quiet-mode: 'yes' - use-verbose-mode: 'no' - config-file: '.github/markdown-link-check-config.json' + python-version: '3.11' - spelling: - name: Spell Check + - name: Run link check + run: python scripts/check_links.py + env: + LINK_CHECK_STRICT: "1" + + mermaid: + name: Mermaid Syntax runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - - name: Run cSpell - uses: streetsidesoftware/cspell-action@v6 + - name: Setup Node.js + uses: actions/setup-node@v4 with: - files: | - **/*.md - **/*.json - **/*.yml - **/*.yaml - incremental: 'no' - config: '.cspell.json' + node-version: '18' - frontmatter: - name: YAML Frontmatter Validation + - name: Install mermaid CLI + run: npm install -g @mermaid-js/mermaid-cli + + - name: Setup Python + uses: actions/setup-python@v4 + with: + python-version: '3.11' + + - name: Validate Mermaid diagrams + run: python scripts/check_mermaid.py + env: + MERMAID_PUPPETEER_NO_SANDBOX: "true" + + cross-references: + name: Cross-reference Check runs-on: ubuntu-latest steps: - name: Checkout code @@ -86,245 +97,12 @@ jobs: with: python-version: '3.11' - - name: Install PyYAML - run: pip install pyyaml - - - name: Validate YAML Frontmatter - run: | - python3 << 'EOF' - import os - import yaml - import re - from pathlib import Path - - errors = [] - - # Check all markdown files in Claude sections - md_files = list(Path('.').glob('**/README.md')) + list(Path('.').glob('01-*/**/*.md')) - - for file_path in md_files: - if '.venv' in str(file_path) or 'node_modules' in str(file_path): - continue - - with open(file_path, 'r') as f: - content = f.read() - - # Check for YAML frontmatter in skill/agent templates - if 'SKILL.md' in str(file_path) or any(x in str(file_path) for x in ['agent', 'template']): - if content.startswith('---'): - try: - # Extract frontmatter - parts = content.split('---', 2) - if len(parts) >= 3: - yaml.safe_load(parts[1]) - except yaml.YAMLError as e: - errors.append(f"{file_path}: Invalid YAML frontmatter - {e}") - else: - if 'skill' in str(file_path).lower(): - print(f"⚠ {file_path}: Consider adding YAML frontmatter") - - if errors: - for error in errors: - print(f"❌ {error}") - exit(1) - else: - print("✅ All YAML frontmatter is valid") - EOF - - structure: - name: Documentation Structure - runs-on: ubuntu-latest - steps: - - name: Checkout code - uses: actions/checkout@v4 - - - name: Setup Python - uses: actions/setup-python@v4 - with: - python-version: '3.11' - - - name: Validate Documentation Structure - run: | - python3 << 'EOF' - import os - from pathlib import Path - import re - - errors = [] - warnings = [] - - # Check that all numbered directories have README.md - for i in range(1, 11): - dir_path = Path(f"{i:02d}-*") - matches = list(dir_path.parent.glob(str(dir_path))) - if matches: - for match in matches: - if (match / "README.md").exists(): - print(f"✅ {match}/README.md found") - else: - errors.append(f"{match}: Missing README.md") - - # Check README.md has required sections - readme_path = Path("README.md") - if readme_path.exists(): - with open(readme_path) as f: - content = f.read() - - required_sections = [ - "## Table of Contents", - "## Contributing", - "## License", - ] - - for section in required_sections: - if section not in content: - errors.append(f"README.md: Missing '{section}' section") - else: - print(f"✅ README.md has '{section}' section") - - # Check for broken relative links - md_files = list(Path(".").rglob("*.md")) - for file_path in md_files: - if ".venv" in str(file_path) or "node_modules" in str(file_path): - continue - - with open(file_path) as f: - content = f.read() - - # Find markdown links to local files - local_links = re.findall(r'\[([^\]]+)\]\(([^)]+\.md)\)', content) - for link_text, link_path in local_links: - # Skip anchor-only links - if link_path.startswith("#"): - continue - - resolved_path = (file_path.parent / link_path).resolve() - if not resolved_path.exists(): - warnings.append(f"{file_path}: Broken link to '{link_path}'") - - if errors: - print("\n❌ Validation Errors:") - for error in errors: - print(f" - {error}") - exit(1) - - if warnings: - print("\n⚠ Warnings:") - for warning in warnings: - print(f" - {warning}") - - print("\n✅ Documentation structure is valid") - EOF - - metadata: - name: File Metadata Checks - runs-on: ubuntu-latest - steps: - - name: Checkout code - uses: actions/checkout@v4 - - - name: Check for common issues - run: | - set +e # Don't exit on first error - - echo "📋 Checking for documentation issues..." - - # Check for files over 100KB - echo "Checking file sizes..." - large_files=$(find . -name "*.md" -size +100k | grep -v ".venv" | grep -v "node_modules") - if [ ! -z "$large_files" ]; then - echo "⚠ Large markdown files found (>100KB):" - echo "$large_files" - fi - - # Check for TODO markers (might indicate incomplete content) - echo "Checking for TODO markers in main docs..." - todos=$(grep -r "TODO\|FIXME" --include="*.md" . --exclude-dir=.venv --exclude-dir=node_modules --exclude-dir=.git | grep -v ".github" | head -10) - if [ ! -z "$todos" ]; then - echo "⚠ Found TODO/FIXME markers:" - echo "$todos" - fi - - # Check for consistent heading structure - echo "Checking heading consistency in key files..." - for file in README.md CONTRIBUTING.md; do - if [ -f "$file" ]; then - heading_count=$(grep -c "^##" "$file") - echo "✅ $file has $heading_count main sections" - fi - done - - # Check that LICENSE file exists - if [ -f "LICENSE" ]; then - echo "✅ LICENSE file exists" - else - echo "❌ LICENSE file not found" - exit 1 - fi - - consistency: - name: Content Consistency - runs-on: ubuntu-latest - steps: - - name: Checkout code - uses: actions/checkout@v4 - - - name: Setup Python - uses: actions/setup-python@v4 - with: - python-version: '3.11' - - - name: Check Content Consistency - run: | - python3 << 'EOF' - import re - from pathlib import Path - - errors = [] - - # Check that all numbered sections are referenced in README - readme_path = Path("README.md") - with open(readme_path) as f: - readme_content = f.read() - - # Look for numbered directories - for i in range(1, 11): - dir_pattern = f"{i:02d}-" - dirs = list(Path(".").glob(f"{dir_pattern}*")) - - if dirs: - for dir_path in dirs: - if dir_path.is_dir(): - # Check if referenced in README - dir_name = dir_path.name - if dir_name not in readme_content: - errors.append(f"README.md: Directory '{dir_name}' not mentioned") - else: - print(f"✅ '{dir_name}' is referenced in README") - - # Check for consistent code fence formatting - md_files = [f for f in Path(".").rglob("*.md") if ".venv" not in str(f)] - for file_path in md_files: - with open(file_path) as f: - content = f.read() - - # Count code fence types - backtick_fences = len(re.findall(r'```', content)) - if backtick_fences % 2 != 0: - errors.append(f"{file_path}: Unmatched code fences (backticks)") - - if errors: - print("\n❌ Consistency Errors:") - for error in errors: - print(f" - {error}") - exit(1) - - print("\n✅ Content is consistent") - EOF + - name: Validate cross-references + run: python scripts/check_cross_references.py summary: name: Summary - needs: [markdown-lint, link-check, spelling, frontmatter, structure, metadata, consistency] + needs: [markdown-lint, link-check, mermaid, cross-references] runs-on: ubuntu-latest if: always() steps: @@ -332,11 +110,8 @@ jobs: run: | if [ "${{ needs.markdown-lint.result }}" = "failure" ] || \ [ "${{ needs.link-check.result }}" = "failure" ] || \ - [ "${{ needs.spelling.result }}" = "failure" ] || \ - [ "${{ needs.frontmatter.result }}" = "failure" ] || \ - [ "${{ needs.structure.result }}" = "failure" ] || \ - [ "${{ needs.metadata.result }}" = "failure" ] || \ - [ "${{ needs.consistency.result }}" = "failure" ]; then + [ "${{ needs.mermaid.result }}" = "failure" ] || \ + [ "${{ needs.cross-references.result }}" = "failure" ]; then echo "❌ Some documentation checks failed" exit 1 else diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000..760ce39 --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,13 @@ +{ + "default": false, + "MD009": true, + "MD010": true, + "MD011": true, + "MD014": true, + "MD018": true, + "MD019": true, + "MD037": true, + "MD038": true, + "MD039": true, + "MD047": true +} diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 7331f61..e10aa7e 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -10,13 +10,11 @@ repos: - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.8.2 hooks: - # Ruff linter - id: ruff name: ruff-lint args: [--fix, --exit-non-zero-on-fix] types_or: [python, pyi] files: ^scripts/ - # Ruff formatter (replaces black) - id: ruff-format name: ruff-format types_or: [python, pyi] @@ -28,7 +26,7 @@ repos: hooks: - id: bandit name: bandit-security - args: [-c, pyproject.toml] + args: [-c, scripts/pyproject.toml] additional_dependencies: ["bandit[toml]"] types: [python] files: ^scripts/ @@ -52,3 +50,44 @@ repos: args: [--maxkb=1000] - id: check-merge-conflict name: check-merge-conflict + + # Local doc quality hooks (mirrors CI checks — CI is a 2nd pass of these) + - repo: local + hooks: + - id: markdown-lint + name: markdown-lint + language: node + entry: markdownlint + args: ['--ignore', 'node_modules', '--ignore', '.venv', '--config', '.markdownlint.json'] + types: [markdown] + additional_dependencies: ['markdownlint-cli'] + + - id: cross-references + name: cross-references + language: system + entry: python scripts/check_cross_references.py + pass_filenames: false + types: [markdown] + + - id: mermaid + name: mermaid-syntax + language: system + entry: python scripts/check_mermaid.py + pass_filenames: false + types: [markdown] + verbose: true + + - id: link-check + name: link-check + language: system + entry: python scripts/check_links.py + pass_filenames: false + types: [markdown] + verbose: true + + - id: build-epub + name: build-epub + language: system + entry: uv run scripts/build_epub.py + pass_filenames: false + files: ^(.*\.md|scripts/build_epub\.py)$ diff --git a/03-skills/code-review/templates/finding-template.md b/03-skills/code-review/templates/finding-template.md index 17d7ee0..919d9d6 100644 --- a/03-skills/code-review/templates/finding-template.md +++ b/03-skills/code-review/templates/finding-template.md @@ -80,7 +80,6 @@ usersWithPosts.forEach(({ user, posts }) => { - [N+1 Query Problem](https://en.wikipedia.org/wiki/N%2B1_problem) - [Database Join Documentation](https://docs.example.com/joins) -- [Performance Optimization Guide](./docs/performance.md) ### Reviewer Notes diff --git a/07-plugins/README.md b/07-plugins/README.md index e7d92f5..496462d 100644 --- a/07-plugins/README.md +++ b/07-plugins/README.md @@ -306,7 +306,7 @@ Use **standalone slash commands** for quick personal workflows. Use **plugins** "author": { "name": "Anthropic" }, - "repository": "https://github.com/anthropic/pr-review", + "repository": "https://github.com/your-org/pr-review", "license": "MIT" } ``` diff --git a/09-advanced-features/README.md b/09-advanced-features/README.md index fb060c0..6dcabd3 100644 --- a/09-advanced-features/README.md +++ b/09-advanced-features/README.md @@ -32,7 +32,7 @@ Comprehensive guide to Claude Code's advanced capabilities including planning mo 21. [Managed Settings (Enterprise)](#managed-settings-enterprise) 22. [Configuration and Settings](#configuration-and-settings) 23. [Best Practices](#best-practices) -24. [Related Concepts](#related-concepts) +24. [Additional Resources](#additional-resources) --- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3582013..9c8a7a1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -67,19 +67,45 @@ git checkout -b docs/improvement-area ``` ### 3. Set Up Your Environment + +Pre-commit hooks run the same checks as CI locally before every commit. All four checks must pass before a PR will be accepted. + +**Required dependencies:** + ```bash -# Create virtual environment -python3 -m venv .venv +# Python tooling (uv is the package manager for this project) +pip install uv +uv venv source .venv/bin/activate +uv pip install -r scripts/requirements-dev.txt -# Install pre-commit hooks (optional but recommended) -pip install pre-commit +# Markdown linter (Node.js) +npm install -g markdownlint-cli + +# Mermaid diagram validator (Node.js) +npm install -g @mermaid-js/mermaid-cli + +# Install pre-commit and activate hooks +uv pip install pre-commit pre-commit install +``` -# Run pre-commit checks manually +**Verify your setup:** + +```bash pre-commit run --all-files ``` +The hooks that run on every commit are: + +| Hook | What it checks | +|------|---------------| +| `markdown-lint` | Markdown formatting and structure | +| `cross-references` | Relative links, anchors, code fences | +| `mermaid-syntax` | All ` ```mermaid ` blocks parse correctly | +| `link-check` | External URLs are reachable | +| `build-epub` | EPUB generates without errors (on `.md` changes) | + ## Directory Structure ``` @@ -219,17 +245,11 @@ docs(skills): Add comprehensive code review skill ### Local Testing ```bash -# Check file formatting +# Run all pre-commit checks (same checks as CI) pre-commit run --all-files -# Verify links work (if applicable) -# Test examples manually with Claude Code - # Review your changes git diff - -# Test the EPUB generation (if docs changed) -uv run scripts/build_epub.py ``` ## Pull Request Process diff --git a/README.backup.md b/README.backup.md deleted file mode 100644 index b8315a2..0000000 --- a/README.backup.md +++ /dev/null @@ -1,945 +0,0 @@ - - - Claude How To - - -# Claude How To - -> A visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value. - -## Why This Guide? - -This project complements [Anthropic's official documentation](https://code.claude.com/docs/en/overview) with a different approach: - -| | Official Docs | This Guide | -|--|---------------|------------| -| **Format** | Reference documentation | Visual tutorials with diagrams | -| **Depth** | Feature descriptions | How it works under the hood | -| **Examples** | Basic snippets | Production-ready templates you can use immediately | -| **Structure** | Feature-organized | Progressive learning path (beginner → advanced) | -| **Onboarding** | Self-directed | Guided roadmap with time estimates | -| **Self-Assessment** | None | Interactive quizzes to identify skill gaps and build a personalized learning path | - -**What you'll find here:** -- Mermaid diagrams explaining how each feature works -- Ready-to-use configurations you can copy into your project -- Real-world examples with context and best practices -- Clear progression from `/help` to building custom agents -- Troubleshooting guides based on common issues - ---- - -## Table of Contents - -- [Why This Guide?](#why-this-guide) -- [Feature Catalog](#-feature-catalog) -- [Quick Navigation](#quick-navigation) -- [Learning Path](#-learning-path) -- [Quick Reference](#-quick-reference-choose-your-features) -- [Getting Started](#-getting-started) -- **Features** - - [01. Slash Commands](#01-slash-commands) - - [02. Memory](#02-memory) - - [03. Skills](#03-skills) - - [04. Subagents](#04-subagents) - - [05. MCP Protocol](#05-mcp-protocol) - - [06. Hooks](#06-hooks) - - [07. Plugins](#07-plugins) - - [08. Checkpoints](#08-checkpoints-and-rewind) - - [09. Advanced Features](#09-advanced-features) - - [10. CLI Reference](#10-cli-reference) -- [Directory Structure](#directory-structure) -- [Installation Quick Reference](#installation-quick-reference) -- [Example Workflows](#example-workflows) -- [Best Practices](#best-practices) -- [Troubleshooting](#troubleshooting) -- [Testing](#testing) -- [Additional Resources](#additional-resources) -- [Contributing](#contributing) -- [EPUB Generation](#epub-generation) -- [Contributors](#contributors) -- [Star History](#star-history) - ---- - -## Feature Catalog - -**Looking for a quick reference?** Check out our comprehensive **[Feature Catalog](CATALOG.md)** for: - -- All slash commands (built-in and custom) with descriptions -- Sub-agents and their capabilities -- Skills with auto-invocation triggers -- Plugins with components and installation commands -- MCP servers for external integrations -- Hooks for event-driven automation -- One-command installation for each feature - -**[View Full Catalog](CATALOG.md)** - ---- - -## Quick Navigation - -| Feature | Description | Folder | -|---------|-------------|--------| -| **Feature Catalog** | Complete reference with installation commands | [CATALOG.md](CATALOG.md) | -| **Slash Commands** | User-invoked shortcuts | [01-slash-commands/](01-slash-commands/) | -| **Memory** | Persistent context | [02-memory/](02-memory/) | -| **Skills** | Reusable capabilities | [03-skills/](03-skills/) | -| **Subagents** | Specialized AI assistants | [04-subagents/](04-subagents/) | -| **MCP Protocol** | External tool access | [05-mcp/](05-mcp/) | -| **Hooks** | Event-driven automation | [06-hooks/](06-hooks/) | -| **Plugins** | Bundled features | [07-plugins/](07-plugins/) | -| **Checkpoints** | Session snapshots & rewind | [08-checkpoints/](08-checkpoints/) | -| **Advanced Features** | Planning, thinking, background tasks | [09-advanced-features/](09-advanced-features/) | -| **CLI Reference** | Commands, flags, and options | [10-cli/](10-cli/) | -| **Blog Posts** | Real-world usage examples | [Blog Posts](https://medium.com/@luongnv89) | - ---- - -## 📚 Learning Path - -**Not sure where to start?** Take the [Self-Assessment Quiz](LEARNING-ROADMAP.md#-find-your-level) to find your recommended path, or run `/self-assessment` in Claude Code for an interactive version. - -> **Built-in skills**: This repo includes two interactive skills you can use directly in Claude Code: -> - `/self-assessment` — Evaluate your overall Claude Code proficiency and get a personalized learning path -> - `/lesson-quiz [lesson]` — Test your understanding of any specific lesson (e.g., `/lesson-quiz hooks`) - -| Order | Feature | Level | Time | Recommended For | -|-------|---------|-------|------|-----------------| -| **1** | [Slash Commands](01-slash-commands/) | ⭐ Beginner | 30 min | Level 1 start | -| **2** | [Memory](02-memory/) | ⭐⭐ Beginner+ | 45 min | Level 1 | -| **3** | [Checkpoints](08-checkpoints/) | ⭐⭐ Intermediate | 45 min | Level 1 | -| **4** | [CLI Basics](10-cli/) | ⭐⭐ Beginner+ | 30 min | Level 1 | -| **5** | [Skills](03-skills/) | ⭐⭐ Intermediate | 1 hour | Level 2 start | -| **6** | [Hooks](06-hooks/) | ⭐⭐ Intermediate | 1 hour | Level 2 | -| **7** | [MCP](05-mcp/) | ⭐⭐⭐ Intermediate+ | 1 hour | Level 2 | -| **8** | [Subagents](04-subagents/) | ⭐⭐⭐ Intermediate+ | 1.5 hours | Level 2 | -| **9** | [Advanced](09-advanced-features/) | ⭐⭐⭐⭐⭐ Advanced | 2-3 hours | Level 3 start | -| **10** | [Plugins](07-plugins/) | ⭐⭐⭐⭐ Advanced | 2 hours | Level 3 | -| **11** | [CLI Mastery](10-cli/) | ⭐⭐⭐ Advanced | 1 hour | Level 3 | - -**Total**: ~11-13 hours | 📖 **[Complete Learning Roadmap →](LEARNING-ROADMAP.md)** - ---- - -## 🎯 Quick Reference: Choose Your Features - -### Feature Comparison - -| Feature | Invocation | Persistence | Best For | -|---------|-----------|------------|----------| -| **Slash Commands** | Manual (`/cmd`) | Session only | Quick shortcuts | -| **Memory** | Auto-loaded | Cross-session | Long-term learning | -| **Skills** | Auto-invoked | Filesystem | Automated workflows | -| **Subagents** | Auto-delegated | Isolated context | Task distribution | -| **MCP Protocol** | Auto-queried | Real-time | Live data access | -| **Hooks** | Event-triggered | Configured | Automation & validation | -| **Plugins** | One command | All features | Complete solutions | -| **Checkpoints** | Manual/Auto | Session-based | Safe experimentation | -| **Planning Mode** | Manual/Auto | Plan phase | Complex implementations | -| **Background Tasks** | Manual | Task duration | Long-running operations | -| **CLI Reference** | Terminal commands | Session/Script | Automation & scripting | - -### Use Case Matrix - -| Use Case | Recommended Features | -|----------|---------------------| -| **Team Onboarding** | Memory + Slash Commands + Plugins | -| **Code Quality** | Subagents + Skills + Memory + Hooks | -| **Documentation** | Skills + Subagents + Plugins | -| **DevOps** | Plugins + MCP + Hooks + Background Tasks | -| **Security Review** | Subagents + Skills + Hooks (read-only mode) | -| **API Integration** | MCP + Memory | -| **Quick Tasks** | Slash Commands | -| **Complex Projects** | All Features + Planning Mode | -| **Refactoring** | Checkpoints + Planning Mode + Hooks | -| **Learning/Experimentation** | Checkpoints + Extended Thinking + Permission Mode | -| **CI/CD Automation** | CLI Reference + Hooks + Background Tasks | -| **Performance Optimization** | Planning Mode + Checkpoints + Background Tasks | -| **Script Automation** | CLI Reference + Hooks + MCP | -| **Batch Processing** | CLI Reference + Background Tasks | - ---- - -## ⚡ Getting Started - -### 15 Minutes - First Steps -```bash -# Copy your first slash command -cp 01-slash-commands/optimize.md .claude/commands/ - -# Try it! -# In Claude Code: /optimize -``` - -### 1 Hour - Essential Setup -```bash -# 1. Slash commands (15 min) -cp 01-slash-commands/*.md .claude/commands/ - -# 2. Project memory (15 min) -cp 02-memory/project-CLAUDE.md ./CLAUDE.md - -# 3. Install a skill (15 min) -cp -r 03-skills/code-review ~/.claude/skills/ - -# 4. Try them together (15 min) -# See how they work in harmony! -``` - -### Weekend - Full Setup -- **Day 1**: Slash Commands, Memory, Skills, Hooks -- **Day 2**: Subagents, MCP integration, Plugins -- **Result**: Complete Claude Code power user setup - -📖 **[Detailed milestones and exercises →](LEARNING-ROADMAP.md)** - ---- - -## 01. Slash Commands - -**Location**: [01-slash-commands/](01-slash-commands/) - -**What**: User-invoked shortcuts stored as Markdown files - -**Examples**: -- `optimize.md` - Code optimization analysis -- `pr.md` - Pull request preparation -- `generate-api-docs.md` - API documentation generator - -**Installation**: -```bash -cp 01-slash-commands/*.md /path/to/project/.claude/commands/ -``` - -**Usage**: -``` -/optimize -/pr -/generate-api-docs -``` - -**Learn More**: [Discovering Claude Code Slash Commands](https://medium.com/@luongnv89/discovering-claude-code-slash-commands-cdc17f0dfb29) - ---- - -## 02. Memory - -**Location**: [02-memory/](02-memory/) - -**What**: Persistent context across sessions - -**Examples**: -- `project-CLAUDE.md` - Team-wide project standards -- `directory-api-CLAUDE.md` - Directory-specific rules -- `personal-CLAUDE.md` - Personal preferences - -**Installation**: -```bash -# Project memory -cp 02-memory/project-CLAUDE.md /path/to/project/CLAUDE.md - -# Directory memory -cp 02-memory/directory-api-CLAUDE.md /path/to/project/src/api/CLAUDE.md - -# Personal memory -cp 02-memory/personal-CLAUDE.md ~/.claude/CLAUDE.md -``` - -**Usage**: Automatically loaded by Claude - ---- - -## 03. Skills - -**Location**: [03-skills/](03-skills/) - -**What**: Reusable, auto-invoked capabilities with instructions and scripts - -**Examples**: -- `code-review/` - Comprehensive code review with scripts -- `brand-voice/` - Brand voice consistency checker -- `doc-generator/` - API documentation generator - -**Installation**: -```bash -# Personal skills -cp -r 03-skills/code-review ~/.claude/skills/ - -# Project skills -cp -r 03-skills/code-review /path/to/project/.claude/skills/ -``` - -**Usage**: Automatically invoked when relevant - ---- - -## 04. Subagents - -**Location**: [04-subagents/](04-subagents/) - -**What**: Specialized AI assistants with isolated contexts and custom prompts - -**Examples**: -- `code-reviewer.md` - Comprehensive code quality analysis -- `test-engineer.md` - Test strategy and coverage -- `documentation-writer.md` - Technical documentation -- `secure-reviewer.md` - Security-focused review (read-only) -- `implementation-agent.md` - Full feature implementation - -**Installation**: -```bash -cp 04-subagents/*.md /path/to/project/.claude/agents/ -``` - -**Usage**: Automatically delegated by main agent - ---- - -## 05. MCP Protocol - -**Location**: [05-mcp/](05-mcp/) - -**What**: Model Context Protocol for accessing external tools and APIs - -**Examples**: -- `github-mcp.json` - GitHub integration -- `database-mcp.json` - Database queries -- `filesystem-mcp.json` - File operations -- `multi-mcp.json` - Multiple MCP servers - -**Installation**: -```bash -# Set environment variables -export GITHUB_TOKEN="your_token" -export DATABASE_URL="postgresql://..." - -# Add MCP server via CLI -claude mcp add github -- npx -y @modelcontextprotocol/server-github - -# Or add to project .mcp.json manually (see 05-mcp/ for examples) -``` - -**Usage**: MCP tools are automatically available to Claude once configured - ---- - -## 06. Hooks - -**Location**: [06-hooks/](06-hooks/) - -**What**: Event-driven shell commands that execute automatically in response to Claude Code events - -**Examples**: -- `format-code.sh` - Auto-format code before writing -- `pre-commit.sh` - Run tests before commits -- `security-scan.sh` - Scan for security issues -- `log-bash.sh` - Log all bash commands -- `validate-prompt.sh` - Validate user prompts -- `notify-team.sh` - Send notifications on events - -**Installation**: -```bash -mkdir -p ~/.claude/hooks -cp 06-hooks/*.sh ~/.claude/hooks/ -chmod +x ~/.claude/hooks/*.sh -``` - -Configure hooks in `~/.claude/settings.json`: -```json -{ - "hooks": { - "PreToolUse": [{ - "matcher": "Write", - "hooks": ["~/.claude/hooks/format-code.sh"] - }], - "PostToolUse": [{ - "matcher": "Write", - "hooks": ["~/.claude/hooks/security-scan.sh"] - }] - } -} -``` - -**Usage**: Hooks execute automatically on events - -**Hook Types**: -- **Tool Hooks**: `PreToolUse:*`, `PostToolUse:*` -- **Session Hooks**: `Stop`, `SubagentStop`, `SubagentStart` -- **Lifecycle Hooks**: `Notification`, `ConfigChange`, `WorktreeCreate`, `WorktreeRemove` - ---- - -## 07. Plugins - -**Location**: [07-plugins/](07-plugins/) - -**What**: Bundled collections of commands, agents, MCP, and hooks - -**Examples**: -- `pr-review/` - Complete PR review workflow -- `devops-automation/` - Deployment and monitoring -- `documentation/` - Documentation generation - -**Installation**: -```bash -/plugin install pr-review -/plugin install devops-automation -/plugin install documentation -``` - -**Usage**: Use bundled slash commands and features - ---- - -## 08. Checkpoints and Rewind - -**Location**: [08-checkpoints/](08-checkpoints/) - -**What**: Save conversation state and rewind to previous points to explore different approaches - -**Key Concepts**: -- **Checkpoint**: Snapshot of conversation state -- **Rewind**: Return to previous checkpoint -- **Branch Point**: Explore multiple approaches from same checkpoint - -**Usage**: -``` -# Checkpoints are created automatically with every user prompt -# To rewind, press Esc twice or use: -/rewind - -# Then choose from five options: -# 1. Restore code and conversation -# 2. Restore conversation -# 3. Restore code -# 4. Summarize from here -# 5. Never mind -``` - -**Use Cases**: -- Try different implementation approaches -- Recover from mistakes -- Safe experimentation -- Compare alternative solutions -- A/B testing different designs - -**Example Workflow**: -``` -1. Work normally (checkpoints are created automatically) -2. Try experimental approach -3. If it works: Continue -4. If it fails: Press Esc+Esc or /rewind to go back -``` - ---- - -## 09. Advanced Features - -**Location**: [09-advanced-features/](09-advanced-features/) - -**What**: Advanced capabilities for complex workflows and automation - -### Planning Mode - -Create detailed implementation plans before coding: -``` -User: /plan Implement user authentication system - -Claude: [Creates comprehensive step-by-step plan] - -User: Approve and proceed -``` - -**Benefits**: Clear roadmap, time estimates, risk assessment - -### Extended Thinking - -Deep reasoning for complex problems. Toggle with `Alt+T` / `Option+T`, or set `MAX_THINKING_TOKENS` environment variable: -```bash -# Toggle in-session: press Alt+T (Option+T on macOS) - -# Or set via environment variable -MAX_THINKING_TOKENS=10000 claude - -# Then ask complex questions -User: Should we use microservices or monolith? -Claude: [Analyzes trade-offs systematically with extended reasoning] -``` - -**Benefits**: Better architectural decisions, thorough analysis - -### Background Tasks - -Run long operations without blocking: -``` -User: Run tests in background - -Claude: Started bg-1234, you can continue working - -[Later] Test results: 245 passed, 3 failed -``` - -**Benefits**: Parallel development, no waiting - -### Permission Modes - -Control what Claude can do: -- **`default`**: Standard permissions with confirmation prompts -- **`acceptEdits`**: Auto-accept file edits, confirm other actions -- **`plan`**: Analysis and planning only, no modifications -- **`dontAsk`**: Accept all actions without confirmation -- **`bypassPermissions`**: Skip all permission checks (dangerous) - -```bash -claude --permission-mode plan # Code review mode -claude --permission-mode acceptEdits # Learning mode -claude --permission-mode default # Standard mode -``` - -### Headless Mode - -Run Claude Code in CI/CD and automation: -```bash -claude -p "Run tests and generate report" -``` - -**Use Cases**: CI/CD, automated reviews, batch processing - -### Session Management - -Manage multiple work sessions: -```bash -/resume # Resume a previous session interactively -/rename # Rename the current session -/fork # Fork the current session -claude -c # Continue the most recent session -claude -r "session" # Resume a session matching the query -``` - -### Interactive Features - -**Keyboard Shortcuts**: Ctrl+R (search), Tab (complete), ↑/↓ (history) - -**Command History**: Access previous commands - -**Multi-line Input**: Complex prompts across multiple lines - -### Configuration - -Customize Claude Code behavior in `~/.claude/settings.json`: -```json -{ - "permissions": { - "allow": ["Read", "Glob", "Grep", "Bash(git *)"], - "deny": ["Bash(rm -rf *)"] - }, - "hooks": { - "PreToolUse": [{ - "matcher": "Write", - "hooks": ["~/.claude/hooks/format-code.sh"] - }] - }, - "env": { - "MAX_THINKING_TOKENS": "10000" - } -} -``` - -See [config-examples.json](09-advanced-features/config-examples.json) for complete configurations. - ---- - -## 10. CLI Reference - -**Location**: [10-cli/](10-cli/) - -**What**: Complete command-line interface reference for Claude Code - -**Key Areas**: -- CLI commands (`claude`, `claude -p`, `claude -c`, `claude -r`) -- Core flags (print mode, continue, resume, version) -- Model & configuration (`--model`, `--agents`) -- System prompt customization -- Tool & permission management -- Output formats (text, JSON, stream-JSON) -- MCP configuration -- Session management - -**Quick Examples**: -```bash -# Interactive mode -claude "explain this project" - -# Print mode (non-interactive) -claude -p "review this code" - -# Process file content -cat error.log | claude -p "explain this error" - -# JSON output for scripts -claude -p --output-format json "list functions" - -# Resume session -claude -r "feature-auth" "continue implementation" -``` - -**Use Cases**: -- CI/CD pipeline integration -- Script automation and piping -- Batch processing -- Multi-session workflows -- Custom agent configurations - ---- - -## Directory Structure - -``` - -├── 01-slash-commands/ -│ ├── optimize.md -│ ├── pr.md -│ ├── generate-api-docs.md -│ └── README.md -├── 02-memory/ -│ ├── project-CLAUDE.md -│ ├── directory-api-CLAUDE.md -│ ├── personal-CLAUDE.md -│ └── README.md -├── 03-skills/ -│ ├── code-review/ -│ │ ├── SKILL.md -│ │ ├── scripts/ -│ │ └── templates/ -│ ├── brand-voice/ -│ │ ├── SKILL.md -│ │ └── templates/ -│ ├── doc-generator/ -│ │ ├── SKILL.md -│ │ └── generate-docs.py -│ └── README.md -├── 04-subagents/ -│ ├── code-reviewer.md -│ ├── test-engineer.md -│ ├── documentation-writer.md -│ ├── secure-reviewer.md -│ ├── implementation-agent.md -│ └── README.md -├── 05-mcp/ -│ ├── github-mcp.json -│ ├── database-mcp.json -│ ├── filesystem-mcp.json -│ ├── multi-mcp.json -│ └── README.md -├── 06-hooks/ -│ ├── format-code.sh -│ ├── pre-commit.sh -│ ├── security-scan.sh -│ ├── log-bash.sh -│ ├── validate-prompt.sh -│ ├── notify-team.sh -│ └── README.md -├── 07-plugins/ -│ ├── pr-review/ -│ ├── devops-automation/ -│ ├── documentation/ -│ └── README.md -├── 08-checkpoints/ -│ ├── checkpoint-examples.md -│ └── README.md -├── 09-advanced-features/ -│ ├── config-examples.json -│ ├── planning-mode-examples.md -│ └── README.md -├── 10-cli/ -│ └── README.md -└── README.md (this file) -``` - ---- - -## Installation Quick Reference - -```bash -# Slash Commands -cp 01-slash-commands/*.md .claude/commands/ - -# Memory -cp 02-memory/project-CLAUDE.md ./CLAUDE.md - -# Skills -cp -r 03-skills/code-review ~/.claude/skills/ - -# Subagents -cp 04-subagents/*.md .claude/agents/ - -# MCP -export GITHUB_TOKEN="token" -claude mcp add github -- npx -y @modelcontextprotocol/server-github - -# Hooks -mkdir -p ~/.claude/hooks -cp 06-hooks/*.sh ~/.claude/hooks/ -chmod +x ~/.claude/hooks/*.sh - -# Plugins -/plugin install pr-review - -# Checkpoints (auto-enabled, configure in settings) -# See 08-checkpoints/README.md - -# Advanced Features (configure in settings) -# See 09-advanced-features/config-examples.json - -# CLI Reference (no installation needed) -# See 10-cli/README.md for usage examples -``` - ---- - -## Example Workflows - -### 1. Complete Code Review Workflow - -```markdown -# Uses: Slash Commands + Subagents + Memory + MCP - -User: /review-pr - -Claude: -1. Loads project memory (coding standards) -2. Fetches PR via GitHub MCP -3. Delegates to code-reviewer subagent -4. Delegates to test-engineer subagent -5. Synthesizes findings -6. Provides comprehensive review -``` - -### 2. Automated Documentation - -```markdown -# Uses: Skills + Subagents + Memory - -User: "Generate API documentation for the auth module" - -Claude: -1. Loads project memory (doc standards) -2. Detects doc generation request -3. Auto-invokes doc-generator skill -4. Delegates to api-documenter subagent -5. Creates comprehensive docs with examples -``` - -### 3. DevOps Deployment - -```markdown -# Uses: Plugins + MCP + Hooks - -User: /deploy production - -Claude: -1. Runs pre-deploy hook (validates environment) -2. Delegates to deployment-specialist subagent -3. Executes deployment via Kubernetes MCP -4. Monitors progress -5. Runs post-deploy hook (health checks) -6. Reports status -``` - ---- - -## Best Practices - -### Do's ✅ -- Start simple with slash commands -- Add features incrementally -- Use memory for team standards -- Test configurations locally first -- Document custom implementations -- Version control project configurations -- Share plugins with team - -### Don'ts ❌ -- Don't create redundant features -- Don't hardcode credentials -- Don't skip documentation -- Don't over-complicate simple tasks -- Don't ignore security best practices -- Don't commit sensitive data - ---- - -## Troubleshooting - -### Feature Not Loading -1. Check file location and naming -2. Verify YAML frontmatter syntax -3. Check file permissions -4. Review Claude Code version compatibility - -### MCP Connection Failed -1. Verify environment variables -2. Check MCP server installation -3. Test credentials -4. Review network connectivity - -### Subagent Not Delegating -1. Check tool permissions -2. Verify agent description clarity -3. Review task complexity -6. Test agent independently - ---- - -## Testing - -This project includes comprehensive automated testing to ensure code quality and reliability. - -### Testing Overview - -- **Unit Tests**: Python tests using pytest (Python 3.10, 3.11, 3.12) -- **Code Quality**: Linting and formatting with Ruff -- **Security**: Vulnerability scanning with Bandit -- **Type Checking**: Static type analysis with mypy -- **Build Verification**: EPUB generation testing -- **Coverage Tracking**: Codecov integration - -### Running Tests Locally - -```bash -# Install development dependencies -uv pip install -r requirements-dev.txt - -# Run all unit tests -pytest scripts/tests/ -v - -# Run tests with coverage report -pytest scripts/tests/ -v --cov=scripts --cov-report=html - -# Run code quality checks -ruff check scripts/ -ruff format --check scripts/ - -# Run security scan -bandit -c pyproject.toml -r scripts/ --exclude scripts/tests/ - -# Run type checking -mypy scripts/ --ignore-missing-imports -``` - -### Automated Testing on GitHub - -Tests run automatically on: -- Every push to `main` or `develop` branches -- Every pull request to `main` - -View test results in the GitHub Actions tab or check the [TESTING.md](.github/TESTING.md) guide for detailed information. - -### Writing Tests - -When contributing, please include tests for new functionality: - -1. **Write tests** in `scripts/tests/test_*.py` -2. **Run tests locally** to verify they pass -3. **Check coverage** with `pytest --cov=scripts` -4. **Submit with PR** - tests are required for all contributions - -For detailed testing guidelines, see [TESTING.md](.github/TESTING.md). - ---- - -## Additional Resources - -- [Claude Code Documentation](https://code.claude.com/docs/en/overview) -- [MCP Protocol Specification](https://modelcontextprotocol.io) -- [Skills Repository](https://github.com/luongnv89/skills) - Collection of ready-to-use skills -- [Anthropic Cookbook](https://github.com/anthropics/anthropic-cookbook) -- [Boris Cherny's Claude Code Workflow](https://x.com/bcherny/status/2007179832300581177) - The creator of Claude Code shares his systematized workflow: parallel agents, shared CLAUDE.md, Plan mode, slash commands, subagents, and verification hooks for autonomous long-running sessions. Key insights include turning recurring workflows into reusable commands and wiring Claude into team tools (GitHub, Slack, BigQuery, Sentry) for end-to-end work with feedback loops. - ---- - -## Contributing - -Found an issue or want to contribute an example? We'd love your help! - -**Please read [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines on:** -- Types of contributions (examples, docs, features, bugs, feedback) -- How to set up your development environment -- Directory structure and how to add content -- Writing guidelines and best practices -- Commit and PR process - -**Our Community Standards:** -- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) - How we treat each other -- [SECURITY.md](SECURITY.md) - Security policy and vulnerability reporting - -### Reporting Security Issues - -If you discover a security vulnerability, please report it responsibly: - -1. **Use GitHub Private Vulnerability Reporting**: https://github.com/luongnv89/claude-howto/security/advisories -2. **Or read** [.github/SECURITY_REPORTING.md](.github/SECURITY_REPORTING.md) for detailed instructions -3. **Do NOT** open a public issue for security vulnerabilities - -Security issues are taken seriously and will be addressed promptly. See [SECURITY.md](SECURITY.md) for our full security policy. - -Quick start: -1. Fork and clone the repository -2. Create a descriptive branch (`add/feature-name`, `fix/bug`, `docs/improvement`) -3. Make your changes following the guidelines -4. Submit a pull request with a clear description - -**Need help?** Open an issue or discussion, and we'll guide you through the process. - ---- - -## License - -This project is licensed under the MIT License - see [LICENSE](LICENSE) file for details. - -You are free to: -- Use this guide and examples in your projects -- Modify and adapt the content -- Share and distribute -- Use for commercial purposes - -The only requirement is to include a copy of the license and copyright notice. - ---- - -## EPUB Generation - -Want to read this guide offline? Generate an EPUB ebook: - -```bash -uv run scripts/build_epub.py -``` - -This creates `claude-howto-guide.epub` with all content, including rendered Mermaid diagrams. - -See [scripts/README.md](scripts/README.md) for more options. - ---- - -## Contributors - -Thanks to everyone who has contributed to this project! - -| Contributor | PRs | -|-------------|-----| -| [wjhrdy](https://github.com/wjhrdy) | [#1 - add a tool to create an epub](https://github.com/luongnv89/claude-howto/pull/1) | -| [VikalpP](https://github.com/VikalpP) | [#7 - fix(docs): Use tilde fences for nested code blocks in concepts guide](https://github.com/luongnv89/claude-howto/pull/7) | - ---- - -## Star History - -[![Star History Chart](https://api.star-history.com/svg?repos=luongnv89/claude-howto&type=Date)](https://star-history.com/#luongnv89/claude-howto&Date) - ---- - -**Last Updated**: March 2026 -**Claude Code Version**: 2.1+ -**Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.6, Claude Haiku 4.5 diff --git a/README.md b/README.md index 09e9b3c..d23b260 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ Go from typing `claude` to orchestrating agents, hooks, skills, and MCP servers — with visual tutorials, copy-paste templates, and a guided learning path. -**[Get Started in 15 Minutes](#-get-started-in-15-minutes)** | **[Find Your Level](#-not-sure-where-to-start)** | **[Browse the Feature Catalog](CATALOG.md)** +**[Get Started in 15 Minutes](#get-started-in-15-minutes)** | **[Find Your Level](#not-sure-where-to-start)** | **[Browse the Feature Catalog](CATALOG.md)** --- @@ -28,8 +28,8 @@ Go from typing `claude` to orchestrating agents, hooks, skills, and MCP servers - [The Problem](#the-problem) - [How Claude How To Fixes This](#how-claude-how-to-fixes-this) - [How It Works](#how-it-works) -- [Not Sure Where to Start?](#-not-sure-where-to-start) -- [Get Started in 15 Minutes](#-get-started-in-15-minutes) +- [Not Sure Where to Start?](#not-sure-where-to-start) +- [Get Started in 15 Minutes](#get-started-in-15-minutes) - [What Can You Build With This?](#what-can-you-build-with-this) - [FAQ](#faq) - [Contributing](#contributing) @@ -92,7 +92,7 @@ The real power is in combining features. Learn to wire slash commands + memory + Run `/lesson-quiz [topic]` after each module. The quiz pinpoints what you missed so you can fill gaps fast. -**[Get Started in 15 Minutes](#-get-started-in-15-minutes)** +**[Get Started in 15 Minutes](#get-started-in-15-minutes)** --- @@ -173,7 +173,7 @@ cp -r 03-skills/code-review ~/.claude/skills/ # Follow the learning path for guided setup ``` -**[View the Full Installation Reference](#installation-quick-reference)** +**[View the Full Installation Reference](#get-started-in-15-minutes)** --- @@ -222,7 +222,7 @@ You already have Claude Code installed. The only thing between you and 10x produ MIT licensed. Free forever. Clone it, fork it, make it yours. -**[Start the Learning Path ->](LEARNING-ROADMAP.md)** | **[Browse the Feature Catalog](CATALOG.md)** | **[Get Started in 15 Minutes](#-get-started-in-15-minutes)** +**[Start the Learning Path ->](LEARNING-ROADMAP.md)** | **[Browse the Feature Catalog](CATALOG.md)** | **[Get Started in 15 Minutes](#get-started-in-15-minutes)** --- diff --git a/claude_concepts_guide.md b/claude_concepts_guide.md index 65eb161..a13f2db 100644 --- a/claude_concepts_guide.md +++ b/claude_concepts_guide.md @@ -16,7 +16,7 @@ A comprehensive reference guide covering Slash Commands, Subagents, Memory, MCP 3. [Memory](#memory) 4. [MCP Protocol](#mcp-protocol) 5. [Agent Skills](#agent-skills) -6. [Plugins](#plugins) +6. [Plugins](#claude-code-plugins) 7. [Hooks](#hooks) 8. [Checkpoints and Rewind](#checkpoints-and-rewind) 9. [Advanced Features](#advanced-features) @@ -1754,7 +1754,6 @@ usersWithPosts.forEach(({ user, posts }) => { - [N+1 Query Problem](https://en.wikipedia.org/wiki/N%2B1_problem) - [Database Join Documentation](https://docs.example.com/joins) -- [Performance Optimization Guide](./docs/performance.md) ### Reviewer Notes diff --git a/docs/ROADMAP-20260401.md b/docs/ROADMAP-20260401.md new file mode 100644 index 0000000..e333c56 --- /dev/null +++ b/docs/ROADMAP-20260401.md @@ -0,0 +1,153 @@ +# Roadmap: claude-howto 2026–2027 + +> April 2026 – March 2027 · Dual-Layer Knowledge Base | Full plan: `TASKS-20260401.md` + +--- + +## Vision + +Transform claude-howto from a static tutorial repo into a **living, dual-audience knowledge system**: + +- **For humans** — interactive, scenario-based learning with progressive difficulty, decision trees, and named patterns that experts bookmark +- **For AI agents** — structured metadata index that agents query before performing Claude Code tasks, making this repo infrastructure, not just content + +No competitor targets AI agents as a primary audience. This is the moat. + +--- + +## The 7 Pillars + +| # | Pillar | What it delivers | +|---|--------|-----------------| +| P1 | Fun Layer | Scenario intros + "Try It Now" blocks in every module | +| P2 | AI Agent Index | Generated `agent-manifest.json` + `AGENT-INDEX.md` + lookup skill | +| P3a | Expert Reference (in-module) | Decision trees + named patterns per module | +| P3b | Expert Reference (cross-module) | `RECIPES.md` — compound multi-feature workflows | +| P4 | Newcomer Onboarding | `quickstart.sh` + `QUICKSTART.md` + difficulty badges | +| P5 | Community Showcase | `COMMUNITY-PROJECTS.md` — curated user projects | +| P6 | Content Quality | Expand weakest modules; project `CLAUDE.md` | +| P7 | Living Curriculum | `WHATS-NEW.md` + version badges + weekly staleness CI action | + +--- + +## Timeline at a Glance + +``` +Apr 2026 May–Jun 2026 Jul–Aug 2026 Sep 2026 Oct–Nov 2026 Dec 2026–Mar 2027 + | | | | | | + [M1] [M2] [M3] [M4] [M5] [M6] +Infrastructure 6/10 modules 10/10 Agent layer Version audit Self-sustaining ++ hooks/checks complete complete + recipes complete system +``` + +--- + +## Milestones + +### M1 — Infrastructure Live · End of April 2026 + +**What ships:** +- `scripts/quickstart.sh` — one-command setup for new users (idempotent) +- `QUICKSTART.md` — First 15 Minutes visual guide +- Difficulty badges + "What you'll build" previews on all 10 modules +- `WHATS-NEW.md` + version badges on all modules +- `.github/workflows/staleness-check.yml` — weekly Monday issue if module unverified 30+ days +- Root `CLAUDE.md` — project's own configuration as a best-practice example +- `scripts/build-agent-index.py` — generator that reads all 10 modules → outputs `agent-manifest.json` + `AGENT-INDEX.md` +- **06-hooks** — full deep pass: 5 complete hook scripts, decision tree, Try It Now, patterns +- **08-checkpoints** — full deep pass: 311 → 800+ lines, 3 workflow templates, decision tree, patterns + +**Why start here:** Infrastructure benefits every future phase. Hooks and checkpoints are the weakest modules and most likely to lose new visitors. + +--- + +### M2 — 6/10 Modules Complete · End of June 2026 + +**What ships (one deep pass per module):** +- **01-slash-commands** — scenario intro, decision tree, Try It Now, named patterns +- **02-memory** — scenario intro, decision tree, Try It Now, named patterns +- **03-skills** — scenario intro, decision tree, Try It Now, named patterns +- **10-cli** — scenario intro, decision tree, Try It Now, named patterns +- CI step: validate `agent-manifest.json` schema on every push + +Each module pass = run the generator to confirm valid manifest output. + +--- + +### M3 — All 10 Modules Complete · End of August 2026 + +**What ships:** +- **04-subagents** — full deep pass (incl. "The Multi-Agent Review Pattern") +- **05-mcp** — full deep pass +- **07-plugins** — full deep pass +- **09-advanced-features** — full deep pass + +Every module now has: scenario intro, 2+ Try It Now blocks, Mermaid decision tree, 2+ named patterns. + +--- + +### M4 — Agent Layer Live · End of September 2026 + +**What ships:** +- Final `agent-manifest.json` covering 100% of modules (generated from completed content) +- `AGENT-INDEX.md` linked from `README.md` +- `skills/claude-howto-lookup/SKILL.md` — lightweight agent skill that queries the manifest +- `RECIPES.md` — 5+ compound workflows (schema: name, modules-used, problem, solution, expected outcome) +- `COMMUNITY-PROJECTS.md` — static curated list with PR-based submission format + +**Why September:** The agent index is only meaningful once all 10 modules are content-complete. + +--- + +### M5 — Version Audit Complete · End of November 2026 + +**What ships:** +- Full version audit: all 10 modules verified against current CC version +- Updated `cc_version_verified` frontmatter + version badges everywhere +- `RECIPES.md` expanded to 8+ recipes based on observed community patterns +- Pinned GitHub Discussion: "Share your Claude Code workflows" — signal collection for agent usage + +--- + +### M6 — Self-Sustaining System · End of March 2027 + +**What ships / runs continuously:** +- `/docs-sync-claude-code` skill runs after every CC release → `WHATS-NEW.md` updated +- Agent manifest CI regression: 100% module coverage enforced +- `RECIPES.md` at 10+ recipes +- `COMMUNITY-PROJECTS.md` growing organically +- Agent usage signal evaluated → if validated, promote the lookup skill (marketing, asm registry) + +--- + +## Deliverables Summary + +| Deliverable | Type | Phase | +|-------------|------|-------| +| `scripts/quickstart.sh` | Script | P1 | +| `QUICKSTART.md` | Doc | P1 | +| Root `CLAUDE.md` | Config | P1 | +| `WHATS-NEW.md` | Doc | P1 | +| `.github/workflows/staleness-check.yml` | CI | P1 | +| `scripts/build-agent-index.py` | Script | P1 | +| 10 module deep passes (scenario + Try It Now + decision tree + patterns) | Content | P1–P3 | +| `agent-manifest.json` (generated) | Data | P4 | +| `AGENT-INDEX.md` (generated) | Doc | P4 | +| `skills/claude-howto-lookup/SKILL.md` | Skill | P4 | +| `RECIPES.md` (5 → 8 → 10+ recipes) | Doc | P4–P6 | +| `COMMUNITY-PROJECTS.md` | Doc | P4 | + +--- + +## What Is NOT in Scope + +Deferred to `TODOS.md` — do not let these creep in: + +- Skill marketplace or installable registry +- Custom website or dashboard +- Completion tracking (cc-progress) +- Community tutorial CI validation +- Auto-generated CONTRIBUTORS.md +- Multi-language translations +- Quiz/assessment infrastructure +- Community voting on projects diff --git a/docs/TASKS-20260401.md b/docs/TASKS-20260401.md new file mode 100644 index 0000000..fdad321 --- /dev/null +++ b/docs/TASKS-20260401.md @@ -0,0 +1,291 @@ +# Tasks: Dual-Layer Knowledge Base — claude-howto + +> Created: 2026-04-01 + +--- + +## Milestones + +| # | Milestone | Target | Description | +|---|-----------|--------|-------------| +| M1 | Infrastructure Live | End of April 2026 | quickstart.sh, CLAUDE.md, staleness action, agent index generator live; 2 weakest modules upgraded | +| M2 | 6/10 Modules Complete | End of June 2026 | Slash commands, memory, skills, CLI modules fully upgraded; generator producing valid manifest | +| M3 | All 10 Modules Complete | End of August 2026 | Every module has scenario intro, Try It Now blocks, decision tree, named patterns | +| M4 | Agent Layer Live | End of September 2026 | agent-manifest.json + AGENT-INDEX.md generated; lookup skill in repo; RECIPES.md + COMMUNITY-PROJECTS.md live | +| M5 | Version Audit Complete | End of November 2026 | All 10 modules verified against current CC version; RECIPES.md at 8+ recipes | +| M6 | Self-Sustaining System | End of March 2027 | Agent manifest covers 100% modules (CI-validated); RECIPES.md at 10+; community page growing organically | + +--- + +## Phase 1 — Infrastructure & Weak Modules (April 2026) + +**Target milestone: M1** + +### Pillar 4: Newcomer Onboarding + +- [ ] **T-001** — Write `scripts/quickstart.sh` + - Detects `~/.claude/` directory (creates with user confirmation if missing) + - Copies first slash command + CLAUDE.md + skill to user's setup + - Appends agent-discovery line to CLAUDE.md linking to AGENT-INDEX.md + - Idempotent: skips existing files with a warning, never overwrites + - Prints next steps on completion + +- [ ] **T-002** — Create `QUICKSTART.md` (First 15 Minutes visual guide) + - Annotated terminal steps as code blocks (avoid PNG screenshots where possible; prefer ASCII or Mermaid) + - Document which commands produce each visual so they can be re-captured + +- [ ] **T-003** — Add difficulty badges to all 10 module READMEs + - Format: `> 🟢 **Beginner** | ⏱ 30 minutes` at top of each module README + - Add "What you'll build" bullet preview below the badge + +### Pillar 7: Living Curriculum + +- [ ] **T-004** — Create `WHATS-NEW.md` + - Format: `## CC vX.X — DATE` with bullet items per feature change + - Add at least one entry for current CC version + +- [ ] **T-005** — Add version badges to all 10 module READMEs + - Format: `> ✅ Verified against Claude Code **vX.X.X** · Last verified: YYYY-MM-DD` + - Add `cc_version_verified` to each module's frontmatter + +- [ ] **T-006** — Create `.github/workflows/staleness-check.yml` + - Schedule: weekly Monday 09:00 UTC + - Reads each module's `last_verified` date from frontmatter (use `yq` or 10-line Python script) + - Creates a GitHub Issue for any module not verified in 30+ days + - Skips if open issue with same title already exists + +### Pillar 6: Content Quality (CLAUDE.md) + +- [ ] **T-007** — Create root `CLAUDE.md` for the project + - Demonstrates best practices as the project's own configuration + - Documents contributing conventions, module structure, and maintenance workflow + +### Pillar 2: AI Agent Index (Generator) + +- [ ] **T-008** — Write `scripts/build-agent-index.py` + - Reads all 10 module README files + - Extracts: headings (→ topics), code blocks (→ examples with language tags), tables (→ reference data) + - Outputs `agent-manifest.json` with schema defined in CEO plan + - Outputs `AGENT-INDEX.md` (human-readable summary) + - Validates references point to actual files + +### Module 08-checkpoints: Full Deep Pass (311 → 800+ lines) + +- [ ] **T-009** — Rewrite module intro with real-world scenario + - Example: "Your refactor just broke 3 things. Here's how checkpoints save you..." + +- [ ] **T-010** — Add checkpoint strategy decision tree (Mermaid flowchart) + - "I want to do X" → follow arrows → land on checkpoint pattern + +- [ ] **T-011** — Add 3 workflow templates + - Safe refactoring workflow + - A/B testing with checkpoints + - Disaster recovery workflow + +- [ ] **T-012** — Add integration with planning mode section + +- [ ] **T-013** — Add Mermaid diagram for checkpoint lifecycle + +- [ ] **T-014** — Add 2+ "Try It Now" blocks with verifiable commands + - Each: context sentence, command to run, expected output description + +- [ ] **T-015** — Add "Patterns & Recipes" section with 2+ named patterns + - Each pattern: problem, solution code, when to use, when NOT to use + +### Module 06-hooks: Full Deep Pass + +- [ ] **T-016** — Rewrite module intro with real-world scenario + - Example: "Your CI caught a lint error after 20 minutes. Hooks catch it in 2 seconds..." + +- [ ] **T-017** — Add hooks decision tree (Mermaid flowchart) + - "I want to trigger X when Y happens" → follow arrows → land on hook type + +- [ ] **T-018** — Add 5 complete hook examples with full scripts (~80 lines each) + 1. Auto-format on write (prettier/black) + 2. Security scan on commit (trufflehog/bandit) + 3. Test runner on file change + 4. Notification on session end + 5. Prompt validation (block dangerous patterns) + +- [ ] **T-019** — Add 2+ "Try It Now" blocks with verifiable commands + +- [ ] **T-020** — Add "Patterns & Recipes" section with 2+ named patterns + +**M1 Checkpoint: infrastructure live, 2 weakest modules fully upgraded** + +--- + +## Phase 2 — Deep Pass: Strong Modules Batch 1 (May–June 2026) + +**Target milestone: M2** + +### Module 01-slash-commands: Full Deep Pass + +- [ ] **T-021** — Rewrite intro with scenario ("Your teammate just pushed 47 files...") +- [ ] **T-022** — Add decision tree (Mermaid) +- [ ] **T-023** — Add 2+ "Try It Now" blocks +- [ ] **T-024** — Add "Patterns & Recipes" section with 2+ named patterns + +### Module 02-memory: Full Deep Pass + +- [ ] **T-025** — Rewrite intro with real-world scenario +- [ ] **T-026** — Add decision tree (Mermaid) +- [ ] **T-027** — Add 2+ "Try It Now" blocks +- [ ] **T-028** — Add "Patterns & Recipes" section with 2+ named patterns + +### Module 03-skills: Full Deep Pass + +- [ ] **T-029** — Rewrite intro with real-world scenario +- [ ] **T-030** — Add decision tree (Mermaid) +- [ ] **T-031** — Add 2+ "Try It Now" blocks +- [ ] **T-032** — Add "Patterns & Recipes" section with 2+ named patterns + +### Module 10-cli: Full Deep Pass + +- [ ] **T-033** — Rewrite intro with real-world scenario +- [ ] **T-034** — Add decision tree (Mermaid) +- [ ] **T-035** — Add 2+ "Try It Now" blocks +- [ ] **T-036** — Add "Patterns & Recipes" section with 2+ named patterns + +### Generator Validation + +- [ ] **T-037** — Run `scripts/build-agent-index.py` after each module upgrade; confirm valid manifest output +- [ ] **T-038** — Add CI step: validate agent-manifest.json schema on every push + +**M2 Checkpoint: 6/10 modules complete, generator producing valid manifest** + +--- + +## Phase 3 — Deep Pass: Strong Modules Batch 2 (July–August 2026) + +**Target milestone: M3** + +### Module 04-subagents: Full Deep Pass + +- [ ] **T-039** — Rewrite intro with real-world scenario +- [ ] **T-040** — Add decision tree (Mermaid) +- [ ] **T-041** — Add 2+ "Try It Now" blocks +- [ ] **T-042** — Add "Patterns & Recipes" section (e.g., "The Multi-Agent Review Pattern") + +### Module 05-mcp: Full Deep Pass + +- [ ] **T-043** — Rewrite intro with real-world scenario +- [ ] **T-044** — Add decision tree (Mermaid) +- [ ] **T-045** — Add 2+ "Try It Now" blocks +- [ ] **T-046** — Add "Patterns & Recipes" section with 2+ named patterns + +### Module 07-plugins: Full Deep Pass + +- [ ] **T-047** — Rewrite intro with real-world scenario +- [ ] **T-048** — Add decision tree (Mermaid) +- [ ] **T-049** — Add 2+ "Try It Now" blocks +- [ ] **T-050** — Add "Patterns & Recipes" section with 2+ named patterns + +### Module 09-advanced-features: Full Deep Pass + +- [ ] **T-051** — Rewrite intro with real-world scenario +- [ ] **T-052** — Add decision tree (Mermaid) +- [ ] **T-053** — Add 2+ "Try It Now" blocks +- [ ] **T-054** — Add "Patterns & Recipes" section with 2+ named patterns + +**M3 Checkpoint: all 10 modules complete and consistent** + +--- + +## Phase 4 — Agent Layer & Cross-Module (September 2026) + +**Target milestone: M4** + +### Pillar 2: Finalize AI Agent Index + +- [ ] **T-055** — Run `scripts/build-agent-index.py` against all 10 completed modules + - Produce final `agent-manifest.json` with 100% module coverage + - Produce `AGENT-INDEX.md` and link from README.md + +- [ ] **T-056** — Create `skills/claude-howto-lookup/SKILL.md` + - Reads `agent-manifest.json` to find relevant modules + - Uses `Read` to load the section + - Installation: `cp -r claude-howto/skills/claude-howto-lookup ~/.claude/skills/` + +- [ ] **T-057** — Mention lookup skill in quickstart.sh and QUICKSTART.md as optional feature + +### Pillar 3b: Cross-Module RECIPES.md + +- [ ] **T-058** — Create `RECIPES.md` with 5+ compound workflows + - Schema per recipe: name, modules-used, problem, solution code block, expected outcome + - Example: skill + hook + subagent = automated review pipeline + - Ensure HTML anchors on all major headings for deep-linking + +### Pillar 5: Community Showcase + +- [ ] **T-059** — Create `COMMUNITY-PROJECTS.md` + - Static Markdown page with submission format: name, description, link, features used + - Template entry included + - PR-based submission instructions + +**M4 Checkpoint: agent index live, recipes live, community page live** + +--- + +## Phase 5 — Version Audit & Recipe Expansion (October–November 2026) + +**Target milestone: M5** + +- [ ] **T-060** — Run full version audit: verify all 10 modules against current CC version + - Update `cc_version_verified` frontmatter in each module + - Update version badges + +- [ ] **T-061** — Expand `RECIPES.md` to 8+ recipes based on observed community patterns + +- [ ] **T-062** — Iterate agent manifest schema if new patterns emerge from completed modules + +- [ ] **T-063** — Open pinned GitHub Discussion: "Share your Claude Code workflows" + - Collect signal on real agent usage to inform future recipe expansion + +**M5 Checkpoint: all modules verified current, recipes growing** + +--- + +## Phase 6 — Compound & Sustain (December 2026 – March 2027) + +**Target milestone: M6** + +- [ ] **T-064** — Run `/docs-sync-claude-code` skill after every CC release; update `WHATS-NEW.md` + +- [ ] **T-065** — Ensure agent manifest covers 100% of modules (CI regression test) + +- [ ] **T-066** — Grow `RECIPES.md` to 10+ recipes + +- [ ] **T-067** — Monitor `COMMUNITY-PROJECTS.md` for organic growth; curate new entries + +- [ ] **T-068** — Evaluate agent usage signal from GitHub Discussions; if validated, invest in promoting the lookup skill (marketing, asm registry) + +**M6 Checkpoint: the system is self-sustaining** + +--- + +## Deferred (TODOS.md) + +These items are out of scope for this plan. Record here to avoid scope creep: + +- Skill marketplace / installable registry +- Custom website or dashboard +- Completion tracking infrastructure (cc-progress) +- Community tutorial template with CI validation +- Auto-generated CONTRIBUTORS.md +- Multi-language translations +- Quiz/assessment infrastructure upgrades +- Community voting/review mechanism for COMMUNITY-PROJECTS.md + +--- + +## Task Summary by Phase + +| Phase | Tasks | Period | Modules Touched | +|-------|-------|--------|-----------------| +| 1 — Infrastructure & Weak Modules | T-001 to T-020 | April 2026 | 06-hooks, 08-checkpoints + infra | +| 2 — Batch 1 Deep Pass | T-021 to T-038 | May–June 2026 | 01, 02, 03, 10 | +| 3 — Batch 2 Deep Pass | T-039 to T-054 | July–August 2026 | 04, 05, 07, 09 | +| 4 — Agent Layer & Cross-Module | T-055 to T-059 | September 2026 | All (manifest) + new files | +| 5 — Version Audit & Recipes | T-060 to T-063 | October–November 2026 | All (audit) | +| 6 — Sustain | T-064 to T-068 | December 2026–March 2027 | Ongoing | diff --git a/resources.md b/resources.md index d27d4fc..e9118c7 100644 --- a/resources.md +++ b/resources.md @@ -21,7 +21,7 @@ | Keybindings | Keyboard shortcut customization | [code.claude.com/docs/en/keybindings](https://code.claude.com/docs/en/keybindings) | | Desktop App | Native desktop application | [code.claude.com/docs/en/desktop](https://code.claude.com/docs/en/desktop) | | Remote Control | Remote session control | [code.claude.com/docs/en/remote-control](https://code.claude.com/docs/en/remote-control) | -| Auto Mode | Automatic permission management | [code.claude.com/docs/en/auto-mode](https://code.claude.com/docs/en/auto-mode) | +| Auto Mode | Automatic permission management | [code.claude.com/docs/en/permissions](https://code.claude.com/docs/en/permissions) | | Channels | Multi-channel communication | [code.claude.com/docs/en/channels](https://code.claude.com/docs/en/channels) | | Voice Dictation | Voice input for Claude Code | [code.claude.com/docs/en/voice-dictation](https://code.claude.com/docs/en/voice-dictation) | diff --git a/resources/INDEX.txt b/resources/INDEX.txt index e51f4c2..16f7d38 100644 --- a/resources/INDEX.txt +++ b/resources/INDEX.txt @@ -239,4 +239,3 @@ Questions or customization needed? ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Happy building! 🚀 - diff --git a/scripts/check_cross_references.py b/scripts/check_cross_references.py new file mode 100644 index 0000000..7460a88 --- /dev/null +++ b/scripts/check_cross_references.py @@ -0,0 +1,96 @@ +#!/usr/bin/env python3 +"""Validate cross-references, anchors, and code fences in Markdown files.""" + +import re +import sys +from pathlib import Path + +IGNORE_DIRS = { + ".venv", + "node_modules", + ".git", + "blog-posts", + "openspec", + "prompts", + ".agents", +} +IGNORE_FILES = {"README.backup.md"} + + +def iter_md_files(): + for f in Path().rglob("*.md"): + if ( + not any(part in IGNORE_DIRS for part in f.parts) + and f.name not in IGNORE_FILES + ): + yield f + + +def heading_to_anchor(heading: str) -> str: + # Match GitHub's anchor generation: strip non-ASCII (emoji), strip punctuation, + # lowercase, replace spaces with hyphens, strip leading/trailing hyphens. + heading_ascii = heading.encode("ascii", "ignore").decode() + return re.sub(r"[^\w\s-]", "", heading_ascii.lower()).replace(" ", "-").rstrip("-") + + +def strip_code_blocks(content: str) -> str: + """Remove fenced code blocks and inline code spans to avoid scanning example links.""" + # Strip fenced code blocks (``` ... ```) + content = re.sub(r"```[^\n]*\n.*?```", "", content, flags=re.DOTALL) + # Strip inline code spans (` ... `) + content = re.sub(r"`[^`\n]+`", "", content) + return content + + +def main() -> int: + errors = [] + + for file_path in iter_md_files(): + content = file_path.read_text() + # Strip code blocks before scanning for links/anchors to avoid false positives + # from documentation examples inside code fences. + scannable = strip_code_blocks(content) + + # Relative .md links must resolve + errors.extend( + f"{file_path}: broken cross-reference → '{link_path}'" + for link_path in re.findall(r"\[[^\]]+\]\(([^)#]+\.md)[^)]*\)", scannable) + if not (file_path.parent / link_path).resolve().exists() + ) + + # In-page anchors must match a real heading + anchors = re.findall(r"\[[^\]]+\]\(#([^)]+)\)", scannable) + if anchors: + headings = re.findall(r"^#{1,6}\s+(.+)$", content, re.MULTILINE) + valid_anchors = {heading_to_anchor(h) for h in headings} + errors.extend( + f"{file_path}: broken anchor → '#{anchor}'" + for anchor in anchors + if anchor not in valid_anchors + ) + + # Unmatched code fences (only count fences at start of line) + if len(re.findall(r"^```", content, re.MULTILINE)) % 2 != 0: + errors.append(f"{file_path}: unmatched code fences") + + # All numbered lesson dirs must have README.md + for i in range(1, 11): + errors.extend( + f"{d}: missing README.md" + for d in Path().glob(f"{i:02d}-*") + if d.is_dir() and not (d / "README.md").exists() + ) + + if errors: + print("❌ Cross-reference errors:") + for e in errors: + print(f" - {e}") + return 1 + + md_count = sum(1 for _ in iter_md_files()) + print(f"✅ All cross-references valid ({md_count} files checked)") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/check_links.py b/scripts/check_links.py new file mode 100644 index 0000000..fded0d1 --- /dev/null +++ b/scripts/check_links.py @@ -0,0 +1,125 @@ +#!/usr/bin/env python3 +"""Check external URLs in Markdown files are reachable.""" + +import re +import sys +import urllib.error +import urllib.request +from concurrent.futures import ThreadPoolExecutor, as_completed +from pathlib import Path + +IGNORE_DIRS = { + ".venv", + "node_modules", + ".git", + "blog-posts", + "openspec", + "prompts", + ".agents", + ".claude", +} +TIMEOUT = 10 +# Domains/patterns to skip: badges, placeholders, and bot-blocking hosts +SKIP_DOMAINS = { + "shields.io", + "img.shields.io", + "star-history.com", + "api.star-history.com", + "example.com", + "localhost", + "127.0.0.1", + "my-webhook.example.com", + "git.internal", + # Wikipedia blocks HEAD requests — GET also unreliable in CI without network + "en.wikipedia.org", + "wikipedia.org", + # GitHub API requires auth — unauthenticated requests return 404 for protected endpoints + "api.github.com", +} +SKIP_DOMAIN_SUFFIXES = (".example.com", ".example.org", ".internal") +# Placeholder/template URLs that are intentionally non-resolvable +SKIP_URL_PATTERNS = { + "github.com/org/", + "github.com/user/", + "github.com/your-org/", + "docs.example.com", +} + +URL_RE = re.compile(r"https?://[a-zA-Z0-9][a-zA-Z0-9\-._~:/?#\[\]@!$&'()*+,;=%]+") + + +def is_skipped(url: str) -> bool: + try: + domain = url.split("/")[2] + except IndexError: + return True # malformed URL + if any(skip == domain or domain.endswith("." + skip) for skip in SKIP_DOMAINS): + return True + if any(domain.endswith(suffix) for suffix in SKIP_DOMAIN_SUFFIXES): + return True + return any(pattern in url for pattern in SKIP_URL_PATTERNS) + + +def check_url(url: str) -> tuple[str, bool, str]: + if is_skipped(url): + return url, True, "skipped" + try: + req = urllib.request.Request( + url, headers={"User-Agent": "Mozilla/5.0"}, method="HEAD" + ) + with urllib.request.urlopen(req, timeout=TIMEOUT): # nosec B310 + return url, True, "ok" + except urllib.error.HTTPError as e: + # 403/429 often means the server is up but blocks bots — treat as ok + if e.code in (401, 403, 405, 429): + return url, True, f"http {e.code} (ignored)" + return url, False, f"HTTP {e.code}" + except Exception as e: + return url, False, str(e) + + +def main(strict: bool = False) -> int: + urls: dict[str, list[str]] = {} # url -> [file, ...] + + md_files = [ + f + for f in Path().rglob("*.md") + if not any(part in IGNORE_DIRS for part in f.parts) + ] + + for file_path in md_files: + content = file_path.read_text() + for raw_url in URL_RE.findall(content): + # Strip trailing Markdown/punctuation characters the regex may over-capture + # from link syntax like [text](https://url/) or **https://url)** + clean_url = raw_url.rstrip(")>*_`':.,;").split("#")[0] + urls.setdefault(clean_url, []).append(str(file_path)) + + if not urls: + print("✅ No external URLs found") + return 0 + + errors = [] + with ThreadPoolExecutor(max_workers=10) as pool: + futures = {pool.submit(check_url, url): url for url in urls} + for future in as_completed(futures): + url, ok, reason = future.result() + if not ok: + errors.extend(f"{f}: dead link → {url} ({reason})" for f in urls[url]) + + if errors: + print("❌ Dead links found:") + for e in sorted(errors): + print(f" - {e}") + # In non-strict mode (pre-commit), report but don't block the commit. + # Set LINK_CHECK_STRICT=1 (as CI does) to enforce failures. + return 1 if strict else 0 + + print(f"✅ All external URLs reachable ({len(urls)} checked)") + return 0 + + +if __name__ == "__main__": + import os + + sys.exit(main(strict=os.environ.get("LINK_CHECK_STRICT") == "1")) diff --git a/scripts/check_mermaid.py b/scripts/check_mermaid.py new file mode 100644 index 0000000..7ea7802 --- /dev/null +++ b/scripts/check_mermaid.py @@ -0,0 +1,86 @@ +#!/usr/bin/env python3 +"""Validate Mermaid diagram syntax in Markdown files using mmdc.""" + +import json +import os +import re +import shutil +import subprocess # nosec B404 +import sys +import tempfile +from pathlib import Path + +IGNORE_DIRS = {".venv", "node_modules", ".git", "blog-posts", ".agents"} + + +def main() -> int: + if not shutil.which("mmdc"): + print( + "⚠ mmdc not found — skipping Mermaid validation (install @mermaid-js/mermaid-cli)" + ) + return 0 + + errors = [] + checked = 0 + + # On GitHub Actions Linux runners, Chrome/Puppeteer requires --no-sandbox. + # Write a temporary puppeteer config when MERMAID_PUPPETEER_NO_SANDBOX is set. + puppeteer_config_path = None + extra_args: list[str] = [] + if os.environ.get("MERMAID_PUPPETEER_NO_SANDBOX") == "true": + with tempfile.NamedTemporaryFile( + suffix=".json", mode="w", delete=False + ) as pcfg: + json.dump({"args": ["--no-sandbox", "--disable-setuid-sandbox"]}, pcfg) + puppeteer_config_path = pcfg.name + extra_args = ["-p", puppeteer_config_path] + + md_files = [ + f + for f in Path().rglob("*.md") + if not any(part in IGNORE_DIRS for part in f.parts) + ] + + try: + for file_path in md_files: + content = file_path.read_text() + blocks = re.findall(r"```mermaid\n(.*?)```", content, re.DOTALL) + for i, block in enumerate(blocks): + with tempfile.NamedTemporaryFile( + suffix=".mmd", mode="w", delete=False + ) as tmp: + tmp.write(block) + tmp_path = tmp.name + out_path = str(Path(tmp_path).with_suffix(".svg")) + try: + result = subprocess.run( # nosec B603 B607 + ["mmdc", "-i", tmp_path, "-o", out_path, *extra_args], + capture_output=True, + text=True, + check=False, + ) + if result.returncode != 0: + errors.append( + f"{file_path} (block {i + 1}): {result.stderr.strip()}" + ) + else: + checked += 1 + finally: + Path(tmp_path).unlink(missing_ok=True) + Path(out_path).unlink(missing_ok=True) + finally: + if puppeteer_config_path: + Path(puppeteer_config_path).unlink(missing_ok=True) + + print(f"✅ Checked {checked} Mermaid diagram(s)") + if errors: + print("\n❌ Mermaid errors:") + for e in errors: + print(f" - {e}") + return 1 + + return 0 + + +if __name__ == "__main__": + sys.exit(main())