feat(extensions): scaffold config templates on extension add/enable

src/specify_cli/__init__.py

@@ -3666,8 +3666,14 @@ def extension_add(
         if reg_skills:
             console.print(f"\n[green]✓[/green] {len(reg_skills)} agent skill(s) auto-registered")
 
-        console.print("\n[yellow]⚠[/yellow]  Configuration may be required")
-        console.print(f"   Check: .specify/extensions/{manifest.id}/")
+        # Scaffold config templates automatically
+        deployed, skipped = manager.scaffold_config(manifest.id)
+        if deployed:
+            console.print("\n[bold cyan]Config scaffolded:[/bold cyan]")
+            for cfg in deployed:
+                console.print(f"  • .specify/{cfg}")
+        if skipped:
+            console.print(f"\n[dim]Config files already exist (preserved): {', '.join(skipped)}[/dim]")
 
     except ValidationError as e:
         console.print(f"\n[red]Validation Error:[/red] {e}")
@@ -4470,6 +4476,15 @@ def extension_enable(
 
     console.print(f"[green]✓[/green] Extension '{display_name}' enabled")
 
+    # Scaffold config templates on enable
+    deployed, skipped = manager.scaffold_config(extension_id)
+    if deployed:
+        console.print("\n[bold cyan]Config scaffolded:[/bold cyan]")
+        for cfg in deployed:
+            console.print(f"  • .specify/{cfg}")
+    if skipped:
+        console.print(f"\n[dim]Config files already exist (preserved): {', '.join(skipped)}[/dim]")
+
 
 @extension_app.command("disable")
 def extension_disable(

src/specify_cli/extensions.py

@@ -233,6 +233,14 @@ def hooks(self) -> Dict[str, Any]:
         """Get hook definitions."""
         return self.data.get("hooks", {})
 
+    @property
+    def config(self) -> List[Dict[str, Any]]:
+        """Get list of provided config templates."""
+        raw = self.data.get("provides", {}).get("config", [])
+        if not isinstance(raw, list):
+            return []
+        return [entry for entry in raw if isinstance(entry, dict)]
+
     def get_hash(self) -> str:
         """Calculate SHA256 hash of manifest file."""
         with open(self.path, 'rb') as f:
@@ -1125,6 +1133,57 @@ def install_from_zip(
             # Install from extracted directory
             return self.install_from_directory(extension_dir, speckit_version, priority=priority)
 
+    def scaffold_config(self, extension_id: str) -> tuple:
+        """Deploy config templates from an installed extension to the project.
+
+        Reads the extension's manifest provides.config section and copies
+        each config template to the project's .specify/ directory. Existing
+        config files are never overwritten (user customizations are preserved).
+
+        Args:
+            extension_id: ID of the installed extension
+
+        Returns:
+            Tuple of (deployed, skipped_existing) where each is a list of
+            config file names.
+        """
+        ext_dir = self.extensions_dir / extension_id
+        manifest_path = ext_dir / "extension.yml"
+        if not manifest_path.exists():
+            return []
+
+        manifest = ExtensionManifest(manifest_path)
+        deployed = []
+
+        skipped_existing = []
+
+        for config_entry in manifest.config:
+            template_name = config_entry.get("template", "")
+            target_name = config_entry.get("name", template_name)
+            if not template_name:
+                continue
+
+            # Reject path traversal and absolute paths
+            if Path(template_name).is_absolute() or ".." in Path(template_name).parts:
+                continue
+            if Path(target_name).is_absolute() or ".." in Path(target_name).parts:
+                continue
+
+            template_path = ext_dir / template_name
+            if not template_path.exists() or not template_path.is_file():
+                continue
+
+            target_path = self.project_root / ".specify" / target_name
+            if target_path.exists():
+                skipped_existing.append(target_name)
+                continue
+
+            target_path.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(template_path, target_path)
+            deployed.append(target_name)
+
+        return deployed, skipped_existing
+
     def remove(self, extension_id: str, keep_config: bool = False) -> bool:
         """Remove an installed extension.
 

tests/test_extensions.py

@@ -832,6 +832,181 @@ def test_config_backup_on_remove(self, extension_dir, project_dir):
         assert backup_file.read_text() == "test: config"
 
 
+class TestExtensionConfigScaffolding:
+    """Test automatic config scaffolding during add/enable lifecycle."""
+
+    def _make_extension(self, ext_dir, config_entries=None):
+        """Create a minimal extension with optional config templates."""
+        ext_dir.mkdir(parents=True, exist_ok=True)
+        manifest = {
+            "schema_version": "1.0",
+            "extension": {
+                "id": "test-ext",
+                "name": "Test Extension",
+                "version": "1.0.0",
+                "description": "Test extension",
+                "author": "Test",
+                "repository": "https://github.com/test/test",
+                "license": "MIT",
+                "homepage": "https://github.com/test/test",
+            },
+            "requires": {"speckit_version": ">=0.1.0"},
+            "provides": {
+                "commands": [{
+                    "name": "speckit.test-ext.example",
+                    "file": "commands/example.md",
+                    "description": "Example command",
+                }],
+            },
+            "tags": ["test"],
+        }
+        if config_entries:
+            manifest["provides"]["config"] = config_entries
+        import yaml
+        (ext_dir / "extension.yml").write_text(yaml.dump(manifest, default_flow_style=False))
+        # Create command file so validation passes
+        (ext_dir / "commands").mkdir(exist_ok=True)
+        (ext_dir / "commands" / "example.md").write_text("# Example")
+        return manifest
+
+    def test_scaffold_config_deploys_template(self, tmp_path):
+        """Config template should be copied to .specify/ on scaffold."""
+        from specify_cli.extensions import ExtensionManager
+        project = tmp_path / "project"
+        specify_dir = project / ".specify"
+        specify_dir.mkdir(parents=True)
+        ext_dir = specify_dir / "extensions" / "test-ext"
+        self._make_extension(ext_dir, config_entries=[{
+            "name": "test-config.yml",
+            "template": "config-template.yml",
+            "description": "Test config",
+            "required": True,
+        }])
+        (ext_dir / "config-template.yml").write_text("setting: default")
+
+        manager = ExtensionManager(project)
+        deployed, skipped = manager.scaffold_config("test-ext")
+
+        assert deployed == ["test-config.yml"]
+        assert skipped == []
+        assert (specify_dir / "test-config.yml").exists()
+        assert (specify_dir / "test-config.yml").read_text() == "setting: default"
+
+    def test_scaffold_config_preserves_existing(self, tmp_path):
+        """Existing config files should never be overwritten."""
+        from specify_cli.extensions import ExtensionManager
+        project = tmp_path / "project"
+        specify_dir = project / ".specify"
+        specify_dir.mkdir(parents=True)
+        (specify_dir / "test-config.yml").write_text("setting: custom")
+        ext_dir = specify_dir / "extensions" / "test-ext"
+        self._make_extension(ext_dir, config_entries=[{
+            "name": "test-config.yml",
+            "template": "config-template.yml",
+            "description": "Test config",
+            "required": True,
+        }])
+        (ext_dir / "config-template.yml").write_text("setting: default")
+
+        manager = ExtensionManager(project)
+        deployed, skipped = manager.scaffold_config("test-ext")
+
+        assert deployed == []
+        assert skipped == ["test-config.yml"]
+        assert (specify_dir / "test-config.yml").read_text() == "setting: custom"
+
+    def test_scaffold_config_no_config_section(self, tmp_path):
+        """Extensions without config section should return empty list."""
+        from specify_cli.extensions import ExtensionManager
+        project = tmp_path / "project"
+        specify_dir = project / ".specify"
+        specify_dir.mkdir(parents=True)
+        ext_dir = specify_dir / "extensions" / "test-ext"
+        self._make_extension(ext_dir)
+
+        manager = ExtensionManager(project)
+        deployed, skipped = manager.scaffold_config("test-ext")
+
+        assert deployed == []
+        assert skipped == []
+
+    def test_scaffold_config_missing_template_file(self, tmp_path):
+        """Missing template file should be silently skipped."""
+        from specify_cli.extensions import ExtensionManager
+        project = tmp_path / "project"
+        specify_dir = project / ".specify"
+        specify_dir.mkdir(parents=True)
+        ext_dir = specify_dir / "extensions" / "test-ext"
+        self._make_extension(ext_dir, config_entries=[{
+            "name": "test-config.yml",
+            "template": "nonexistent.yml",
+            "description": "Test config",
+        }])
+
+        manager = ExtensionManager(project)
+        deployed, skipped = manager.scaffold_config("test-ext")
+
+        assert deployed == []
+        assert skipped == []
+
+    def test_scaffold_config_rejects_path_traversal(self, tmp_path):
+        """Config names with path traversal should be rejected."""
+        from specify_cli.extensions import ExtensionManager
+        project = tmp_path / "project"
+        specify_dir = project / ".specify"
+        specify_dir.mkdir(parents=True)
+        ext_dir = specify_dir / "extensions" / "test-ext"
+        self._make_extension(ext_dir, config_entries=[
+            {"name": "../etc/passwd", "template": "config.yml"},
+            {"name": "safe.yml", "template": "../../secrets.yml"},
+            {"name": "/absolute/path.yml", "template": "config.yml"},
+        ])
+        (ext_dir / "config.yml").write_text("safe: true")
+
+        manager = ExtensionManager(project)
+        deployed, skipped = manager.scaffold_config("test-ext")
+
+        assert deployed == []
+        assert skipped == []
+
+    def test_scaffold_config_rejects_directory_template(self, tmp_path):
+        """Directory templates should be rejected (must be regular files)."""
+        from specify_cli.extensions import ExtensionManager
+        project = tmp_path / "project"
+        specify_dir = project / ".specify"
+        specify_dir.mkdir(parents=True)
+        ext_dir = specify_dir / "extensions" / "test-ext"
+        self._make_extension(ext_dir, config_entries=[{
+            "name": "test-config.yml",
+            "template": "config-dir",
+        }])
+        (ext_dir / "config-dir").mkdir()
+
+        manager = ExtensionManager(project)
+        deployed, skipped = manager.scaffold_config("test-ext")
+
+        assert deployed == []
+
+    def test_scaffold_config_malformed_manifest(self, tmp_path):
+        """Malformed config sections should not crash."""
+        from specify_cli.extensions import ExtensionManifest
+        import yaml
+        project = tmp_path / "project"
+        specify_dir = project / ".specify"
+        specify_dir.mkdir(parents=True)
+        ext_dir = specify_dir / "extensions" / "test-ext"
+        ext_dir.mkdir(parents=True)
+        manifest_data = {
+            "id": "test-ext",
+            "name": "Test Extension",
+            "version": "1.0.0",
+            "provides": {"config": "not-a-list"},
+        }
+        (ext_dir / "extension.yml").write_text(yaml.dump(manifest_data))
+        manifest = ExtensionManifest(ext_dir / "extension.yml")
+        assert manifest.config == []
+
+
 # ===== CommandRegistrar Tests =====
 
 class TestCommandRegistrar: