feat: add reference mode for local team-ai-directives directories

Author: kanfil

CHANGELOG.md

@@ -6,6 +6,14 @@ All notable changes to the Specify CLI and templates are documented here.
 
 # [0.5.10] - 2026-04-20
 
+### Added
+
+- **team-ai-directives reference mode**: Local directories are now used in-place without copying
+  - When `--team-ai-directives` points to a local directory, it's used directly (reference mode)
+  - When `--team-ai-directives` is a ZIP URL, it's downloaded and installed to `.specify/extensions/`
+  - Added `get_team_directives_path()` helper to resolve path from init-options or extensions dir
+  - Added `install` parameter to `sync_team_ai_directives()` for explicit control
+
 ### Fixed
 
 - **team-ai-directives duplicate installation**: Removed duplicate `sync_team_ai_directives()` call

src/specify_cli/__init__.py

@@ -242,9 +242,20 @@ def _derive_target_repo_from_url(zip_url: str) -> str:
 
 
 def sync_team_ai_directives(
-    repo_url: str, project_root: Path, *, skip_tls: bool = False
+    repo_url: str, project_root: Path, *, install: bool = True, skip_tls: bool = False
 ) -> tuple[str, Path]:
-    """Install team-ai-directives as extension from ZIP URL or local path."""
+    """Install team-ai-directives as extension from ZIP URL or local path.
+
+    Args:
+        repo_url: URL or local path to team-ai-directives
+        project_root: Project root directory
+        install: If True, copy local directories to .specify/extensions/.
+                 If False, use local directories in-place (reference mode).
+        skip_tls: Skip TLS verification (for HTTPS URLs)
+
+    Returns:
+        Tuple of (status, path) where status is "installed", "local", or "reference"
+    """
     from .extensions import ExtensionManager, ExtensionManifest  # noqa: F401
 
     repo_url = (repo_url or "").strip()
@@ -254,6 +265,25 @@ def sync_team_ai_directives(
     potential_path = Path(repo_url).expanduser()
 
     if potential_path.exists() and potential_path.is_dir():
+        # Validate it's a proper extension
+        manifest_path = potential_path / "extension.yml"
+        if not manifest_path.exists():
+            raise ValueError(
+                f"Invalid team-ai-directives directory: {potential_path}\n"
+                f"Missing extension.yml manifest file"
+            )
+
+        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}'"
+                )
+            return ("reference", potential_path)
+
+        # Install mode: copy to .specify/extensions/
         ext_manager = ExtensionManager(project_root)
         speckit_version = get_speckit_version()
         manifest = ext_manager.install_from_directory(
@@ -1199,6 +1229,24 @@ def load_init_options(project_path: Path) -> dict[str, Any]:
         return {}
 
 
+def get_team_directives_path(project_path: Path) -> Path | None:
+    """Get team-ai-directives path from init-options or fallback to extensions dir.
+
+    Checks init-options.json first for external/override path, then falls back
+    to the standard .specify/extensions/team-ai-directives location.
+
+    Returns None if neither location exists.
+    """
+    init_opts = load_init_options(project_path)
+    if "team_ai_directives" in init_opts:
+        path = Path(init_opts["team_ai_directives"])
+        if path.exists():
+            return path
+    # Fallback to installed extension
+    fallback = project_path / ".specify" / "extensions" / TEAM_DIRECTIVES_DIRNAME
+    return fallback if fallback.exists() else None
+
+
 def _get_skills_dir(project_path: Path, selected_ai: str) -> Path:
     """Resolve the agent-specific skills directory.
 

src/specify_cli/cli_customization.py

@@ -326,13 +326,25 @@ def pre_init(
     tracker.start("team-directives")
     directives_path = None
     try:
-        status, directives_path = sync_team_ai_directives(
-            team_ai_directives, project_path
-        )
-        if status == "installed":
-            tracker.complete("team-directives", f"installed to {directives_path}")
-        elif status == "local":
-            tracker.complete("team-directives", f"local: {directives_path}")
+        # Determine if this is a local directory (use reference mode) or URL (install)
+        potential_path = Path(team_ai_directives).expanduser()
+        is_local_dir = potential_path.exists() and potential_path.is_dir()
+
+        if is_local_dir:
+            # Local directory: use reference mode (no copy)
+            status, directives_path = sync_team_ai_directives(
+                team_ai_directives, project_path, install=False
+            )
+            tracker.complete("team-directives", f"referenced: {directives_path}")
+        else:
+            # ZIP URL: install to .specify/extensions/
+            status, directives_path = sync_team_ai_directives(
+                team_ai_directives, project_path, install=True
+            )
+            if status == "installed":
+                tracker.complete("team-directives", f"installed to {directives_path}")
+            elif status == "local":
+                tracker.complete("team-directives", f"local: {directives_path}")
         os.environ["SPECIFY_TEAM_DIRECTIVES"] = str(directives_path)
     except Exception as e:
         tracker.error("team-directives", str(e))
@@ -927,24 +939,21 @@ def skill_install(
     # Check for team manifest and blocked skills enforcement
     team_manifest = None
     if not skip_blocked_check:
-        ext_path = project_path / ".specify" / "extensions" / "team-ai-directives"
-        if ext_path.exists():
-            team_directives_path = str(ext_path)
+        from . import get_team_directives_path
 
+        team_directives_path = get_team_directives_path(project_path)
         if team_directives_path:
-            team_directives = Path(team_directives_path)
-            if team_directives.exists():
-                team_manifest = TeamSkillsManifest(team_directives)
-                if team_manifest.exists() and team_manifest.should_enforce_blocked():
-                    blocked = team_manifest.get_blocked_skills()
-                    for blocked_skill in blocked:
-                        if blocked_skill in skill_ref or skill_ref in blocked_skill:
-                            console.print(
-                                f"[red]✗ Skill blocked by team policy:[/red] {skill_ref}\n"
-                                f"  Blocked pattern: {blocked_skill}\n"
-                                f"  Use --skip-blocked-check to override (not recommended)"
-                            )
-                            raise typer.Exit(1)
+            team_manifest = TeamSkillsManifest(team_directives_path)
+            if team_manifest.exists() and team_manifest.should_enforce_blocked():
+                blocked = team_manifest.get_blocked_skills()
+                for blocked_skill in blocked:
+                    if blocked_skill in skill_ref or skill_ref in blocked_skill:
+                        console.print(
+                            f"[red]✗ Skill blocked by team policy:[/red] {skill_ref}\n"
+                            f"  Blocked pattern: {blocked_skill}\n"
+                            f"  Use --skip-blocked-check to override (not recommended)"
+                        )
+                        raise typer.Exit(1)
 
     installer = SkillInstaller(manifest, team_manifest)
 
@@ -1227,8 +1236,9 @@ def skill_sync_team(
 
     project_path = Path.cwd()
 
-    ext_path = project_path / ".specify" / "extensions" / "team-ai-directives"
-    team_directives_path = str(ext_path) if ext_path.exists() else None
+    from . import get_team_directives_path
+
+    team_directives_path = get_team_directives_path(project_path)
 
     if not team_directives_path:
         console.print(
@@ -1237,7 +1247,7 @@ def skill_sync_team(
         )
         return
 
-    team_directives = Path(team_directives_path)
+    team_directives = team_directives_path
     if not team_directives.exists():
         console.print(f"[red]Team directives not found:[/red] {team_directives}")
         return