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

When an extension is installed via `extension add` or re-enabled via
`extension enable`, automatically deploy config templates from the
extension's `provides.config` section to the project's `.specify/`
directory. Existing config files are preserved (never overwritten).

This replaces the previous "Configuration may be required" warning
with automatic scaffolding, per maintainer feedback on PR #1929.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: mvanhorn

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 = 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}")
+        elif manifest.config:
+            console.print("\n[dim]Config files already exist (preserved).[/dim]")
 
     except ValidationError as e:
         console.print(f"\n[red]Validation Error:[/red] {e}")
@@ -4470,6 +4476,13 @@ def extension_enable(
 
     console.print(f"[green]✓[/green] Extension '{display_name}' enabled")
 
+    # Scaffold config templates on enable
+    deployed = 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}")
+
 
 @extension_app.command("disable")
 def extension_disable(

src/specify_cli/extensions.py

@@ -233,6 +233,11 @@ 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."""
+        return self.data.get("provides", {}).get("config", [])
+
     def get_hash(self) -> str:
         """Calculate SHA256 hash of manifest file."""
         with open(self.path, 'rb') as f:
@@ -1125,6 +1130,48 @@ 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) -> List[str]:
+        """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:
+            List of deployed config file names (empty if all already existed)
+        """
+        ext_dir = self.extensions_dir / extension_id
+        manifest_path = ext_dir / "extension.yml"
+        if not manifest_path.exists():
+            return []
+
+        manifest = ExtensionManifest(manifest_path)
+        deployed = []
+
+        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
+
+            template_path = ext_dir / template_name
+            if not template_path.exists():
+                continue
+
+            target_path = self.project_root / ".specify" / target_name
+            if target_path.exists():
+                # Never overwrite user-customized config
+                continue
+
+            target_path.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(template_path, target_path)
+            deployed.append(target_name)
+
+        return deployed
+
     def remove(self, extension_id: str, keep_config: bool = False) -> bool:
         """Remove an installed extension.
 

tests/test_extensions.py

@@ -832,6 +832,120 @@ 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 = manager.scaffold_config("test-ext")
+
+        assert deployed == ["test-config.yml"]
+        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 = manager.scaffold_config("test-ext")
+
+        assert deployed == []
+        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 = manager.scaffold_config("test-ext")
+
+        assert deployed == []
+
+    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 = manager.scaffold_config("test-ext")
+
+        assert deployed == []
+
+
 # ===== CommandRegistrar Tests =====
 
 class TestCommandRegistrar: