Merge branch 'development' into main — release v3.7.0

Author: yusufkaraaslan

.github/PULL_REQUEST_TEMPLATE.md

@@ -25,6 +25,7 @@ Relates to #(issue number)
 - [ ] I have performed a self-review of my own code
 - [ ] I have commented my code, particularly in hard-to-understand areas
 - [ ] I have made corresponding changes to the documentation
+- [ ] Documentation updated (README, examples, AGENTS.md if CLI changed)
 - [ ] My changes generate no new warnings
 - [ ] I have added tests that prove my fix is effective or that my feature works
 - [ ] New and existing unit tests pass locally with my changes

.github/workflows/release.yml

@@ -39,15 +39,10 @@ jobs:
     - name: Run tests
       timeout-minutes: 30
       run: |
-        # Exclude slow MCP/e2e tests that can hang or run 20+ min each.
-        # The tests.yml workflow (matrix CI) runs these in a separate job with
-        # its own timeout; the release workflow only needs fast confidence that
-        # the package is sound before publishing.
+        pip install pytest-timeout
         python -m pytest tests/ -v \
-          --ignore=tests/test_mcp_fastmcp.py \
-          --ignore=tests/test_mcp_server.py \
-          --ignore=tests/test_install_skill_e2e.py \
-          --ignore=tests/test_bootstrap_skill_e2e.py
+          -m "not slow and not integration and not e2e and not network and not serial and not mcp_only" \
+          --timeout=120
 
     - name: Extract version from tag
       id: get_version

.github/workflows/test-vector-dbs.yml

@@ -9,15 +9,19 @@ on:
     paths:
       - 'src/skill_seekers/cli/adaptors/**'
       - 'src/skill_seekers/mcp/tools/vector_db_tools.py'
-      - 'tests/test_*adaptor.py'
+      - 'tests/test_*adaptor*.py'
       - 'tests/test_mcp_vector_dbs.py'
+      - 'tests/test_docker_smoke.py'
+      - 'tests/test_upload_integration.py'
   pull_request:
     branches: [ main, development ]
     paths:
       - 'src/skill_seekers/cli/adaptors/**'
       - 'src/skill_seekers/mcp/tools/vector_db_tools.py'
-      - 'tests/test_*adaptor.py'
+      - 'tests/test_*adaptor*.py'
       - 'tests/test_mcp_vector_dbs.py'
+      - 'tests/test_docker_smoke.py'
+      - 'tests/test_upload_integration.py'
   workflow_dispatch:
 
 jobs:

.github/workflows/tests.yml

@@ -12,92 +12,61 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
-
     - name: Set up Python 3.12
       uses: actions/setup-python@v5
       with:
         python-version: '3.12'
-
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
         pip install "ruff==0.15.8" mypy
         pip install -e .
-
     - name: Run ruff linter
-      run: |
-        echo "Running ruff check..."
-        ruff check src/ tests/ --output-format=github
-
+      run: ruff check src/ tests/ --output-format=github
     - name: Run ruff formatter check
-      run: |
-        echo "Checking code formatting..."
-        ruff format --check src/ tests/
-
+      run: ruff format --check src/ tests/
     - name: Run mypy type checker
-      run: |
-        echo "Running mypy type checker..."
-        mypy src/skill_seekers --show-error-codes --pretty
-      continue-on-error: true  # Don't fail CI on mypy errors initially
+      run: mypy src/skill_seekers --show-error-codes --pretty
+      continue-on-error: true
 
-  test:
+  test-fast:
+    name: Fast Unit Tests (parallel)
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest]
         python-version: ['3.10', '3.11', '3.12']
         exclude:
-          # Exclude some combinations to speed up CI
           - os: macos-latest
             python-version: '3.10'
-
     steps:
     - uses: actions/checkout@v4
       with:
-        submodules: recursive  # Initialize api/configs_repo submodule
-
+        submodules: recursive
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
-
-    - name: Install uv
-      run: |
-        curl -LsSf https://astral.sh/uv/install.sh | sh
-        echo "$HOME/.local/bin" >> $GITHUB_PATH
-
     - name: Cache pip packages
       uses: actions/cache@v4
       with:
         path: ~/.cache/pip
-        key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt', 'skill_seeker_mcp/requirements.txt') }}
+        key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
         restore-keys: |
           ${{ runner.os }}-pip-
-
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
         pip install -r requirements.txt
-        if [ -f skill_seeker_mcp/requirements.txt ]; then pip install -r skill_seeker_mcp/requirements.txt; fi
-        # Install package in editable mode for tests (required for src/ layout)
+        pip install pytest-xdist pytest-timeout
         pip install -e .
-
-    - name: Run CLI tests
-      run: |
-        python -m pytest tests/test_scraper_features.py -v
-        python -m pytest tests/test_config_validation.py -v
-        python -m pytest tests/test_integration.py -v
-
-    - name: Run MCP server tests
+    - name: Run fast tests (xdist parallel)
       run: |
-        python -m pytest tests/test_mcp_server.py -v
-
-    - name: Generate coverage report
-      run: |
-        python -m pytest tests/ --ignore=tests/test_mcp_fastmcp.py --ignore=tests/test_mcp_server.py --ignore=tests/test_install_skill_e2e.py --cov=src/skill_seekers --cov-report=xml --cov-report=term
-      timeout-minutes: 30
-
+        python -m pytest tests/ -n auto --dist=loadfile \
+          -m "not slow and not integration and not e2e and not network and not serial and not mcp_only" \
+          -q --timeout=120 --cov=src/skill_seekers --cov-report=xml --cov-report=term
+      timeout-minutes: 15
     - name: Upload coverage to Codecov
       uses: codecov/codecov-action@v4
       with:
@@ -106,14 +75,62 @@ jobs:
         name: codecov-umbrella
         fail_ci_if_error: false
 
-  # Summary job that provides a single status check for branch protection.
-  # The job name MUST match the required status check in the branch
-  # protection rules.  GitHub reports status checks using job names
-  # (not the workflow name), so the required check "Tests" will only
-  # be satisfied if a job with exactly that name exists and succeeds.
+  test-serial:
+    name: Serial / Integration / E2E Tests
+    runs-on: ubuntu-latest
+    needs: [test-fast]
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        submodules: recursive
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements.txt
+        pip install pytest-timeout
+        pip install -e .
+    - name: Run serial/integration/E2E tests
+      run: |
+        python -m pytest tests/ \
+          --ignore=tests/test_bootstrap_skill_e2e.py \
+          --ignore=tests/test_bootstrap_skill.py \
+          -m "(integration or e2e or slow or network or serial) and not mcp_only" \
+          -v --timeout=300
+      timeout-minutes: 25
+
+  test-mcp:
+    name: MCP Server Tests
+    runs-on: ubuntu-latest
+    needs: [test-fast]
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        submodules: recursive
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements.txt
+        pip install pytest-timeout
+        pip install -e ".[mcp]"
+        pip install -e .
+    - name: Run MCP tests
+      run: |
+        python -m pytest tests/ \
+          -m "mcp_only and not network" \
+          -v --timeout=180
+      timeout-minutes: 10
+
   tests-complete:
     name: Tests
-    needs: [lint, test]
+    needs: [lint, test-fast, test-serial, test-mcp]
     runs-on: ubuntu-latest
     if: always()
     steps:
@@ -123,8 +140,16 @@ jobs:
             echo "❌ Code quality checks failed!"
             exit 1
           fi
-          if [ "${{ needs.test.result }}" != "success" ]; then
-            echo "❌ Tests failed!"
+          if [ "${{ needs.test-fast.result }}" != "success" ]; then
+            echo "❌ Fast tests failed!"
+            exit 1
+          fi
+          if [ "${{ needs.test-serial.result }}" == "failure" ]; then
+            echo "❌ Serial/integration tests failed!"
+            exit 1
+          fi
+          if [ "${{ needs.test-mcp.result }}" == "failure" ]; then
+            echo "❌ MCP tests failed!"
             exit 1
           fi
           echo "✅ All checks passed!"

.gitignore

@@ -70,3 +70,9 @@ skill-seekers-configs/
 !distribution/claude-plugin/.mcp.json
 settings.json
 USER_GUIDE.md
+
+# Local tooling artifacts (per-developer state, not project state)
+# chromadb's default persistence directory
+chroma_db/
+# Superpowers SDK output
+docs/superpowers/

AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md - Skill Seekers
 
-Comprehensive reference for AI coding agents. Skill Seekers is a Python CLI tool (v3.5.0) that converts documentation sites, GitHub repos, PDFs, videos, notebooks, wikis, and more into AI-ready skills for 21+ LLM platforms and RAG pipelines.
+Comprehensive reference for AI coding agents. Skill Seekers is a Python CLI tool (v3.6.0) that converts documentation sites, GitHub repos, PDFs, videos, notebooks, wikis, and more into AI-ready skills for 21+ LLM platforms and RAG pipelines.
 
 ## Project Overview
 
@@ -44,46 +44,46 @@ OPENAI_API_KEY         # For OpenAI support
 GITHUB_TOKEN           # For GitHub repo scraping (higher rate limits)
 ```
 
-## Build / Test / Lint Commands
+## Build / Test / Lint
 
 ```bash
-# Run ALL tests (never skip tests — all must pass before commits)
+# Full suite (never skip — all must pass)
 pytest tests/ -v
 
-# Run a single test file
-pytest tests/test_scraper_features.py -v
+# Fast iteration (skip slow, integration, E2E, network, MCP)
+pytest tests/ -m "not slow and not integration and not e2e and not network and not serial and not mcp_only" -q
 
-# Run a single test function
-pytest tests/test_scraper_features.py::test_detect_language -v
+# Fast parallel (install pytest-xdist first)
+pytest tests/ -n auto --dist=loadfile -m "not slow and not integration and not e2e and not network and not serial and not mcp_only" -q
+
+# 3-phase runner script (recommended for local dev)
+bash scripts/run_tests_fast.sh
 
-# Run a single test class method
-pytest tests/test_adaptors/test_claude_adaptor.py::TestClaudeAdaptor::test_package -v
+# Single test
+pytest tests/test_scraper_features.py::test_detect_language -v
 
-# Skip slow/integration tests
+# Skip slow/integration
 pytest tests/ -v -m "not slow and not integration"
 
 # With coverage
 pytest tests/ --cov=src/skill_seekers --cov-report=term
 
-# Lint (ruff)
+# Lint + format check (matches CI)
 ruff check src/ tests/
-ruff check src/ tests/ --fix
-
-# Format (ruff)
 ruff format --check src/ tests/
-ruff format src/ tests/
 
-# Type check (mypy)
+# Type check (non-blocking — mypy is continue-on-error in CI)
 mypy src/skill_seekers --show-error-codes --pretty
 ```
 
-**Pytest config** (from pyproject.toml): `addopts = "-v --tb=short --strict-markers"`, `asyncio_mode = "auto"`, `asyncio_default_fixture_loop_scope = "function"`.
-
-**Test markers:** `slow`, `integration`, `e2e`, `venv`, `bootstrap`, `benchmark`, `asyncio`.
+**Pytest config:** `asyncio_mode = "auto"`, so `@pytest.mark.asyncio` is implicit. Test markers: `slow`, `integration`, `e2e`, `venv`, `bootstrap`, `benchmark`, `asyncio`, `serial`, `network`, `mcp_only`.
 
-**Async tests:** use `@pytest.mark.asyncio`; asyncio_mode is `auto` so the decorator is often implicit.
+**CI note:** CI pins `ruff==0.15.8` (not the `>=0.14.13` dev dep). If formatting behaves differently locally, check the CI version.
 
-**Test count:** 160 test files (138 in `tests/`, 22 in `tests/test_adaptors/`).
+**CI test phases:** Tests are split into 3 parallel jobs:
+- `test-fast` — 3386 unit tests with xdist across OS/Python matrix
+- `test-serial` — 69 serial/integration/E2E/network tests
+- `test-mcp` — 193 MCP tests (requires `[mcp]` extras)
 
 ## Code Style
 
@@ -187,6 +187,7 @@ docs/                        # Documentation (guides, integrations, architecture
 ```bash
 # Core commands
 skill-seekers create <source>              # Create skill from any source (auto-detects type)
+skill-seekers scan <dir>                   # AI-detect a project's tech stack and emit per-framework configs
 skill-seekers enhance <directory>          # AI-powered enhancement
 skill-seekers package <directory>          # Package skill for target platform
 skill-seekers upload <file>                # Upload skill to target platform