thothctl 0.30.3__tar.gz → 0.31.0__tar.gz

{thothctl-0.30.3 → thothctl-0.31.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: thothctl
-Version: 0.30.3
+Version: 0.31.0
 Summary: A CLI for Developer Control Plane. Accelerate your cloud IaC deployments.
 Project-URL: SourceCode, https://github.com/thothforge/thothctl
 Project-URL: HomePage, https://github.com/thothforge/thothctl

{thothctl-0.30.3 → thothctl-0.31.0}/src/thothctl/commands/init/commands/env.py

@@ -30,17 +30,24 @@ class EnvInitCommand(ClickCommand):
         operation_system: str,
         project_type: Optional[str] = None,
         with_aidlc: bool = False,
+        with_skills: Optional[str] = "all",
         **kwargs,
     ) -> None:
         """Execute environment initialization."""
         if project_type:
-            self._init_env_with_pack(operation_system, project_type, with_aidlc)
+            self._init_env_with_pack(
+                operation_system, project_type, with_aidlc, with_skills
+            )
         else:
             # Legacy behavior: show all tools for manual selection
             bootstrap_env(so=operation_system)
 
     def _init_env_with_pack(
-        self, operation_system: str, project_type: str, with_aidlc: bool = False
+        self,
+        operation_system: str,
+        project_type: str,
+        with_aidlc: bool = False,
+        with_skills: Optional[str] = "all",
     ) -> None:
         """Initialize environment using project-type tool pack."""
         from colorama import Fore
@@ -162,6 +169,36 @@ class EnvInitCommand(ClickCommand):
         # AI-DLC workflow rules (optional)
         self._handle_aidlc_installation(console, project_type, with_aidlc)
 
+        # AI agent skills (dynamic install from upstream repos)
+        self._handle_skills_installation(console, with_skills)
+
+    def _handle_skills_installation(self, console, with_skills: Optional[str]) -> None:
+        """Dynamically install AI agent skills into ./.kiro/skills/.
+
+        Skills require Kiro, so only install when a .kiro/ directory exists in the
+        current working directory.
+        """
+        from ....services.init.environment.install_skills import (
+            install_skills,
+            resolve_requested_skills,
+        )
+
+        names = resolve_requested_skills(with_skills or "")
+        if not names:
+            return
+
+        kiro_dir = Path.cwd() / ".kiro"
+        if not kiro_dir.exists():
+            console.print(
+                "[yellow]⏭️  Skipping skill install — no .kiro/ in current "
+                "directory (skills require Kiro).[/yellow]"
+            )
+            return
+
+        console.print()
+        console.print(f"[bold]🧠 Installing skill(s): {', '.join(names)}[/bold]")
+        install_skills(names, target_dir=str(Path.cwd()))
+
     def _handle_aidlc_installation(
         self, console, project_type: str, with_aidlc: bool
     ) -> None:
@@ -268,4 +305,12 @@ cli = EnvInitCommand.as_click_command(
         help="Install AI-DLC workflow rules for Kiro (.kiro/steering/). "
         "Non-interactive; in interactive mode, you'll be prompted.",
     ),
+    click.option(
+        "--with-skills",
+        default="all",
+        help="Dynamically install AI agent skills from their upstream repos into "
+        "./.kiro/skills/ (requires a .kiro/ directory). Defaults to 'all' "
+        "distributable skills. Use a comma-separated list (e.g. 'devsecops') to "
+        "select, or 'none' to opt out.",
+    ),
 )

{thothctl-0.30.3 → thothctl-0.31.0}/src/thothctl/commands/init/commands/project.py

@@ -93,6 +93,7 @@ class ProjectInitCommand(ClickCommand):
         language: str = None,
         ai_tools: Optional[str] = None,
         with_aidlc: bool = False,
+        with_skills: Optional[str] = "all",
         **kwargs,
     ) -> None:
         """Execute project initialization"""
@@ -213,6 +214,23 @@ class ProjectInitCommand(ClickCommand):
 
             install_aidlc_rules(target_dir=str(project_path))
 
+        # Dynamically install AI agent skills from their upstream repos.
+        # Skills live under .kiro/skills/, so only install when Kiro is kept.
+        if with_skills and (project_path / ".kiro").exists():
+            from ....services.init.environment.install_skills import (
+                install_skills,
+                resolve_requested_skills,
+            )
+
+            names = resolve_requested_skills(with_skills)
+            if names:
+                self.ui.print_info(f"🧠 Installing skill(s): {', '.join(names)}")
+                install_skills(names, target_dir=str(project_path))
+        elif with_skills:
+            self.ui.print_warning(
+                "Skipping skill install — .kiro/ was not kept (requires Kiro)."
+            )
+
         self.ui.print_success(f"✨ Project '{project_name}' initialized successfully!")
 
     def _select_template(
@@ -710,4 +728,13 @@ cli = ProjectInitCommand.as_click_command(help="Initialize a new project")(
         help="Install AI-DLC workflow rules for Kiro (.kiro/steering/). "
         "Provides structured requirement → design → implementation workflows.",
     ),
+    click.option(
+        "--with-skills",
+        default="all",
+        help="Dynamically install AI agent skills from their upstream repos into "
+        ".kiro/skills/ (keeps canonical skills in sync, avoids scaffold drift). "
+        "Defaults to 'all' distributable skills. Use a comma-separated list "
+        "(e.g. 'devsecops') to select, or 'none' to opt out. Only skills with an "
+        "upstream repo are installable; scaffold-bundled skills are left untouched.",
+    ),
 )

{thothctl-0.30.3 → thothctl-0.31.0}/src/thothctl/common/.thothcf_module.toml

@@ -33,7 +33,8 @@ name = "catalog"
 mandatory = false
 content = [
     "catalog-info.yaml",
-    "mkdocs.yaml"
+    "mkdocs.yaml",
+    "zensical.toml"
 ]
 type= "child"
 [[project_structure.folders]]

{thothctl-0.30.3 → thothctl-0.31.0}/src/thothctl/services/document/iac_grunt_graph.py

@@ -431,16 +431,23 @@ class DependencyGraphGenerator:
     def _generate_graph(self, directory: Path) -> Optional[str]:
         """Generate graph using terragrunt.
 
-        Runs `terragrunt dag graph` from the resolved directory:
-        - For a leaf stack: runs from the stack itself, showing only its
-          direct dependencies (scoped relative graph).
-        - For a stacks root: runs from the root, showing the full DAG.
+        To show the COMPLETE dependency DAG (full blast radius) for the stack
+        being documented, `terragrunt dag graph` is run from the terragrunt
+        project root (where ``root.hcl`` lives). Running from a leaf only
+        reports that unit's *direct* dependencies, which hides transitive
+        dependencies (dependencies-of-dependencies).
+
+        The full-project DAG from the root is then filtered down to only the
+        nodes reachable from the current stack (its transitive dependency
+        closure), so each stack's graph shows its complete hierarchy without
+        unrelated sibling stacks.
         """
-        graph_dir = self._resolve_graph_directory(directory)
+        resolved = directory.resolve()
+        run_dir, stack_key = self._compute_run_context(resolved)
 
         command = ["terragrunt", "dag", "graph", "--non-interactive"]
 
-        stdout, stderr, return_code = self.executor.execute(command, graph_dir)
+        stdout, stderr, return_code = self.executor.execute(command, run_dir)
 
         if return_code != 0:
             self.logger.error("Terragrunt command failed: %s", stderr)
@@ -454,8 +461,26 @@ class DependencyGraphGenerator:
             )
             return None
 
+        # If we ran from the terragrunt root for a specific stack, filter the
+        # full DAG down to that stack's transitive dependency closure.
+        if stack_key is not None:
+            filtered = self._filter_dag_to_stack(stdout, stack_key)
+            if filtered is None:
+                # Stack not found in DAG or has no dependencies — nothing to render
+                self.logger.debug(
+                    "Stack %s not found in DAG or has no dependencies", stack_key
+                )
+                return None
+            stdout = filtered
+            # Re-check for emptiness after filtering (isolated stack)
+            if "->" not in stdout.strip():
+                self.logger.debug(
+                    "Isolated stack %s (no dependencies), skipping graph", stack_key
+                )
+                return None
+
         # Also skip if the only node is "." with no edges (isolated stack)
-        if '"."' in stripped and "->" not in stripped:
+        if '"."' in stdout.strip() and "->" not in stdout.strip():
             self.logger.debug(
                 "Isolated stack %s (no dependencies), skipping graph", directory
             )
@@ -516,6 +541,113 @@ class DependencyGraphGenerator:
             current = parent
         return directory
 
+    def _compute_run_context(self, directory: Path):
+        """Decide where to run `terragrunt dag graph` and which node to focus.
+
+        Returns a tuple ``(run_dir, stack_key)``:
+        - ``run_dir``: directory to run ``terragrunt dag graph`` from.
+        - ``stack_key``: the current stack's node key as it appears in the DAG
+          produced from ``run_dir`` (i.e. the stack path relative to the
+          terragrunt root), or ``None`` when ``directory`` is itself a
+          stacks root and the full DAG should be rendered as-is.
+
+        For a leaf stack we run from the terragrunt root so the DAG includes
+        transitive dependencies, then filter to this stack's closure.
+        """
+        resolved = directory.resolve()
+
+        # Is this directory itself a stacks root (has multiple child units)?
+        child_hcl_files = [
+            f
+            for f in resolved.rglob("terragrunt.hcl")
+            if ".terragrunt-cache" not in str(f) and f.parent != resolved
+        ]
+        if len(child_hcl_files) > 1:
+            # Already a root/aggregate context — render the full DAG as-is.
+            return resolved, None
+
+        # Leaf stack: run from the terragrunt root for the complete DAG.
+        root = self._find_terragrunt_root(resolved)
+        if root == resolved:
+            # No root.hcl found above — fall back to running from the leaf.
+            return resolved, None
+
+        try:
+            stack_key = str(resolved.relative_to(root))
+        except ValueError:
+            # resolved is not under root — fall back to leaf behavior.
+            return resolved, None
+
+        return root, stack_key
+
+    def _filter_dag_to_stack(self, dot_content: str, stack_key: str):
+        """Filter a full-project DAG to a stack's transitive dependency closure.
+
+        Parses the DOT graph, performs a DFS from ``stack_key`` following
+        dependency edges, and emits a new DOT containing only the reachable
+        nodes/edges. The focal stack's node is relabeled to ``"."`` so the
+        downstream path-simplification (which maps ``"."`` to the stack name)
+        continues to work.
+
+        Returns the filtered DOT string, or ``None`` if the stack has no
+        node in the graph or no dependency edges.
+        """
+        import re
+
+        # Normalize key (strip any trailing slash)
+        stack_key = stack_key.rstrip("/")
+
+        # Parse edges: source -> target
+        adjacency = {}
+        all_nodes = set()
+        edge_re = re.compile(r'"([^"]+)"\s*->\s*"([^"]+)"')
+        node_re = re.compile(r'^\s*"([^"]+)"\s*;')
+        for line in dot_content.split("\n"):
+            m = edge_re.search(line)
+            if m:
+                src, dst = m.group(1), m.group(2)
+                adjacency.setdefault(src, set()).add(dst)
+                all_nodes.add(src)
+                all_nodes.add(dst)
+                continue
+            nm = node_re.match(line)
+            if nm:
+                all_nodes.add(nm.group(1))
+
+        if stack_key not in all_nodes:
+            return None
+
+        # DFS from the stack following dependency edges (transitive closure).
+        reachable = set()
+        stack = [stack_key]
+        while stack:
+            node = stack.pop()
+            if node in reachable:
+                continue
+            reachable.add(node)
+            for nxt in adjacency.get(node, ()):  # dependencies of node
+                if nxt not in reachable:
+                    stack.append(nxt)
+
+        # If the stack has no outgoing dependency edges, there is nothing
+        # meaningful to render.
+        if not adjacency.get(stack_key):
+            return None
+
+        def relabel(node: str) -> str:
+            return "." if node == stack_key else node
+
+        # Rebuild DOT with only reachable nodes/edges.
+        lines = ["digraph {"]
+        for node in sorted(reachable):
+            lines.append(f'\t"{relabel(node)}" ;')
+        for src in sorted(reachable):
+            for dst in sorted(adjacency.get(src, ())):
+                if dst in reachable:
+                    lines.append(f'\t"{relabel(src)}" -> "{relabel(dst)}";')
+        lines.append("}")
+        return "\n".join(lines)
+
     def _parse_terragrunt_hcl(self, hcl_path: Path) -> dict:
         """Parse a terragrunt.hcl file to extract dependency information."""
         import hcl2

{thothctl-0.30.3 → thothctl-0.31.0}/src/thothctl/services/generate/create_template/project_templates.py

@@ -29,6 +29,7 @@ terraform_template = [
                         "name": "catalog",
                         "contents": [
                             {"type": "file", "name": "mkdocs.yaml"},
+                            {"type": "file", "name": "zensical.toml"},
                             {"type": "file", "name": "catalog-info.yaml"},
                             {
                                 "type": "directory",
@@ -126,6 +127,7 @@ terragrunt_template = [
                         "name": "catalog",
                         "contents": [
                             {"type": "file", "name": "mkdocs.yaml"},
+                            {"type": "file", "name": "zensical.toml"},
                             {"type": "file", "name": "catalog-info.yaml"},
                             {
                                 "type": "directory",
@@ -213,6 +215,7 @@ terraform_module_template = [
                         "name": "catalog",
                         "contents": [
                             {"type": "file", "name": "mkdocs.yaml"},
+                            {"type": "file", "name": "zensical.toml"},
                             {"type": "file", "name": "catalog-info.yaml"},
                             {
                                 "type": "directory",

thothctl-0.31.0/src/thothctl/services/init/environment/install_skills.py

@@ -0,0 +1,212 @@
+"""Dynamic installation of AI agent skills from upstream Git repositories.
+
+Skills are reusable knowledge packages that live under ``.kiro/skills/<name>/``.
+Historically they were baked into every scaffold template, which caused drift
+between a scaffold's embedded copy and the canonical upstream repository.
+
+This module installs skills *dynamically* at ``init`` time from their upstream
+GitHub repositories (mirroring ``install_aidlc_rules``), so the canonical repo
+is the single source of truth.
+
+Only skills that have a known upstream repository are dynamically installable.
+Skills authored by third parties or carrying scaffold-local modifications
+(e.g. ``terraform-skill``) are intentionally NOT in the registry — they stay
+bundled in the scaffold and are never overwritten by this installer.
+"""
+
+import io
+import shutil
+import tempfile
+import zipfile
+from pathlib import Path
+from typing import Dict, List, Optional
+
+import requests
+from colorama import Fore
+
+# ---------------------------------------------------------------------------
+# Skill registry
+# ---------------------------------------------------------------------------
+# Maps a skill name to its upstream source. Add an entry here when a skill gets
+# a canonical GitHub repository so it can be installed dynamically.
+#
+#   repo       : "owner/name" GitHub repository slug.
+#   ref        : git ref (branch/tag) to download when no release is published.
+#   use_release: if True, prefer the latest GitHub release asset/zipball,
+#                falling back to ``ref`` when there is no release.
+#   subdir     : path *inside* the downloaded archive that contains the skill
+#                payload (SKILL.md + references/). "" means the archive root.
+#
+# NOTE ON INTENTIONAL OMISSIONS:
+#   - terraform-skill        → third-party (Anton Babenko), scaffold-local mods; DO NOT auto-install.
+#   - thothctl-framework     → no upstream repo yet; scaffold-bundled.
+#   - iac-versioning-commits → no upstream repo yet; scaffold-bundled.
+SKILL_REGISTRY: Dict[str, Dict] = {
+    "devsecops": {
+        "repo": "thothforge/thothctl-devsecops-skill",
+        "ref": "main",
+        "use_release": True,
+        "subdir": "",
+    },
+}
+
+
+def available_skills() -> List[str]:
+    """Return the names of skills that can be installed dynamically."""
+    return sorted(SKILL_REGISTRY.keys())
+
+
+def _resolve_zip_url(repo: str, ref: str, use_release: bool) -> Optional[str]:
+    """Resolve a downloadable zip URL for a repo.
+
+    Prefers the latest release when ``use_release`` is set and a release exists;
+    otherwise falls back to the branch/tag zipball.
+    """
+    if use_release:
+        api_url = f"https://api.github.com/repos/{repo}/releases/latest"
+        try:
+            resp = requests.get(api_url, timeout=30)
+            if resp.status_code == 200:
+                data = resp.json()
+                for asset in data.get("assets", []):
+                    if asset.get("name", "").endswith(".zip"):
+                        return asset["browser_download_url"]
+                if data.get("zipball_url"):
+                    return data["zipball_url"]
+        except requests.RequestException:
+            # Fall through to branch zipball.
+            pass
+
+    # Branch/tag zipball (works even without any published release).
+    return f"https://api.github.com/repos/{repo}/zipball/{ref}"
+
+
+def _find_skill_payload(extract_root: Path, subdir: str) -> Optional[Path]:
+    """Locate the directory holding SKILL.md inside an extracted archive.
+
+    GitHub zipballs wrap everything in a single top-level ``<owner>-<repo>-<sha>/``
+    directory, so we search for SKILL.md rather than assuming a fixed depth.
+    """
+    # Enter the single wrapper directory produced by GitHub zipballs, if present.
+    entries = [p for p in extract_root.iterdir() if p.is_dir()]
+    search_root = entries[0] if len(entries) == 1 else extract_root
+
+    if subdir:
+        candidate = search_root / subdir
+        return candidate if (candidate / "SKILL.md").exists() else None
+
+    # subdir == "" → the skill payload is at the archive root.
+    if (search_root / "SKILL.md").exists():
+        return search_root
+
+    # Fallback: first directory that directly contains a SKILL.md.
+    for skill_md in search_root.rglob("SKILL.md"):
+        return skill_md.parent
+    return None
+
+
+def install_skill(skill_name: str, target_dir: str = ".") -> bool:
+    """Install a single skill from its upstream repo into ``.kiro/skills/<name>/``.
+
+    :param skill_name: Registry key (see ``SKILL_REGISTRY``).
+    :param target_dir: Project root directory (where ``.kiro/`` lives).
+    :return: True on success, False otherwise.
+    """
+    entry = SKILL_REGISTRY.get(skill_name)
+    if not entry:
+        print(
+            f"{Fore.YELLOW}⚠️  Skill '{skill_name}' has no upstream repository; "
+            f"skipping dynamic install (it is bundled in the scaffold).{Fore.RESET}"
+        )
+        return False
+
+    repo = entry["repo"]
+    ref = entry.get("ref", "main")
+    use_release = entry.get("use_release", False)
+    subdir = entry.get("subdir", "")
+
+    print(f"{Fore.MAGENTA}Installing skill '{skill_name}' from {repo}...{Fore.RESET}")
+
+    zip_url = _resolve_zip_url(repo, ref, use_release)
+    if not zip_url:
+        print(f"{Fore.RED}❌ Could not resolve a download URL for {repo}{Fore.RESET}")
+        return False
+
+    try:
+        zip_response = requests.get(zip_url, timeout=60, allow_redirects=True)
+        zip_response.raise_for_status()
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            tmp_path = Path(tmpdir)
+            with zipfile.ZipFile(io.BytesIO(zip_response.content)) as zf:
+                zf.extractall(tmp_path)
+
+            payload = _find_skill_payload(tmp_path, subdir)
+            if not payload:
+                print(
+                    f"{Fore.RED}❌ Could not find SKILL.md in {repo} "
+                    f"(subdir='{subdir or '<root>'}'){Fore.RESET}"
+                )
+                return False
+
+            dst = Path(target_dir) / ".kiro" / "skills" / skill_name
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            if dst.exists():
+                shutil.rmtree(dst)
+            # Copy payload contents into .kiro/skills/<skill_name>/
+            shutil.copytree(payload, dst)
+            # Drop any VCS metadata that may have ridden along.
+            for junk in (".git", ".github"):
+                junk_path = dst / junk
+                if junk_path.exists():
+                    shutil.rmtree(junk_path, ignore_errors=True)
+
+        print(
+            f"{Fore.GREEN}  ✅ Installed skill '{skill_name}' → "
+            f".kiro/skills/{skill_name}/{Fore.RESET}"
+        )
+        return True
+
+    except requests.RequestException as e:
+        print(f"{Fore.RED}❌ Failed to download skill '{skill_name}': {e}{Fore.RESET}")
+        return False
+    except (zipfile.BadZipFile, OSError) as e:
+        print(f"{Fore.RED}❌ Failed to extract skill '{skill_name}': {e}{Fore.RESET}")
+        return False
+
+
+def install_skills(skill_names: List[str], target_dir: str = ".") -> Dict[str, bool]:
+    """Install multiple skills. Returns a map of skill_name → success."""
+    results: Dict[str, bool] = {}
+    for name in skill_names:
+        results[name] = install_skill(name, target_dir=target_dir)
+    return results
+
+
+def resolve_requested_skills(requested: str) -> List[str]:
+    """Translate a CLI ``--with-skills`` value into concrete registry names.
+
+    Accepts:
+      - "all"                   → every skill in the registry
+      - "none"/"false"/"off"/"" → nothing (opt-out)
+      - "devsecops,foo"         → comma-separated explicit list
+    Unknown names are warned about and dropped.
+    """
+    if not requested:
+        return []
+    normalized = requested.strip().lower()
+    if normalized in ("none", "false", "off", "no"):
+        return []
+    if normalized == "all":
+        return available_skills()
+
+    names = [n.strip() for n in requested.split(",") if n.strip()]
+    valid, unknown = [], []
+    for n in names:
+        (valid if n in SKILL_REGISTRY else unknown).append(n)
+    if unknown:
+        print(
+            f"{Fore.YELLOW}⚠️  Unknown/undistributable skill(s): {', '.join(unknown)}. "
+            f"Available: {', '.join(available_skills())}{Fore.RESET}"
+        )
+    return valid

{thothctl-0.30.3 → thothctl-0.31.0}/src/thothctl/services/project/convert/get_project_data.py

@@ -40,6 +40,7 @@ def replace_template_placeholders(
         ".terraform.lock.hcl",
         "catalog-info.yaml",
         "mkdocs.yaml",
+        "zensical.toml",
         "pdf",
         "dot",
         "gif",

{thothctl-0.30.3 → thothctl-0.31.0}/src/thothctl/version.py

@@ -1,3 +1,3 @@
 """Version module."""
 
-__version__ = "0.30.3"
+__version__ = "0.31.0"

thothctl-0.31.0/tests/test_install_skills.py

@@ -0,0 +1,110 @@
+"""Tests for dynamic skill installation (install_skills)."""
+
+import io
+import zipfile
+from unittest.mock import MagicMock, patch
+
+from thothctl.services.init.environment import install_skills
+
+
+def _make_github_zipball(files: dict) -> bytes:
+    """Build an in-memory zip that mimics a GitHub zipball.
+
+    GitHub wraps everything under a single top-level ``<owner>-<repo>-<sha>/``
+    directory. ``files`` maps archive-relative paths (under that wrapper) to
+    their text content.
+    """
+    buf = io.BytesIO()
+    wrapper = "thothforge-thothctl-devsecops-skill-abc1234"
+    with zipfile.ZipFile(buf, "w") as zf:
+        for rel, content in files.items():
+            zf.writestr(f"{wrapper}/{rel}", content)
+    return buf.getvalue()
+
+
+def test_resolve_requested_skills_all():
+    assert install_skills.resolve_requested_skills("all") == install_skills.available_skills()
+
+
+def test_resolve_requested_skills_explicit_and_unknown():
+    # Known skill kept, unknown dropped.
+    result = install_skills.resolve_requested_skills("devsecops,does-not-exist")
+    assert result == ["devsecops"]
+
+
+def test_resolve_requested_skills_empty():
+    assert install_skills.resolve_requested_skills("") == []
+    assert install_skills.resolve_requested_skills(None) == []
+
+
+def test_resolve_requested_skills_optout_keywords():
+    for word in ("none", "None", "NONE", "false", "off", "no"):
+        assert install_skills.resolve_requested_skills(word) == [], word
+
+
+def test_install_skill_unknown_returns_false(tmp_path):
+    assert install_skills.install_skill("terraform-skill", target_dir=str(tmp_path)) is False
+    # Nothing should have been written.
+    assert not (tmp_path / ".kiro").exists()
+
+
+def test_install_skill_devsecops_from_zipball(tmp_path):
+    """install_skill downloads, finds SKILL.md, and copies into .kiro/skills/<name>/."""
+    zip_bytes = _make_github_zipball(
+        {
+            "SKILL.md": "# DevSecOps Skill\n",
+            "references/sdlc_phases.md": "phases\n",
+            "references/command_reference.md": "commands\n",
+            # Simulate VCS junk that must be stripped.
+            ".github/workflows/ci.yml": "ci\n",
+        }
+    )
+
+    fake_release = MagicMock()
+    fake_release.status_code = 404  # force zipball fallback (no release)
+
+    fake_zip = MagicMock()
+    fake_zip.content = zip_bytes
+    fake_zip.raise_for_status = MagicMock()
+
+    def fake_get(url, *args, **kwargs):
+        if "releases/latest" in url:
+            return fake_release
+        return fake_zip
+
+    with patch.object(install_skills.requests, "get", side_effect=fake_get):
+        ok = install_skills.install_skill("devsecops", target_dir=str(tmp_path))
+
+    assert ok is True
+    dst = tmp_path / ".kiro" / "skills" / "devsecops"
+    assert (dst / "SKILL.md").exists()
+    assert (dst / "references" / "sdlc_phases.md").exists()
+    assert (dst / "references" / "command_reference.md").exists()
+    # VCS junk stripped.
+    assert not (dst / ".github").exists()
+
+
+def test_install_skill_overwrites_existing(tmp_path):
+    """Re-installing replaces a stale copy rather than merging into it."""
+    dst = tmp_path / ".kiro" / "skills" / "devsecops"
+    dst.mkdir(parents=True)
+    (dst / "STALE.md").write_text("old")
+
+    zip_bytes = _make_github_zipball({"SKILL.md": "# fresh\n"})
+    fake_release = MagicMock()
+    fake_release.status_code = 404
+    fake_zip = MagicMock()
+    fake_zip.content = zip_bytes
+    fake_zip.raise_for_status = MagicMock()
+
+    with patch.object(
+        install_skills.requests,
+        "get",
+        side_effect=lambda url, *a, **k: fake_release if "releases/latest" in url else fake_zip,
+    ):
+        ok = install_skills.install_skill("devsecops", target_dir=str(tmp_path))
+
+    assert ok is True
+    assert (dst / "SKILL.md").exists()
+    # Stale file from the previous copy must be gone.
+    assert not (dst / "STALE.md").exists()