release: v0.8.4b1

Author: Kasper Junge

CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## [Unreleased]
 
+## [0.8.4b1] - 2026-04-12
+
+### Added
+- Package/bundle dependencies can now expand and install transitive skill and ralph dependencies, including nested packages.
+- `add`, `remove`, `sync`, and `upgrade` now keep package, skill, and ralph lockfile entries in sync across transitive dependency changes.
+
+### Changed
+- Lockfile handling now tracks package parent relationships for entries with one or more parent packages.
+- Package conflict detection now distinguishes resource types with the same installed name.
+- Shared install and lockfile paths were refactored to support package dependency expansion consistently across commands.
+
+### Fixed
+- `remove` now removes package-owned transitive dependencies without removing direct dependencies that share the same installed name.
+- `sync` and `upgrade` now preserve and refresh package parent metadata for transitive lockfile entries.
+- Bare names, trailing slashes, and local dependency paths now match more consistently during remove and upgrade operations.
+- Package expansion now rejects remote package local paths that resolve outside the downloaded repository.
+- Remote package local paths are converted to same-repository remote handles when they point to top-level resource directories.
+- Lockfile commit SHAs and remote handle components receive stricter validation to prevent unsafe substitutions and path traversal.
+
 ## [0.8.3] - 2026-04-12
 
 ### Added

README.md

@@ -75,6 +75,7 @@ everything with one command:
 dependencies = [
     {handle = "anthropics/skills/frontend-design", type = "skill"},
     {handle = "anthropics/skills/pdf", type = "skill"},
+    {handle = "your-team/agent-resources/dev-workflow", type = "package"},
 ]
 ```
 

agr.lock

@@ -19,3 +19,38 @@ source = "github"
 commit = "a0d5bfd4d9658073029d33f979ac5a027568caec"
 content-hash = "sha256:75e47183c30bc8651e76286680eddac88a3024a7ee5a7f1bc486d4d3fdee34ce"
 installed-name = "playwright-cli"
+
+[[skill]]
+handle = "computerlovetech/skills/github-issue-triage"
+source = "github"
+commit = "8bff044d76f9304cbd4981fb3ce4f837fd4eb5a2"
+content-hash = "sha256:35c62982b1bee8c0164a5cd43264b554f9b37697d6fda23f502107956a0ad889"
+installed-name = "github-issue-triage"
+
+[[ralph]]
+handle = "computerlovetech/research/conduct-research"
+source = "github"
+commit = "637025a5e221264845bff7e6a89aaba7a7bdb919"
+content-hash = "sha256:3a9c1ef64234ccb61d9b681afc4305ffadad5735f0536f77759a41366e75c3a2"
+installed-name = "conduct-research"
+
+[[ralph]]
+handle = "computerlovetech/ralphs/improve-codebase"
+source = "github"
+commit = "70a0dabf5a59ae1a3acaf50a9e619c83e174a35f"
+content-hash = "sha256:0afc55d5b2d4061fa82c270a147c66c8bc21589ab62c47d9747ddb5f382c708d"
+installed-name = "improve-codebase"
+
+[[ralph]]
+handle = "computerlovetech/ralphs/bug-hunter"
+source = "github"
+commit = "70a0dabf5a59ae1a3acaf50a9e619c83e174a35f"
+content-hash = "sha256:ab2e4924cbb999f677523211af9cfda48ce8433b17545854bd770f29d7664c64"
+installed-name = "bug-hunter"
+
+[[ralph]]
+handle = "computerlovetech/ralphs/security"
+source = "github"
+commit = "70a0dabf5a59ae1a3acaf50a9e619c83e174a35f"
+content-hash = "sha256:2b025b4e5546f2a04367a79e5f4201892bc155d22f53a55cfc0cd21071922de1"
+installed-name = "security"

agr.toml

@@ -1,9 +1,33 @@
+# Source to fetch skills from
 default_source = "github"
+
+# Tools to install skills to (e.g. "claude", "cursor", "codex")
 tools = ["claude", "codex", "opencode"]
+
+# Primary tool for instruction sync (must be listed in tools)
+# default_tool = "claude"
+
+# Default GitHub owner for short handles (e.g. "skill" resolves to "computerlovetech/skill")
+default_owner = "computerlovetech"
+
+# Default GitHub repo for two-part handles (e.g. "owner/skill" resolves to "owner/skills/skill")
+default_repo = "skills"
+
+# Sync instruction files across tools
+# sync_instructions = false
+
+# Which tool's instruction file is the source of truth
+# canonical_instructions = "CLAUDE.md"
+
 dependencies = [
     {path = "skills/agr-release", type = "skill"},
     {handle = "maragudk/code-review", type = "skill"},
     {handle = "microsoft/playwright-cli/playwright-cli", type = "skill"},
+    {handle = "computerlovetech/research/conduct-research", type = "ralph"},
+    {handle = "computerlovetech/skills/github-issue-triage", type = "skill"},
+    {handle = "computerlovetech/ralphs/improve-codebase", type = "ralph"},
+    {handle = "computerlovetech/ralphs/bug-hunter", type = "ralph"},
+    {handle = "computerlovetech/ralphs/security", type = "ralph"},
 ]
 
 [[source]]

agr/_install_common.py

@@ -18,8 +18,8 @@
     checkout_full,
     checkout_sparse_paths,
     downloaded_repo,
-    get_head_commit_full,
     git_list_files,
+    safe_get_head_commit,
 )
 from agr.handle import ParsedHandle, iter_repo_candidates
 from agr.metadata import (
@@ -437,10 +437,7 @@ def locate_remote_dep(
                     dep_source = prepare_fn(repo_dir, handle.name)
                     if dep_source is None:
                         continue
-                    try:
-                        commit = get_head_commit_full(repo_dir)
-                    except AgrError:
-                        commit = None
+                    commit = safe_get_head_commit(repo_dir)
                     yield RemoteDepLocation(
                         repo_dir=repo_dir,
                         source_path=dep_source,

agr/commands/add.py

@@ -1,5 +1,6 @@
 """agr add command implementation."""
 
+from dataclasses import dataclass
 from pathlib import Path
 
 from agr.commands import CommandResult
@@ -21,7 +22,7 @@
     format_install_error,
 )
 from agr._install_common import InstallResult
-from agr.package import expand_packages, has_package_section
+from agr.package import detect_conflicts, expand_packages, has_package_section
 from agr.ralph_installer import fetch_and_install_ralph
 from agr.skill_installer import fetch_and_install_to_tools, list_remote_repo_skills
 from agr.handle import ParsedHandle, parse_handle
@@ -38,6 +39,25 @@
 from agr.tool import ToolConfig
 
 
+@dataclass
+class AddInstallResult:
+    """Result of installing one requested dependency."""
+
+    installed_paths: list[str]
+    install_result: InstallResult
+    dep_type: str
+    lock_entries: list[tuple[str, LockedEntry]] | None = None
+
+
+def _parent_fields(parent_ids: set[str] | None) -> tuple[str | None, list[str] | None]:
+    if not parent_ids:
+        return None, None
+    sorted_ids = sorted(parent_ids)
+    if len(sorted_ids) == 1:
+        return sorted_ids[0], None
+    return None, sorted_ids
+
+
 def _detect_local_type(source_path: Path) -> str:
     """Detect whether a local path is a skill, ralph, or package.
 
@@ -100,7 +120,7 @@ def _install_dependency(
     default_repo: str | None,
     *,
     config: AgrConfig | None = None,
-) -> tuple[list[str], InstallResult, str]:
+) -> AddInstallResult:
     """Install a dependency and return paths, metadata, and resolved type.
 
     For local deps, installs directly as the detected type. For remote deps,
@@ -137,7 +157,7 @@ def _install_dependency(
         installed_paths = [
             f"{name}: {path}" for name, path in installed_paths_dict.items()
         ]
-        return installed_paths, install_result, dep_type
+        return AddInstallResult(installed_paths, install_result, dep_type)
 
     if handle.is_local:
         installed_path, install_result = fetch_and_install_ralph(
@@ -148,7 +168,7 @@ def _install_dependency(
             source=source,
             default_repo=default_repo,
         )
-        return [str(installed_path)], install_result, dep_type
+        return AddInstallResult([str(installed_path)], install_result, dep_type)
 
     # Remote — try as skill first, fall back to ralph.
     try:
@@ -165,7 +185,7 @@ def _install_dependency(
         installed_paths = [
             f"{name}: {path}" for name, path in installed_paths_dict.items()
         ]
-        return installed_paths, install_result, DEPENDENCY_TYPE_SKILL
+        return AddInstallResult(installed_paths, install_result, DEPENDENCY_TYPE_SKILL)
     except SkillNotFoundError:
         pass
 
@@ -178,11 +198,23 @@ def _install_dependency(
             source=source,
             default_repo=default_repo,
         )
-        return [str(installed_path)], install_result, DEPENDENCY_TYPE_RALPH
+        return AddInstallResult(
+            [str(installed_path)], install_result, DEPENDENCY_TYPE_RALPH
+        )
     except RalphNotFoundError:
-        raise SkillNotFoundError(
-            f"'{handle.name}' not found as a skill or ralph in any configured source."
-        ) from None
+        pass
+
+    return _install_package(
+        handle,
+        repo_root,
+        tools,
+        overwrite,
+        resolver,
+        source,
+        skills_dirs,
+        default_repo,
+        config=config,
+    )
 
 
 def _install_package(
@@ -196,7 +228,7 @@ def _install_package(
     default_repo: str | None,
     *,
     config: AgrConfig | None = None,
-) -> tuple[list[str], InstallResult, str]:
+) -> AddInstallResult:
     """Expand a package and install its transitive leaf deps."""
     if config is None:
         config = AgrConfig()
@@ -214,9 +246,26 @@ def _install_package(
         config.default_owner,
         config.default_repo,
     )
+    direct_ids = {dep.identifier for dep in config.dependencies}
+    direct_ids.add(pkg_dep.identifier)
+    direct_leaf_deps = [dep for dep in config.dependencies if not dep.is_package]
+    resolved_deps = detect_conflicts(
+        [*direct_leaf_deps, *expanded.dependencies], expanded.parents, direct_ids
+    )
+    resolved_keys = {(dep.type, dep.identifier) for dep in resolved_deps}
+    direct_leaf_keys = {(dep.type, dep.identifier) for dep in direct_leaf_deps}
+    expanded.dependencies = [
+        dep
+        for dep in expanded.dependencies
+        if (dep.type, dep.identifier) in resolved_keys
+        and (dep.type, dep.identifier) not in direct_leaf_keys
+    ]
 
     installed_paths: list[str] = []
     first_result: InstallResult | None = None
+    lock_entries: list[tuple[str, LockedEntry]] = [
+        ("package", entry) for entry in expanded.package_entries
+    ]
     for dep in expanded.dependencies:
         sub_handle = dep.to_parsed_handle(config.default_owner)
         sub_source = dep.resolve_source_name(config.default_source)
@@ -246,23 +295,68 @@ def _install_package(
             )
         if first_result is None:
             first_result = result
+        parent_id = expanded.parents.get(dep.identifier)
+        parent, parents = _parent_fields(
+            expanded.parent_sets.get(dep.identifier)
+            or ({parent_id} if parent_id else None)
+        )
+        if dep.is_local:
+            lock_entries.append(
+                (
+                    dep.type,
+                    LockedEntry(
+                        path=dep.path,
+                        installed_name=dep.installed_name,
+                        parent=parent,
+                        parents=parents,
+                    ),
+                )
+            )
+        else:
+            lock_entries.append(
+                (
+                    dep.type,
+                    LockedEntry(
+                        handle=dep.handle,
+                        source=result.source_name,
+                        commit=result.commit,
+                        content_hash=result.content_hash,
+                        installed_name=dep.installed_name,
+                        parent=parent,
+                        parents=parents,
+                    ),
+                )
+            )
 
     if first_result is None:
         first_result = InstallResult()
 
-    return installed_paths, first_result, DEPENDENCY_TYPE_PACKAGE
+    return AddInstallResult(
+        installed_paths,
+        first_result,
+        DEPENDENCY_TYPE_PACKAGE,
+        lock_entries=lock_entries,
+    )
 
 
 def _update_lockfile_for_adds(
-    lockfile_updates: list[tuple[ParsedHandle, str, InstallResult, str]],
+    lockfile_updates: list[
+        tuple[
+            ParsedHandle, str, InstallResult, str, list[tuple[str, LockedEntry]] | None
+        ]
+    ],
     config_path: Path,
 ) -> None:
     """Write install results to the lockfile."""
     if not lockfile_updates:
         return
     lockfile_path = build_lockfile_path(config_path)
     lockfile = load_lockfile(lockfile_path) or Lockfile()
-    for handle, ref, install_result, dep_type in lockfile_updates:
+    for handle, ref, install_result, dep_type, entries in lockfile_updates:
+        if entries is not None:
+            for kind, entry in entries:
+                lockfile.update_entry(entry, kind=kind)
+            continue
         if handle.is_local:
             lockfile.update_entry(
                 LockedEntry(path=ref, installed_name=handle.name),
@@ -305,7 +399,11 @@ def run_add(
     # Track results for summary
     results: list[CommandResult] = []
     # Track install results for lockfile: (handle, ref, install_result, dep_type)
-    lockfile_updates: list[tuple[ParsedHandle, str, InstallResult, str]] = []
+    lockfile_updates: list[
+        tuple[
+            ParsedHandle, str, InstallResult, str, list[tuple[str, LockedEntry]] | None
+        ]
+    ] = []
 
     for ref in refs:
         try:
@@ -325,7 +423,7 @@ def run_add(
                 dep_type = DEPENDENCY_TYPE_SKILL  # default, may change below
 
             # Install
-            installed_paths, install_result, dep_type = _install_dependency(
+            install = _install_dependency(
                 handle,
                 dep_type,
                 repo_root,
@@ -337,6 +435,9 @@ def run_add(
                 config.default_repo,
                 config=config,
             )
+            installed_paths = install.installed_paths
+            install_result = install.install_result
+            dep_type = install.dep_type
 
             # Add to config
             if handle.is_local:
@@ -356,7 +457,9 @@ def run_add(
 
             # Track for lockfile update
             lockfile_ref = path_value if handle.is_local else ref
-            lockfile_updates.append((handle, lockfile_ref, install_result, dep_type))
+            lockfile_updates.append(
+                (handle, lockfile_ref, install_result, dep_type, install.lock_entries)
+            )
             results.append(CommandResult(ref, True, ", ".join(installed_paths)))
 
         except SkillNotFoundError as e: