feat(extensions): support .extensionignore to exclude files during install

Add .extensionignore support so extension authors can exclude files and
folders from being copied when users run 'specify extension add'.

The file uses glob-style patterns (one per line), supports comments (#),
blank lines, trailing-slash directory patterns, and relative path matching.
The .extensionignore file itself is always excluded from the copy.

- Add _load_extensionignore() to ExtensionManager
- Integrate ignore function into shutil.copytree in install_from_directory
- Document .extensionignore in EXTENSION-DEVELOPMENT-GUIDE.md
- Add 6 tests covering all pattern matching scenarios
- Bump version to 0.1.14

Author: Rubiss

CHANGELOG.md

@@ -7,6 +7,12 @@ Recent changes to the Specify CLI and templates are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.14] - 2026-03-09
+
+### Added
+
+- feat(extensions): support `.extensionignore` to exclude files/folders during `specify extension add` (#TBD)
+
 ## [0.1.13] - 2026-03-03
 
 ### Changed

extensions/EXTENSION-DEVELOPMENT-GUIDE.md

@@ -332,6 +332,50 @@ echo "$config"
 
 ---
 
+## Excluding Files with `.extensionignore`
+
+Extension authors can create a `.extensionignore` file in the extension root to exclude files and folders from being copied when a user installs the extension with `specify extension add`. This is useful for keeping development-only files (tests, CI configs, docs source, etc.) out of the installed copy.
+
+### Format
+
+The file uses glob-style patterns, one per line:
+
+- Blank lines are ignored
+- Lines starting with `#` are comments
+- Patterns are matched against both the file/folder name and its path relative to the extension root
+- The `.extensionignore` file itself is always excluded automatically
+
+### Example
+
+```gitignore
+# .extensionignore
+
+# Development files
+tests/
+.github/
+.gitignore
+
+# Build artifacts
+__pycache__/
+*.pyc
+dist/
+
+# Documentation source (keep only the built README)
+docs/
+CONTRIBUTING.md
+```
+
+### Pattern Matching
+
+| Pattern | Matches |
+|---------|---------|
+| `*.pyc` | Any `.pyc` file in any directory |
+| `tests/` | The `tests` directory (and all its contents) |
+| `docs/*.draft.md` | Draft markdown files inside `docs/` |
+| `.github` | The `.github` directory at any level |
+
+---
+
 ## Validation Rules
 
 ### Extension ID

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "specify-cli"
-version = "0.1.13"
+version = "0.1.14"
 description = "Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD)."
 requires-python = ">=3.11"
 dependencies = [

src/specify_cli/extensions.py

@@ -6,13 +6,14 @@
 without bloating the core framework.
 """
 
+import fnmatch
 import json
 import hashlib
 import tempfile
 import zipfile
 import shutil
 from pathlib import Path
-from typing import Optional, Dict, List, Any
+from typing import Optional, Dict, List, Any, Callable, Set
 from datetime import datetime, timezone
 import re
 
@@ -268,6 +269,56 @@ def __init__(self, project_root: Path):
         self.extensions_dir = project_root / ".specify" / "extensions"
         self.registry = ExtensionRegistry(self.extensions_dir)
 
+    @staticmethod
+    def _load_extensionignore(source_dir: Path) -> Optional[Callable[[str, List[str]], Set[str]]]:
+        """Load .extensionignore and return an ignore function for shutil.copytree.
+
+        The .extensionignore file uses glob-style patterns (one per line).
+        Lines starting with '#' are comments. Blank lines are ignored.
+        The .extensionignore file itself is always excluded.
+
+        Args:
+            source_dir: Path to the extension source directory
+
+        Returns:
+            An ignore function compatible with shutil.copytree, or None
+            if no .extensionignore file exists.
+        """
+        ignore_file = source_dir / ".extensionignore"
+        if not ignore_file.exists():
+            return None
+
+        patterns: List[str] = []
+        for line in ignore_file.read_text().splitlines():
+            stripped = line.strip()
+            if stripped and not stripped.startswith("#"):
+                patterns.append(stripped)
+
+        # Always ignore the .extensionignore file itself
+        patterns.append(".extensionignore")
+
+        def _ignore(directory: str, entries: List[str]) -> Set[str]:
+            ignored: Set[str] = set()
+            rel_dir = Path(directory).relative_to(source_dir)
+            for entry in entries:
+                rel_path = str(rel_dir / entry) if str(rel_dir) != "." else entry
+                # Normalise to forward slashes for consistent matching
+                rel_path_fwd = rel_path.replace("\\", "/")
+                for pattern in patterns:
+                    # Strip trailing slash so "tests/" matches directory name "tests"
+                    pat = pattern.rstrip("/")
+                    # Match against the entry name itself
+                    if fnmatch.fnmatch(entry, pat):
+                        ignored.add(entry)
+                        break
+                    # Match against the relative path from the source root
+                    if fnmatch.fnmatch(rel_path_fwd, pat):
+                        ignored.add(entry)
+                        break
+            return ignored
+
+        return _ignore
+
     def check_compatibility(
         self,
         manifest: ExtensionManifest,
@@ -341,7 +392,8 @@ def install_from_directory(
         if dest_dir.exists():
             shutil.rmtree(dest_dir)
 
-        shutil.copytree(source_dir, dest_dir)
+        ignore_fn = self._load_extensionignore(source_dir)
+        shutil.copytree(source_dir, dest_dir, ignore=ignore_fn)
 
         # Register commands with AI agents
         registered_commands = {}

tests/test_extensions.py

@@ -1133,3 +1133,179 @@ def test_clear_cache(self, temp_dir):
 
         assert not catalog.cache_file.exists()
         assert not catalog.cache_metadata_file.exists()
+
+
+class TestExtensionIgnore:
+    """Test .extensionignore support during extension installation."""
+
+    def _make_extension(self, temp_dir, valid_manifest_data, extra_files=None, ignore_content=None):
+        """Helper to create an extension directory with optional extra files and .extensionignore."""
+        import yaml
+
+        ext_dir = temp_dir / "ignored-ext"
+        ext_dir.mkdir()
+
+        # Write manifest
+        with open(ext_dir / "extension.yml", "w") as f:
+            yaml.dump(valid_manifest_data, f)
+
+        # Create commands directory with a command file
+        commands_dir = ext_dir / "commands"
+        commands_dir.mkdir()
+        (commands_dir / "hello.md").write_text(
+            "---\ndescription: \"Test hello command\"\n---\n\n# Hello\n\n$ARGUMENTS\n"
+        )
+
+        # Create any extra files/dirs
+        if extra_files:
+            for rel_path, content in extra_files.items():
+                p = ext_dir / rel_path
+                p.parent.mkdir(parents=True, exist_ok=True)
+                if content is None:
+                    # Create directory
+                    p.mkdir(parents=True, exist_ok=True)
+                else:
+                    p.write_text(content)
+
+        # Write .extensionignore
+        if ignore_content is not None:
+            (ext_dir / ".extensionignore").write_text(ignore_content)
+
+        return ext_dir
+
+    def test_no_extensionignore(self, temp_dir, valid_manifest_data):
+        """Without .extensionignore, all files are copied."""
+        ext_dir = self._make_extension(
+            temp_dir,
+            valid_manifest_data,
+            extra_files={"README.md": "# Hello", "tests/test_foo.py": "pass"},
+        )
+
+        proj_dir = temp_dir / "project"
+        proj_dir.mkdir()
+        (proj_dir / ".specify").mkdir()
+
+        manager = ExtensionManager(proj_dir)
+        manager.install_from_directory(ext_dir, "0.1.0", register_commands=False)
+
+        dest = proj_dir / ".specify" / "extensions" / "test-ext"
+        assert (dest / "README.md").exists()
+        assert (dest / "tests" / "test_foo.py").exists()
+
+    def test_extensionignore_excludes_files(self, temp_dir, valid_manifest_data):
+        """Files matching .extensionignore patterns are excluded."""
+        ext_dir = self._make_extension(
+            temp_dir,
+            valid_manifest_data,
+            extra_files={
+                "README.md": "# Hello",
+                "tests/test_foo.py": "pass",
+                "tests/test_bar.py": "pass",
+                ".github/workflows/ci.yml": "on: push",
+            },
+            ignore_content="tests/\n.github/\n",
+        )
+
+        proj_dir = temp_dir / "project"
+        proj_dir.mkdir()
+        (proj_dir / ".specify").mkdir()
+
+        manager = ExtensionManager(proj_dir)
+        manager.install_from_directory(ext_dir, "0.1.0", register_commands=False)
+
+        dest = proj_dir / ".specify" / "extensions" / "test-ext"
+        # Included
+        assert (dest / "README.md").exists()
+        assert (dest / "extension.yml").exists()
+        assert (dest / "commands" / "hello.md").exists()
+        # Excluded
+        assert not (dest / "tests").exists()
+        assert not (dest / ".github").exists()
+
+    def test_extensionignore_glob_patterns(self, temp_dir, valid_manifest_data):
+        """Glob patterns like *.pyc are respected."""
+        ext_dir = self._make_extension(
+            temp_dir,
+            valid_manifest_data,
+            extra_files={
+                "README.md": "# Hello",
+                "helpers.pyc": b"\x00".decode("latin-1"),
+                "commands/cache.pyc": b"\x00".decode("latin-1"),
+            },
+            ignore_content="*.pyc\n",
+        )
+
+        proj_dir = temp_dir / "project"
+        proj_dir.mkdir()
+        (proj_dir / ".specify").mkdir()
+
+        manager = ExtensionManager(proj_dir)
+        manager.install_from_directory(ext_dir, "0.1.0", register_commands=False)
+
+        dest = proj_dir / ".specify" / "extensions" / "test-ext"
+        assert (dest / "README.md").exists()
+        assert not (dest / "helpers.pyc").exists()
+        assert not (dest / "commands" / "cache.pyc").exists()
+
+    def test_extensionignore_comments_and_blanks(self, temp_dir, valid_manifest_data):
+        """Comments and blank lines in .extensionignore are ignored."""
+        ext_dir = self._make_extension(
+            temp_dir,
+            valid_manifest_data,
+            extra_files={"README.md": "# Hello", "notes.txt": "some notes"},
+            ignore_content="# This is a comment\n\nnotes.txt\n\n# Another comment\n",
+        )
+
+        proj_dir = temp_dir / "project"
+        proj_dir.mkdir()
+        (proj_dir / ".specify").mkdir()
+
+        manager = ExtensionManager(proj_dir)
+        manager.install_from_directory(ext_dir, "0.1.0", register_commands=False)
+
+        dest = proj_dir / ".specify" / "extensions" / "test-ext"
+        assert (dest / "README.md").exists()
+        assert not (dest / "notes.txt").exists()
+
+    def test_extensionignore_itself_excluded(self, temp_dir, valid_manifest_data):
+        """.extensionignore is never copied to the destination."""
+        ext_dir = self._make_extension(
+            temp_dir,
+            valid_manifest_data,
+            ignore_content="# nothing special here\n",
+        )
+
+        proj_dir = temp_dir / "project"
+        proj_dir.mkdir()
+        (proj_dir / ".specify").mkdir()
+
+        manager = ExtensionManager(proj_dir)
+        manager.install_from_directory(ext_dir, "0.1.0", register_commands=False)
+
+        dest = proj_dir / ".specify" / "extensions" / "test-ext"
+        assert (dest / "extension.yml").exists()
+        assert not (dest / ".extensionignore").exists()
+
+    def test_extensionignore_relative_path_match(self, temp_dir, valid_manifest_data):
+        """Patterns matching relative paths work correctly."""
+        ext_dir = self._make_extension(
+            temp_dir,
+            valid_manifest_data,
+            extra_files={
+                "docs/guide.md": "# Guide",
+                "docs/internal/draft.md": "draft",
+                "README.md": "# Hello",
+            },
+            ignore_content="docs/internal/draft.md\n",
+        )
+
+        proj_dir = temp_dir / "project"
+        proj_dir.mkdir()
+        (proj_dir / ".specify").mkdir()
+
+        manager = ExtensionManager(proj_dir)
+        manager.install_from_directory(ext_dir, "0.1.0", register_commands=False)
+
+        dest = proj_dir / ".specify" / "extensions" / "test-ext"
+        assert (dest / "docs" / "guide.md").exists()
+        assert not (dest / "docs" / "internal" / "draft.md").exists()