fix: team-ai-directives reference mode registration in extension registry

Author: kanfil

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to the Specify CLI and templates are documented here.
 
+# [0.8.12+adlc18] - 2026-05-23
+
+### Fixed
+
+- **team-ai-directives reference mode**: Extension is now properly registered in `.specify/extensions/.registry` when using `--team-ai-directives` with a local directory path. Previously, the extension was not registered, causing `specify extension list` and `specify extension remove` to not recognize it, and hooks/commands were not registered with AI agents.
+
 # [0.8.12+adlc17] - 2026-05-22
 
 ### Added

FORK.md

@@ -39,6 +39,7 @@ Use `agentic-sdlc-v<version>` with plus:
 
 | Version | Date | Base Upstream | Changes |
 |---------|------|---------------|---------|
+| 0.8.12+adlc18 | 2026-05-23 | 0.8.12 | Fix team-ai-directives reference mode registration in extension registry |
 | 0.8.12+adlc17 | 2026-05-22 | 0.8.12 | LevelUp extension v1.6.0: Repair command for CDR.md, .skills.json, and AGENTS.md reindexing |
 | 0.8.12+adlc16 | 2026-05-20 | 0.8.12 | Architect extension v2.1.0: Technology neutrality in Functional View, Functional-Development view parity, analyze Pass E.6/E.7 |
 | 0.8.12+adlc14 | 2026-05-19 | 0.8.12 | Product extension v1.5.6: In-section diagrams, remove Visual Summary, sections renumbered 1-12, delete visual templates, no .specify/product/visuals/ |

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentic-sdlc-specify-cli"
-version = "0.8.12+adlc17"
+version = "0.8.12+adlc18"
 description = "Specify CLI (tikalk fork). Agentic SDLC toolkit for Spec-Driven Development with pre-installed extensions and AI integrations."
 requires-python = ">=3.11"
 dependencies = [

src/specify_cli/cli_customization.py

@@ -799,13 +799,18 @@ def sync_team_ai_directives(
             )
 
         if not install:
-            # Reference mode: use directory in-place without copying
-            manifest = ExtensionManifest(manifest_path)
-            if manifest.id != TEAM_DIRECTIVES_DIRNAME:
-                raise ValueError(
-                    f"Extension ID mismatch: expected '{TEAM_DIRECTIVES_DIRNAME}', "
-                    f"got '{manifest.id}'"
-                )
+            # Reference mode: register extension without copying
+            ext_manager = ExtensionManager(project_root)
+            speckit_version = get_speckit_version()
+
+            # Force override: remove existing registration before re-registering
+            if force and ext_manager.registry.is_installed(TEAM_DIRECTIVES_DIRNAME):
+                ext_manager.remove(TEAM_DIRECTIVES_DIRNAME)
+
+            manifest = ext_manager.register_reference_extension(
+                potential_path, speckit_version, priority=1
+            )
+            _store_extension_source_url(project_root, manifest.id, str(potential_path.resolve()))
             return ("reference", potential_path)
 
         # Install mode: copy to .specify/extensions/

src/specify_cli/extensions.py

@@ -1244,6 +1244,78 @@ def install_from_directory(
 
         return manifest
 
+    def register_reference_extension(
+        self,
+        source_dir: Path,
+        speckit_version: str,
+        register_commands: bool = True,
+        priority: int = 10,
+    ) -> ExtensionManifest:
+        """Register an extension from a local directory without copying it.
+
+        Similar to install_from_directory() but:
+        - Does NOT copy files to .specify/extensions/
+        - Stores absolute path in registry for resolution
+        - Still registers commands, hooks, and skills
+
+        Args:
+            source_dir: Path to extension directory
+            speckit_version: Current spec-kit version
+            register_commands: If True, register commands with AI agents
+            priority: Resolution priority (lower = higher precedence, default 10)
+
+        Returns:
+            Registered extension manifest
+
+        Raises:
+            ValidationError: If manifest is invalid or priority is invalid
+            CompatibilityError: If extension is incompatible
+            ExtensionError: If extension is already installed
+        """
+        if priority < 1:
+            raise ValidationError("Priority must be a positive integer (1 or higher)")
+
+        manifest_path = source_dir / "extension.yml"
+        manifest = ExtensionManifest(manifest_path)
+
+        self.check_compatibility(manifest, speckit_version)
+
+        if self.registry.is_installed(manifest.id):
+            raise ExtensionError(
+                f"Extension '{manifest.id}' is already installed. "
+                f"Use 'specify extension remove {manifest.id}' first."
+            )
+
+        self._validate_install_conflicts(manifest)
+
+        registered_commands = {}
+        if register_commands:
+            registrar = CommandRegistrar()
+            registered_commands = registrar.register_commands_for_all_agents(
+                manifest, source_dir, self.project_root
+            )
+
+        registered_skills = self._register_extension_skills(manifest, source_dir)
+
+        hook_executor = HookExecutor(self.project_root)
+        hook_executor.register_hooks(manifest)
+
+        self.registry.add(
+            manifest.id,
+            {
+                "version": manifest.version,
+                "source": "reference",
+                "path": str(source_dir.resolve()),
+                "manifest_hash": manifest.get_hash(),
+                "enabled": True,
+                "priority": priority,
+                "registered_commands": registered_commands,
+                "registered_skills": registered_skills,
+            },
+        )
+
+        return manifest
+
     def install_from_zip(
         self,
         zip_path: Path,
@@ -1331,6 +1403,8 @@ def remove(self, extension_id: str, keep_config: bool = False) -> bool:
         else:
             registered_skills = []
 
+        # Check if this is a reference extension (no directory to delete)
+        is_reference = metadata and metadata.get("source") == "reference"
         extension_dir = self.extensions_dir / extension_id
 
         # Unregister commands from all AI agents
@@ -1341,39 +1415,41 @@ def remove(self, extension_id: str, keep_config: bool = False) -> bool:
         # Unregister agent skills
         self._unregister_extension_skills(registered_skills, extension_id)
 
-        if keep_config:
-            # Preserve config files, only remove non-config files
-            if extension_dir.exists():
-                for child in extension_dir.iterdir():
-                    # Keep top-level *-config.yml and *-config.local.yml files
-                    if child.is_file() and (
-                        child.name.endswith("-config.yml")
-                        or child.name.endswith("-config.local.yml")
-                    ):
-                        continue
-                    if child.is_dir():
-                        shutil.rmtree(child)
-                    else:
-                        child.unlink()
-        else:
-            # Backup config files before deleting
-            if extension_dir.exists():
-                # Use subdirectory per extension to avoid name accumulation
-                # (e.g., jira-jira-config.yml on repeated remove/install cycles)
-                backup_dir = self.extensions_dir / ".backup" / extension_id
-                backup_dir.mkdir(parents=True, exist_ok=True)
-
-                # Backup both primary and local override config files
-                config_files = list(extension_dir.glob("*-config.yml")) + list(
-                    extension_dir.glob("*-config.local.yml")
-                )
-                for config_file in config_files:
-                    backup_path = backup_dir / config_file.name
-                    shutil.copy2(config_file, backup_path)
+        # Only remove directory for non-reference extensions
+        if not is_reference:
+            if keep_config:
+                # Preserve config files, only remove non-config files
+                if extension_dir.exists():
+                    for child in extension_dir.iterdir():
+                        # Keep top-level *-config.yml and *-config.local.yml files
+                        if child.is_file() and (
+                            child.name.endswith("-config.yml")
+                            or child.name.endswith("-config.local.yml")
+                        ):
+                            continue
+                        if child.is_dir():
+                            shutil.rmtree(child)
+                        else:
+                            child.unlink()
+            else:
+                # Backup config files before deleting
+                if extension_dir.exists():
+                    # Use subdirectory per extension to avoid name accumulation
+                    # (e.g., jira-jira-config.yml on repeated remove/install cycles)
+                    backup_dir = self.extensions_dir / ".backup" / extension_id
+                    backup_dir.mkdir(parents=True, exist_ok=True)
+
+                    # Backup both primary and local override config files
+                    config_files = list(extension_dir.glob("*-config.yml")) + list(
+                        extension_dir.glob("*-config.local.yml")
+                    )
+                    for config_file in config_files:
+                        backup_path = backup_dir / config_file.name
+                        shutil.copy2(config_file, backup_path)
 
-            # Remove extension directory
-            if extension_dir.exists():
-                shutil.rmtree(extension_dir)
+                # Remove extension directory
+                if extension_dir.exists():
+                    shutil.rmtree(extension_dir)
 
         # Unregister hooks
         hook_executor = HookExecutor(self.project_root)
@@ -1546,8 +1622,13 @@ def list_installed(self) -> List[Dict[str, Any]]:
             # Ensure metadata is a dictionary to avoid AttributeError when using .get()
             if not isinstance(metadata, dict):
                 metadata = {}
-            ext_dir = self.extensions_dir / ext_id
-            manifest_path = ext_dir / "extension.yml"
+
+            # For reference extensions, use the stored path; otherwise use standard location
+            if metadata.get("source") == "reference" and metadata.get("path"):
+                manifest_path = Path(metadata["path"]) / "extension.yml"
+            else:
+                ext_dir = self.extensions_dir / ext_id
+                manifest_path = ext_dir / "extension.yml"
 
             try:
                 manifest = ExtensionManifest(manifest_path)
@@ -1594,8 +1675,14 @@ def get_extension(self, extension_id: str) -> Optional[ExtensionManifest]:
         if not self.registry.is_installed(extension_id):
             return None
 
-        ext_dir = self.extensions_dir / extension_id
-        manifest_path = ext_dir / "extension.yml"
+        metadata = self.registry.get(extension_id)
+
+        # For reference extensions, use the stored path; otherwise use standard location
+        if metadata and metadata.get("source") == "reference" and metadata.get("path"):
+            manifest_path = Path(metadata["path"]) / "extension.yml"
+        else:
+            ext_dir = self.extensions_dir / extension_id
+            manifest_path = ext_dir / "extension.yml"
 
         try:
             return ExtensionManifest(manifest_path)